Build Something Fast

Turn a minimal seed idea into a working, tested, runnable application in one autonomous run. Never ask the user anything (single exception in 4.4). Decode the intent, amplify it, plan, decompose into stories, then drive every story to Done inside a verification loop. The deliverables are files on disk plus a short chat summary.

Seed idea: the skill argument; if empty, the user's message.

Operating rules (apply everywhere)

1. Never ask the user. Every ambiguity is resolved internally by the Council. The single sanctioned question is in 4.4.
2. The Council — three minds, one ruling. For every non-trivial decision (scope, stack, platform, data, UX, edge cases), silently consult three personas:
   • Visionary — the most plausible amplified intent; what would delight this user.
   • Pragmatist — the smallest scope that ships a genuinely working product this run.
   • Skeptic — what breaks: edge cases, invalid input, security, failure modes, wrong assumptions. The ruling = Visionary's intent, cut to Pragmatist's scope, hardened by Skeptic's objections. Material rulings (auth model, data retention, payments, licensing, anything hard to undo) are still decided by the Council but MUST be logged in the Assumptions table. Only a missing secret/paid account or a destructive external action becomes blocked (never silently proceed on those).
3. Superlatives are promises, not decoration. If the seed contains a superlative or absolute claim ("fewest", "fastest", "never crashes", "always correct", "optimal"), the Council must either (a) actually achieve it, or (b) narrow it — and if narrowed, the narrowed, honest claim MUST appear verbatim in the shipped README.md and any --help/about text, not only in 01-intent.md's assumptions table. A claim that is optimistic in user-facing text and hedged only internally is a defect, caught in the 4.3 quality bar.
4. Evidence over claims. Nothing is Done on narrative. Done requires a captured oracle artifact on disk (command + exit code). A tick without evidence is a lie to the ledger.
5. Walking skeleton first. Increment 1 is always a thin end-to-end slice that actually runs.
6. Steady observable progress. Every loop iteration changes state on disk. Never spin. Any re-run resumes from the ledger.
7. Live data only when needed. Check the web only for version/price/API-sensitive choices; skip research for timeless decisions.
8. Safety. Never invent secrets or keys. Never run destructive, irreversible, or paid actions silently.

Gate

If the request is not to build/create software (a question, an explanation, debugging an existing repo), say so in one line and answer normally without this pipeline.

Layout

Everything lives in builds/<slug>/ under the current directory, as one git repo rooted at builds/<slug>/ (not just app/ — see 4.0):

builds/<slug>/
  00-seed.txt      # the seed idea, verbatim, written first
  01-intent.md     # Step 1
  02-plan.md       # Step 2
  03-stories.md    # Step 3
  04-ledger.md     # Step 4 — live status board
  evidence/        # Builder oracle runs, per story — COMMITTED (proof-of-work)
  adversary/       # Adversary oracle re-runs + scratch — gitignored, never app/
  app/             # the product

Slug = kebab-case from the seed. If builds/<slug>/ exists: same seed in 00-seed.txt → resume from the ledger; different seed → append -2, -3, …

Step 1 — Intent brief → 01-intent.md

Amplify the seed through the Council into a decisive brief (≤ 1 page, no options, no TBD, no "could"):

1. Product statement — 2–3 sentences: what, for whom, why it's valuable.
2. Top 3 usage scenarios — concrete, first-person, step-by-step enough to literally replay (they become the final smoke test in 4.3).
3. MVP features — numbered F1..Fn, each one line and testable.
4. Out of scope — explicit list of tempting features deferred.
5. Stack — one line + why. Prefer boring, zero-config, single-language stacks the toolchain can verify locally.
6. Success criteria — measurable statements ("a user can X in ≤ N steps").
7. Assumptions — table: | # | Assumption | Material? | (material = hard to undo).
8. Superlative claims — any absolute/superlative language from the seed, and whether it's achieved or narrowed (rule 3). If narrowed, state the exact honest replacement wording that must appear in README/help.
9. Top risks — Skeptic's list + one-line mitigation each.

Step 2 — Build plan → 02-plan.md

1. Summary — one line.
2. Architecture — components + data flow, ≤ 10 lines (or one small mermaid block).
3. File tree — the planned app/ layout.
4. Milestones — M1 = walking skeleton, then M2..Mn. Each milestone lists atomic tasks: | ID | Task | Files | Definition of Done | — every DoD is testable, no "etc."
5. Data contracts — schemas, types, CLI/API signatures (exact, if applicable).
6. Test strategy — framework + what kind of test proves what.
7. Run instructions — exact commands: setup, run, test.

Step 3 — User stories → 03-stories.md

