# Feature Plan

> Feature Plan is an Agent Skill for productivity published in the levy-street/world-of-claudecraft repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Break a big feature into a phased implementation plan with starter prompts, progress tracking, and cross-session state. Opus 4.8 native - each phase runs as its own session with context-saving subagents, agent teams, and (for batch-heavy work) deterministic Workflows, plus a web-research pass for any third-party surface. Use when a feature is too large for one session.

- Skill name: `feature-plan`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/levy-street/world-of-claudecraft/blob/HEAD/.claude/skills/feature-plan/SKILL.md
- Repository: levy-street/world-of-claudecraft (1,713 GitHub stars when collected)

## SKILL.md

# Feature Plan: Multi-Phase Implementation Planning (Opus 4.8)

Break a large feature into a phased implementation plan designed for multiple Claude Code sessions. Every phase runs as its own fresh session and uses **Opus 4.8 at xhigh effort** (`ultracode` where the phase warrants deterministic multi-agent orchestration). The whole point is to **save context per phase**: the orchestrator delegates reading and fan-out to subagents and keeps only conclusions, so each session stays sharp.

The user will provide a feature description either inline (e.g., `/feature-plan add a guild bank`) or you will ask them to describe it.

**Before doing anything else: scan memory.** If you use Claude Code's memory feature, check your `MEMORY.md` index and project memory entries for prior decisions or feedback relevant to this feature's domain. Past incidents encoded there are cheaper than rediscovering them.

---

## What this repo is (so the plan fits it)

Architecture and invariants live in the root `CLAUDE.md` (one sim three hosts, the `IWorld` seam, server authority, 20 Hz determinism via `Rng`, the i18n contract); the plan must respect all of them, so reference that file rather than restating it. Two planning-specific consequences:

- A feature added to the offline `Sim` is not done until it is mirrored online (via `ClientWorld`) and, where relevant, exposed to the RL env. Extend `IWorld` first, then implement it in **both** worlds.
- **The contributor i18n policy is English-only.** Every new player-visible string is a `t()` key added in ENGLISH to the matching `src/ui/i18n.catalog/<domain>.ts` module and rendered via `t()`. Never edit the `src/ui/i18n.locales/<lang>.ts` overlays: locale fills are release-time maintainer work (the one exception, M16: a wordy new English value also needs its five non-Latin fills in the same change, see `src/ui/CLAUDE.md`). Sim/server stay language-agnostic (no `t()`, no DOM) but their player text needs a matcher rule in `src/ui/sim_i18n.ts` / `src/ui/server_i18n.ts` in the SAME change; the S3 guard (`tests/localization_fixes.test.ts`) enforces it.

---

## Orchestration Toolbox (Opus 4.8) - choose deliberately before running any phase

Opus 4.8 self-initiates **fewer** subagents than prior models, so you MUST request fan-out explicitly. Pick the lightest tool that fits; escalate only when the work demands it.

| Tool | What it is | Use it when | Context effect |
|------|-----------|-------------|----------------|
| **Explore subagent** (`subagent_type: "Explore"`) | Read-only search agent; reads excerpts, returns conclusions | Mapping the codebase, locating files/patterns, "where is X used" | Raw file reads stay in the subagent; only the summary returns. Default for all recon. |
| **Parallel Agent fan-out** (multiple `Agent` calls in one message) | Several independent agents in one turn | Independent vertical slices in a phase (sim + server + ui + tests); parallel reviews | Each agent's work stays in its own context; you keep the results. Cap at ~5 manual agents. |
| **Agent teams** (`name:` + `SendMessage`) | Addressable, longer-lived agents you can hand more work to with context intact | Multi-round collaboration where an agent needs its prior context (iterative implement, fix, re-review) | Reuses a warm agent instead of re-priming a fresh one. Never `mode: "plan"` on teammates (they stall). |
| **Workflow** (the `Workflow` tool) | A JS script orchestrating dozens to hundreds of subagents deterministically (pipeline / parallel / loop-until-dry / adversarial-verify), with structured-output schemas | A phase is batch-heavy or needs scale + verification: mass edits, content sweeps across many tables, exhaustive audits, adversarially-verified review. Requires explicit `ultracode` opt-in in the running prompt. | Intermediate results live in script variables, not your context. Scales far past manual fan-out (16 concurrent / 1000 total). |
| **ToolSearch / deferred tools** | On-demand tool-schema loading | A phase needs an MCP/integration tool not loaded by default | Keeps unused tool schemas out of context until needed. |

Hard rules (Opus 4.8 + this repo):
- **Subagents inherit the parent model.** No need to set model unless you deliberately want a cheaper tier; when unsure, omit.
- **Request fan-out explicitly** - say "spawn N agents in parallel", name the split. 4.8 will not infer it.
- **Manual parallel fan-out caps at ~5 agents.** Beyond that, coordination overhead wins - use a Workflow instead.
- **Workflow is opt-in.** Only reach for it when the running phase prompt includes `ultracode` (or the user asked for a workflow). For batch-heavy phases, the starter prompt should TELL the runner to add `ultracode` and orchestrate via a Workflow.
- **Shared working tree.** A concurrent session may share this exact checkout. Commit sequentially with EXPLICIT paths, never `git add -A`; often the right move is to commit nothing that is not yours. (See memory: shared-worktree-commit-care.)

