BuilderOS
The operating system for product builders. From an idea or a problem to a product running in production, in eight gated phases.
Not a prompt pack. A pipeline with state, evidence rules and gates that refuse to let you build on fiction.
flowchart LR
I([idea or problem]) --> P0
P0["0<br/>FRAME"] --> P1["1<br/>DISCOVER"]
P1 --> P2["2<br/>DEFINE"]
P2 --> P3["3<br/>IDEATE"]
P3 --> P4["4<br/>SHAPE"]
P4 --> P5["5<br/>BUILD"]
P5 --> P6["6<br/>SHIP"]
P6 --> P7["7<br/>LEARN"]
P7 -.->|keep / iterate| P2
P7 -.->|new evidence| P1
P1 -.->|KILLED| K(["stop: problem killed"])
classDef dt fill:#e8f0fe,stroke:#4285f4,color:#111
classDef dl fill:#e6f4ea,stroke:#34a853,color:#111
classDef term fill:#fff,stroke:#999,color:#111,stroke-dasharray:3 3
class P0,P1,P2,P3,P4 dt
class P5,P6,P7 dl
class I,K term
Phases 0–4 are design thinking: empathize, define, ideate, prototype, test. Phases 5–7 are delivery and learning. Phase 7 re-enters the loop rather than ending it.
Between every pair of phases sits a gate.
The three ideas
1. Gates you cannot argue with
Each phase ends at a list of conditions decided by reading the artifact, not by judging it. Where commands can run, a script with no dependencies (scripts/bos.mjs) decides the structural ones, so the model that wrote the artifact does not grade it; the model judges only the few conditions that need meaning, and the state records which was which. Gate 1 does not ask "was the research good?" It asks for five evidence units from five distinct sources and an explicit verdict. Gate 3 wants three options with mechanically different user actions, and kill criteria with a metric, a threshold and a date.
stateDiagram-v2
[*] --> Working
Working --> Checking: phase artifact written
Checking --> Passed: all conditions met
Checking --> Failed: condition N.N fails
Failed --> Working: fix the named condition
Failed --> Overridden: explicit reason, logged forever
Passed --> [*]: next phase
Overridden --> [*]: next phase, flagged
Checking --> Killed: problem did not survive
Killed --> [*]: pipeline stops. This is a win
A failed gate produces the failed condition, what was found, what would satisfy it, and the cheapest path there. Overrides exist, take a written reason, and stay visible in every status report afterwards. An undocumented bypass is worse than a documented one.
A passed gate is not an acceptance. Where the work changes hands (the frame, the spec, the build plan, the release) a person accepts it, in their own words, and the state records who and when. The agent never approves its own work. The build starts from a plan accepted before any code changes, bug fixes start from a failing test the fix cannot edit, and a KEEP at phase 7 leaves a watch behind it: a breach of its bands starts the next initiative.
Not every request needs all eight phases. Before the first one runs, the work is classified into a track and the classification is said out loud: a spike wants an answer and stops at the phase 1 verdict; a change is a modification to a live product whose solution is already decided (a bug, agreed debt, a compliance rule, a contract, a removal) and starts at the spec once its mandate passes a check; an internal tool, whose users are the builder or their own team, skips customer validation and the market (the need check covers phases 0 to 2) but keeps the options, valued in hours saved against not building, and every gate from the spec on, closing at the release unless it sets an outcome review; a feature changes an existing product where something is still to be chosen and starts at phase 2 once PRODUCT.md and the request's own evidence pass a coverage check; a product runs everything. A track only ever upgrades: a change that turns out to need a choice becomes a feature, a feature whose evidence turns out missing becomes a product and re-enters phase 0, and an internal tool that people outside the team start using becomes a product.
Work on a product that already exists gets what a new product never needed: the spec states what the change does to existing data, contracts, tracking events, permissions and current users; the release notes say what changes for people already using it; a suite that was red before the change is judged against its baseline instead of blocking forever; what an initiative settled about the product (its entities, its rules, its look) moves into DOMAIN.md and TECH.md at ship, so the next feature starts from it.
2. The evidence ledger
Every factual claim in every artifact carries a source tag:
Activation drops 62% between signup and first call. [data:mixpanel:funnel_q3]
Users describe onboarding as "a second job". [interview:P3,P7]
Enterprise buyers need SSO before evaluating. [assumption:unvalidated]
Every interview, doc and data tag points at a file in evidence/ holding the raw material: the interview notes, the pasted query output, the excerpt. A tag with no file fails the gate like an untagged claim. Gates count the tags, so an artifact resting on assumptions cannot pass a gate that requires evidence. The file does not make a source true; it makes it auditable, which is the most a text file can do.
Phase 0 is supposed to be mostly assumptions. Phase 2 is not: gate 2.4 rejects an estimated baseline outright, because a target measured against a guess makes phase 7 decorative.
3. Host-agnostic by construction
The skills hold both the method and the procedure. Agents and slash commands are thin adapters over them.
flowchart TB
subgraph portable["portable — the product"]
S["skills/<br/>method + procedure"]
R["references/<br/>templates, state schema, capability map"]
A["AGENTS.md<br/>shared contract"]
end
subgraph adapters["adapters — deletable"]
AG["agents/<br/>subagent wrappers, ~30 lines"]
CM["commands/<br/>slash commands"]
PL[".claude-plugin/<br/>manifest"]
CL["CLAUDE.md<br/>imports AGENTS.md"]
end
AG --> S
CM --> AG
CL --> A
classDef p fill:#e6f4ea,stroke:#34a853,color:#111
classDef ad fill:#fef7e0,stroke:#f9ab00,color:#111
class S,R,A p
class AG,CM,PL,CL ad
The test: delete agents/, commands/ and .claude-plugin/, and BuilderOS still takes someone from idea to production. That is why the procedure lives in the skill.
How a phase actually runs
Same steps, same artifacts, same gates, whatever the host.
flowchart TD
START([phase requested]) --> ST["read the active initiative's state.json"]
ST --> G{"previous gate<br/>passed?"}
G -->|no| REF["refuse<br/>name the failed condition"]
G -->|yes| CAP["resolve capabilities<br/>against this session's tools"]
CAP --> PREV["read PRODUCT.md<br/>+ previous phase artifact"]
PREV --> SUB{"host can delegate<br/>to a subagent?"}
SUB -->|yes| DEL["dispatch agent<br/>isolated context"]
SUB -->|no| INL["run the skill's procedure<br/>inline, in sequence"]
DEL --> ART["write .builderos/NN-phase.md"]
INL --> ART
ART --> GATE["run this phase's gate"]
GATE --> OUT([advance, or refuse])
classDef warn fill:#fce8e6,stroke:#d93025,color:#111
class REF warn
The only difference between the two paths is context isolation, which is a performance property, not a capability. Nothing is unavailable because of the host.
Capabilities, not tools
No skill names a tool. It names a capability and resolves it at runtime.
flowchart LR
NEED["phase needs<br/>analytics.query"] --> R{"resolve against<br/>session tools"}
R -->|found| LIVE["live query<br/>tag: data:posthog:funnel_q3"]
R -->|not found| D1{"numbers recorded<br/>in docs?"}
D1 -->|yes| DOC["dated figure<br/>tag: doc:board-deck-jul"]
D1 -->|no| D2{"instrumentation<br/>readable in code?"}
D2 -->|yes| CODE["tag: code:src/track.ts:42"]
D2 -->|no| FLOOR["state the gap<br/>ask the user<br/>tag: doc:user-2026-09-25-mrr"]
classDef ok fill:#e6f4ea,stroke:#34a853,color:#111
classDef fl fill:#fef7e0,stroke:#f9ab00,color:#111
class LIVE,DOC,CODE ok
class FLOOR fl
The floor is always the same: say what could not be retrieved and ask. The floor is never a plausible-sounding number.
A hardcoded tool name breaks three ways at once: on a different agent, on a different analytics stack, and on a different user's connector. So there are none. Full list in references/capability-map.md.
Prerequisites are zero. Nothing connected, no API key, no vault, no analytics account: every command still runs and still writes its artifact. Reading and writing files is the only hard dependency.
Analytics in particular is a category, not a product. BuilderOS asks five question shapes (catalogue, volume, funnel, retention, breakdown) and Mixpanel, Amplitude, PostHog, a warehouse or a pasted CSV are all valid answers. The shapes, the provider differences that matter, and the floor for each are in references/analytics-contract.md.
Two kinds of work
| Lifecycle | Standalone answer |
|---|
| Entry | using-builder-os, then builder-os | using-builder-os, then one specialist skill |
| Shape | Stateful, gated, sequential | Stateless, immediate |
| For | Taking something from idea to production | A scoped answer or artifact: PRD, research plan, growth, finance, competition, OKRs |
Invoke a specialist directly when the task is clear. using-builder-os briefs and routes when loaded by a hook or invoked explicitly; /builder-os:bos-ask asks it explicitly. /builder-os:bos-learn is the bridge: phase 7 runs the specialists against the phase 2 target and the phase 3 kill criteria.
How it works with you
One sentence is enough to start. /builder-os:bos-init "a tool that warns account managers before a client churns" drafts PRODUCT.md from the sentence, announces the name, track and mode it picked as defaults you can override, and opens the first round of questions in the same turn. No setup interview.
Questions come in rounds, with options and a recommendation. The first round opens with the claim as it understood it, so you can correct it before anything rests on it. Each round asks every question that can be asked before an answer arrives, each with two to four options and what each leads to, one recommended with its reason; a line at the end says how much is left:
🎯 Thesis: account managers lose renewals they could have saved; it rests on the churn signals being visible weeks ahead.
❓ Q1 · Who feels this first?
- A Account managers → they lose the renewal, they see the signals first
- B Customer success leads → they own the number, not the daily signals
- C The founder → only at your size today
➡️ A: the phase 1 evidence has to come from whoever sees the signals
📍 0 decided · 3 open · 0 deferred · next: what the signals are
✍️ 1A, or "go with the recommendations"
You answer by code (1A, 2C). "Go with the recommendations" counts as a decision, recorded as yours. A fact it can look up, it looks up. A fact only you know is asked in one plain line. A fact nobody has is never filled with a guess: its options are ways to close the gap (find it, query it, or proceed with it recorded as an unvalidated assumption).
It watches while you work. Before acting on a request mid-initiative, it checks it against recorded decisions, non-goals, the conditions earlier phases set, and the spec's out-of-scope list. It also notices when your decision has made PRODUCT.md or the roadmap wrong, when the request builds on an unvalidated assumption, and when more work is asked for on something whose result nobody has read or whose pilot never started. Each finding takes two lines and never blocks: you choose. The session briefing flags what the files show mechanically (see Project memory below).
The look, the stack and the bet are yours to pick. Phase 3 lists at least eight raw ideas before converging, and you choose the bet. Phase 4 models the domain rules with you, shows at least three visual directions as pages you can open (two layout versions inside an existing design system), and turns every open stack layer into a decision card with cost, lock-in and the boring default among the options. The build then sticks to what was decided: a new framework or paid service mid-build stops the slice and comes back to you.
You see it, click it and can send it. Every message the product will send (the welcome email, the reminder, the WhatsApp reply) is designed with its real text and a preview before the build. The first slice puts the product online behind a password, so launch day is opening a door, not a first deploy; every change after that has a link you open and try, and the build is not done until you have. .builderos/index.html shows the whole project on one page, in four parts: the open decisions and what each one blocks, what is in progress, what comes next, what is done. Each item opens down to everything behind it: every phase with its gate and its document in full, earlier cycles, the question log, the history, every decision and the project memory, with links to every file, design, demo and preview. .builderos/STATUS.md says the same in Markdown for the code host, a phone or a new session. Both are generated from the files on every state change and at every session start, never written by hand.
Every phase report opens with a plain recap. Five lines at most, for someone who did not follow the work: what was decided, what changed, what is still unknown. Condition ids and file names come after.
Install
Claude Code
/plugin marketplace add mariomile/builder-os
/plugin install builder-os@builder-os
Skills, agents and commands load with the builder-os: namespace. Commands dispatch in the foreground and await completion before reading artifacts or running gates. The installed plugin does not load this repository’s root CLAUDE.md as project instructions.
/builder-os:bos-init start from one sentence
/builder-os:bos stateful hub — routes to the current phase
/builder-os:bos-status pipeline state on one screen
/builder-os:bos-gate run the current gate
/builder-os:bos-review product review: levers, stage, what to build next
/builder-os:bos-frame … /builder-os:bos-learn
Codex and other agents
Prefer the Codex plugin, which preserves the complete bundle:
codex plugin marketplace add mariomile/builder-os
codex plugin add builder-os@builder-os
For manual discovery, retain a complete checkout with skills/, references/ and scripts/; point the host at its skill path or symlink individual skill folders. Copying only skills/ is unsupported. Resolve support files from the loaded skill’s real installation root and run the fully quoted script path from the user's project. AGENTS.md applies in the BuilderOS checkout, not automatically in unrelated projects.
Resolve subagent.dispatch against the current session on every host, including Codex. Where delegation is available and authorized, pass the skill and context to an agent and await it; otherwise run inline. Claude-specific agent profiles are optional adapters.
Details and the per-host difference table: docs/hosts.md.
What's in the box
24 skills. One entry point (using-builder-os: briefing and routing), the lifecycle hub (builder-os), four cross-cutting (gate-checks, evidence-ledger, pressure-testing, wayfinding for work too big for one session), agents-md (keeps the repository's AGENTS.md and CLAUDE.md a short index the coding agent can trust, and runs the retro that turns a slow session into pointers and checks), the rest split between the eight phases and the specialists that answer standalone questions. Fewer skills, each owning a whole job: research-methods plans, runs and synthesizes research; ux-architecture designs the flows and lets the person choose the look; system-design decides the stack and the backend; tracking-standards covers events and experiments; spec-writing writes specs and the communication around them (to-spec by name); delivery-discipline slices, builds and records the demo (to-tickets by name); release-ops sets up production from the first slice and releases. Among the specialists, product-analysis is one skill for metrics, growth, revenue, strategy, OKRs and competitors, business-case values a bet in money with its load-bearing assumption and sizes the stake, and go-to-market plans how buyers arrive before the build and reads each channel after. Each SKILL.md holds the procedure; a second mode, methods, templates and examples sit in the skill's own references/ and are read only when a step needs them. The gate conditions are one file per phase, so a gate loads only its own.
14 agents. Claude Code adapters, none longer than 35 lines by contract. They name the skill they load and add only what a delegated context needs: role, Iron Law, context contract, reporting.
16 commands, namespaced /builder-os:bos-* on Claude Code. Not sure which one? /builder-os:bos-ask.
A release plan ends with ## RELEASE READY. ## SHIPPED and advancement to LEARN require actual exposure evidence: status verified, an actual timestamp, environment, version and an observed result with a resolvable data/document source. Preparation does not authorize deployment.
Three hooks on Claude Code. At session start a short briefing (under 3,000 characters inside a project, two lines outside one); before each file write, a refusal to hand-write state.json; with each message, one line naming the active phase and what to check the request against.
One script. scripts/bos.mjs, Node built-ins only: briefing, gates, captured check runs, state recording with acceptance, process pace, initiative management, evidence import, the product review check, roadmap regeneration, the project page and migration. bos.mjs vendor copies it into the project (.builderos/bin/bos.mjs) so a session without the plugin still runs the gates.
An eval suite. evals/ runs with claude plugin eval ., each case with and without the plugin. Optional everywhere; where it cannot run, the model applies the same rules and the state says so.
Project memory
PRODUCT.md what the product is: ICP, problem, non-goals, constraints, voice, language, and the business: stage, North Star, metric tree, revenue model
DOMAIN.md the product's things and their rules: entities, states, invariants, business rules
TECH.md how it is built and run: stack, design system, verify and run commands, environments, operations, technical constraints, conventions, known traps
AGENTS.md gets a BuilderOS block telling every new session to read the files below first
.builderos/
index.html the project on one page, to open or send: open decisions, in progress, next, done (generated)
STATUS.md the same four parts in Markdown, readable on the code host (generated with index.html)
ROADMAP.md the master plan: direction, now / next / later, done and dropped
decisions/ ADRs, shared across initiatives
reviews/ product reviews: levers read, stage, what to build next
evidence/ the sources behind PRODUCT.md and TECH.md
local.json which initiative is active on this checkout (gitignored)
initiatives/{name}/ one folder per piece of work
state.json phase, track, gates, overrides, history
00-request.md feature and change: the request, its own evidence, the mandate
evidence/ one file per source a tag cites
00-frame.md problem, ICP, riskiest assumption
01-discovery.md evidence ledger, JTBD, VALIDATED / KILLED / RESHAPED
02-definition.md opportunity tree, selected opportunity, success metric
03-solution-bet.md options scored, kill criteria
DESIGN.md flows, states, components, accessibility
04-spec.md scope, not yet specified, conflicts, acceptance criteria, tracking plan
05-build-plan.md accepted plan, test map, review record
06-release.md rollout, rollback test, baseline, actual exposure verification
07-outcome.md actual vs target, keep / iterate / kill, watch
questionnaires/ async questions for people the user cannot interview
The bootstrap reads relevant project memory and briefs on active work and stale commitments: due watches, decisions past their revisit date or without one, unvalidated assumptions still in PRODUCT.md after discovery, and history events the schema does not know (a sign that state was written by hand). SessionStart refreshes this context on startup, resume, fork, clear and compact where the host supports and trusts the hook. Without it, invoke using-builder-os or use the project briefing block written by authorized lifecycle initialization. Standalone requests do not create lifecycle state. Several initiatives can be open at once; one is active, and lifecycle commands act on it.
Each phase reads the one before it. Starting phase 3 without 02-definition.md produces confident fiction, so the hub refuses.
Status
Version 3.4.1, see CHANGELOG.md. Honest state:
| Area | Status |
|---|
Spine — state, gates, evidence ledger, pressure testing, /builder-os:bos-init, /builder-os:bos, /builder-os:bos-status, /builder-os:bos-gate | Shipped |
| Phases 0–7 — all eight, each with its own skills, procedure and enforceable gate | Shipped |
| Host portability | Applied across the whole repo. No tool identifier in any skill, agent or command |
| Zero prerequisites | Every command runs with nothing connected; files are the only hard dependency |
| Gate enforcement | Script checks cover structural conditions and execution records; semantic conditions remain explicit model judgements. bos.mjs record writes gate results where shell execution is available. Regression checks run with pnpm test; they do not prove model compliance |
| Runtime verification | 11 behavioral scenarios in tests/scenarios/. The 9 that existed passed on Claude Code on 2026-10-05. On 2026-10-20 the two new cases for existing products (live-product-first-feature, change-with-red-suite) and both feature-track cases passed after three fixes they found; the other five were not rerun after the design and stack rework. One initiative rehearsed from /builder-os:bos-init to phase 7 and into its second cycle, on a stand-in for a captoo feature with synthetic evidence: seven defects found and fixed, see docs/runs/2026-09-27-captoo-rehearsal.md. Codex CLI 0.157.1 installs the plugin and assembles the prompt correctly; no phase has yet run under a Codex model |
| Real use | One real product, an internal team tool, taken by its author from frame to phase 6 between 2026-09-29 and 2026-10-03, with phases 1 and 5 overridden. Its pilot has not started, so no phase 7 has yet run on real outcomes. What the run showed shaped the question rounds, the watch and the recap above |
The Node tests pass (pnpm test), including one that checks every skill against the writing standard, one that runs every gate against a project where every artifact exists and nothing it describes does, and one that checks the counts in this README. The eval suite in evals/ (claude plugin eval) scored 1.0 with the plugin on all eleven cases that need no shell on 2026-10-22, one of them after the fix it found. They prove the script and the adapters, not model compliance; that is what the scenarios are for.
Roadmap and task state: docs/plans/2026-09-20-lifecycle-os-v1.md.
Influences
Patterns borrowed, not dependencies. BuilderOS installs on its own.
- obra/superpowers — phase discipline with hard refusal to skip ahead, "evidence over claims", the short bootstrap skill with its red-flags table, and classifying work into paths before starting
- mattpocock/skills — small composable skills, interview rounds (here extended to options with consequences and a recommendation with its reason, per question), the async questionnaire, the ADR test, the glossary, and "not yet specified" kept apart from out of scope
- pbakaus/impeccable — durable product truth kept separate from surface decisions, deterministic detectors
Docs
MIT.
