Gm Build

---
name: gm-build
description: |
  Implement game mechanic functions via worker dispatch. Covers risk-first then main implementation.
  Dispatches workers until PLAN is clean, then runs one verify+review pass; loops until convergence.
  Explicit invocation only — use /gm-build.
disable-model-invocation: true
---

# GodotMaker Build

$ARGUMENTS

You are implementing a Godot game by dispatching Worker subagents. Risk tasks first, then main tasks — both surfaced from PLAN.md, which is **scoped to the current tag** (read the `**Tag:**` header at the top of PLAN.md). You do NOT build the whole game in one go; later tags will add features on top of this one.

## Session Setup

**FIRST ACTION — before anything else:** Write `build` to `.godotmaker/current_role`.

## Resume Check

Read `.godotmaker/stage.jsonl` (treat as empty if missing) — each line is `{"role": X, "ts": Y}`.

- If `project.godot` does not exist → STOP. Tell user to run `/gm-scaffold` first.
- If `ROADMAP.md` does not exist → STOP. Tell user to run `/gm-gdd` first.
- If **no event with `role == "gdd"`** exists anywhere in the file → STOP. Tell user to run `/gm-gdd` first.
- If `PLAN.md` is missing the `**Tag:**` header → STOP. Tell user the file is stale and to re-run `/gm-gdd` to regenerate it for the current tag.

Read `.godotmaker/verify_report.json` if it exists.

Define **pending verify feedback** as:
- `.godotmaker/verify_report.json` exists.
- Its top-level `result` is `"fail"`.
- Its `ts` is later than the latest `role == "build"` event in `stage.jsonl`, or there is no prior build event.

Apply the resume gates in this order:

- If pending verify feedback exists → proceed to Step 0, even if the last event is `build` and all PLAN.md tasks are already `verified`.
- If the **last event** has `role == "build"` AND all PLAN.md tasks are `verified` → STOP. Tell the user:
  > "Build already completed for the current tag at {timestamp}. Recommended next: /gm-verify.
  > If you need to redo this step or have other plans, just tell me."
- Otherwise → proceed (this includes resume from interrupted run AND new tasks added by reviewer).