---

## Opus 4.8 Prompting Discipline (apply to EVERY prompt this skill emits)

1. **State scope literally and exhaustively.** 4.8 follows instructions literally and will NOT generalize from one example. Write "all three hosts", "every new player string", "each of the nine classes" - never "the sections" or "the files".
2. **Reserve ALL-CAPS / NON-NEGOTIABLE for genuine determinism, server-authority, security, and data-integrity gates.** If everything is emphasized, nothing is. Routine conventions read fine in plain voice.
3. **For review/QA agents, the finding stage is COVERAGE, not filtering.** 4.8 honors "be conservative / don't nitpick" literally and reports fewer real issues. Always prompt: "report every issue including low-severity and uncertain ones; ranking happens in a later step."
4. **Review agents truncate mid-analysis.** Budget 2-3 SendMessage rounds; resume with: *"Stop reading more files. Output the full report now based on what you've already seen. No more tool calls. Format: BLOCKING / SHOULD-FIX / NICE-TO-HAVE / VERDICT."*
5. **Demand structured handoffs.** A phase ends by writing its state to `progress.md` / `state.md` and (for big packets) a per-phase resume file - that IS the cross-session memory. The next session reads the summary, not the transcript.

---

## Context Discipline (how each phase stays cheap)

- The orchestrator (main loop) does **not** read large docs or sprawl across source files. It spawns an Explore agent that returns a focused summary. (The coordinator monoliths `src/ui/hud.ts`, `src/sim/sim.ts`, and `src/main.ts` are huge, and the big i18n surface is `src/ui/i18n.catalog/*` plus the generated overlays; never read these whole in the main loop.)
- Give each implementation agent ONLY the slice of context it needs (the Explore summary + its own files), never the raw planning docs.
- Delegate web/doc lookups to a subagent (classic-era MMO formula references, a Three.js or GLB asset technique, the `pg` Postgres driver, Cloudflare Turnstile, any third-party surface); keep raw docs out of the main context.
- For 12+ phase packets, use per-phase resume files so a fresh session resumes from a checkpoint, not from scratch.
- Use ToolSearch to pull in deferred tool schemas only when a phase actually needs them.

---

## Step 1: Understand the Feature

If the user did not provide a feature description inline, ask them to describe what they want to build. Get enough detail to understand scope, but do not over-interrogate.

## Step 2: Explore the Codebase + Research the External Surface (parallel agents)

Spawn these in parallel in a single message. Do NOT read these files yourself - save your context window. Each returns a summary, not raw dumps.

### Codebase Explore agents (`subagent_type: "Explore"`)
Adapt the split to the feature (a content-only feature needs the sim/content explorer, not the net explorer; add a `headless-explorer` for RL-env work):

**`sim-explorer`** - `src/sim/` core: tick loop, combat/abilities/threat, mob AI, parties/duels/arena/trade/market/dungeons, the RL observation surface, `Rng` usage, and overlapping content in `src/sim/content/` (classes, abilities, zones, dungeons, items, talents). Note relevant test patterns in `tests/`.

**`server-explorer`** - `server/`: `GameServer` loop and command dispatch (`server/game.ts`), interest-scoped snapshots (`wireEntity`/`selfWireJson`), Postgres persistence and the inline `SCHEMA` (`server/db.ts`) + `SOCIAL_SCHEMA` (`server/social_db.ts`), auth (`server/auth.ts`), social/moderation, rate limiting.

**`client-explorer`** - `src/render/` (Three.js renderer; reads world, never mutates), `src/ui/` (HUD, windows, tooltips, map, FCT, i18n), and `src/game/` (input, camera, keybinds, mobile/touch controls). Note which `IWorld` members the feature will read or call.

**`net-explorer`** - `src/net/` (`ClientWorld implements IWorld`, REST auth, WS mirror) and the wire-protocol lockstep with `server/game.ts` (`applySnapshot`/`applyWire`, `SimEvent` handling). Use when the feature changes anything that crosses the network.

**`admin-explorer`** - `src/admin/` (the separate admin dashboard SPA, its own `admin.html` entry and `admin/api`) and its dedicated i18n catalog `src/admin/i18n.ts`. Use when the feature has an admin, moderation, or operator surface. Operators are users, so admin strings localize too.

(Add **`headless-explorer`** for `headless/` + `python/` RL-env work. One focused agent per surface, up to the ~5-agent cap.)

### Web-research agent (REQUIRED when the feature touches any third-party surface)
If the feature involves a third-party API, SDK, library, framework, cloud service, or a real classic-era MMO formula you need to get exactly right, spawn a web-research agent (`general-purpose`, or `claude-code-guide` for Claude tooling; both have WebSearch/WebFetch). Instruct it to pull **current, primary-source** data (prefer official docs over blogs), since APIs and references drift. Ask for: exact endpoints/auth/schemas (for an API), the canonical formula/constants (for balance math), version/migration notes, and licensing for any asset. It must return a tight brief with citations and **mark anything unverifiable as OPEN** rather than guessing. Fold OPEN items into the plan as blockers, never as assumptions. (Gameplay math must follow real classic-era formulas; do not invent balance numbers.)

For sweeping research (many sources cross-checked), the running session can use an `ultracode` Workflow (multi-modal sweep + adversarial-verify) instead of a single agent.

