Skip to content

RandallLiuXin/GodotMaker / skills/core/gm-build

gm-build

Verified

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.

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 ownership, dependencies, ordering constraints, stable invariants, 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
  • 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 Contract

  • Read STRUCTURE.md before dispatching workers.
  • Keep architecture ownership, dependencies, ordering constraints, and stable invariants in STRUCTURE.md. Do not record task history, failures, gotchas, workarounds, reviewer triage, or other dynamic learning there.
  • 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

SkillPurposePath
gecsECS framework API + patterns.claude/skills/gecs/SKILL.md
headless-buildCompile verification.claude/skills/headless-build/SKILL.md
gdunit-driverUnit test execution.claude/skills/gdunit-driver/SKILL.md
godot-apiGodot API reference.claude/skills/godot-api/SKILL.md
screenshotGameplay screenshot capture.claude/skills/screenshot/SKILL.md
mcp-driverRuntime 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 turn project documents into context-recovery logs.

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
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall