BuilderOS 3.0.0

A major version because existing work changes under it (#16, #17, #18): six analysis skills and six agents are replaced by product-analysis, and frames, discoveries, definitions, specs, build plans and releases written before now fail new gates until they carry the new sections (see each Upgrading note). What it adds: hooks for the rules that must always hold, gates on the quality of what is built, the product loop from stage to payment, decisions recorded as the person's, wayfinding, retro, to-spec, to-tickets, agents-md, and every skill rewritten to one writing standard kept by a test.

A deep pass against what a tier-1 product team would do, and against the Claude Code plugin guidance. Analysis and decisions (Q1 to Q7) in the project thread.

Added

• Hooks for rules that must hold every time. PreToolUse denies a hand-written state.json (bos.mjs guard); UserPromptSubmit adds one line per message with the phase and what to check the request against (bos.mjs context).
• The script travels with the project. bos.mjs vendor copies it to .builderos/bin/bos.mjs; init runs it and writes the Session Start block into both AGENTS.md and CLAUDE.md. The briefing flags a stale copy.
• Evidence from outside the session. bos.mjs evidence add --class interview|doc|data --id --where [--shared] [--from file] saves notes, tickets, exports or excerpts as evidence files the tags resolve to. Raw material is required, files are never overwritten, one participant per interview file. Starting with no evidence is described in references/lifecycle-setup.md.
• Quality of what is built. Gate 4.12 quality bar (permissions, personal data, performance as criteria or a reason), 4.13 a real-user session before the build on the product track, 5.9 interface review of the built states against the chosen direction, 5.10 automatic quality checks in the guardrail (accessibility, end-to-end, dependency audit, secret scan), 6.10 production readiness (errors seen before users report them, a restore tested), 6.11 first real use on the product track. New capability ui.capture.
• Eval suite in evals/ for claude plugin eval: routing, briefing, evidence, gates, with and without the plugin. CI runs npm test on GitHub Actions.

Changed

• Session context from 8,440 to about 2,100 characters on a project, briefing first; two lines outside a project.
• Code before an accepted build plan is a stop, not a flag, even when the user says to skip: name what the gate needs and offer to finish it, a change, or a recorded override. Found by the first eval run, where the plugin wrote code at phase 2.
• product-analysis replaces saas-metrics-reference, growth-frameworks, financial-models, okr-frameworks, strategy-frameworks and competitive-intel; their procedures are its references. product-diagnostician runs any of its areas; the agents growth-architect, finance-analyst, okr-architect, north-star-analyst, competitive-analyst and product-strategist are removed.
• Skill descriptions say what the skill does and when to use it. With the new outside-project session line, skills loaded on a standalone PRD and a retention question went from 0 of 4 eval runs to 4 of 4.

Upgrading. Specs fail 4.12 until ## Quality bar is written (and 4.13 on the product track until ## Real users); build plans fail 5.9 until ## Interface review, and 5.10 until TECH.md has **Quality checks:**; releases fail 6.10 until ## Production readiness (and 6.11 on the product track until ## First real use). Run bos.mjs vendor once in each existing project.

The person decides, and four skills from Matt Pocock (2026-10-21)

Where BuilderOS still let the agent decide, it now asks; and the parts of Pocock's skills it lacked are in. Analysis in the project thread "Skill scritte alla Pocock" (skill-alla-pocock-2026-10-21.md), decisions 1A 2A 3A 4A.

• Decisions belong to a person. The agent analyses and recommends in a round; the person chooses, recorded as **Chosen by:** and checked by the script: the assumption phase 1 tests (gate 0.5), what a discovery verdict means for the work (1.6), the opportunity and its target (2.8), the rollout (6.13), keep, iterate or kill (7.7), next to the bet (3.6) and the look (4.9) that already were. Scope boundaries in the spec and the slicing of the build plan are round questions too.
• pressure-testing is relentless. It keeps a design tree and stops when the frontier is empty, not after one round; each question is worded so "yes" accepts the recommendation; facts are looked up in parallel while the rest of the round is asked.
• wayfinding (from Pocock's wayfinder): work too big for one session becomes a map in .builderos/maps/{slug}/ with decision tickets (research, prototype, grilling, task), the fog of war and out of scope, one ticket per session. bos.mjs map prints the frontier; the briefing shows the next ticket of every open map.
• retro, to-spec, to-tickets, called by name on Claude Code and Codex (disable-model-invocation, agents/openai.yaml), each over one method: retro holds the environment retrospective that phases 5 and 7 now run; to-spec runs the new Synthesis Procedure of spec-writing (no interview, one question on the test seams, gaps named); to-tickets runs delivery-discipline/references/tickets.md (vertical slices, expand–contract for wide refactors, a quiz on the breakdown, one ticket per file or per issue). The spec template gains ## User stories and ## Test seams; the build plan gains **Tickets:** and ## Retro.
• New capabilities tickets.write and sessions.read.
• Every skill rewritten to one writing standard (decision 1A), after Pocock's writing-for-agents and Anthropic's skill guidance, and a test that keeps it (tests/scripts/skill-writing.test.mjs): descriptions at most 250 characters with what the skill does and when to use it; one Mode line pointing at references/operating-modes.md instead of five copied variants (delegation now lives there, once); every skill that drives work has ## Procedure with numbered steps that each end on Done when, and an output contract with its completion marker; guidance written as the behavior wanted, in Watch for tables (Do / Instead of) that replace the Common Mistakes tables; every relative link resolves. Across the 28 skills: prohibitions 148 → 31, description text 8,334 → 6,575 characters, completion criteria 14 → 193, words 30,718 → 28,924. spec-writing moves its synthesis procedure to references/synthesis.md and the real-user session script to its methods; delivery-discipline and spec-writing collapse their standalone and lifecycle procedures into one, so the step numbers named by the agents changed (build reviewer: steps 7 to 10).
• The coding agent stays on the code (round 2, decisions 5A 6A 7A 8A). TECH.md → ## Map says where the entry points, modules, tests and generated files are; AGENTS.md stays a short index of pointers, commands and must-hold rules. New skill agents-md creates or prunes AGENTS.md and CLAUDE.md on any repository, showing the diff before touching the person's lines; init runs it, the build updates the map, ship adds pointers to promoted files. Gate 5.11: a map exists and every path in it, AGENTS.md and CLAUDE.md exists. The briefing flags a dead pointer, a DOMAIN.md older than the last schema or migration change, and an AGENTS.md over 150 lines.

Upgrading. Frames, discoveries, definitions, releases and outcomes fail their gate until the decision carries **Chosen by:** from the person's answer. Build plans fail 5.11 until TECH.md has ## Map; run agents-md once in each existing project.

From one bet to a product that earns (2026-10-21)

The lifecycle shipped one bet well and said nothing between bets or around the product: no stage, no link from initiatives to a North Star, no channel, price or payment, no operations beyond the first incident. Analysis in the project thread "Da zero a milioni" (da-zero-a-milioni-2026-10-21.md), decisions 1A 2A 3A 4A.

• The product loop. PRODUCT.md → ## Business replaces ## Success: stage exit thresholds, North Star, revenue model, growth engine and a metric tree of three to six levers. A product review (skills/builder-os/references/product-review.md, /builder-os:bos-review, checked by bos.mjs review, conditions R.1 to R.5) reads every lever, judges the stage, and proposes one to three initiatives for a person to pick; it is written to .builderos/reviews/. The briefing flags it weekly before PMF and monthly after. Gate 2.7: each initiative names the lever it moves.
• The stage changes the rules. Before PMF scale work is rejected (2.5, new 3.8 and 4.15, model-judged), experiments are judged qualitatively against thresholds written first, concierge and Wizard of Oz are the preferred tests. After PMF, operations carry an SLO, incident response and a cost per active user.
• Distribution and money in the bet. Gate 3.7 (product track): ## Business case with the first 100 users, cost per user, and for a product for sale the price and the willingness-to-pay test. Gate 4.14: a tagged willingness-to-pay result and a payments row in the stack (payments and tax join the layer catalogue, with the Italian SdI and EU OSS case). Gate 6.12: a first real payment before phase 7. Products "not for sale" skip the money lines. Subscription states join the domain method.
• Operations by stage. Gate 6.10 now also reads TECH.md → ## Operations: Privacy always, AI disclosure when a model speaks (AI Act Article 50), SLO, incident response and cost per active user after PMF. Product facts written once, not per release.

Upgrading. Gate 2.7 warns until a first product review writes the metric tree. Product-track bets fail 3.7 until PRODUCT.md declares a revenue model and the bet has a business case; specs for products for sale fail 4.14 until a willingness-to-pay result and a payments layer exist; releases fail 6.10 until TECH.md → Operations has Privacy (plus the post-PMF lines at emerging-PMF or scaling), and 6.12 until a first payment on a product for sale.