## Step 3: Brainstorm with the User

Present findings from the Explore + research agents (summarized, not raw) and brainstorm:
- What systems/content already exist vs what is new
- What `IWorld` surface exists vs what needs adding
- Creative ideas that leverage existing infrastructure (the sim already has parties, duels, arena, trade, market, dungeons, talents, pets)
- What would make this feature stand out while staying classic-faithful
- Any OPEN items from research that need a human/credential/design decision before phasing

Get user buy-in on the overall vision before planning phases.

## Step 4: Create Planning Documents

Create `docs/{feature-name}/` with these files:

- `README.md` - packet entry point and index, links to every phase file plus the cross-cutting docs.
- `brainstorm.md` - feature vision, approved ideas, current state summary, reusable systems/`IWorld` members, new work needed, research findings + OPEN items.
- `implementation-plan.md` - TOC + canonical workflow + phase summary table.
- `progress.md` - status table + per-phase deliverables/acceptance checklists.
- `state.md` - cross-phase cheat sheet (locked decisions, validation matrix, file paths, new `IWorld` methods / `SimEvent`s / wire fields / endpoints / tables / i18n keys).
- `qa-checklist.md` - whole-feature integration QA matrix (three-host parity, determinism, i18n completeness, classic fidelity, persistence, performance, deploy verification).

**For packets with 12+ phases (or when each phase is non-trivial), prefer per-phase resume files** instead of inlining everything into `implementation-plan.md`:
- `phase-XX-{slug}.md` - implementation prompt for phase XX (self-contained; a fresh-context Claude can paste it into a new session and execute without referring back to the TOC).
- `phase-XX-qa.md` - QA prompt for phase XX.
- `implementation-plan.md` then becomes a TOC + canonical workflow + summary table that references the per-phase files.

### README.md
The packet entry point: a one-paragraph feature summary, an index linking every phase and QA file in order, and links to the cross-cutting docs (`brainstorm.md`, `implementation-plan.md`, `progress.md`, `state.md`, `qa-checklist.md`). A newcomer should be able to orient from here alone.

### brainstorm.md
- Feature vision and approved ideas
- Current state summary
- Existing systems / `IWorld` members / content tables that can be reused
- New work needed (sim / server / net / render / ui / headless)
- Web-research findings (with citations) and OPEN items
- Open questions for design decisions

### implementation-plan.md
Split the feature into phases. Each implementation phase is followed by a dedicated QA phase. Both are separate Claude Code sessions. The numbering is: Phase 1 (implement), Phase 1 QA (verify), Phase 2 (implement), Phase 2 QA (verify), etc.

**Phase sizing (critical):**
Prefer many small phases over fewer large ones. A phase that tries to do too much burns context, produces sloppier output, and misses details. Each implementation phase should be completable in a single focused session without exhausting the context window. Rules of thumb:
- One phase = one logical slice (e.g., "add the ability to the sim + content data + tests" or "wire the HUD window to the new `IWorld` members"). If you find yourself writing "and also..." in the phase description, split it.
- 2-4 deliverables per phase is ideal. More than 5 is a sign the phase is too big.
- When in doubt, split. Two small phases with QA passes will always produce better work than one large phase that rushes through.

**Phase ordering principles:**
1. Phase 1 is always architecture/foundation: extend `IWorld` and the sim data model, establish the pattern all later phases follow.
2. Phase 1 QA verifies Phase 1.
3. Next phases implement sim behavior server-side and mirror it in `ClientWorld` (keep the offline and online worlds in lockstep as you go, not at the end).
4. Then phases that add server persistence (extend the `SCHEMA` DDL, save/load round-trip, back-compat for existing JSONB saves).
5. Then renderer/HUD/i18n surface, then polish/optimization last.
6. Every implementation phase gets a QA phase immediately after it.
7. The final QA phase closes the packet: once it passes, it offers **Packet teardown** (below), deleting `docs/{feature-name}/` only on explicit user confirmation so the PR does not ship the planning scaffolding.

