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.
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. 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
- 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
- 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 selected with written rejections
- A baseline that was measured, not estimated
- The metric measures an outcome, not the build
- 3/builder-os:bos-ideatewrites 03-solution-bet.md
Ideate
Options, the bet, kill criteria and the cheapest test.
Gate 3 asks for
- Three options with different user actions
- Kill criteria with a metric, a threshold and a date
- The cheapest test of the riskiest assumption
- 4/builder-os:bos-shapewrites 04-spec.md
Shape
The spec, DESIGN.md, acceptance criteria 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
- 5/builder-os:bos-buildwrites 05-build-plan.md
Build
Tracer tickets, the test map and the review record.
Gate 5 asks for
- Every acceptance criterion has a test
- Tests run through the recorder, exit 0. Pasted output does not count
- Instrumentation verified to fire
- No scope creep against the spec
- 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: timestamp, environment, version
- Outcome review date set
- 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
- 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"24 skills, 20 agents and 15 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.8k tokens a session)
claude plugin disable builder-os@builder-osFifteen 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
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 2.1.1 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 |
| Regression tests | 55 of 55 pass. They check the gates, not model behavior |
| Behavioral scenarios on Claude Code | 7 of 7 passed on 27 September. Not rerun after the latest hardening |
| 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. The first real initiatives are in phase 6 |
Shipped and verified Partly verified Not yet