1. If

   --review [full|lean|solo]

   was passed → use that
2. Else read

   production/review-mode.txt

   → use that value
3. Else → default to

   lean

.claude/docs/director-gates.md

1. Check if

   design/gdd/systems-index.md

   exists.
2. If it exists: read it, find the highest-priority system with status "Not Started" or equivalent, and use

   AskUserQuestion

   :
   • Prompt: "The next system in your design order is [system-name] ([priority] | [layer]). Start designing it?"
   • Options:

     [A] Yes — design [system-name]

     /

     [B] Pick a different system

     /

     [C] Stop here

   • If [A]: proceed with that system name. If [B]: ask which system to design (plain text). If [C]: exit.
3. If no systems index exists, fail with:

   "Usage:

   /design-system <system-name>

   — e.g.,

   /design-system movement

   Or to fill gaps in an existing GDD:

   /design-system retrofit design/gdd/[system-name].md

   No systems index found. Run

   /map-systems

   first to map your systems and get the design order."

retrofit

.md

design/gdd/

1. Read the existing GDD file.
2. Identify which of the 8 required sections are present (scan for section headings). Required sections: Overview, Player Fantasy, Detailed Design/Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
3. Identify which sections contain only placeholder text (

   [To be designed]

   or equivalent — blank, a single line, or obviously incomplete).
4. Present to the user before doing anything:

   ## Retrofit: [System Name]
   File: design/gdd/[filename].md
   
   Sections already written (will not be touched):
   ✓ [section name]
   ✓ [section name]
   
   Missing or incomplete sections (will be authored):
   ✗ [section name] — missing
   ✗ [section name] — placeholder only

5. Ask: "Shall I fill the [N] missing sections? I will not modify any existing content."
6. If yes: proceed to Phase 2 (Gather Context) as normal, but in Phase 3 skip creating the skeleton (file already exists) and in Phase 4 skip sections that are already complete. Only run the section cycle for missing/ incomplete sections.
7. Never overwrite existing section content. Use Edit tool to replace only

   [To be designed]

   placeholders or empty section bodies.

combat-system

• Game concept: Read

  design/gdd/game-concept.md

  — fail if missing:

  "No game concept found. Run

  /brainstorm

  first."

• Systems index: Read

  design/gdd/systems-index.md

  — fail if missing:

  "No systems index found. Run

  /map-systems

  first to map your systems."

• Target system: Find the system in the index. If not listed, warn:

  "[system-name] is not in the systems index. Would you like to add it, or design it as an off-index system?"

• Entity registry: Read

  design/registry/entities.yaml

  if it exists. Extract all entries referenced by or relevant to this system (grep

  referenced_by.*[system-name]

  and

  source.*[system-name]

  ). Hold these in context as known facts — values that other GDDs have already established and this GDD must not contradict.
• Reflexion log: Read

  docs/consistency-failures.md

  if it exists. Extract entries whose Domain matches this system's category. These are recurring conflict patterns — present them under "Past failure patterns" in the Phase 2d context summary so the user knows where mistakes have occurred before in this domain.

• Upstream dependencies: Systems this one depends on. Read their GDDs if they exist (these contain decisions this system must respect).
• Downstream dependents: Systems that depend on this one. Read their GDDs if they exist (these contain expectations this system must satisfy).

• Key interfaces (what data flows between the systems)
• Formulas that reference this system's outputs
• Edge cases that assume this system's behavior
• Tuning knobs that feed into this system

• Game pillars: Read

  design/gdd/game-pillars.md

  if it exists
