Youragentwillbuildanything.BuilderOSasksforprooffirst.
A free plugin for Claude Code and Codex. Eight phases from an idea to a product in production. Every claim carries its source, and every phase ends at a gate that refuses to move on without evidence.
/plugin marketplace add mariomile/builder-osNot a prompt pack. A pipeline with rules.
State on disk, evidence behind every sentence, and gates checked by code the model did not write.
- 3.1passThree options with different user actions
- 3.2passBet selected, rejections written
- 3.3failKill criteria: metric and threshold, no date
- 3.4passCheapest test of the riskiest assumption
- E.1passEvery tag resolves to a file in evidence/
- Refused. Add a date to 3.3, or override with a written reason.
Gates you cannot argue with
A dependency-free script checks the structural conditions, so the model that wrote the document does not grade it. A refusal names the condition and the cheapest way to pass.
needs: analytics.query
No invented numbers
Nothing connected? It walks down to the floor: say what is missing, ask you, tag your answer.
Every claim carries its source
Tags point to files with the raw notes, exports and excerpts. Gates count them. An artifact built on assumptions cannot pass a gate that asks for evidence.
Memory that lives in your repo
Plain Markdown next to your code. Every session opens with a five-line briefing, and flags what has gone stale. Every message carries one line with the phase.
skills/
method and procedure
Runs on any agent
The procedure lives in the skills. Commands and subagents are thin adapters you could delete. Claude Code gets the richest surface; Codex runs the same gates.
A track only moves up. A spike that says build it keeps its files.
Not everything needs eight phases
The work is classified before the first phase runs, and you hear why. Spikes stop at a verdict. A decided change, like a bug fix, starts at the spec. Features on a proven product start at phase 2. A request for a PRD or a research plan gets just that, no pipeline.
Eight phases. A gate between each.
Phases 0 to 4 are design thinking, 5 to 7 are delivery and learning. Phase 7 sends you back into the loop. A problem killed in phase 1 is a win: you stopped before building it.
- 0/builder-os:bos-framewrites 00-frame.md
Frame
A stated problem, one ICP and the riskiest assumption.
Gate 0 asks for
- No solution language in the problem
- One ICP, named
- A falsifiable riskiest assumption, chosen by a named person
- A dated why-now
- 1/builder-os:bos-discoverwrites 01-discovery.md
Discover
The evidence ledger, jobs to be done and a verdict.
Gate 1 asks for
- Five primary evidence units from five distinct sources
- Contrary evidence searched and recorded
- Verdict stated: VALIDATED, KILLED or RESHAPED
- What the verdict means for the work, decided by a person
- 2/builder-os:bos-definewrites 02-definition.md
Define
An opportunity tree, one opportunity and the success metric.
Gate 2 asks for
- Three opportunities, one chosen by a named person with written rejections
- A baseline that was measured, not estimated
- The metric measures an outcome, not the build
- Each initiative names the product lever it moves
- Coherent with the stage: before product-market fit, no scale work
- 3/builder-os:bos-ideatewrites 03-solution-bet.md
Ideate
Options, the bet, kill criteria and the cheapest test.
Gate 3 asks for
- Eight raw ideas before converging on options
- Three options with different user actions
- The bet chosen by a named person, not the agent
- Kill criteria with a metric, a threshold and a date
- The cheapest test of the riskiest assumption
- Business case: the first 100 users, cost per user, price
- 4/builder-os:bos-shapewrites 04-spec.md
Shape
Business rules, the chosen look and stack, the spec and the tracking plan.
Gate 4 asks for
- Testable acceptance criteria
- Out of scope is not empty
- Error and empty states for every step
- Tracking on the phase 2 metric
- Every stack layer decided by a person, or marked open
- Visual direction and domain model chosen, or not applicable with a reason
- Impact on existing data, contracts, events, permissions and users
- A quality bar: permissions, personal data, performance
- A session with a real user from the ICP, before the build
- Willingness to pay tested, for a product for sale
- 5/builder-os:bos-buildwrites 05-build-plan.md
Build
An accepted plan, tracer tickets, the test map and the review record.
Gate 5 asks for
- The plan, in plain words, accepted before any code
- Every acceptance criterion has a test
- Tests run through the recorder. Pasted output does not count
- A suite already red is judged against its baseline, not exit 0
- Instrumentation verified to fire
- No scope creep against the spec
- A guardrail runs the checks on every change, accessibility and security included
- Built states reviewed on screenshots against the chosen look
- A code map, and no dead pointer in AGENTS.md
- 6/builder-os:bos-shipwrites 06-release.md
Ship
Rollout, rollback, baseline and release notes.
Gate 6 asks for
- Rollback tested, with an owner
- Baseline captured before the actual exposure
- Exposure observed and authorized by a named person
- Outcome review date set
- Domain and design system promoted to the project
- Production ready: errors seen before users report them, a restore tested
- First real use: someone outside the team did the main action
- A first real payment, for a product for sale
- 7/builder-os:bos-learnwrites 07-outcome.md
Learn
Actual against target, and the decision.
Gate 7 asks for
- Kill criteria evaluated
- KEEP, ITERATE or KILL, chosen by a named person
- A KEEP leaves a watch on the metric
- Cleanup scheduled: the flag after KEEP, the code after KILL
- One lesson that outlives the feature
From one line to evidence you can build on.
Four steps. Commands shown for Claude Code; on other agents, say the same thing in words.
Transcript shortened for the page.
Two commands. Nothing to connect.
No API keys, no analytics account, no config. An agent that can read and write files is the only requirement.
Add the marketplace, inside a Claude Code session
/plugin marketplace add mariomile/builder-osInstall the plugin, then start a new session
/plugin install builder-os@builder-osRun your first command
/builder-os:bos-init "your idea in one line"28 skills, 14 agents and 16 commands load, all under the builder-os: prefix. From a terminal, the same install is claude plugin marketplace add then claude plugin install.
Update
claude plugin marketplace update builder-os && claude plugin update builder-os@builder-osPause it outside product work (about 3.5k tokens a session)
claude plugin disable builder-os@builder-osSixteen commands. Remember one.
/builder-os:bos reads the state and routes you to the right phase. Everything else is there when you want to be explicit.
Start and find your place
/builder-os:bos-initStart a project or add an initiative
/builder-os:bosRead the state, go to the right phase
/builder-os:bos-askThree questions, then a route
/builder-os:bos-statusEvery initiative and gate on one screen
/builder-os:bos-reviewRead every lever, judge the stage, pick what is next
Run a phase
/builder-os:bos-framePhase 0: problem, ICP, assumption
/builder-os:bos-discoverPhase 1: research and a verdict
/builder-os:bos-definePhase 2: opportunity and metric
/builder-os:bos-ideatePhase 3: options, bet, kill criteria
/builder-os:bos-shapePhase 4: spec and tracking plan
/builder-os:bos-buildPhase 5: tracer bullets, test first
/builder-os:bos-shipPhase 6: rollout, rollback, baseline
/builder-os:bos-learnPhase 7: keep, iterate or kill
Shortcuts and records
/builder-os:bos-discovery-sprintPhases 0 to 2 in a row
/builder-os:bos-gateRun the gate, or override it on the record
/builder-os:bos-adrRecord a decision that is hard to undo
Six source tags.
Every fact in every artifact carries one. The first three must point to a file in evidence/ with the raw material, or the gate fails the same way it fails an untagged sentence. What you say in chat becomes doc:user-date-topic, with your words saved.
- needs file
[data:…]Live query or pasted export
- needs file
[interview:…]Notes from a real conversation
- needs file
[doc:…]A document, or what you told it
- no file
[code:…]A line in the codebase, by path
- no file
[estimate:…]Reasoned out, not measured
- no file
[assumption:…]Believed, not yet tested
Where 3.0.0 honestly stands.
A tool that refuses unsourced claims should not make any about itself. The last row is the one to read.
| Eight phases, each with its skills, procedure and gate | Shipped |
|---|---|
| Evidence ledger, tracks, multiple initiatives, session briefing | Shipped |
| Gate enforcement | A script checks structure and execution records and writes every result to state. Meaning stays a model judgement, recorded as one |
| Build and release evidence | Tests count only from a recorded run. SHIPPED needs observed exposure, not a planned date |
| The person decides at every phase | The agent analyses and asks in rounds, each question with its recommended answer. The assumption, the verdict, the opportunity, the bet, the stack, the look, the rollout and keep or kill are recorded as Chosen by a named person |
| Work on a product that already exists | A change track, the request's own evidence, impact on what exists, cleanup after the decision, gates that cope with a suite already red |
| The product loop, from stage to first payment | Stage thresholds, North Star and a metric tree in PRODUCT.md. A product review proposes what is next. Before PMF scale work is rejected; a product for sale needs a price tested before the build and a first real payment. After PMF, operations need an SLO, incident response and a cost per active user |
| Quality gates and hooks | Gates on what is built: a quality bar, an interface review, automatic checks, production readiness. Hooks block a hand-written state file on every call and put the phase on every message |
| Big work, retros and handoffs | wayfinding maps work too big for one session. retro, to-spec, to-tickets and agents-md run by name |
| Product analysis in one skill | Metrics, growth, finance, OKRs, strategy and competitors live in product-analysis, run by one agent |
| Every skill to one writing standard | 28 skills, each step ending on a Done when, checked by a test |
| Regression tests | 127 of 127 pass, in CI on every change. They check the gates, not model behavior |
| Eval suite | 11 of 11 cases that need no shell scored 1.0 with the plugin on 22 October. Routing, briefing, evidence and gates |
| Behavioral scenarios on Claude Code | The 4 cases for live products and the feature track passed on 20 October. The rest last passed on 5 October |
| Idea to phase 7 and back into a second cycle | Rehearsed once, with synthetic evidence. Seven defects found and fixed |
| Codex | Installs as a plugin. No phase run under a Codex model yet |
| Idea to phase 7 on a real product with real users | Not yet. One internal team tool reached phase 6; its pilot has not started |
Shipped and verified Partly verified Not yet