# Boom — Field Guide No. 5 Build Plan

**Project:** a first-person shooter in a browser tab — no engine, no WebGL,
no library. 13 stages, 4 phases, ~900 lines of vanilla JS on one canvas,
ending with the inversion: enemies that must *perceive* the map instead of
reading it.
**Spec source:** `docs/tutorial-draft.html` — the full stage-by-stage guide
(goals, requirements, non-goals, acceptance criteria per stage). This plan
does not restate the specs; it governs HOW the build runs.
**Doubles as:** framelogic.ai Field Guide No. 5 — "multi-agent done right
this time." The rules below ARE the tutorial's thesis.

---

## §0 Rules of engagement (distilled from the Potluck + game post-mortems)

Every rule below was paid for. Violations get field-noted, not hidden.

1. **Multi-agent is a build tool, not an iteration tool.** Fan-out happens
   exactly once, in Phase Three (stages 06–09), where four lanes are big,
   independent, and contract-bound. Phases One, Two, and Four are ONE agent,
   serial — and the moment Tommy is playtesting, everything is one agent.
2. **Every agent builds its own unit tests as it goes, and delivers them
   green.** There is no QA lane — the last build's QA agent generated more
   coordination cost than defects found (Tommy's call, 2026-09-06). A lane's
   delivery = code + tests + a passing `npm test` in its own worktree,
   stated in its report with the count. The lead re-runs the full suite at
   every merge gate; a lane whose tests don't run doesn't merge.
3. **Contracts freeze before fan-out.** Phase One ends by freezing the
   `cast()` interface and the map format (the draft marks the spot). The
   Phase-Three lanes build against those frozen seams plus pre-declared
   entity/render interfaces committed to main before any lane starts.
   package.json is lead-owned; lanes request scripts via field notes.
4. **A narrated action is not an action.** The lead verifies every spawn,
   every merge, every "done" against the filesystem/git before reporting it.
5. **A finding is a hypothesis, not a work order.** Before dispatching
   anything, the lead runs the ten-second check: did a human do this on
   purpose? Is it real on the latest code? What does the resume cost?
6. **Budget checks are part of the loop.** Note session-token state before
   and after fan-out; if the fan-out isn't visibly outrunning one agent,
   fold back. Nothing waits parked behind a rate limit — stalled lanes get
   folded, not babysat.
7. **Test where the user is looking.** The game ships embedded on
   framelogic.ai like the others: every playability check includes the
   EMBED on a phone-sized viewport, not just the direct URL. Instrument
   rules apply: window raised (rAF throttles minimized), viewport floors
   known, cache-busted re-vendors.
8. **Restart long-lived processes after merges.** Any watcher/server
   running across a merge is stale by definition.
9. **Decisions land in this file the moment they're made** (§Decisions
   below). Chat is a scratchpad; the plan file is the memory.
10. **Raw records are sacred.** `docs/field-notes.md` is append-only from
    day zero — every surprise, wrong turn, and pushback, written when it
    happens. The guide and its post-mortem get generated from it.

---

## Build method by phase (from the draft's own structure)

| Phase | Stages | Method | Gate to next |
|---|---|---|---|
| One — The sensor | 00–02 | ONE agent, serial | top-down debug view; `cast()` measures correctly; **interface freeze commits** |
| Two — The world | 03–05 | ONE agent, serial | walkable textured-less hallway; fisheye corrected; collision solid; tests green |
| Three — The game | 06–09 | **Team of 4** in worktrees: `textures` · `sprites` · `weapon` · `feel` | each lane: acceptance criteria from its stage spec + own tests green; lead merges in dependency order, full suite green after each |
| Four — The inversion | 10–12 | ONE agent, serial (Tommy playtesting between stages) | enemies navigate a map they discovered; model-driven mode; GPU cast loop |

Phase Three lane boundaries (pre-declared, one writer per file):
- **textures** — wall/floor texture mapping (stage 06); owns the column
  renderer's texture path.
- **sprites** — billboarded sprites + depth sort (stage 07); owns the
  sprite pipeline and z-buffer seam.
- **weapon** — weapon, firing, hit resolution, enemy damage states
  (stage 08); owns combat logic.
- **feel** — screen shake, head bob, sound hooks, HUD polish (stage 09);
  owns the juice layer, touches the frame loop last.

## §Decisions (append as made)

- 2026-09-06: no QA lane; per-agent tests-with-the-work (Tommy).
- 2026-09-06: working repo name `raycaster`; the game's real name is
  Tommy's call before the guide publishes.

## Stage index (specs live in the draft)

00 map+debug · 01 one ray badly · 02 DDA · 03 the 3D appears · 04 fisheye ·
05 collision · 06 textures · 07 sprites · 08 weapon+combat · 09 feel ·
10 enemies without the map · 11 let a model drive · 12 cast loop on GPU