**Team Workflow section (include at top of plan):**
Every phase runs on **Opus 4.8 at xhigh effort** (1m context variant where the file load demands it; `ultracode` for batch-heavy phases). Include this standard workflow:
1. **Step 0 - Pre-flight**: Verify `git status` is clean (and that no concurrent session is mid-change in your files). Scan your Claude Code memory (the `MEMORY.md` index and any entries matching the phase domain), if you use it.
2. **Step 1 - Load Context**: Spawn an Explore agent to read planning docs and relevant source files. The main agent does NOT read large docs directly. The Explore agent returns a focused summary.
3. **Step 2 - Choose Orchestration + Execute**: Pick the lightest tool from the Orchestration Toolbox. Default: parallel Agent fan-out, one agent per vertical slice (give each ONLY the Explore summary, not raw planning docs). For batch-heavy/audit/content-sweep phases, run an `ultracode` Workflow (pipeline + adversarial-verify) instead. Use `isolation: "worktree"` only when agents mutate overlapping files in parallel.
4. **Step 3 - Validation + Multi-Agent Review Dispatch**:
   - Run validation (see the matrix in `state.md`): `npx tsc --noEmit`; `npx vitest run tests/<affected>.ts` (or `npm test` for broad changes). If `src/sim/` changed, run `npx vitest run tests/architecture.test.ts` (the sim-purity guard: no render/ui/game/net/three imports, no DOM globals, no nondeterminism). If any player-visible text was added or an emit changed, run `npx vitest run tests/localization_fixes.test.ts` (the S3 i18n drift guard). If the wire protocol / snapshots changed, run `npx vitest run tests/snapshots.test.ts tests/env_protocol.test.ts tests/bandwidth.test.ts`. If assets changed, `npm run asset:budget`. Before a big merge, run `npm run gate` (the CI-equivalent gate: i18n gen + freshness, malware scan, changed-files biome, sfx check, full tests with bounded workers, typecheck, all builds; release-tier automatically on a `release/**` branch). Never an ad-hoc `&&` chain: piping `npm test` masks its exit code and an unbounded run flakes heavy suites.
   - Spawn review agents using the **Review Dispatch Matrix** below. Spawn ONLY the agents
     whose surface this change actually touches. Most phases trigger one or two, not all
     of them; a docs/test-only change triggers none. (Each agent also self-gates and exits
     cheaply if mis-dispatched, but spawning an out-of-scope agent still costs tokens, so
     gate at dispatch too.)
   - Prompt every review agent you DO spawn for COVERAGE not filtering ("report every issue including low-severity and uncertain ones"). Do not commit until each reports no BLOCKING issues. Resume any agent that truncates with: *"Stop reading more files. Output the full report now based on what you've already seen. No more tool calls. Format: BLOCKING / SHOULD-FIX / NICE-TO-HAVE / VERDICT."*

#### Review Dispatch Matrix (single source of truth: copy this table into the generated `implementation-plan.md`; starter prompts reference it, never inline a copy)

Match the change surface to the agent. Spawn an agent ONLY when its row matches the diff:

| Agent | Spawn ONLY when the diff touches | Skip it for |
|-------|----------------------------------|-------------|
| `privacy-security-review` | `server/`, `src/admin/`, `src/net/`, a deploy/secret file (Docker/compose/env/CI yml/`DEPLOY.md`), OR introduces SQL / auth / a secret / `ALLOW_DEV_COMMANDS` / a new `Math.random`\|`Date.now`\|`performance.now` in `src/sim/` | a pure `src/ui` / `src/render` / `src/game` / `src/sim/content` / docs / test change |
| `migration-safety` | `server/db.ts`, `server/social_db.ts`, a `server/*_db.ts`, or a `characters.state` JSONB serialize/deserialize path | any diff with no DDL and no persisted-state shape change |
| `database-performance-reviewer` | SQL or a database call site, schema/indexes, query cadence or cardinality, pool/lock/timeout behavior, scheduled database work, a database driver or Postgres engine/config change, or stored-data growth | any diff that cannot change database work or growth |
| `cross-platform-sync` | `src/world_api.ts` or `src/world_api/**` (the IWorld facets), `src/sim/` behavior/obs/`SimEvent`, `src/net/online.ts`, `server/game.ts` wire/dispatch, the matchers `src/ui/sim_i18n.ts`\|`src/ui/server_i18n.ts`, or the RL surface (`headless/`, `python/`) | a pure i18n *catalog* refactor (only `src/ui/i18n.ts` + locale data, `t()` keys unchanged) - `tsc` (`: typeof en`) + the resolved-equivalence test already cover it |
| `architecture-reviewer` | a `src/sim/` change: determinism, rng draw-order, tick-phase order, the `SimContext` seam, or a move-not-rewrite relocation | a non-sim change, or a pure data/content/test change |
| `frontend-seam-reviewer` | `src/ui/`, `src/render/`, `src/game/`, or `src/styles/` (the view-core + `PainterHost` painter seams, graphics-settings fairness, mobile/touch surfaces) | a diff with no frontend surface |
| `qa-checklist` | a phase / deliverable set is COMPLETE (it self-scales via its per-category Skip rules) | per-commit / mid-phase work, or a docs/test-only change |

If NO row matches (e.g. a docs-only, test-only, or comment change), spawn NO review agent.
Do not default to "run `privacy-security-review` anyway."
5. **Step 4 - Update Docs + Memory**: Update `progress.md` (mark phase complete; note deferrals) and `state.md` (new `IWorld` members, `SimEvent`s, wire fields, endpoints, tables, i18n keys, locked decisions). If you use Claude Code memory, record any surprising rules learned or current-state notes there for the next session. Commit doc updates in the same logical commit as the implementation (EXPLICIT paths).