Then read context:
- `PLAN.md` → current tag's `**Tag:**` header + Tag Mechanics + Inherited Mechanics + Playable Unit + pending/in_progress/completed tasks (anything not `verified`)
- `STRUCTURE.md` → architecture and build order (current tag scope: previous tags' systems already exist on disk and may be touched only when PLAN.md explicitly lists a refactor task for them)
- `ASSETS.md` → the generated-runtime authority; for a visual task, derive each asset with `tools/asset_result_registration.py --snapshot`
- `MEMORY.md` index + sub-files → stable architecture decisions and project constraints
- `docs/tags/<prev_tag>/STRUCTURE.md` (only if PLAN.md has Inherited Mechanics or refactor tasks touching prior systems) → know what already exists before adding/refactoring. Read `docs/tags/<prev_tag>/SUMMARY.md` first — it is one screen and often answers the question without opening the full archive; `docs/tags/README.md` lists every sealed tag if you are not sure which one to open.

## Hard Rules

### Asset Runtime Authority

`ASSETS.md` is the sole runtime-asset authority. For a visual task,
derive the snapshot with `tools/asset_result_registration.py --snapshot` and
never read a stable entry, manifest pointer, or root index. The snapshot
resolves generated and complete user-provided runtime rows, including uniquely
named rows introduced by earlier tags.

1. **You CANNOT write .gd/.tscn/.tres directly.** All game code goes through Worker dispatch.
2. **You and your workers CANNOT write to e2e/ directory.** E2E tests are owned by the Evaluator.
3. **Workers CANNOT modify PLAN.md/STRUCTURE.md/ASSETS.md.**
4. **Worker reports are validated by hooks** — incomplete reports are blocked and retried.
5. **MUST NOT skip stages.** Fix issues first; apply the evidence-based five-repair gate in `references/repair-attempt-accounting.md`.
6. **MUST NOT self-certify completion.** Dispatch verifiers, then reviewers. Triaging a reviewer finding to REJECT or SKIP requires a citation per `references/reviewer-finding-triage.md` (mandatory for critical/major; optional for minor).
7. **Tag scope discipline.** Workers MAY touch files from previous tags **only if** PLAN.md has an explicit refactor / fix task naming those files. New systems live alongside existing ones; do not silently rewrite prior-tag code as a "cleanup" detour.
8. **Build the Playable Unit.** PLAN.md tasks must integrate into the Playable Unit's player-experienced path. Do not treat isolated systems, simulation helpers, or unit tests as sufficient.

## Honest Reporting

- If tests fail, report failures with output — do not claim success
- If a verification step was not run, say SKIP — do not imply PASS
- If a worker's output is unclear, re-verify before accepting
- Never characterize incomplete work as done

## Plan Discipline (Single-Direction State)

Tasks transition forward only:

```
pending → in_progress → completed → verified
```

- **Never** move backward (e.g., `verified` → `pending`)
- **Never** skip states
- Update PLAN.md IMMEDIATELY when a task changes status

**When you ACCEPT a reviewer finding against a verified task:** Do NOT change the existing task's state. Add a NEW task (status `pending`) describing the fix. The original task stays `verified`. The new task goes through the full lifecycle. REJECT and SKIP do not create tasks; see `references/reviewer-finding-triage.md`.

This way the state is always monotonic and the audit trail is preserved.

A `failed` task requires a new task or user escalation — do not retry in place.

## Build Cycle

The cycle has three steps and runs until convergence (PLAN clean **and** the
last verify+review pass produced no new ACCEPTED tasks). Reviewer is invoked
**once per cycle iteration** — after every PLAN task reaches `completed`,
not on a worker-count cadence.

### Step 0 — Process Verify Feedback

Run this step before Step 1 only if pending verify feedback exists. Otherwise → skip to Step 1.

Translate failures into `pending` tasks at the bottom of `PLAN.md`.

**Project-code tasks** (any `checks.<name>.result == "fail"`) — go through the normal Worker → Verifier → Reviewer cycle:

- `checks.build.errors[]` → one task per distinct compile error (file + line + message in Notes).
- `checks.unit_tests.failures[]` → one task per failing test. If `failed > 0` but `failures[]` is empty, one task: "investigate test runner output".
- `checks.lint.issues[]` → group by file when multiple issues hit the same file; otherwise one per issue.
- `checks.lint.format_drift` → one task: "run `<format_drift.command>` to format the drifted files (`<file_count>` files)".
- `checks.static_check.issues[]` → one task per issue, using `check` as the title prefix (e.g. `missing_unit_test: s_player_input`). For unknown `check` discriminators, use the raw value verbatim — generic project-code fix.

**Config tasks** (any `checks.<name>.result == "error"`, paired with one `tooling_notes[]` entry) — main agent applies directly, NO worker dispatch:

- Routable fallback (`exclude_file` / `scope_narrow` / `add_gdlintrc_rule` / `skip_check`) WITH operand present (per the fallback table in `gm-verify/SKILL.md` Section B) → apply the structured edit using the note's operand. Mark `verified` after the next verify round confirms the tool no longer crashes there. Hard Rule 1 only restricts `.gd/.tscn/.tres`.
- `escalate`, OR routable with missing operand, OR unknown discriminator → do NOT auto-fix. Surface `tool` + `error` + `crashed_on` (and any original `suggested_fallback`) to the user verbatim, halt the build cycle, leave the task `pending` until the user resolves the underlying issue.

Do NOT delete project code as a "fix" for a tool crash.

### Step 1 — Dispatch Workers (until PLAN is clean)

- Read `references/worker-dispatch.md` for the brief template
- Read and apply `references/repair-attempt-accounting.md` after every worker
  handoff. Increment `dispatch_count` for the handoff, then classify it from
  the report evidence before changing any retry counter or task state.
- Use `subagent_type: "worker"`. Each worker implements ONE game mechanic function + its tests.
- Include the relevant Playable Unit fields in each worker brief.
- For visual tasks, fill the `Asset Runtime Snapshot` and
  `Visual Asset Contract` sections from `references/worker-dispatch.md`. The
  snapshot is `tools/asset_result_registration.py --snapshot` output pasted
  verbatim. If it fails for an asset, report its error instead of dispatching
  against an invented path.
- Max 3 in parallel with disjoint file sets via `isolation: "worktree"` (send all Agent calls in one message).
- After each worker reports DONE, mark its task in PLAN.md as `completed`.
- **`main_scene` retarget is your job.** Scaffold leaves `run/main_scene="res://scenes/main.tscn"` (placeholder). After the worker that creates this tag's entry scene (per SCENES.md) completes and the `.tscn` is on disk, `Edit` `project.godot`'s `[application] run/main_scene` to `res://<path>`.
- Continue dispatching until PLAN.md has no `pending` or `in_progress` tasks (everything is `completed` or `verified`). Then go to Step 2.

### Step 2 — Verify + Review Pass

Run ONE verifier, then ONE reviewer, on the integrated state:

**Verifier:**
- Read `references/verifier-dispatch.md` for the brief template
- Use `subagent_type: "verifier"`. Pass all `completed`-but-not-yet-`verified` workers' deliverables.
- On FAIL: add NEW `pending` fix tasks in PLAN.md. Failed tasks stay `completed`. Go back to Step 1.
- On PASS: update those tasks from `completed` → `verified`.

**Reviewer** (after verifier passes):
- Read `references/reviewer-dispatch.md` for the brief template
- Use `subagent_type: "reviewer"`. Reviewer reports back; do not let it modify project files.
- Ask the reviewer to check gameplay authenticity for the integrated Playable Unit.
- Include `Asset Runtime Snapshot` when reviewed files use visual assets.
- Triage each finding per `references/reviewer-finding-triage.md` into one of three options:
  - **ACCEPT** → add NEW `pending` fix task to PLAN.md.
  - **REJECT** → finding is wrong; do not create a task (citation required for critical/major).
  - **SKIP** → finding is real but not worth fixing now; do not create a task (citation required for critical/major).
- Defaults when uncertain: critical/major → ACCEPT; minor → SKIP.
- If you ACCEPTED any findings → go back to Step 1.
- If verifier passed AND reviewer added zero ACCEPTED tasks → exit cycle (proceed to "When Done").

The build cycle continues until ALL tasks are `verified` AND the most recent
verify+review pass produced no new ACCEPTED tasks AND the verifier passed.

## Retry Limits

Five **effective production repairs**, not five dispatches, are the only
failure gate. Apply `references/repair-attempt-accounting.md`: incomplete
handoffs and orchestration failures use its no-progress process, keep the task
continuable, and do not consume the repair budget.

## Parallel Worker Rules

- **Never parallelize workers that share files**
- Workers with disjoint file sets use `isolation: "worktree"`
- **Max 3 parallel workers** at once (file isolation constraint)
- After parallel workers complete, merge branches and build-check
- See `references/worker-dispatch.md` → Parallel Worker Dispatch for merge procedure

## Architecture and Constraints Record

```
MEMORY.md              <- Architecture and constraints index
memory/
  {system_name}.md     <- Detailed system architecture and constraints
```

- Read MEMORY.md before dispatching workers.
- Write only stable architecture decisions or project constraints. Do not
  record task history, failures, gotchas, workarounds, reviewer triage, or
  other dynamic learning.
- Do not update MEMORY.md when no durable architecture or constraint changed.
- Where the runtime exposes SubagentStop lifecycle hooks (currently Claude
  Code and Codex), Worker failures become diagnostic `worker_error` events,
  not project rules or prompt context for the next dispatch.

## Available Skills & Tools

| Skill | Purpose | Path |
|-------|---------|------|
| gecs | ECS framework API + patterns | .claude/skills/gecs/SKILL.md |
| headless-build | Compile verification | .claude/skills/headless-build/SKILL.md |
| gdunit-driver | Unit test execution | .claude/skills/gdunit-driver/SKILL.md |
| godot-api | Godot API reference | .claude/skills/godot-api/SKILL.md |
| screenshot | Gameplay screenshot capture | .claude/skills/screenshot/SKILL.md |
| mcp-driver | Runtime debugging via godot-mcp | .claude/skills/mcp-driver/SKILL.md |

**Asset analysis:** Dispatch an Analyst subagent (`subagent_type: "analyst"`, see `references/analyst-dispatch.md`) when you need to analyze user-provided assets.

## Context Management

Your context window is finite. Protect it:

**In your context:** PLAN.md status, STRUCTURE.md architecture, worker briefs (~200 tokens), worker summaries (~100 tokens), verification results, design decisions.

**Out of your context (delegate to workers):** Asset generation, system implementation code, test code, build/lint output, screenshot analysis.

**When context gets large:** Summarize completed phases and reference documents by path. Do not use MEMORY.md as a context-recovery log.

## When Done

When ALL PLAN.md tasks are `verified` AND the most recent verify+review pass produced no new ACCEPTED fix tasks:

1. From the project root run `python tools/append_stage_event.py build` to append a `{"role": "build", "ts": "<server-generated UTC>"}` line to `.godotmaker/stage.jsonl`. Do NOT hand-write the JSON or the timestamp — the helper exists so the timestamp comes from the system clock, not your own output.
2. `git add -A && git commit -m "chore(build): <Tag>"`
3. Inform the user: `Build complete. Recommended next: /gm-verify`