• Existing GDD: Read

  design/gdd/[system-name].md

  if it exists (resume, don't restart from scratch)
• Related GDDs: Glob

  design/gdd/*.md

  and read any that are thematically related (e.g., if designing a system that overlaps with another in scope, read the related GDD even if it's not a formal dependency)

Designing: [System Name]

• Priority: [from index] | Layer: [from index]
• Depends on: [list, noting which have GDDs vs. undesigned]
• Depended on by: [list, noting which have GDDs vs. undesigned]
• Existing decisions to respect: [key constraints from dependency GDDs]
• Pillar alignment: [which pillar(s) this system primarily serves]
• Known cross-system facts (from registry):
  • [entity_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD])
  • [item_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD])
  • [formula_name]: variables=[list], output=[min–max] (owned by [source GDD])
  • [constant_name]: [value] [unit] (owned by [source GDD]) (These values are locked — if this GDD needs different values, surface the conflict before writing. Do not silently use different numbers.)

If no registry entries are relevant: omit the "Known cross-system facts" section.

"[dependency] doesn't have a GDD yet. We'll need to make assumptions about its interface. Consider designing it first, or we can define the expected contract and flag it as provisional."

• Read

  .claude/docs/technical-preferences.md

  to identify the engine and version
• If engine is configured, read

  docs/engine-reference/[engine]/VERSION.md

• Read

  docs/engine-reference/[engine]/modules/[domain].md

  if it exists
• Read

  docs/engine-reference/[engine]/breaking-changes.md

  for domain-relevant entries
• Glob

  docs/architecture/adr-*.md

  and read any ADRs whose domain matches (check the Engine Compatibility table's "Domain" field)

undefined

• [capability relevant to this system]
• [capability 2]

• [constraint from engine-reference or existing ADR]

• [post-cutoff feature this design might rely on — mark HIGH/MEDIUM risk]

• ADR-XXXX: [decision summary] — means [implication for this GDD] (or "None yet")

If no engine reference docs exist (engine not yet configured), show a short note:
> "No engine configured yet — skipping technical feasibility check. Run
> `/setup-engine` before moving to architecture if you haven't already."

**Step 4 — Ask before proceeding:**

Use `AskUserQuestion`:
- "Any constraints to add before we begin, or shall we proceed with these noted?"
  - Options: "Proceed with these noted", "Add a constraint first", "I need to check the engine docs — pause here"

---

Use `AskUserQuestion`:
- "Ready to start designing [system-name]?"
  - Options: "Yes, let's go", "Show me more context first", "Design a dependency first"

---

Status: In Design Author: [user + agents] Last Updated: [today's date] Implements Pillar: [from context]

Context  ->  Questions  ->  Options  ->  Decision  ->  Draft  ->  Approval  ->  Write

1. Context: State what this section needs to contain, and surface any relevant decisions from dependency GDDs that constrain it.
2. Questions: Ask clarifying questions specific to this section. Use

   AskUserQuestion

   for constrained questions, conversational text for open-ended exploration.
3. Options: Where the section involves design choices (not just documentation), present 2-4 approaches with pros/cons. Explain reasoning in conversation text, then use

   AskUserQuestion

   to capture the decision.
4. Decision: User picks an approach or provides custom direction.
5. Draft: Write the section content in conversation text for review. Flag any provisional assumptions about undesigned dependencies.
6. Approval: Immediately after the draft — in the SAME response — use

   AskUserQuestion

   . NEVER use plain text. NEVER skip this step.
   • Prompt: "Approve the [Section Name] section?"
   • Options:

     [A] Approve — write it to file

     /

     [B] Make changes — describe what to fix

     /

     [C] Start over

   The draft and the approval widget MUST appear together in one response. If the draft appears without the widget, the user is left at a blank prompt with no path forward — this is a protocol violation.
7. Write: Use the Edit tool to replace the placeholder with the approved content. CRITICAL: Always include the section heading in the

   old_string

   to ensure uniqueness — never match

   [To be designed]

   alone, as multiple sections use the same placeholder and the Edit tool requires a unique match. Use this pattern:

   old_string: "## [Section Name]\n\n[To be designed]"
   new_string: "## [Section Name]\n\n[approved content]"

   Confirm the write.
8. Registry conflict check (Sections C and D only — Detailed Design and Formulas): After writing, scan the section content for entity names, item names, formula names, and numeric constants that appear in the registry. For each match:
   • Compare the value just written against the registry entry.
   • If they differ: surface the conflict immediately before starting the next section. Do not continue silently.

     "Registry conflict: [name] is registered in [source GDD] as [registry_value]. This section just wrote [new_value]. Which is correct?"

   • If new (not in registry): flag it as a candidate for registry registration (will be handled in Phase 5).

production/session-state/active.md

• Framing tab: Foundation/Infrastructure layer →

  [A]

  recommended. Player-facing categories (Combat, UI, Dialogue, Character, Animation, Visual Effects, Audio) →

  [C] Both

  recommended.
• ADR ref tab: Glob

  docs/architecture/adr-*.md

  and grep for the system name in the GDD Requirements section of any ADR. If a matching ADR is found →

  [A] Yes — cite the ADR

  recommended. If none found →

  [B] No

  recommended.
• Fantasy tab: Foundation/Infrastructure layer →

  [B] No

  recommended. All other categories →

  [A] Yes

  recommended.

(Recommended)

AskUserQuestion

• Tab "Framing" — "How should the overview frame this system?" Options:

  [A] As a data/infrastructure layer (technical framing)

  /

  [B] Through its player-facing effect (design framing)

  /

  [C] Both — describe the data layer and its player impact

• Tab "ADR ref" — "Should the overview reference the existing ADR for this system?" Options:

  [A] Yes — cite the ADR for implementation details

  /

  [B] No — keep the GDD at pure design level

• Tab "Fantasy" — "Does this system have a player fantasy worth stating?" Options:

  [A] Yes — players feel it directly

  /

  [B] No — pure infrastructure, players feel what it enables

• What is this system in one sentence?
• How does a player interact with it? (active/passive/automatic)
• Why does this system exist — what would the game lose without it?

/architecture-decision

• Player-facing categories (Combat, UI, Dialogue, Character, Animation, Audio, Level/World) →

  [A] Direct

  recommended
• Foundation/Infrastructure layer →

  [B] Indirect

  recommended
• Mixed categories (Camera/input, Economy, AI with visible player effects) →

  [C] Both

  recommended

(Recommended)

AskUserQuestion

• Prompt: "Is this system something the player engages with directly, or infrastructure they experience indirectly?"
• Options:

  [A] Direct — player actively uses or feels this system

  /

  [B] Indirect — player experiences the effects, not the system

  /

  [C] Both — has a direct interaction layer and infrastructure beneath it

• What emotion or power fantasy does this serve?
• What reference games nail this feeling? What specifically creates it?
• Is this a "system you love engaging with" or "infrastructure you don't notice"?

creative-director

• Provide: system name, framing answer (direct/indirect/both), game pillars, any reference games the user mentioned, the game concept summary
• Ask: "Shape the Player Fantasy for this system. What emotion or power fantasy should it serve? What player moment should we anchor to? What tone and language fits the game's established feeling? Be specific — give me 2-3 candidate framings."
• Collect the creative-director's framings and present them to the user alongside the draft.

creative-director

1. Core Rules: The fundamental mechanics. Use numbered rules for sequential processes, bullets for properties.
2. States and Transitions: If the system has states, map every state and every valid transition. Use a table.
3. Interactions with Other Systems: For each dependency (upstream and downstream), specify what data flows in, what flows out, and who owns the interface.

• Walk me through a typical use of this system, step by step
• What are the decision points the player faces?
• What can the player NOT do? (Constraints are as important as capabilities)

• Look up the system category in the routing table (Section 6 of this skill)
• Spawn the Primary Agent AND Supporting Agent(s) listed for this category
• Provide each agent: system name, game concept summary, pillar set, dependency GDD excerpts, the specific section being worked on
• Collect their findings before drafting
• Surface any disagreements between agents to the user via

  AskUserQuestion

• Draft only after receiving specialist input

systems-designer

The [formula_name] formula is defined as:

`[formula_name] = [expression]`

**Variables:**
| Variable | Symbol | Type | Range | Description |
|----------|--------|------|-------|-------------|
| [name] | [sym] | float/int | [min–max] | [what it represents] |

**Output Range:** [min] to [max] under normal play; [behaviour at extremes]
**Example:** [worked example with real numbers]

[Formula TBD]

• What are the core calculations this system performs?
• Should scaling be linear, logarithmic, or stepped?
• What should the output ranges be at early/mid/late game?

• Always spawn

  systems-designer

  : provide Core Rules from Section C, tuning goals from user, balance context from dependency GDDs. Ask them to propose formulas with variable tables and output ranges.
• For economy/cost systems, also spawn

  economy-designer

  : provide placement costs, upgrade cost intent, and progression goals. Ask them to validate cost curves and ratios.
• Present the specialists' proposals to the user for review via

  AskUserQuestion

• The user decides; the main session writes to file
• Do NOT invent formula values or balance numbers without specialist input. A user without balance design expertise cannot evaluate raw numbers — they need the specialists' reasoning.

• If [condition]: [exact outcome]. [rationale if non-obvious]

• If [resource] reaches 0 while [protective condition] is active: hold at minimum until condition ends, then apply consequence.
• If two [triggers/events] fire simultaneously: resolve in [defined priority order]; ties use [defined tiebreak rule].

• What happens at zero? At maximum? At out-of-range values?
• What happens when two rules apply at the same time?
• What happens if a player finds an unintended interaction? (Identify degenerate strategies)

systems-designer

narrative-director

• Are there dependencies I'm missing?
• For each dependency, what's the specific data interface?
• Which dependencies are hard (system cannot function without it) vs. soft (enhanced by it but works without it)?

• What values should designers be able to tweak without code changes?
• For each knob, what breaks if it's set too high? Too low?
• Which knobs interact with each other? (Changing A makes B irrelevant)

systems-designer

• GIVEN [initial state], WHEN [action or trigger], THEN [measurable outcome]

• GIVEN [initial state], WHEN [player action or system trigger], THEN [specific measurable outcome].
• GIVEN [a constraint is active], WHEN [player attempts an action], THEN [feedback shown and action result].

qa-lead

• What's the minimum set of tests that prove this works?
• What performance budget does this system get? (frame time, memory)
• What would a QA tester check first?

• Combat, damage, health
• UI systems (HUD, menus)
• Animation, character movement
• Visual effects, particles, shaders
• Character systems
• Dialogue, quests, lore
• Level/world systems

art-director

[To be designed]

AskUserQuestion

• "The 8 required sections are complete. Do you want to also define Visual/Audio requirements, UI requirements, or capture open questions?"
  • Options: "Yes, all three", "Just open questions", "Skip — I'll add these later"

art-director

audio-director

Asset Spec Flag: After the Visual/Audio section is written with real content, output this notice: "📌 Asset Spec — Visual/Audio requirements are defined. After the art bible is approved, run

/asset-spec system:[system-name]

to produce per-asset visual descriptions, dimensions, and generation prompts from this section."

ux-designer

[To be designed]

📌 UX Flag — [System Name]: This system has UI requirements. In Phase 4 (Pre-Production), run

/ux-design

to create a UX spec for each screen or HUD element this system contributes to before writing epics. Stories that reference UI should cite

design/ux/[screen].md

, not the GDD directly.

Note this in the systems index for this system if you update it.

• All 8 required sections have real content (not placeholders)
• Formulas reference defined variables
• Edge cases have resolutions
• Dependencies are listed with interfaces
• Acceptance criteria are testable

• solo

  → skip. Note: "CD-GDD-ALIGN skipped — Solo mode." Proceed to Step 5b.

• lean

  → skip (not a PHASE-GATE). Note: "CD-GDD-ALIGN skipped — Lean mode." Proceed to Step 5b.

• full

  → spawn as normal.

creative-director

.claude/docs/director-gates.md

design/gdd/game-concept.md

design/gdd/game-pillars.md

director-gates.md

> **Creative Director Review (CD-GDD-ALIGN)**: APPROVED [date] / CONCERNS (accepted) [date] / REVISED [date]

• Named entities (enemies, NPCs, bosses) with stats or drops
• Named items with values, weights, or categories
• Named formulas with defined variables and output ranges
• Named constants referenced by value in more than one place

design/registry/entities.yaml

Grep pattern="  - name: [candidate_name]" path="design/registry/entities.yaml"

Registry candidates from this GDD:
  NEW (not yet registered):
    - [entity_name] [entity]: [attribute]=[value], [attribute]=[value]
    - [item_name] [item]: [attribute]=[value], [attribute]=[value]
    - [formula_name] [formula]: variables=[list], output=[min–max]
  ALREADY REGISTERED (referenced_by will be updated):
    - [constant_name] [constant]: value=[N] ← matches registry ✅

design/registry/entities.yaml

referenced_by

referenced_by

value

GDD Complete: [System Name]

• Sections written: [list]
• Provisional assumptions: [list any assumptions about undesigned dependencies]
• Cross-system conflicts found: [list or "none"]

To validate this GDD, open a fresh Claude Code session and run:

/design-review design/gdd/[system-name].md

Never run

/design-review

in the same session as

/design-system

. The reviewing agent must be independent of the authoring context. Running it here would inherit the full design history, making independent critique impossible.

/design-review

• Read the systems index
• Update the target system's row:
  • If design-review was run and verdict is APPROVED: Status → "Approved"
  • If design-review was run and verdict is NEEDS REVISION: Status → "In Review"
  • If design-review was skipped: Status → "Designed" (pending review)
  • If the user chose "I'll review it myself first": Status → "Designed"
  • Design Doc: link to

    design/gdd/[system-name].md

• Update the Progress Tracker counts

design/gdd/systems-index.md

production/session-state/active.md

• Task: [system-name] GDD
• Status: Complete (or In Review if design-review was run)
• File: design/gdd/[system-name].md
• Sections: All 8 written
• Next: [suggest next system from design order]

AskUserQuestion

• "What's next?"
  • Options:
    • "Run

      /consistency-check

      — verify this GDD's values don't conflict with existing GDDs (recommended before designing the next system)"
    • "Design next system ([next-in-order])" — if undesigned systems remain
    • "Fix review findings" — if design-review flagged issues
    • "Stop here for this session"
    • "Run

      /gate-check

      " — if enough MVP systems are designed

systems-designer

gameplay-programmer

engine-programmer

game-designer

systems-designer

ai-programmer

art-director

economy-designer

systems-designer

game-designer

game-designer

systems-designer

economy-designer

game-designer

narrative-director

writer

art-director

game-designer

ux-designer

ui-programmer

art-director

technical-artist

game-designer

audio-director

sound-designer

game-designer

ai-programmer

systems-designer

game-designer

level-designer

world-builder

game-designer

ux-designer

gameplay-programmer

game-designer

art-director

technical-artist

gameplay-programmer

game-designer

art-director

technical-artist

systems-designer

game-designer

art-director

narrative-director

systems-designer

• Provide: system name, game concept summary, dependency GDD excerpts, the specific section being worked on, and what question needs expert input
• The agent returns analysis/proposals to the main session
• The main session presents the agent's output to the user via

  AskUserQuestion

• The user decides; the main session writes to file
• Agents do NOT write to files directly — the main session owns all file writes

1. Read

   production/session-state/active.md

   — it records the current system and which sections are complete
2. Read

   design/gdd/[system-name].md

   — sections with real content are done; sections with

   [To be designed]

   still need work
3. Resume from the next incomplete section — no need to re-discuss completed ones

1. Question -> Options -> Decision -> Draft -> Approval for every section
2. AskUserQuestion at every decision point (Explain -> Capture pattern):
   • Phase 2: "Ready to start, or need more context?"
   • Phase 3: "May I create the skeleton?"
   • Phase 4 (each section): Design questions, approach options, draft approval
   • Phase 5: "Run design review? Update systems index? What's next?"
3. "May I write to [filepath]?" before the skeleton and before each section write
4. Incremental writing: Each section is written to file immediately after approval
5. Session state updates: After every section write
6. Cross-referencing: Every section checks existing GDDs for conflicts
7. Specialist routing: Complex sections get expert agent input, presented to the user for decision — never written silently

Context is approaching the limit (≥70%). Your progress is saved — all approved sections are written to

design/gdd/[system-name].md

. When you're ready to continue, open a fresh Claude Code session and run

/design-system [system-name]

— it will detect which sections are complete and resume from the next one.

• Run

  /design-review design/gdd/[system-name].md

  in a fresh session to validate the completed GDD independently
• Run

  /consistency-check

  to verify this GDD's values don't conflict with other GDDs
• Run

  /map-systems next

  to move to the next highest-priority undesigned system
• Run

  /gate-check pre-production

  when all MVP GDDs are authored and reviewed