Boom — The Build Kit
The plan, the rules of engagement, and the agent prompts — published before the build, on purpose
Guide No. 5 builds a first-person shooter in a browser tab — no engine, no WebGL, thirteen stages ending with enemies that must perceive the map instead of reading it. This time the method is the thesis: every rule below was paid for in the Potluck post-mortem and the game builds post-mortem, and the kit ships before the first commit so the build can be judged against its own rules. The finished build write-up is now published as Field Guide No. 5: Boom.
Pull the kit
Raw files — open in a browser, or curl -O each into a working directory:
- PLAN.md — the build plan: rules of engagement, phase-by-phase method, lane boundaries, stage index
- prompts/lead.md — the opening prompt for the lead window (the only window until Phase Three)
- prompts/textures.md · sprites.md · weapon.md · feel.md — the four Phase-Three lane prompts
- tutorial-draft.html — the full 13-stage tutorial draft ("Write the renderer. Then teach it to see.") with per-stage specs: goal, requirements, non-goals, acceptance criteria
mkdir raycaster-kit && cd raycaster-kit
for f in PLAN.md prompts/lead.md prompts/textures.md prompts/sprites.md \
prompts/weapon.md prompts/feel.md tutorial-draft.html; do
curl -fsS --create-dirs -o "$f" "https://framelogic.ai/kit/raycaster/$f"
done
The rules of engagement
The §0 the whole kit hangs on — each rule cites the failure that minted it:
- 1 — Multi-agent is a build tool, not an iteration tool. Fan-out happens exactly once (Phase Three, four lanes); every other phase is one agent, serial — and the moment a human is playtesting, everything is one agent. (Potluck RC1.)
- 2 — Every agent builds its own unit tests as it goes, and delivers them green. There is no QA lane. A lane's delivery is code + tests + a passing run in its own worktree, stated with the count; the lead re-runs the full suite at every merge gate. A lane whose tests don't run doesn't merge. (The QA lane generated more coordination cost than defects found — Tommy's call, and this build's defining change.)
- 3 — Contracts freeze before fan-out. Phase One ends by freezing the
cast()interface and map format; lanes build against frozen seams. package.json is lead-owned. (Potluck's zero-conflict result — the part worth keeping.) - 4 — A narrated action is not an action. Verify every spawn, merge, and "done" against the filesystem before reporting it. (The announced-but-never-spawned implementer, games post-mortem.)
- 5 — A finding is a hypothesis, not a work order. Ten-second triage before any dispatch: did a human do this on purpose? Real on latest code? What does the resume cost? (Three agents chasing two deliberate deletions, Potluck RC2.)
- 6 — Budget checks are part of the loop. Token state noted before and after fan-out; if parallel isn't visibly winning, fold back. Nothing waits parked behind a rate limit. (92% of an allowance in ten minutes, Potluck RC1.)
- 7 — Test where the user is looking. Playability checks include the phone-sized embed, not just the direct URL. Measure the instrument first — minimized windows throttle rAF; viewports have floors. (The white box; the 1fps phantom — games post-mortem.)
- 8 — Restart long-lived processes after merges. A watcher running across a merge is stale by definition. (Nine recipes ruined by version skew, Potluck RC5.)
- 9 — Decisions land in the plan file the moment they're made. Chat is a scratchpad; the plan is the memory. (The lost Orchestrator conversation, Potluck RC7.)
- 10 — Raw records are sacred. Field notes are append-only from day zero; the guide and its post-mortem get generated from them, not from memory.
The build, in one table
| Phase | Stages | Method | Ends with |
|---|---|---|---|
| One — The sensor | 00–02 | one agent, serial | a ray that measures; interface freeze |
| Two — The world | 03–05 | one agent, serial | a hallway you can walk |
| Three — The game | 06–09 | team of 4 (textures · sprites · weapon · feel), tests-with-the-work | a playable shooter |
| Four — The inversion | 10–12 | one agent + playtests | a perception system |
What it cost
The game is live as Boom (78 commits, 220 tests, one lead window from 00:58 to 00:12 the next day, with Tommy playtesting between rounds). Rule 6 says note the token state before and after fan-out. The field notes got the before (about 170K of context spent for Phases One and Two) and never the after, so the figures below come from the session log itself, usage deduplicated per API response. Tokens, not dollars.
| API calls | Output tokens | Cache writes | Cache reads | |
|---|---|---|---|---|
| Lead window (one agent, serial, all four phases + playtest rounds) | 288 | 671,656 | 2,348,093 | 140,865,970 |
| The fan-out: 4 lanes + 4 retries, zero commits | 36 | 5,697 | 228,558 | 483,868 |
| Build total | 324 | 677,353 | 2,576,651 | 141,349,838 |
How to read it: output — the tokens that became code, tests and field notes — is under half a percent of what was read. That is the shape of one long window: every call re-reads everything before it, so the average call carried about 490K of context and the largest carried 900K. The honest number is not "677K tokens wrote a shooter"; it is "141M tokens of re-reading did." The fan-out that never ran cost about 0.7M tokens and 68 minutes of wall clock for no code — cheap in tokens, expensive in time, and the on-disk monitor (commits and dirty files per lane) was the only signal that said so.