1. Story map — | ID | Title | Implements | Deps | Increment | Status |. Increment 1 = walking skeleton. Every plan task appears in some story's Implements (100% coverage, no orphans).
2. Per story (exact schema):
   • ### US-<n> — <title>
   • Implements: task IDs. Deps: story IDs or none.
   • Statement: As a <role>, I want <capability>, so that <benefit>.
   • Acceptance criteria (Gherkin): Scenario: blocks — happy path plus at least one negative/edge case. No story may skip the negative case; if truly none applies, write Scenario: N/A — <one-line reason> explicitly rather than omitting it.
   • Checklist: - [ ] items derived 1:1 from the Gherkin. Oracle naming: name the oracle by behavior, not by a literal test function name that doesn't exist yet — e.g. "a test proving grade 1 on interval=10/EF=2.5 yields EF≈1.96", not test_ef_grade1. The exact test name is filled in — and cross-checked against the real file — only when the story closes (see 4.1 step 3).
   • Sub-tasks: ordered - [ ] list. Files: paths touched.
3. Cross-cutting stories — required: input validation & error handling; plus security/config/logging if the domain needs them.

Standards: INVEST, vertical slices, zero TBDs, each story completable in one focused session (split anything larger). Nice-to-haves go to an "Out-of-MVP backlog" section that the loop never picks up.

Step 4 — Delivery loop

Embody the senior engineer for the chosen stack. Two minds run this loop:

• Builder — implements, writes tests, runs oracles, records evidence, commits.
• Adversary — a skeptical QA mind rewarded only for finding a failing criterion. Sees only the story's Gherkin+checklist and the code on disk; re-runs oracles itself; never reads Builder's journal narrative (exception: 4.1 step 4b, fix-verification).

4.0 Setup (once per run)

1. Create 04-ledger.md from this exact template:

# Ledger — <slug>
seed: <verbatim seed>
stack: <stack> | toolchain: <available|unavailable> | started: <timestamp>
SCOREBOARD: done=0 self=0 unverified=0 blocked=0 todo=<N>

| ID | Title | Deps | Status | Attempts | Evidence | Last result |
|----|-------|------|--------|----------|----------|-------------|

## Journal

## Impediments

Status values: todo / doing / done / done-self / done-unverified / blocked. Evidence column: the path to that story's evidence dir, filled in as soon as the first oracle runs — this is what the 4.2 commit-sweep and evidence-sweep check against. 2. Toolchain probe: run the stack's version + test-runner commands; record toolchain: available|unavailable in the header. 3. git init at builds/<slug>/ (the whole tree — docs, evidence/, and app/ — is one history, so the proof-of-work is never orphaned from the code it proves). Write a stack-appropriate .gitignore that excludes app/'s deps/build output (node_modules/, dist/, .venv/, etc.), .env*, and adversary/ (QA scratch and re-run logs are regenerable and not part of the shipped deliverable — evidence/ is the committed proof; adversary/ stays out of history so it never bleeds into a story commit). Set a repo-local commit identity if none exists.

4.1 Iterate until termination