**Agent Scaling Guidelines (include in Team Workflow):**
The starter prompts suggest a default split (sim + server + client + tests), but the orchestrator MUST assess the actual workload and scale accordingly:
- **Split large sim work across multiple agents** when a single agent would handle 4+ independent concerns (e.g., a new ability system + threat changes + content tables + RL obs surface). Signs a split is needed: the deliverable list has 10+ items, the work spans 4+ modules, or the concerns are independent.
- **Merge small work into a single agent** when one side has only 1-2 trivial changes (e.g., adding one `IWorld` getter, adding one i18n key). Do not spawn a dedicated agent for work that takes five minutes.
- **Split large client work** when a phase adds 3+ HUD windows plus renderer changes plus input wiring. One agent for HUD/i18n, one for renderer, one for input/camera/mobile.
- **Use dedicated test agents** when a phase has complex test requirements across multiple suites. A test agent can run in parallel after implementation agents commit their code.
- **Escalate to a Workflow past the manual cap.** Hand-orchestrated parallel fan-out tops out at ~5 agents. When a phase has 10+ independent, uniform tasks (e.g., add a new field to every zone's mob table, register 30 new English i18n keys across the catalog domains, transform many content entries), do not hand-spawn - write an `ultracode` Workflow that pipelines them with structured outputs and verifies each.
- **Each agent should own complete vertical slices** - do not split by file type (one for types, another for tests). Split by domain (one for the sim behavior + its tests, another for the HUD surface + its tests). Each agent writes its own tests for the code it creates.

**Code Hygiene section (include in Team Workflow):**
Every phase must enforce:
- **Module-first**: new self-contained behavior goes in its own focused module behind an existing seam (`IWorld`, a `src/sim/content/` record, a `src/render/<thing>.ts`), not appended to a monolith (`sim.ts`, `hud.ts`, `renderer.ts`). Do not split a monolith for line count. Fix bugs test-first. See the `extract-and-test` skill and the root Modularity section.
- **New code gets tests**: Every new ability, system, command, `IWorld` member, server endpoint, query, and behavior gets unit tests. Sim: combat math, abilities, AI, economy. Server: command dispatch, persistence, snapshots. Net: wire round-trip. UI: data transforms, frame logic. E2E (`scripts/*.mjs`): user flows where applicable. If you wrote it, test it.
- **Determinism tests**: For sim changes, assert same-seed-same-result; never introduce `Math.random` / `Date.now` / `performance.now` into `src/sim/`.
- **Test maintenance**: Update/remove tests when modifying existing code. When placeholder content is replaced with real content, update the tests. Never leave orphaned or broken tests.
- **Dead code removal**: Delete fully replaced abilities, systems, components, helpers, and types. No commented-out code, unused imports, or deprecated functions.
- **Import cleanup**: Zero unused imports. And uphold the import invariant: `src/sim/` imports nothing from `render/`, `ui/`, `game/`, `net/`, and has no DOM/Three.js imports.
- **Type cleanup**: Remove unreferenced interfaces/types. Consolidate evolved types, do not accumulate.
- **No generated-file hand-edits**: Never hand-edit generated output (e.g. `src/render/assets/manifest.generated.ts` or the media manifest emitted by `npm run build`); regenerate via the build instead.

**Every phase starter prompt must follow this structure:**
````
### Starter Prompt
```
This is Phase N of the {Feature Name} feature: {Phase Title}.

Model: Opus 4.8, xhigh effort (reserve max for genuinely frontier problems), 1m context variant where the file load demands it.
Harness: Claude Code.
ULTRACODE: add the keyword `ultracode` to this prompt if this phase is batch-heavy
(content sweeps across many tables, bulk i18n catalog additions, exhaustive audit) so you
orchestrate via a Workflow (pipeline + adversarial-verify) instead of hand-spawning agents.

Goal: {one sentence}

STEP 0 - PRE-FLIGHT:
- Verify `git status` is clean before starting. If not, ask the user (a concurrent
  session may share this checkout).
- Memory scan (if you use Claude Code memory): check your `MEMORY.md` index and any
  entries relevant to this phase's domain (suggested topics: {phase-specific patterns}).

STEP 1 - LOAD CONTEXT (do NOT read planning docs directly, save your context):
Spawn an Explore agent to read and summarize:
- docs/{feature-name}/state.md (locked decisions, validation matrix, file paths)
- docs/{feature-name}/progress.md (Phase N status + deliverable checklist)
- docs/{feature-name}/phase-N-{slug}.md (this prompt) - verify the agent has the same understanding
- {relevant source files for this phase, listed individually}
- CLAUDE.md (root) + the relevant sub-CLAUDE.md files
  ({e.g. src/sim/CLAUDE.md, server/CLAUDE.md, src/ui/CLAUDE.md, src/net/CLAUDE.md})
The agent should return: {specific info this phase needs}.
{If this phase integrates a third-party API/SDK or needs an exact classic-era formula:
also spawn a web-research agent for current primary-source docs/constants; mark
unverifiable facts OPEN rather than guessing.}

STEP 2 - CHOOSE ORCHESTRATION + EXECUTE:
Pick the lightest tool that fits (Explore for recon, then parallel Agent fan-out for
independent slices, then Workflow for batch/scale). Request fan-out EXPLICITLY (Opus 4.8
will not self-initiate it). Give each agent ONLY the Explore summary, not raw planning
docs. Never `mode: "plan"` on teammates. Use `isolation: "worktree"` only if agents edit
overlapping files in parallel.

{Agent A} deliverables:
- {bullet}
- {bullet}

{Agent B} deliverables:
- {bullet}
- {bullet}

INVARIANTS THIS PHASE MUST KEEP (call out the ones in play):
- Determinism: all randomness via `Rng`; no `Math.random` / `Date.now` / `performance.now` in `src/sim/`.
- Seam: extend `IWorld` first, then implement in BOTH `Sim` and `ClientWorld`.
- Server authority: the client never decides combat/loot/quest/economy outcomes.
- i18n: every new player string is a `t()` key added in ENGLISH ONLY to the matching
  `src/ui/i18n.catalog/<domain>.ts` module (never edit the locale overlays; M16: a wordy
  new English value also needs its five non-Latin fills in the same change); sim/server
  player text gets a matcher rule in `src/ui/sim_i18n.ts` / `src/ui/server_i18n.ts` in
  the SAME change.
- Classic-era formulas only; do not invent balance numbers.

Out of scope (do NOT do in this phase):
- {explicit exclusions to prevent scope creep}

STEP 3 - VALIDATION + MULTI-AGENT REVIEW:
- Run: {phase-specific validation commands referencing the state.md matrix}
  (baseline: `npx tsc --noEmit` + `npx vitest run tests/<affected>.ts`; add
  `npx vitest run tests/localization_fixes.test.ts` if any player text changed; add the
  wire/snapshot suites if the protocol changed).
- Spawn review agents in parallel per the Review Dispatch Matrix in
  docs/{feature-name}/implementation-plan.md (the plan carries the one canonical copy).
  Check `git diff --name-only` against the phase-start commit and spawn ONLY the agents
  whose row matches; most phases trigger one or two, and if no row matches, spawn none.
- Prompt each agent you spawn for COVERAGE not filtering. Resume any that truncates with the
  "Stop reading. Output verdict now." message.
- Do not commit until each reports no BLOCKING issues.

STEP 4 - COMMIT CADENCE:
Aim for {2-5} commits with these headlines (Conventional Commits with a scope, e.g.
`feat(sim): ...`, `fix(net): ...`; EXPLICIT paths, never `git add -A`; no em dashes/emojis):
- {commit 1 headline}
- {commit 2 headline}
- ...

STEP 5 - ACCEPTANCE CRITERIA (verifiable checklist; do not mark complete until all check):
- [ ] {acceptance item}
- [ ] {acceptance item}
- ...

STEP 6 - DOC UPDATES + MEMORY:
- Update docs/{feature-name}/progress.md (mark Phase N status; note deferrals).
- Update docs/{feature-name}/state.md (new IWorld members, SimEvents, wire fields,
  endpoints, tables, i18n keys; locked decisions).
- If you use Claude Code memory, record any surprising rules or current-state notes for
  the next session.

STEP 7 - FINAL RESPONSE FORMAT:
End your turn with: phase status, files touched, validation results, review-agent verdicts,
any deferred items, and a one-line handoff for the QA session.

STOPPING RULES:
- {explicit stop conditions: "stop if determinism cannot be preserved", "stop and ask if
  Y changes the wire protocol in a backwards-incompatible way", etc.}
```
````

**Every QA phase starter prompt must follow this structure:**
````
### QA Starter Prompt
```
This is Phase N QA of the {Feature Name} feature: Verify {Phase Title}.

Model: Opus 4.8, xhigh effort (reserve max for genuinely frontier problems), 1m context variant where the file load demands it.
Harness: Claude Code.
ULTRACODE: for a large or high-risk phase, add `ultracode` so you can run an
adversarial-verify Workflow (each finding independently confirmed by a skeptic agent
before it counts).

Goal: Audit Phase N implementation for correctness, missing tests, dead code, determinism,
three-host parity, and i18n completeness.

STEP 0 - PRE-FLIGHT:
- Verify `git status` is clean (Phase N implementation should already be committed). If dirty, ask the user.
- Memory scan (if you use Claude Code memory): check entries from the Phase N domain.

STEP 1 - LOAD CONTEXT (do NOT read planning docs directly, save your context):
Spawn an Explore agent to read and summarize:
- docs/{feature-name}/state.md (new IWorld members, SimEvents, wire fields, endpoints, tables from Phase N)
- docs/{feature-name}/progress.md (Phase N deliverables checklist + acceptance criteria)
- docs/{feature-name}/phase-N-{slug}.md (the implementation prompt - what was promised)
- All files created or modified in Phase N (use `git diff` against the phase start commit)
- CLAUDE.md (root) and relevant sub-CLAUDE.md files
The agent should return: full list of Phase N deliverables, all new/modified files, and any known issues.

STEP 2 - QA AUDIT (spawn parallel review agents using the Explore summary; prompt each for COVERAGE not filtering):

Correctness agent:
- Verify every deliverable from Phase N was actually implemented
- Verify every acceptance criterion in the phase prompt is met
- Check for logic bugs, off-by-one errors, missing error handling
- Verify classic-era formulas match the cited references; no invented constants
- Verify the offline `Sim` path and the online `ClientWorld` path behave identically
- Test edge cases: empty states, error states, boundary values, concurrent access
- Run the affected tests and (where useful) an E2E script (`scripts/*.mjs`) and verify behavior matches intent

Test coverage agent:
- Identify new code paths without tests
- Add missing unit tests for new sim behavior, commands, IWorld members, endpoints, queries
- Add a determinism test (same seed, same result) for new sim logic
- Update existing tests broken by Phase N changes
- Remove orphaned tests for deleted/replaced code
- Verify test assertions are meaningful (not just "it runs")

Dead code & cleanup agent:
- Find unused imports, functions, types, components left behind
- Verify the import invariant holds (`src/sim/` imports nothing from render/ui/game/net; no DOM/Three)
- Remove commented-out code
- Consolidate duplicate or near-duplicate logic
- Verify no TODO/FIXME items were left unresolved
- Check for inconsistent naming or patterns vs the rest of the codebase

Multi-agent review dispatch: apply the Review Dispatch Matrix in
docs/{feature-name}/implementation-plan.md (the plan carries the one canonical copy).
Check `git diff --name-only` against the phase-start commit and spawn ONLY the agents
whose row matches, plus `qa-checklist` (this is the phase-completion QA gate).
Resume any review agent that truncates mid-analysis with: *"Stop reading more files. Output the full report now. No more tool calls. Format: BLOCKING / SHOULD-FIX / NICE-TO-HAVE / VERDICT."*

STEP 3 - FIX: Apply all BLOCKING and SHOULD-FIX items. Run the full validation matrix from state.md
(at minimum `npx tsc --noEmit` and the relevant vitest files; the S3 i18n guard if player text changed).
Commit fixes (separate commits from the QA verdicts themselves so the history is reviewable; EXPLICIT paths).

STEP 4 - UPDATE DOCS + MEMORY:
- Update docs/{feature-name}/progress.md (mark Phase N QA complete; note any items deferred to follow-up).
- Update docs/{feature-name}/state.md (any drift discovered during QA).
- If you use Claude Code memory, record any surprising rules learned during QA.

STEP 5 - PACKET TEARDOWN (final phase only; skip entirely otherwise):
If this is the LAST phase in the packet and everything is complete and green, ask the user
for explicit confirmation to delete the planning scaffolding before the PR, e.g.:
"All phases are complete and green. OK to delete docs/{feature-name}/ before the PR?"
- Surface any deferred follow-ups first so nothing tracked only in the packet is lost.
- On confirmation, delete ONLY that directory with an explicit path: `git rm -r
  docs/{feature-name}/` (if it was committed) then commit
  `docs: remove {feature-name} planning scaffolding`, or `rm -rf docs/{feature-name}/`
  (if it was never committed).
- If the user declines, leave it in place. Never delete anything outside that directory and
  never `git add -A`.

STEP 6 - FINAL RESPONSE FORMAT:
End your turn with: QA verdict (PASS / PASS-WITH-FOLLOWUPS / FAIL), counts of
BLOCKING/SHOULD-FIX/NICE-TO-HAVE found and fixed, deferred items, whether the planning
packet was removed, and a one-line handoff for the next implementation phase (or
"packet complete" if this was the final phase).

STOPPING RULES:
- Stop and surface to the user if any BLOCKING item cannot be fixed without changing the phase scope.
```
````

**Every phase that changes server persistence MUST also:**
- Extend the DDL additively: edit `server/db.ts` `SCHEMA` (or `server/social_db.ts` `SOCIAL_SCHEMA`) using `CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` so existing realms upgrade in place under the boot advisory lock. There is no migrations directory; the inline DDL is the schema.
- Guarantee back-compat for existing JSONB character state: loading a character saved before this change must not throw or lose data (default any missing fields).
- Add appropriate indexes for any new query predicate.
- Add a persistence round-trip test under `tests/` (save then load, assert equality).

**Mobile in every client phase (the game ships touch controls):**
- Any HUD/input change must work with the touch controls in `src/game/` and respect mobile safe areas.
- Verify with the mobile screenshot scripts (e.g. `node scripts/mobile_visual.mjs`, the `mobile_*_shot.mjs` family) against a phone viewport with `npm run dev` running.
- Keep tap targets comfortable; do not rely on hover for essential info.

**Performance in every phase (the sim is a fixed 20 Hz budget):**
- Sim work per tick must stay within the 20 Hz frame budget; avoid per-tick allocations in hot paths.
- Keep snapshots interest-scoped and delta-guarded; do not send unchanged heavy fields (see the interest radius and `wireEntity` / `selfWireJson` in `server/game.ts`).
- The renderer reads the world and never mutates it; keep draw-call and texture budgets in check (`npm run asset:budget`, `npm run perf:tour`).
- Keep the dependency set tiny; do not add packages without a clear need.

**Deploy gates (any phase that ships server or client changes to production):**
- Production runs in Docker (see `DEPLOY.md`). Standalone update path: ssh to the host, `cd /opt/eastbrook`, `sudo git pull`, `sudo docker compose up -d --build`. Players are saved on shutdown and briefly disconnect.
- Health check after deploy: `curl -s localhost:8787/api/status` returns `{"ok":true,"players_online":N,...}`.
- Before any deploy, the CI-equivalent gate must be green locally: `npm run gate` (mirrors `.github/workflows/ci.yml`: i18n gen + freshness, malware scan, changed-files biome, sfx check, full tests, typecheck, all builds; release-tier on `release/**`).
- Never set `ALLOW_DEV_COMMANDS=1` in production (it enables level/teleport/item cheats).
- Most phases do not deploy; deploys are manual and infrequent. Treat deploy as a deliberate, separate step, not part of every phase.

**Packet teardown (final phase only):**
The planning packet in `docs/{feature-name}/` is cross-session scaffolding, not a shipping artifact. The final QA phase, once every phase is complete and the build / CI-equivalent gate is green, MUST offer to remove it before a PR is opened:
- Ask the user explicitly, in plain language, for example: "All phases are complete and green. OK to delete `docs/{feature-name}/` (the planning scaffolding) before the PR?" Do not delete on assumption.
- Surface any deferred follow-up items FIRST, so nothing tracked only inside the packet is lost when it goes.
- Delete ONLY on explicit confirmation, and ONLY that one directory, with an explicit path:
  - If the docs were committed during the packet: `git rm -r docs/{feature-name}/`, then commit `docs: remove {feature-name} planning scaffolding`.
  - If they were never committed: `rm -rf docs/{feature-name}/`.
- If the user declines or wants to keep them, leave the directory in place and say so; delete nothing.
- Never delete anything outside `docs/{feature-name}/`, never fold the deletion into an unrelated commit, and never `git add -A` (a concurrent session may share this checkout).

### progress.md
- Overall status table (phase | status | date started | date completed) - includes both implementation and QA phases (e.g., "Phase 1", "Phase 1 QA", "Phase 2", "Phase 2 QA")
- Per-phase checklist matching deliverables from implementation-plan.md
- Per-QA-phase checklist (fixes applied, tests added, dead code removed)
- Notes section per phase (filled in after completion)

### state.md
Cross-phase cheat sheet. Contains ONLY what the next session needs:
- Current phase number + status
- Locked design decisions (record once, reference forever)
- Non-negotiable constraints (determinism, server authority, `IWorld`-first, English-only i18n catalog keys, no generated-file edits, shared-worktree commit care)
- Validation matrix by change type:
  - **sim-only**: `npx tsc --noEmit` + `npx vitest run tests/sim.test.ts` (and the relevant command suites); determinism check.
  - **content-only**: `npx tsc --noEmit` + `npx vitest run tests/progression.test.ts tests/talents.test.ts` (referential integrity); i18n if new names.
  - **server-only**: relevant server suites + `npx tsc --noEmit` + `npm run build:server`.
  - **net/wire**: `npx vitest run tests/snapshots.test.ts tests/env_protocol.test.ts tests/bandwidth.test.ts` + parity check.
  - **ui/render**: `npx tsc --noEmit` + `npx vitest run tests/localization_fixes.test.ts` (if text) + a mobile screenshot script.
  - **headless/RL**: `npm run build:env` + `npx vitest run tests/env_protocol.test.ts` + a short `npm run bench`.
  - **full-stack / pre-merge**: `npm run gate` (the CI-equivalent gate; release-tier on `release/**`).
  - **any code change (Biome / CI ratchet)**: `npm run ci:changed` (Biome on the files you changed, what the `.githooks/pre-push` floor runs). Fix formatting with a SCOPED `npx @biomejs/biome check --write <file>`, never a whole-tree `--write`.
- Key file paths (existing + created by this feature)
- New files created per phase
- New `IWorld` members added per phase
- New `SimEvent`s and wire/snapshot fields added per phase
- API endpoints created per phase
- Database tables/columns added per phase (in the inline `SCHEMA`)
- New i18n keys + matcher rules added per phase
- Architecture decisions (locked once made)
- OPEN research items + known issues / gotchas

### qa-checklist.md
Whole-feature integration matrix verified once at packet completion:
- **Three-host parity**: the offline browser `Sim`, the online `ClientWorld`, and the headless env behave consistently for this feature.
- **Determinism**: same seed gives the same world; no `Math.random` / `Date.now` / `performance.now` in `src/sim/`; determinism tests pass.
- **i18n completeness**: every new player-visible string is a `t()` key in the English catalog (`src/ui/i18n.catalog/`), rendered via `t()`, with the locale overlays untouched (release-tier fills them; M16 wordy strings carry their five non-Latin fills); sim/server emits have matcher rules in `sim_i18n.ts` / `server_i18n.ts`; `npx tsc --noEmit` and `npx vitest run tests/localization_fixes.test.ts` (S3 guard) are green; numbers/money/dates go through `formatNumber` / `formatMoney` / `formatDateTime`.
- **Classic-era fidelity**: formulas match the cited references; no invented balance numbers.
- **Server authority**: no client-trusted outcomes; WS commands validated server-side.
- **Persistence**: characters saved before this feature still load; save/load round-trip verified; DDL changes are additive and idempotent.
- **Performance / budgets**: snapshot bandwidth sane; `npm run asset:budget` and `npm run perf:tour` within budget.
- **Copy review**: no em dashes or emojis in player-facing text (raw emojis as in-game icons are also disallowed by the aesthetic rule).
- **Build gate**: `npm run gate` is green (the CI-equivalent gate; release-tier on `release/**`).
- **Deploy verification** (only if deployed): `curl -s localhost:8787/api/status` returns ok with the expected build.

## Step 5: Commit

Stage and commit all planning docs (EXPLICIT paths, Conventional Commit, short message, no em dashes/emojis):
```
docs: add {feature-name} phased implementation plan
```

Present a summary to the user:
- Number of phases (implementation + QA)
- What each phase covers (one line each, showing the implement/QA pairs)
- How to start Phase 1 (copy the starter prompt from `phase-01-{slug}.md` or the implementation-plan.md Phase 1 section)
- Locked design decisions captured in state.md
- OPEN research items still needing a human/credential/design answer
- Cross-cutting workflow blocks the user can edit centrally (memory scan, orchestration choice, multi-agent dispatch, validation matrix, deploy gate)
- That the final QA phase will offer **packet teardown** (delete `docs/{feature-name}/`) before the PR, on your explicit confirmation, so the planning scaffolding does not ship

---

Source: https://www.openparable.com/skill/productivity/feature-plan (OpenParable). Cite the canonical URL above.
