buildflow walks one project through eleven stages. Every stage boundary has a gate — a checklist that must be honestly satisfied before you advance. The files are the state, one command drives it, and killing a weak idea at a gate is a success, not a failure.
The left half plans — each stage is one file in flow/, unlocked by /flow next
only when the previous gate passes. The right half ships — those stages live inside each card and repeat per card.
Click any stage to see its gate.
Can you name ONE real person or group who has this pain? Three sentences, no more.
The runner (flow.sh) does the mechanical checks — unchecked boxes, leftover
[FILL] placeholders, a card marked done without pasted evidence. The /flow skill makes the AI a
gatekeeper for what scripts can't judge: hollow content, fake evidence, grade-laundering, contract drift.
It may show you one example. It never fills your artifact.
Try it. This is the real stage-00 gate. /flow next refuses until every box is honestly checked.
/flow mode teach|work decides who writes the plan;
/flow auto decides who drives the build. The gates, the rubric, and the
done-rules are identical everywhere.
The attendee fills every artifact themselves. The gatekeeper refuses hollow work with a specific reason and never fills a template — the attendee writing it IS the method. Built for learning.
The AI interviews the operator once, drafts all six stages itself while self-gating, pauses exactly ONCE — the scope sign-off — then delivers the full card set as one plan summary. Live: 6–8 minutes.
After a preflight (plan complete, deps graph whole), a planner session drives the cards: one subagent per card, worktree isolation for parallel groups, planner reviews every diff and runs every verify itself. Seven principles govern it — done = world-state, halts batch at operator gates, two strikes per card, never destructive, all state in files (resumable). The run log is AUTO-LOG.md, not scrollback.
Every feature gets a business-impact score FIRST (H = moves money or the core promise · M = retention, time saved · L = nobody would pay or switch for it), then an AI-coding grade. H-impact justifies B/C cost; no L-impact feature above grade A survives — the classic failure is a v1 full of A-grade L-impact features: cheap to build, worthless to sell. The flow also proposes up to 3 impact-first features you didn't list (tied to the GTM research), default OUT, each needing your explicit decision. The cost grades:
When the real need is grade C, there are exactly three honest paths:
Invert the cut: the C feature goes FIRST (riskiest assumption first), everything else is minimized to serve it. One C proves the value prop — its siblings are v2.
The highest-leverage move. Multi-step agent → single LLM call. Auto-send → human-approves-draft. Custom pipeline → managed service. Same value, one grade cheaper.
An irreducible C that doesn't fit the budget. Both outcomes are honest, and killing here costs almost nothing — that's the point of gating early.
After planning, work becomes cards — one thing each. This is a real card from the courtbook run, after a full local build with every check green. Note what it still says.
One thing, stated negatively too. The NOT-list is what keeps a long AI session from helpfully building three other features.
Not intentions. The second curl proves the DB constraint; the SELECT proves the row persisted, not echoed. Sabotage checks included.
Named before building. “Tests pass” and “code merged” are mid-pipeline — done is a URL someone clicked.
This card passed every local check and still says todo — the executor itself reported: “without CLAUDE.md I'd have flipped the status on passing curls.”
Contract-first, slice early, UI last. Each card is one focused build session — human or AI coder.
These rules ship in the project's CLAUDE.md, so they're in context exactly when the building happens.
Repo, deploy pipeline, /healthz on a public URL. The deploy path exists before any feature does.
One contract endpoint + one ugly page calling it, deployed. The motivation hit and the integration proof.
One endpoint-group per card, built TO the contract. The contract is law — wrong contract? Amend it first, then code.
An automated suite hitting EVERY contract endpoint with edge + failure cases against the deployed API.
Static HTML, real copy, no logic. Iterate here: mock retries cost seconds, framework retries cost deploys.
Implement the approved mock, consuming the contract. Neither side improvises shapes.
Automated browser test over the DEPLOYED app covering the PRD's user actions. Its run doubles as verify-live.
Parallel when it's safe. Cards declare
deps:; /flow ready computes which todo cards have their deps done AND no
allowed-files overlap — those may build in parallel, one git worktree per card, merged back in card
order with a run-the-merged-app check between merges. The runner advises; the operator dispatches.
Contract-test and e2e cards stay serial by nature.
Six protocols, each born from a real failure, each living where the work happens — not in a handbook nobody opens.
Every UI card is built and reviewed against the design law: the edit-affordance ladder, object-first pages, locked tokens, a banned-words table (engine words never reach user copy). Structure is law; tokens are taste — replaceable deliberately, never ad-hoc.
One playbook per stack, written only after it worked for real — gotcha at the top, runnable smoke tests. Read before building on that stack; harvest after paying for a lesson. Auto briefs include them.
Skipping a gate deliberately is a legit operator call — and opens a DEBT.md line: the exposure, concretely, plus a close-before condition. Security-class skips are never silent. Status shows the count.
Branch per card, PR = the card's review surface, merges in card order. After merge: deploy, then verify on the LIVE URL — only then does the card close. Deploy-success is not proof the surface changed.
The served spec is live from the vertical slice onward; every backend card verifies its endpoints appear in the live /docs. Bonus: a route missing from /openapi.json after a green deploy = stale image, not your code — diagnosis in one curl.
Process lesson → RETRO.md. Stack lesson → a playbook. Flow lesson → FLOW-FEEDBACK.md, carried upstream to the template repo. Projects never edit the engine for themselves — feedback is the legal channel.
Six independent test rounds, each a fresh AI session in its own workspace, reports archived in
docs/test-reports/.
| Round | Mode | What it proved | |
|---|---|---|---|
| R1 | Honest attendee | Full walk-through; every gate advanced and refused correctly | PASS |
| R2 | Adversarial | 8 cheat attempts (checked boxes over placeholders, hollow research, C-graded-as-B, done-without-evidence) — all caught at the right layer | PASS |
| R3 | End-to-end | Empty folder → full plan → cards → retro, zero misbehaviors | PASS |
| R4 | Real idea (tickets + deepagents) | AI wishlist converted to 3 single LLM calls; agent framework declined with reasons | PASS |
| R5 | Real idea (booking + payments + realtime) | Realtime→DB constraint (C→A), VietQR split, chatbot cut; caught its own contract drift | PASS |
| PoC | Real build (C-001) | Card built exactly to scope; all checks green locally; card correctly STAYED todo — deploy gate unmet | PASS |
| R6 | Work-mode rehearsal | Interview consumed once, stages self-drafted with real research, exactly one scope pause, 7 cards + one plan summary | PASS |
Copy the template, open Claude Code in it, and let the first gate teach you the method.
Three rules under everything: inspect first — evidence before planning. The contract is the seam — backend builds to it, UI consumes from it. Done = proof in the world — a URL you clicked, never “tests pass.”