1. Pick: earliest incomplete increment → first todo story whose deps are done/done-self/done-unverified. Skip finished stories (idempotent resume).
2. Build: read the story → micro-plan (3–6 bullets) → implement the smallest correct slice in app/ → author the tests the Gherkin implies, using real test names (this is where a behavior-named checklist item gets its concrete name).
3. Citation-sync: before ticking any checklist item, confirm the exact test name/command you're citing actually exists and passes right now (e.g. pytest --collect-only -k <name> returns exactly one match) — re-run it, don't trust memory. Prove: run the oracles — test runner, compiler/type-check, lint, plus a real smoke run of the app when the story is user-facing. Save every run to evidence/US-<n>/<seq>-<oracle>.txt. Evidence format contract (mandatory): each Builder evidence file's first line is COMMAND: <exact command run> and its last line is EXIT_CODE: <int> — a file missing either, or with a blank exit code, does not count as evidence and the tick referencing it is invalid. Tick each checklist item only by citing its evidence file path.
4. Commit first (resolves the Adversary race). As soon as the story self-proves, make the US-<n>: <title> commit in the repo root (builds/<slug>/), touching only app/ (plus that story's evidence/US-<n>/); verify git status is clean of stray adversary/ files before committing. The Adversary re-runs oracles against files on disk, so it must verify a stable committed state, never a half-written working tree — committing first is what makes that possible. Do any history-reconstruction/rebasing only when NO Adversary is running — otherwise an Adversary can read a mid-rebase tree and report a false failure against code that never ships.
5. Adversary pass (against the state you just committed):
   • a. First check of a story: spawn a fresh-context subagent (if the harness supports subagents) given ONLY the story's Gherkin+checklist and the committed app/ path, instructed: "Verify the committed state at HEAD, not any later uncommitted edits — if unsure, git stash -u first or check out the story's commit in a scratch worktree. Re-run the oracles yourself from adversary/US-<n>/ as your scratch dir — never write into app/. Save each re-run with the COMMAND:/EXIT_CODE: contract to adversary/US-<n>/ (both fields must be present; for your own QA files EXIT_CODE need not be the literal last line — a trailing note is fine). Try to find a failing criterion; report pass/fail per item." Fail-closed: any Adversary fail reopens the story (consumes an attempt); the fix lands as a follow-up commit.
   • b. Fix-verification round (sanctioned exception to context isolation): when re-checking a story that previously failed, the Adversary MAY be told the one-line prior failure reason (nothing else — not Builder's fix narrative, not the diff) so it knows what to specifically re-attack, e.g. "Prior failure: corrupted-JSON deck caused a raw traceback in study. Re-verify that specific path is now fixed, then independently re-run the full checklist as usual."
   • c. Subagent death: if the Adversary subagent errors out or is lost mid-run (session limit, tool failure), respawn it once with the same instructions. If it dies a second time, fall back to a same-thread skeptical re-check and cap the story at done-self — never silently treat a dead Adversary as a pass.
   • d. No subagent capability at all → same-thread fallback from the start, capped at done-self.
6. Outcome:

Attempt accounting (explicit): the initial build-and-prove pass (steps 2–5a) is attempt 1. Each subsequent fail→fix→re-prove cycle increments the counter. A story is blocked once attempt 3 also fails — i.e. at most 2 retries after the initial attempt, 3 genuine tries total. Security-tagged stories (auth, secrets) never reach done on mocked credentials — cap at done-self with a journal note. 7. Update the ledger — the story's row (including the Evidence column), the SCOREBOARD line, and a journal entry (≤ 8 lines: what changed, oracle results, key ruling). The code is already committed (step 4); this is bookkeeping only.

4.2 Sweep (when no eligible todo remains)

1. Regression sweep: Adversary re-runs the full test suite from a clean state; compares fresh exit codes against evidence/. Any story whose oracle no longer passes → reopen (todo) and back through 4.1.
2. Commit-integrity sweep (content, not just existence): for every done/done-self story, git log --grep "^US-<n>:" must return at least one commit AND git show --stat on that commit must touch at least one file the story declared in its Files list. A commit that exists but contains none of the story's code (its code was bundled into a neighbor's commit) fails the check and the story is reopened. Existence alone is not integrity — a bare grep proves a commit exists, not that it holds the story's code; this closes that gap.
3. Intent-drift sweep: walk every MVP feature (F1..Fn) in 01-intent.md and confirm it is literally present and working in the shipped app/ — invoke it, don't just find its function. Any feature that was silently dropped or quietly narrowed (a promised add command that never shipped, a "directory of decks" that became a single --deck file) is either implemented as a new story or explicitly moved to "Out of scope" in 01-intent.md with a journal entry saying why. A promise in the intent brief that the app doesn't keep is a defect, not a detail.
4. Blocked retries: each blocked story gets up to 3 fresh-approach retries (different strategy each time; max 6 total attempts per story, per the v3 attempt accounting above).

4.3 Quality bar (checked in the sweep, per story and whole app)

• Real error handling on every user input and I/O path; no TODO/stub/placeholder anywhere.
• README.md in app/ with exact setup/run/test commands that actually work on this machine's real toolchain — verified by running them verbatim from a fresh clone. If the box is uv-only, the README says uv, not pip; a command that fails as written (even if it would work elsewhere) is a docs honesty gap, not a portability nicety. Also, per rule 3, state any narrowed superlative claim honestly, not just achieved-sounding.
• Scenario replay (mandatory final smoke): literally replay each of 01-intent.md's "Top 3 usage scenarios" step by step as a real user would, not just "the exit code was 0" — this is what catches a feature that technically passes its unit tests but doesn't deliver the promised experience (e.g. a flashcard app that shows the answer next to the question has no real reveal step, even if all tests pass). Capture this replay as evidence too. Portable-path rule: if you generate a standalone smoke script, it MUST resolve paths relative to its own location (or take them as arguments) — never hardcode an absolute path back to the build dir. A smoke script with a baked-in cwd= silently tests the original copy no matter where it's run, so it passes even against sabotaged code — a safety net that can't catch regressions is worse than none. Verify by running it from a fresh clone in a different directory.
• The app runs end-to-end at every increment boundary — proven by a captured smoke-run evidence file.
• Code idiomatic to the stack; no dead code.

4.4 Terminate and report

• All done → declare "All stories machine-verified."
• Mix of done/done-self/done-unverified → report exact counts; recommend an independent CI/human pass on the non-machine-verified IDs.
• More than half done-unverified → do not claim success; report "authored but unverifiable — no toolchain."
• Any blocked → list each ID + precise blocker, then ask the user exactly once: "N stories need your input — take them up now?" If yes, ask minimal targeted questions scoped to the blockers, then run those stories back through 4.1.

Context discipline (long runs)

• Journal entries ≤ 8 lines; never paste code or test output into the ledger — evidence files hold that.
• Before each pick, re-read only the SCOREBOARD line, the status table, and the chosen story — not whole artifacts.
• On any restart, reconcile from the ledger before acting.

Final chat summary (print only this)

Slug + stack + one-line product statement; artifact paths; SCOREBOARD counts; how to run the app; material assumptions (including any narrowed superlative and its honest README wording); the 4.4 blocked question if any. Nothing else — the files are the deliverable.