Release v0.3.0: /design-system, /map-systems, status line, UPGRADING guide (#2)

* Add UPGRADING.md migration guide and link from README

Covers v0.1→v0.2 upgrade with three strategies (git merge, cherry-pick,
manual copy), file safety categories, and post-upgrade verification steps.
Structured to support future version sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Rename /design-systems to /map-systems + /design-system and fix all references

Split the monolithic /design-systems skill into two focused skills:
- /map-systems: systems decomposition and index creation
- /design-system: guided section-by-section GDD authoring

Updated all cross-references across 14 files: README, UPGRADING,
WORKFLOW-GUIDE, quick-start, skills-reference, game-concept template,
systems-index template, brainstorm, design-review, gate-check,
project-stage-detect, setup-engine, and start skills. Fixed skill
counts from 36 to 37 everywhere. Added /map-systems and /design-system
to quick-start Paths A and B workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix cross-reference gaps, broken hooks, and stale workflow chains

- Fix log-agent.sh parsing agent_type instead of agent_name (always logged "unknown")
- Fix GDD status lifecycle: design-system now writes Approved/Designed/In Review
- Clean up settings.local.json vestigial Bash grants from development
- Delete orphaned docs marked for removal in UPGRADING.md
- Add /design-system to next-steps in /start, /brainstorm, /setup-engine
- Fix WORKFLOW-GUIDE: add /map-systems + /design-system to Appendix C Workflow 1
- Fix invalid /map-systems map argument in WORKFLOW-GUIDE Step 2.1
- Update map-systems frontmatter to document [system-name] argument
- Update commit hook to validate all 8 required GDD sections (was 5)
- Update README template count 28 → 29, add 5 missing templates to quick-start

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add custom status line with 7-stage production pipeline

Introduces a status line showing context %, model name, and production
stage at a glance. Aligns gate-check and project-stage-detect to a
unified 7-stage model (Concept → Systems Design → Technical Setup →
Pre-Production → Production → Polish → Release). Stage is determined
by explicit override (production/stage.txt) or auto-detected from
project artifacts. Epic/Feature/Task breadcrumb appears conditionally
in Production+ stages via a structured STATUS block in active.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add v0.2→v0.3 upgrade guide and PR validation test suite

- UPGRADING.md: add v0.2.0→v0.3.0 section documenting breaking rename
  of /design-systems→/map-systems, new /design-system skill, statusline.sh,
  gate-check stage advancement, and safe-to-overwrite file list

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.claude/agents/art-director.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Art Bible Maintenance**: Create and maintain the art bible defining style,

.claude/agents/audio-director.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Sound Palette Definition**: Define the sonic palette for the game --

.claude/agents/creative-director.md

@@ -154,6 +154,24 @@ You: [Creates ADR, updates docs, notifies relevant agents]
 - Once decided, commit fully — document and cascade the decision
 - Set up success metrics — "we'll know this was right if..."
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full strategic analysis in conversation: options with
+   pillar alignment, downstream consequences, risk assessment, recommendation.
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**Guidelines:**
+- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
+- Add "(Recommended)" to your preferred option's label
+- For open-ended context gathering, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Vision Guardianship**: Maintain and communicate the game's core pillars,

.claude/agents/economy-designer.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Resource Flow Modeling**: Map all resource sources (faucets) and sinks in

.claude/agents/game-designer.md

@@ -33,14 +33,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -53,6 +58,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Core Loop Design**: Define and refine the moment-to-moment, session, and

.claude/agents/level-designer.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Level Layout Design**: Create top-down layout documents for each level/area

.claude/agents/live-ops-designer.md

@@ -48,6 +48,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ## Core Responsibilities
 - Design seasonal content calendars and event cadences
 - Plan battle passes, seasons, and time-limited content

.claude/agents/narrative-director.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Story Architecture**: Design the narrative structure -- act breaks, major

.claude/agents/producer.md

@@ -58,6 +58,24 @@ When the user asks you to make a decision or resolve a conflict:
 - Once decided, commit fully — document and cascade the decision
 - Set up success metrics — "we'll know this was right if..."
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full strategic analysis in conversation: options with
+   pillar alignment, downstream consequences, risk assessment, recommendation.
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**Guidelines:**
+- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
+- Add "(Recommended)" to your preferred option's label
+- For open-ended context gathering, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Sprint Planning**: Break milestones into 1-2 week sprints with clear,

.claude/agents/systems-designer.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Formula Design**: Create mathematical formulas for damage, healing, XP

.claude/agents/technical-director.md

@@ -57,6 +57,24 @@ When the user asks you to make a decision or resolve a conflict:
 - Once decided, commit fully — document and cascade the decision
 - Set up success metrics — "we'll know this was right if..."
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full strategic analysis in conversation: options with
+   pillar alignment, downstream consequences, risk assessment, recommendation.
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**Guidelines:**
+- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
+- Add "(Recommended)" to your preferred option's label
+- For open-ended context gathering, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Architecture Ownership**: Define and maintain the high-level system

.claude/agents/ux-designer.md

@@ -51,6 +51,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **User Flow Mapping**: Document every user flow in the game -- from boot to

.claude/agents/world-builder.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Create sections iteratively (show one section, get feedback, refine)
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
+   - Show the draft section or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Lore Consistency**: Maintain a lore database and cross-reference all new

.claude/agents/writer.md

@@ -30,22 +30,21 @@ Before writing any code:
    - "The design doc doesn't specify [edge case]. What should happen when...?"
    - "This will require changes to [other system]. Should I coordinate with that first?"
 
-3. **Propose architecture before implementing:**
+3. **Draft based on user's choice (incremental file writing):**
-   - Show class structure, file organization, data flow
+   - Create the target file immediately with a skeleton (all section headers)
-   - Explain WHY you're recommending this approach (patterns, engine conventions, maintainability)
+   - Draft one section at a time in conversation
-   - Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible"
+   - Ask about ambiguities rather than assuming
-   - Ask: "Does this match your expectations? Any changes before I write the code?"
+   - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
-4. **Implement with transparency:**
+4. **Get approval before writing files:**
-   - If you encounter spec ambiguities during implementation, STOP and ask
+   - Show the draft section or summary
-   - If rules/hooks flag issues, fix them and explain what was wrong
+   - Explicitly ask: "May I write this section to [filepath]?"
-   - If a deviation from the design doc is necessary (technical constraint), explicitly call it out
-
-5. **Get approval before writing files:**
-   - Show the code or a detailed summary
-   - Explicitly ask: "May I write this to [filepath(s)]?"
-   - For multi-file changes, list all affected files
    - Wait for "yes" before using Write/Edit tools
+   - If user says "no" or "change X", iterate and return to step 3
 
 6. **Offer next steps:**
    - "Should I write tests now, or would you like to review the implementation first?"
@@ -61,6 +60,13 @@ Before writing any code:
 - Rules are your friend — when they flag issues, they're usually right
 - Tests prove it works — offer to write them proactively
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool for implementation choices and next-step decisions.
+Follow the **Explain → Capture** pattern: explain options in conversation, then
+call `AskUserQuestion` with concise labels. Batch up to 4 questions in one call.
+For open-ended writing questions, use conversation instead.
+
 ### Key Responsibilities
 
 1. **Dialogue Writing**: Write character dialogue following voice profiles

.claude/docs/CLAUDE-local-template.md

@@ -34,4 +34,4 @@ This file is gitignored and will not be committed.
 
 1. Copy this template to your project root: `cp .claude/docs/CLAUDE-local-template.md CLAUDE.local.md`
 2. Edit to match your preferences
-3. Verify `.claude/CLAUDE.local.md` or `CLAUDE.local.md` is in `.gitignore`
+3. Verify `CLAUDE.local.md` is in `.gitignore` (Claude Code reads it from the project root)

.claude/docs/context-management.md

@@ -1,22 +1,89 @@
 # Context Management
 
-Context is the most critical resource in a Claude Code session. Manage it actively:
+Context is the most critical resource in a Claude Code session. Manage it actively.
 
-- **Compact proactively** at ~65-70% context usage, not reactively when at the limit
+## File-Backed State (Primary Strategy)
+
+**The file is the memory, not the conversation.** Conversations are ephemeral and
+will be compacted or lost. Files on disk persist across compactions and session crashes.
+
+### Session State File
+
+Maintain `production/session-state/active.md` as a living checkpoint. Update it
+after each significant milestone:
+
+- Design section approved and written to file
+- Architecture decision made
+- Implementation milestone reached
+- Test results obtained
+
+The state file should contain: current task, progress checklist, key decisions
+made, files being worked on, and open questions.
+
+### Status Line Block (Production+ only)
+
+When the project is in Production, Polish, or Release stage, include a structured
+status block in `active.md` that the status line script can parse:
+
+```markdown
+<!-- STATUS -->
+Epic: Combat System
+Feature: Melee Combat
+Task: Implement hitbox detection
+<!-- /STATUS -->
+```
+
+- All three fields (Epic, Feature, Task) are optional — include only what applies
+- Update this block when switching focus areas
+- The status line displays it as a breadcrumb: `Combat System > Melee Combat > Hitboxes`
+- Remove or empty the block when no active work focus exists
+
+After any disruption (compaction, crash, `/clear`), read the state file first.
+
+### Incremental File Writing
+
+When creating multi-section documents (design docs, architecture docs, lore entries):
+
+1. Create the file immediately with a skeleton (all section headers, empty bodies)
+2. Discuss and draft one section at a time in conversation
+3. Write each section to the file as soon as it's approved
+4. Update the session state file after each section
+5. After writing a section, previous discussion about that section can be safely
+   compacted — the decisions are in the file
+
+This keeps the context window holding only the *current* section's discussion
+(~3-5k tokens) instead of the entire document's conversation history (~30-50k tokens).
+
+## Proactive Compaction
+
+- **Compact proactively** at ~60-70% context usage, not reactively at the limit
 - **Use `/clear`** between unrelated tasks, or after 2+ failed correction attempts
-- **Context budgets by task type**:
+- **Natural compaction points:** after writing a section to file, after committing,
-  - Light (read/review): ~3k tokens startup
+  after completing a task, before starting a new topic
-  - Medium (implement feature): ~8k tokens
+- **Focused compaction:** `/compact Focus on [current task] — sections 1-3 are
-  - Heavy (multi-system refactor): ~15k tokens
+  written to file, working on section 4`
-- **Preserve during compaction**: modified file list, active sprint tasks, architectural
-  decisions made this session, agent invocation outcomes, test results, unresolved blockers
-- When delegating to subagents, provide full context in the prompt -- subagents do not
-  inherit conversation history unless explicitly given it
 
-# Compaction Instructions
+## Context Budgets by Task Type
+
+- Light (read/review): ~3k tokens startup
+- Medium (implement feature): ~8k tokens
+- Heavy (multi-system refactor): ~15k tokens
+
+## Subagent Delegation
+
+Use subagents for research and exploration to keep the main session clean.
+Subagents run in their own context window and return only summaries:
+
+- **Use subagents** when investigating across multiple files, exploring unfamiliar code,
+  or doing research that would consume >5k tokens of file reads
+- **Use direct reads** when you know exactly which 1-2 files to check
+- Subagents do not inherit conversation history — provide full context in the prompt
+
+## Compaction Instructions
 
 When context is compacted, preserve the following in the summary:
 
+- Reference to `production/session-state/active.md` (read it to recover state)
 - List of files modified in this session and their purpose
 - Any architectural decisions made and their rationale
 - Active sprint tasks and their current status
@@ -24,3 +91,17 @@ When context is compacted, preserve the following in the summary:
 - Test results (pass/fail counts, specific failures)
 - Unresolved blockers or questions awaiting user input
 - The current task and what step we are on
+- Which sections of the current document are written to file vs. still in progress
+
+**After compaction:** Read `production/session-state/active.md` and any files being
+actively worked on to recover full context. The files contain the decisions; the
+conversation history is secondary.
+
+## Recovery After Session Crash
+
+If a session dies ("prompt too long") or you start a new session to continue work:
+
+1. The `session-start.sh` hook will detect and preview `active.md` automatically
+2. Read the full state file for context
+3. Read the partially-completed file(s) listed in the state
+4. Continue from the next incomplete section or task

.claude/docs/directory-structure.md

@@ -13,4 +13,6 @@
 ├── tools/                       # Build and pipeline tools (ci, build, asset-pipeline)
 ├── prototypes/                  # Throwaway prototypes (isolated from src/)
 └── production/                  # Production management (sprints, milestones, releases)
+    ├── session-state/           # Ephemeral session state (active.md — gitignored)
+    └── session-logs/            # Session audit trail (gitignored)
 ```

.claude/docs/hooks-reference.md

@@ -7,9 +7,9 @@ Hooks are configured in `.claude/settings.json` and fire automatically:
 | `validate-commit.sh` | PreToolUse (Bash) | `git commit` commands | Validates design doc sections, JSON data files, hardcoded values, TODO format |
 | `validate-push.sh` | PreToolUse (Bash) | `git push` commands | Warns on pushes to protected branches (develop/main) |
 | `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks naming conventions and JSON validity for files in `assets/` |
-| `session-start.sh` | SessionStart | Session begins | Loads current sprint context, active milestone, recent git activity |
+| `session-start.sh` | SessionStart | Session begins | Loads sprint context, milestone, git activity; detects and previews active session state file for recovery |
 | `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect |
-| `pre-compact.sh` | PreCompact | Context compression | Logs session progress notes before context window compression |
+| `pre-compact.sh` | PreCompact | Context compression | Dumps session state (active.md, modified files, WIP design docs) into conversation before compaction so it survives summarization |
 | `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log |
 | `log-agent.sh` | SubagentStart | Agent spawned | Audit trail of all subagent invocations with timestamps |
 

.claude/docs/hooks-reference/post-merge-asset-validation.md

@@ -31,7 +31,7 @@ for file in $MERGED_ASSETS; do
     filename=$(basename "$file")
 
     # Check naming convention (lowercase with underscores)
-    if echo "$filename" | grep -qP '[A-Z\s-]'; then
+    if echo "$filename" | grep -qE '[A-Z[:space:]-]'; then
         WARNINGS="$WARNINGS\nNAMING: $file -- must be lowercase with underscores"
         EXIT_CODE=1
     fi

.claude/docs/hooks-reference/pre-commit-code-quality.md

@@ -27,14 +27,14 @@ if [ -n "$CODE_FILES" ]; then
         if [[ "$file" == src/gameplay/* ]]; then
             # Look for numeric literals that are likely balance values
             # Adjust the pattern for your language
-            if grep -nP '(?<![\w.])(?:damage|health|speed|rate|chance|cost|duration)\s*[:=]\s*\d+' "$file"; then
+            if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file"; then
                 echo "WARNING: $file may contain hardcoded gameplay values. Use data files."
                 # Warning only, not blocking
             fi
         fi
 
         # Check for TODO/FIXME without assignee
-        if grep -nP '(TODO|FIXME|HACK)(?!\()' "$file"; then
+        if grep -nE '(TODO|FIXME|HACK)[^(]' "$file"; then
             echo "WARNING: $file has TODO/FIXME without owner tag. Use TODO(name) format."
         fi
 

.claude/docs/hooks-reference/pre-commit-design-check.md

@@ -43,7 +43,15 @@ fi
 if [ -n "$DATA_FILES" ]; then
     for file in $DATA_FILES; do
         if [[ "$file" == *.json ]]; then
-            if ! python -m json.tool "$file" > /dev/null 2>&1; then
+            # Find a working Python command
+            PYTHON_CMD=""
+            for cmd in python python3 py; do
+                if command -v "$cmd" >/dev/null 2>&1; then
+                    PYTHON_CMD="$cmd"
+                    break
+                fi
+            done
+            if [ -n "$PYTHON_CMD" ] && ! "$PYTHON_CMD" -m json.tool "$file" > /dev/null 2>&1; then
                 echo "ERROR: $file is not valid JSON"
                 EXIT_CODE=1
             fi

.claude/docs/quick-start.md

@@ -99,6 +99,8 @@ Ask yourself: "What department would handle this in a real studio?"
 | `/project-stage-detect` | Analyze project state, detect stage, identify gaps |
 | `/reverse-document` | Generate design/architecture docs from existing code |
 | `/setup-engine` | Configure engine + version, populate reference docs |
+| `/map-systems` | Decompose concept into systems, map dependencies, guide per-system GDDs |
+| `/design-system` | Guided, section-by-section GDD authoring for a single game system |
 | `/team-combat` | Orchestrate full combat team pipeline |
 | `/team-narrative` | Orchestrate full narrative team pipeline |
 | `/team-ui` | Orchestrate full UI team pipeline |
@@ -135,6 +137,11 @@ Templates are in `.claude/docs/templates/`:
 - `pitch-document.md` -- for pitching the game to stakeholders
 - `economy-model.md` -- for virtual economy design (sink/faucet model)
 - `faction-design.md` -- for faction identity, lore, and gameplay role
+- `systems-index.md` -- for systems decomposition and dependency mapping
+- `project-stage-report.md` -- for project stage detection output
+- `design-doc-from-implementation.md` -- for reverse-documenting existing code into GDDs
+- `architecture-doc-from-code.md` -- for reverse-documenting code into architecture docs
+- `concept-doc-from-prototype.md` -- for reverse-documenting prototypes into concept docs
 
 ### 5. Follow the Coordination Rules
 
@@ -164,10 +171,13 @@ If you already know what you need, jump directly to the relevant path:
    - If the engine version is newer than the LLM's training data, it fetches
      current docs from the web so agents suggest correct APIs
 3. **Validate the concept** — Run `/design-review design/gdd/game-concept.md`
-4. **Test the core loop** — Run `/prototype [core-mechanic]`
+4. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies
-5. **Playtest it** — Run `/playtest-report` to validate the hypothesis
+5. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`)
-6. **Plan the first sprint** — Run `/sprint-plan new`
+   to write GDDs in dependency order
-7. Start building
+6. **Test the core loop** — Run `/prototype [core-mechanic]`
+7. **Playtest it** — Run `/playtest-report` to validate the hypothesis
+8. **Plan the first sprint** — Run `/sprint-plan new`
+9. Start building
 
 ### Path B: "I know what I want to build"
 
@@ -176,10 +186,12 @@ If you already have a game concept and engine choice:
 1. **Set up the engine** — Run `/setup-engine [engine] [version]`
    (e.g., `/setup-engine godot 4.6`) — also creates technical preferences
 2. **Write the Game Pillars** — delegate to `creative-director`
-3. **Create the initial ADR** — Run `/architecture-decision`
+3. **Decompose into systems** — Run `/map-systems` to enumerate systems and dependencies
-4. **Create the first milestone** in `production/milestones/`
+4. **Design each system** — Run `/design-system [system-name]` for GDDs in dependency order
-5. **Plan the first sprint** — Run `/sprint-plan new`
+5. **Create the initial ADR** — Run `/architecture-decision`
-6. Start building
+6. **Create the first milestone** in `production/milestones/`
+7. **Plan the first sprint** — Run `/sprint-plan new`
+8. Start building
 
 ### Path C: "I know the game but not the engine"
 
@@ -207,7 +219,7 @@ CLAUDE.md                          -- Master config (read this first, ~60 lines)
 .claude/
   settings.json                    -- Claude Code hooks and project settings
   agents/                          -- 48 agent definitions (YAML frontmatter)
-  skills/                          -- 35 slash command definitions (YAML frontmatter)
+  skills/                          -- 37 slash command definitions (YAML frontmatter)
   hooks/                           -- 8 hook scripts (.sh) wired by settings.json
   rules/                           -- 11 path-specific rule files
   docs/

.claude/docs/skills-reference.md

@@ -25,15 +25,17 @@
 | `/perf-profile` | Structured performance profiling with bottleneck identification and recommendations |
 | `/project-stage-detect` | Automatically analyze project state, detect stage, identify gaps, and recommend next steps |
 | `/reverse-document` | Generate design or architecture documents from existing implementation (works backwards from code) |
-| `/team-combat` | Orchestrate combat team: game-designer + gameplay-programmer + ai-programmer + tech-artist + sound-designer + qa-tester |
+| `/team-combat` | Orchestrate combat team: game-designer + gameplay-programmer + ai-programmer + technical-artist + sound-designer + qa-tester |
 | `/team-narrative` | Orchestrate narrative team: narrative-director + writer + world-builder + level-designer |
 | `/team-ui` | Orchestrate UI team: ux-designer + ui-programmer + art-director |
 | `/team-release` | Orchestrate release team: release-manager + qa-lead + devops-engineer + producer |
-| `/team-polish` | Orchestrate polish team: performance-analyst + tech-artist + sound-designer + qa-tester |
+| `/team-polish` | Orchestrate polish team: performance-analyst + technical-artist + sound-designer + qa-tester |
 | `/team-audio` | Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer |
 | `/team-level` | Orchestrate level team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester |
 | `/launch-checklist` | Complete launch readiness validation across all departments |
 | `/patch-notes` | Generate player-facing patch notes from git history and internal data |
 | `/brainstorm` | Guided ideation using professional studio methods (MDA, SDT, Bartle, verb-first) |
 | `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/FAIL) |
+| `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order, guide per-system GDDs |
+| `/design-system` | Guided, section-by-section GDD authoring for a single game system with cross-referencing and incremental writing |
 | `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs |

.claude/docs/templates/collaborative-protocols/design-agent-protocol.md

@@ -16,12 +16,14 @@ Before proposing any design:
    - What are the constraints (scope, complexity, existing systems)?
    - Any reference games or mechanics the user loves/hates?
    - How does this connect to the game's pillars?
+   - *Use `AskUserQuestion` to batch up to 4 constrained questions at once*
 
 2. **Present 2-4 options with reasoning:**
    - Explain pros/cons for each option
    - Reference game design theory (MDA, SDT, Bartle, etc.)
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
+   - *After the full explanation, use `AskUserQuestion` to capture the decision*
 
 3. **Draft based on user's choice:**
    - Create sections iteratively (show one section, get feedback, refine)
@@ -102,4 +104,54 @@ You: [uses Write tool]
 - Explain WHY you recommend something (theory, examples, pillar alignment)
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
+
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write your full analysis in conversation text: detailed
+   pros/cons, theory references, example games, pillar alignment. This is where
+   the expert reasoning lives — don't try to fit it into the tool.
+
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels
+   and short descriptions. The user picks from the UI or types a custom answer.
+
+**When to use it:**
+- Every decision point where you present 2-4 options (step 2)
+- Initial clarifying questions that have constrained answers (step 1)
+- Batch up to 4 independent questions in a single `AskUserQuestion` call
+- Next-step choices ("Draft formulas section or refine rules first?")
+
+**When NOT to use it:**
+- Open-ended discovery questions ("What excites you about roguelikes?")
+- Single yes/no confirmations ("May I write to file?")
+- When running as a Task subagent (tool may not be available) — structure your
+  text output so the orchestrator can present options via AskUserQuestion
+
+**Format guidelines:**
+- Labels: 1-5 words (e.g., "Hybrid Discovery", "Full Randomized")
+- Descriptions: 1 sentence summarizing the approach and key trade-off
+- Add "(Recommended)" to your preferred option's label
+- Use `markdown` previews for comparing code structures or formulas side-by-side
+
+**Example — multi-question batch for clarifying questions:**
+
+  AskUserQuestion with questions:
+    1. question: "Should crafting recipes be discovered or learned?"
+       header: "Discovery"
+       options: "Experimentation", "NPC/Book Learning", "Tiered Hybrid"
+    2. question: "How punishing should failed crafts be?"
+       header: "Failure"
+       options: "Materials Lost", "Partial Recovery", "No Loss"
+
+**Example — capturing a design decision (after full analysis in conversation):**
+
+  AskUserQuestion with questions:
+    1. question: "Which crafting approach fits your vision?"
+       header: "Approach"
+       options:
+         "Hybrid Discovery (Recommended)" — balances exploration and accessibility
+         "Full Discovery" — maximum mystery, risk of frustration
+         "Hint System" — accessible but less surprise
 ```

.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md

@@ -21,6 +21,7 @@ Before writing any code:
    - "Where should [data] live? (CharacterStats? Equipment class? Config file?)"
    - "The design doc doesn't specify [edge case]. What should happen when...?"
    - "This will require changes to [other system]. Should I coordinate with that first?"
+   - *Use `AskUserQuestion` to batch constrained architecture questions*
 
 3. **Propose architecture before implementing:**
    - Show class structure, file organization, data flow
@@ -119,4 +120,33 @@ You: [creates tests/combat/test_damage_calculator.gd]
 - Flag deviations from design docs explicitly — designer should know if implementation differs
 - Rules are your friend — when they flag issues, they're usually right
 - Tests prove it works — offer to write them proactively
+
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool for architecture decisions and next-step choices.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Describe the architectural options and trade-offs in
+   conversation text.
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**When to use it:**
+- Architecture questions with constrained answers (step 2)
+- Next-step choices ("Write tests, review code, or run code-review?")
+- Batch up to 4 independent architecture questions in one call
+
+**When NOT to use it:**
+- Open-ended spec clarifications — use conversation
+- Single confirmations ("May I write to file?")
+- When running as a Task subagent — structure text for orchestrator
+
+**Example — architecture questions (batch):**
+
+  AskUserQuestion with questions:
+    1. question: "Where should DamageCalculator live?"
+       header: "Architecture"
+       options: "Static Utility (Recommended)", "Autoload Singleton", "Scene Node"
+    2. question: "How should damage be rounded?"
+       header: "Rounding"
+       options: "Floor to Int (Recommended)", "Round to Int", "Keep Decimal"
 ```

.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md

@@ -15,6 +15,7 @@ When the user asks you to make a decision or resolve a conflict:
    - Ask questions to understand all perspectives
    - Review relevant docs (pillars, constraints, prior decisions)
    - Identify what's truly at stake (often deeper than the surface question)
+   - *Use `AskUserQuestion` to batch up to 4 constrained questions at once*
 
 2. **Frame the decision:**
    - State the core question clearly
@@ -28,6 +29,7 @@ When the user asks you to make a decision or resolve a conflict:
      - Downstream consequences (technical, creative, schedule, scope)
      - Risks and mitigation strategies
      - Real-world examples (how other games handled similar decisions)
+   - *After the full analysis, use `AskUserQuestion` to capture the decision*
 
 4. **Make a clear recommendation:**
    - "I recommend Option [X] because..."
@@ -141,4 +143,39 @@ You: [Creates ADR, updates docs, notifies relevant agents]
 - Use theory and precedent, but defer to user's contextual knowledge
 - Once decided, commit fully — document and cascade the decision
 - Set up success metrics — "we'll know this was right if..."
+
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full strategic analysis in conversation: options with
+   pillar alignment, downstream consequences, risk assessment, recommendation.
+
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**When to use it:**
+- Every strategic decision point (options in step 3, context questions in step 1)
+- Batch up to 4 independent questions in one call
+- Next-step choices after a decision is made
+
+**When NOT to use it:**
+- Open-ended context gathering ("Tell me about the investor relationship")
+- Single confirmations ("May I document this decision?")
+- When running as a Task subagent — structure text for orchestrator
+
+**Format guidelines:**
+- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
+- Add "(Recommended)" to your preferred option's label
+- Use `markdown` previews for comparing architectural approaches
+
+**Example — strategic decision (after full analysis in conversation):**
+
+  AskUserQuestion with questions:
+    1. question: "How should we handle crafting scope for Alpha?"
+       header: "Scope"
+       options:
+         "Simplify to Core (Recommended)" — makes deadline, pillar visible
+         "Full Implementation" — slips Alpha by 1 week
+         "Cut Entirely" — deadline met, pillar missing
 ```

.claude/docs/templates/game-concept.md

@@ -307,8 +307,9 @@ the combat-crafting loop engaging for 30+ minute sessions"]
 ## Next Steps
 
 - [ ] Get concept approval from creative-director
-- [ ] Fill in CLAUDE.md technology stack based on engine choice
+- [ ] Fill in CLAUDE.md technology stack based on engine choice (`/setup-engine`)
 - [ ] Create game pillars document (`/design-review` to validate)
+- [ ] Decompose concept into systems (`/map-systems` — maps dependencies, assigns priorities, guides per-system GDD writing)
 - [ ] Create first architecture decision record (`/architecture-decision`)
 - [ ] Prototype core loop (`/prototype [core-mechanic]`)
 - [ ] Validate core loop with playtest (`/playtest-report`)

.claude/docs/templates/project-stage-report.md

@@ -1,7 +1,7 @@
 # Project Stage Analysis Report
 
 **Generated**: [DATE]
-**Stage**: [Concept | Pre-production | Production | Post-Launch]
+**Stage**: [Concept | Systems Design | Technical Setup | Pre-Production | Production | Polish | Release]
 **Analysis Scope**: [Full project | Specific role: programmer/designer/producer]
 
 ---

.claude/docs/templates/systems-index.md

@@ -0,0 +1,146 @@
+# Systems Index: [Game Title]
+
+> **Status**: [Draft / Under Review / Approved]
+> **Created**: [Date]
+> **Last Updated**: [Date]
+> **Source Concept**: design/gdd/game-concept.md
+
+---
+
+## Overview
+
+[One paragraph explaining the game's mechanical scope. What kind of systems does
+this game need? Reference the core loop and game pillars. This should help any
+team member understand the "big picture" of what needs to be designed and built.]
+
+---
+
+## Systems Enumeration
+
+| # | System Name | Category | Priority | Status | Design Doc | Depends On |
+|---|-------------|----------|----------|--------|------------|------------|
+| 1 | [e.g., Player Controller] | Core | MVP | [Not Started / In Design / In Review / Approved / Implemented] | [design/gdd/player-controller.md or "—"] | [e.g., Input System, Physics] |
+| 2 | [e.g., Camera System] | Core | MVP | Not Started | — | Player Controller |
+
+[Add a row for every identified system. Use the categories and priority tiers
+defined below. Mark systems that were inferred (not explicitly in the concept doc)
+with "(inferred)" in the system name.]
+
+---
+
+## Categories
+
+| Category | Description | Typical Systems |
+|----------|-------------|-----------------|
+| **Core** | Foundation systems everything depends on | Player controller, input, physics, camera, scene management, state machine |
+| **Gameplay** | The systems that make the game fun | Combat, AI, stealth, movement abilities, interaction |
+| **Progression** | How the player grows over time | XP/leveling, skill trees, unlocks, achievements, reputation |
+| **Economy** | Resource creation and consumption | Currency, loot, crafting, shops, item database, drop tables |
+| **Persistence** | Save state and continuity | Save/load, settings, cloud sync, profile management |
+| **UI** | Player-facing information displays | HUD, menus, inventory screen, dialogue UI, map, notifications |
+| **Audio** | Sound and music systems | Music manager, SFX bus, ambient audio, adaptive music, voice |
+| **Narrative** | Story and dialogue delivery | Dialogue system, quest tracking, cutscenes, journal, lore entries |
+| **Meta** | Systems outside the core game loop | Analytics, tutorials/onboarding, accessibility options, photo mode |
+
+[Not every game needs every category. Remove categories that don't apply.
+Add custom categories if needed.]
+
+---
+
+## Priority Tiers
+
+| Tier | Definition | Target Milestone | Design Urgency |
+|------|------------|------------------|----------------|
+| **MVP** | Required for the core loop to function. Without these, you can't test "is this fun?" | First playable prototype | Design FIRST |
+| **Vertical Slice** | Required for one complete, polished area. Demonstrates the full experience. | Vertical slice / demo | Design SECOND |
+| **Alpha** | All features present in rough form. Complete mechanical scope, placeholder content OK. | Alpha milestone | Design THIRD |
+| **Full Vision** | Polish, edge cases, nice-to-haves, and content-complete features. | Beta / Release | Design as needed |
+
+---
+
+## Dependency Map
+
+[Systems sorted by dependency order — design and build from top to bottom.
+Systems at the top are foundations; systems at the bottom are wrappers.]
+
+### Foundation Layer (no dependencies)
+
+1. [System] — [one-line rationale for why this is foundational]
+
+### Core Layer (depends on foundation)
+
+1. [System] — depends on: [list]
+
+### Feature Layer (depends on core)
+
+1. [System] — depends on: [list]
+
+### Presentation Layer (depends on features)
+
+1. [System] — depends on: [list]
+
+### Polish Layer (depends on everything)
+
+1. [System] — depends on: [list]
+
+---
+
+## Recommended Design Order
+
+[Combining dependency sort and priority tiers. Design these systems in this
+order. Each system's GDD should be completed and reviewed before starting the
+next, though independent systems at the same layer can be designed in parallel.]
+
+| Order | System | Priority | Layer | Agent(s) | Est. Effort |
+|-------|--------|----------|-------|----------|-------------|
+| 1 | [First system to design] | MVP | Foundation | game-designer | [S/M/L] |
+| 2 | [Second system] | MVP | Foundation | game-designer | [S/M/L] |
+
+[Effort estimates: S = 1 session, M = 2-3 sessions, L = 4+ sessions.
+A "session" is one focused design conversation producing a complete GDD.]
+
+---
+
+## Circular Dependencies
+
+[List any circular dependency chains found during analysis. These require
+special architectural attention — either break the cycle with an interface,
+or design the systems simultaneously.]
+
+- [None found] OR
+- [System A <-> System B: Description of the circular relationship and
+  proposed resolution]
+
+---
+
+## High-Risk Systems
+
+[Systems that are technically unproven, design-uncertain, or scope-dangerous.
+These should be prototyped early regardless of priority tier.]
+
+| System | Risk Type | Risk Description | Mitigation |
+|--------|-----------|-----------------|------------|
+| [System] | [Technical / Design / Scope] | [What could go wrong] | [Prototype, research, or scope fallback] |
+
+---
+
+## Progress Tracker
+
+| Metric | Count |
+|--------|-------|
+| Total systems identified | [N] |
+| Design docs started | [N] |
+| Design docs reviewed | [N] |
+| Design docs approved | [N] |
+| MVP systems designed | [N/total MVP] |
+| Vertical Slice systems designed | [N/total VS] |
+
+---
+
+## Next Steps
+
+- [ ] Review and approve this systems enumeration
+- [ ] Design MVP-tier systems first (use `/design-system [system-name]`)
+- [ ] Run `/design-review` on each completed GDD
+- [ ] Run `/gate-check pre-production` when MVP systems are designed
+- [ ] Prototype the highest-risk system early (`/prototype [system]`)

.claude/hooks/detect-gaps.sh

@@ -15,7 +15,7 @@ FRESH_PROJECT=true
 # Check if engine is configured
 if [ -f ".claude/docs/technical-preferences.md" ]; then
   ENGINE_LINE=$(grep -E "^\- \*\*Engine\*\*:" .claude/docs/technical-preferences.md 2>/dev/null)
-  if echo "$ENGINE_LINE" | grep -qv "TO BE CONFIGURED" 2>/dev/null; then
+  if [ -n "$ENGINE_LINE" ] && ! echo "$ENGINE_LINE" | grep -q "TO BE CONFIGURED" 2>/dev/null; then
     FRESH_PROJECT=false
   fi
 fi
@@ -151,3 +151,5 @@ fi
 echo ""
 echo "💡 To get a comprehensive project analysis, run: /project-stage-detect"
 echo "==================================="
+
+exit 0

.claude/hooks/log-agent.sh

@@ -3,7 +3,7 @@
 # Tracks which agents are being used and when
 #
 # Input schema (SubagentStart):
-# { "agent_name": "game-designer", "model": "sonnet", ... }
+# { "agent_id": "agent-abc123", "agent_name": "game-designer", ... }
 
 INPUT=$(cat)
 
@@ -11,7 +11,7 @@ INPUT=$(cat)
 if command -v jq >/dev/null 2>&1; then
     AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_name // "unknown"' 2>/dev/null)
 else
-    AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_name"\s*:\s*"[^"]*"' | sed 's/"agent_name"\s*:\s*"//;s/"$//')
+    AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_name"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"agent_name"[[:space:]]*:[[:space:]]*"//;s/"$//')
     [ -z "$AGENT_NAME" ] && AGENT_NAME="unknown"
 fi
 

.claude/hooks/pre-compact.sh

@@ -1,15 +1,82 @@
 #!/bin/bash
-# Claude Code PreCompact hook: Save session state before context compression
+# Claude Code PreCompact hook: Dump session state before context compression
-# Ensures progress notes survive context window compression
+# This output appears in the conversation right before compaction, ensuring
+# critical state survives the summarization process.
 
-TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+echo "=== SESSION STATE BEFORE COMPACTION ==="
+echo "Timestamp: $(date)"
+
+# --- Active session state file ---
+STATE_FILE="production/session-state/active.md"
+if [ -f "$STATE_FILE" ]; then
+    echo ""
+    echo "## Active Session State (from $STATE_FILE)"
+    STATE_LINES=$(wc -l < "$STATE_FILE" 2>/dev/null | tr -d ' ')
+    if [ "$STATE_LINES" -gt 100 ] 2>/dev/null; then
+        head -n 100 "$STATE_FILE"
+        echo "... (truncated — $STATE_LINES total lines, showing first 100)"
+    else
+        cat "$STATE_FILE"
+    fi
+else
+    echo ""
+    echo "## No active session state file found"
+    echo "Consider maintaining production/session-state/active.md for better recovery."
+fi
+
+# --- Files modified this session (unstaged + staged + untracked) ---
+echo ""
+echo "## Files Modified (git working tree)"
+
+CHANGED=$(git diff --name-only 2>/dev/null)
+STAGED=$(git diff --staged --name-only 2>/dev/null)
+UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null)
+
+if [ -n "$CHANGED" ]; then
+    echo "Unstaged changes:"
+    echo "$CHANGED" | while read -r f; do echo "  - $f"; done
+fi
+if [ -n "$STAGED" ]; then
+    echo "Staged changes:"
+    echo "$STAGED" | while read -r f; do echo "  - $f"; done
+fi
+if [ -n "$UNTRACKED" ]; then
+    echo "New untracked files:"
+    echo "$UNTRACKED" | while read -r f; do echo "  - $f"; done
+fi
+if [ -z "$CHANGED" ] && [ -z "$STAGED" ] && [ -z "$UNTRACKED" ]; then
+    echo "  (no uncommitted changes)"
+fi
+
+# --- Work-in-progress design docs ---
+echo ""
+echo "## Design Docs — Work In Progress"
+
+WIP_FOUND=false
+for f in design/gdd/*.md; do
+    [ -f "$f" ] || continue
+    INCOMPLETE=$(grep -n -E "TODO|WIP|PLACEHOLDER|\[TO BE|\[TBD\]" "$f" 2>/dev/null)
+    if [ -n "$INCOMPLETE" ]; then
+        WIP_FOUND=true
+        echo "  $f:"
+        echo "$INCOMPLETE" | while read -r line; do echo "    $line"; done
+    fi
+done
+
+if [ "$WIP_FOUND" = false ]; then
+    echo "  (no WIP markers found in design docs)"
+fi
+
+# --- Log compaction event ---
 SESSION_LOG_DIR="production/session-logs"
-
-# Create session log directory if it doesn't exist
 mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
-
+echo "Context compaction occurred at $(date)." \
-# Save a marker file noting that compaction occurred
-echo "Context compaction occurred at $(date). Session state may have been compressed." \
     >> "$SESSION_LOG_DIR/compaction-log.txt" 2>/dev/null
 
+echo ""
+echo "## Recovery Instructions"
+echo "After compaction, read $STATE_FILE to recover full working context."
+echo "Then read any files listed above that are being actively worked on."
+echo "=== END SESSION STATE ==="
+
 exit 0

.claude/hooks/session-start.sh

@@ -54,5 +54,22 @@ if [ -d "src" ]; then
     fi
 fi
 
+# --- Active session state recovery ---
+STATE_FILE="production/session-state/active.md"
+if [ -f "$STATE_FILE" ]; then
+    echo ""
+    echo "=== ACTIVE SESSION STATE DETECTED ==="
+    echo "A previous session left state at: $STATE_FILE"
+    echo "Read this file to recover context and continue where you left off."
+    echo ""
+    echo "Quick summary:"
+    head -20 "$STATE_FILE" 2>/dev/null
+    TOTAL_LINES=$(wc -l < "$STATE_FILE" 2>/dev/null)
+    if [ "$TOTAL_LINES" -gt 20 ]; then
+        echo "  ... ($TOTAL_LINES total lines — read the full file to continue)"
+    fi
+    echo "=== END SESSION STATE PREVIEW ==="
+fi
+
 echo "==================================="
 exit 0

.claude/hooks/session-stop.sh

@@ -7,10 +7,23 @@ SESSION_LOG_DIR="production/session-logs"
 
 mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
 
-# Log recent git activity from this session
+# Log recent git activity from this session (check up to 8 hours for long sessions)
-RECENT_COMMITS=$(git log --oneline --since="1 hour ago" 2>/dev/null)
+RECENT_COMMITS=$(git log --oneline --since="8 hours ago" 2>/dev/null)
 MODIFIED_FILES=$(git diff --name-only 2>/dev/null)
 
+# --- Clean up active session state on normal shutdown ---
+STATE_FILE="production/session-state/active.md"
+if [ -f "$STATE_FILE" ]; then
+    # Archive to session log before removing
+    {
+        echo "## Archived Session State: $TIMESTAMP"
+        cat "$STATE_FILE"
+        echo "---"
+        echo ""
+    } >> "$SESSION_LOG_DIR/session-log.md" 2>/dev/null
+    rm "$STATE_FILE" 2>/dev/null
+fi
+
 if [ -n "$RECENT_COMMITS" ] || [ -n "$MODIFIED_FILES" ]; then
     {
         echo "## Session End: $TIMESTAMP"

.claude/hooks/validate-assets.sh

@@ -12,7 +12,7 @@ INPUT=$(cat)
 if command -v jq >/dev/null 2>&1; then
     FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 else
-    FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"\s*:\s*"[^"]*"' | sed 's/"file_path"\s*:\s*"//;s/"$//')
+    FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
 fi
 
 # Normalize path separators (Windows backslash to forward slash)

.claude/hooks/validate-commit.sh

@@ -12,7 +12,7 @@ INPUT=$(cat)
 if command -v jq >/dev/null 2>&1; then
     COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 else
-    COMMAND=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | sed 's/"command"\s*:\s*"//;s/"$//')
+    COMMAND=$(echo "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
 fi
 
 # Only process git commit commands
@@ -31,15 +31,15 @@ WARNINGS=""
 # Check design documents for required sections
 DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/')
 if [ -n "$DESIGN_FILES" ]; then
-    for file in $DESIGN_FILES; do
+    while IFS= read -r file; do
         if [[ "$file" == *.md ]] && [ -f "$file" ]; then
-            for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do
+            for section in "Overview" "Player Fantasy" "Detailed" "Formulas" "Edge Cases" "Dependencies" "Tuning Knobs" "Acceptance Criteria"; do
                 if ! grep -qi "$section" "$file"; then
                     WARNINGS="$WARNINGS\nDESIGN: $file missing required section: $section"
                 fi
             done
         fi
-    done
+    done <<< "$DESIGN_FILES"
 fi
 
 # Validate JSON data files -- block invalid JSON
@@ -54,7 +54,7 @@ if [ -n "$DATA_FILES" ]; then
         fi
     done
 
-    for file in $DATA_FILES; do
+    while IFS= read -r file; do
         if [ -f "$file" ]; then
             if [ -n "$PYTHON_CMD" ]; then
                 if ! "$PYTHON_CMD" -m json.tool "$file" > /dev/null 2>&1; then
@@ -65,32 +65,32 @@ if [ -n "$DATA_FILES" ]; then
                 echo "WARNING: Cannot validate JSON (python not found): $file" >&2
             fi
         fi
-    done
+    done <<< "$DATA_FILES"
 fi
 
 # Check for hardcoded gameplay values in gameplay code
 # Uses grep -E (POSIX extended) instead of grep -P (Perl) for cross-platform compatibility
 CODE_FILES=$(echo "$STAGED" | grep -E '^src/gameplay/')
 if [ -n "$CODE_FILES" ]; then
-    for file in $CODE_FILES; do
+    while IFS= read -r file; do
         if [ -f "$file" ]; then
             if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file" 2>/dev/null; then
                 WARNINGS="$WARNINGS\nCODE: $file may contain hardcoded gameplay values. Use data files."
             fi
         fi
-    done
+    done <<< "$CODE_FILES"
 fi
 
 # Check for TODO/FIXME without assignee -- uses grep -E instead of grep -P
 SRC_FILES=$(echo "$STAGED" | grep -E '^src/')
 if [ -n "$SRC_FILES" ]; then
-    for file in $SRC_FILES; do
+    while IFS= read -r file; do
         if [ -f "$file" ]; then
             if grep -nE '(TODO|FIXME|HACK)[^(]' "$file" 2>/dev/null; then
                 WARNINGS="$WARNINGS\nSTYLE: $file has TODO/FIXME without owner tag. Use TODO(name) format."
             fi
         fi
-    done
+    done <<< "$SRC_FILES"
 fi
 
 # Print warnings (non-blocking) and allow commit

.claude/hooks/validate-push.sh

@@ -12,7 +12,7 @@ INPUT=$(cat)
 if command -v jq >/dev/null 2>&1; then
     COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 else
-    COMMAND=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | sed 's/"command"\s*:\s*"//;s/"$//')
+    COMMAND=$(echo "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
 fi
 
 # Only process git push commands
@@ -21,23 +21,23 @@ if ! echo "$COMMAND" | grep -qE '^git[[:space:]]+push'; then
 fi
 
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
-FULL_GATE=false
+MATCHED_BRANCH=""
 
 # Check if pushing to a protected branch
 for branch in develop main master; do
     if [ "$CURRENT_BRANCH" = "$branch" ]; then
-        FULL_GATE=true
+        MATCHED_BRANCH="$branch"
         break
     fi
     # Also check if pushing to a protected branch explicitly (quote branch name for safety)
     if echo "$COMMAND" | grep -qE "[[:space:]]${branch}([[:space:]]|$)"; then
-        FULL_GATE=true
+        MATCHED_BRANCH="$branch"
         break
     fi
 done
 
-if [ "$FULL_GATE" = true ]; then
+if [ -n "$MATCHED_BRANCH" ]; then
-    echo "Push to protected branch '$CURRENT_BRANCH' detected." >&2
+    echo "Push to protected branch '$MATCHED_BRANCH' detected." >&2
     echo "Reminder: Ensure build passes, unit tests pass, and no S1/S2 bugs exist." >&2
     # Allow the push but warn -- uncomment below to block instead:
     # echo "BLOCKED: Run tests before pushing to $CURRENT_BRANCH" >&2

.claude/rules/design-docs.md

@@ -13,3 +13,6 @@ paths:
 - Acceptance criteria must be testable — a QA tester must be able to verify pass/fail
 - No hand-waving: "the system should feel good" is not a valid specification
 - Balance values must link to their source formula or rationale
+- Design documents MUST be written incrementally: create skeleton first, then fill
+  each section one at a time with user approval between sections. Write each
+  approved section to the file immediately to persist decisions and manage context

.claude/settings.json

@@ -1,5 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "statusLine": {
+    "type": "command",
+    "command": "bash .claude/statusline.sh"
+  },
   "permissions": {
     "allow": [
       "Bash(git status*)",
@@ -81,7 +85,7 @@
           {
             "type": "command",
             "command": "bash .claude/hooks/pre-compact.sh",
-            "timeout": 5
+            "timeout": 10
           }
         ]
       }

.claude/skills/brainstorm/SKILL.md

@@ -3,7 +3,7 @@ name: brainstorm
 description: "Guided game concept ideation — from zero idea to a structured game concept document. Uses professional studio ideation techniques, player psychology frameworks, and structured creative exploration."
 argument-hint: "[genre or theme hint, or 'open' for fully open brainstorm]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, WebSearch
+allowed-tools: Read, Glob, Grep, Write, WebSearch, AskUserQuestion
 ---
 
 When this skill is invoked:
@@ -21,6 +21,14 @@ When this skill is invoked:
    exploration** where the AI acts as a creative facilitator, not a replacement
    for the human's vision.
 
+   **Use `AskUserQuestion`** at key decision points throughout brainstorming:
+   - Constrained taste questions (genre preferences, scope, team size)
+   - Concept selection ("Which 2-3 concepts resonate?") after presenting options
+   - Direction choices ("Develop further, explore more, or prototype?")
+   - Pillar ranking after concepts are refined
+   Write full creative analysis in conversation text first, then use
+   `AskUserQuestion` to capture the decision with concise labels.
+
    Professional studio brainstorming principles to follow:
    - Withhold judgment — no idea is bad during exploration
    - Encourage unusual ideas — outside-the-box thinking sparks better concepts
@@ -192,6 +200,8 @@ Ground the concept in reality:
    - "Run `/setup-engine [engine] [version]` to configure the engine and populate version-aware reference docs"
    - "Use `/design-review design/gdd/game-concept.md` to validate completeness"
    - "Discuss vision with the `creative-director` agent for pillar refinement"
+   - "Decompose the concept into individual systems with `/map-systems` — maps dependencies, assigns priorities, and creates the systems index"
+   - "Author per-system GDDs with `/design-system` — guided, section-by-section GDD writing"
    - "Prototype the core loop with `/prototype [core-mechanic]`"
    - "Playtest the prototype with `/playtest-report` to validate the hypothesis"
    - "If validated, plan the first sprint with `/sprint-plan new`"

.claude/skills/design-review/SKILL.md

@@ -62,3 +62,19 @@ When this skill is invoked:
 
 ### Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]
 ```
+
+9. **Contextual next step recommendations**:
+   - If the document being reviewed is `game-concept.md` or `game-pillars.md`:
+     - Check if `design/gdd/systems-index.md` exists
+     - If it does NOT exist, add to Recommendations:
+       > "This concept is ready for systems decomposition. Run `/map-systems`
+       > to break it down into individual systems with dependencies and priorities,
+       > then write per-system GDDs."
+   - If the document is an individual system GDD:
+     - Check if the systems index references this system
+     - If verdict is APPROVED: suggest "Update the systems index status for
+       this system to 'Approved'."
+     - If verdict is NEEDS REVISION or MAJOR REVISION NEEDED: suggest "Update
+       the systems index status for this system to 'In Review'."
+     - Note: This skill is read-only. The user (or `/design-system`) must
+       perform the actual status update in the systems index.

.claude/skills/design-system/SKILL.md

@@ -0,0 +1,496 @@
+---
+name: design-system
+description: "Guided, section-by-section GDD authoring for a single game system. Gathers context from existing docs, walks through each required section collaboratively, cross-references dependencies, and writes incrementally to file."
+argument-hint: "<system-name> (e.g., 'combat-system', 'inventory', 'dialogue')"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite
+---
+
+When this skill is invoked:
+
+## 1. Parse Arguments & Validate
+
+A system name argument is **required**. If missing, fail with:
+> "Usage: `/design-system <system-name>` — e.g., `/design-system combat-system`
+> Run `/map-systems` first to create the systems index, then use this skill
+> to write individual system GDDs."
+
+Normalize the system name to kebab-case for the filename (e.g., "combat system"
+becomes `combat-system`).
+
+---
+
+## 2. Gather Context (Read Phase)
+
+Read all relevant context **before** asking the user anything. This is the skill's
+primary advantage over ad-hoc design — it arrives informed.
+
+### 2a: Required Reads
+
+- **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?"
+
+### 2b: Dependency Reads
+
+From the systems index, identify:
+- **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).
+
+For each dependency GDD that exists, extract and hold in context:
+- 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
+
+### 2c: Optional Reads
+
+- **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 "status-effects", also read "combat-system" even if it's not
+  a direct dependency)
+
+### 2d: Present Context Summary
+
+Before starting design work, present a brief summary to the user:
+
+> **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]
+
+If any upstream dependencies are undesigned, warn:
+> "[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."
+
+Use `AskUserQuestion`:
+- "Ready to start designing [system-name]?"
+  - Options: "Yes, let's go", "Show me more context first", "Design a dependency first"
+
+---
+
+## 3. Create File Skeleton
+
+Once the user confirms, **immediately** create the GDD file with empty section
+headers. This ensures incremental writes have a target.
+
+Use the template structure from `.claude/docs/templates/game-design-document.md`:
+
+```markdown
+# [System Name]
+
+> **Status**: In Design
+> **Author**: [user + agents]
+> **Last Updated**: [today's date]
+> **Implements Pillar**: [from context]
+
+## Overview
+
+[To be designed]
+
+## Player Fantasy
+
+[To be designed]
+
+## Detailed Design
+
+### Core Rules
+
+[To be designed]
+
+### States and Transitions
+
+[To be designed]
+
+### Interactions with Other Systems
+
+[To be designed]
+
+## Formulas
+
+[To be designed]
+
+## Edge Cases
+
+[To be designed]
+
+## Dependencies
+
+[To be designed]
+
+## Tuning Knobs
+
+[To be designed]
+
+## Visual/Audio Requirements
+
+[To be designed]
+
+## UI Requirements
+
+[To be designed]
+
+## Acceptance Criteria
+
+[To be designed]
+
+## Open Questions
+
+[To be designed]
+```
+
+Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?"
+
+After writing, update `production/session-state/active.md` with:
+- Task: Designing [system-name] GDD
+- Current section: Starting (skeleton created)
+- File: design/gdd/[system-name].md
+
+---
+
+## 4. Section-by-Section Design
+
+Walk through each section in order. For **each section**, follow this cycle:
+
+### The Section Cycle
+
+```
+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**: Ask "Approve this section, or would you like changes?"
+
+7. **Write**: Use the Edit tool to replace the `[To be designed]` placeholder with
+   the approved content. Confirm the write.
+
+After writing each section, update `production/session-state/active.md` with the
+completed section name.
+
+### Section-Specific Guidance
+
+Each section has unique design considerations and may benefit from specialist agents:
+
+---
+
+### Section A: Overview
+
+**Goal**: One paragraph a stranger could read and understand.
+
+**Questions to ask**:
+- 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?
+
+**Cross-reference**: Check that the description aligns with how the systems index
+describes it. Flag discrepancies.
+
+---
+
+### Section B: Player Fantasy
+
+**Goal**: The emotional target — what the player should *feel*.
+
+**Questions to ask**:
+- 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"?
+
+**Cross-reference**: Must align with the game pillars. If the system serves a pillar,
+quote the relevant pillar text.
+
+---
+
+### Section C: Detailed Design (Core Rules, States, Interactions)
+
+**Goal**: Unambiguous specification a programmer could implement without questions.
+
+This is usually the largest section. Break it into sub-sections:
+
+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.
+
+**Questions to ask**:
+- 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)
+
+**Agent delegation**: For complex mechanics, use the Task tool to delegate to
+`game-designer` for high-level design review, or `systems-designer` for detailed
+mechanical modeling. Provide the full context gathered in Phase 2.
+
+**Cross-reference**: For each interaction listed, verify it matches what the
+dependency GDD specifies. If the dependency says "damage is calculated as X" and
+this system expects something different, flag the conflict.
+
+---
+
+### Section D: Formulas
+
+**Goal**: Every mathematical formula, with variables defined, ranges specified,
+and edge cases noted.
+
+**Questions to ask**:
+- 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?
+
+**Agent delegation**: For formula-heavy systems (combat, economy, progression),
+delegate to `systems-designer` via the Task tool. Provide:
+- The Core Rules from Section C (already written to file)
+- Tuning goals from the user
+- Balance context from dependency GDDs
+
+The agent should return proposed formulas with variable tables and expected output
+ranges. Present these to the user for review before approving.
+
+**Cross-reference**: If a dependency GDD defines a formula whose output feeds into
+this system, reference it explicitly. Don't reinvent — connect.
+
+---
+
+### Section E: Edge Cases
+
+**Goal**: Explicitly handle unusual situations so they don't become bugs.
+
+**Questions to ask**:
+- What happens at zero? At maximum? At negative values?
+- What happens when two effects trigger simultaneously?
+- What happens if the player tries to exploit this? (Identify degenerate strategies)
+
+**Agent delegation**: For systems with complex interactions, delegate to
+`systems-designer` to identify edge cases from the formula space. For narrative
+systems, consult `narrative-director` for story-breaking edge cases.
+
+**Cross-reference**: Check edge cases against dependency GDDs. If combat says
+"damage cannot go below 1" but this system can reduce damage to 0, that's a
+conflict to resolve.
+
+---
+
+### Section F: Dependencies
+
+**Goal**: Map every system connection with direction and nature.
+
+This section is partially pre-filled from the context gathering phase. Present the
+known dependencies from the systems index and ask:
+- 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)?
+
+**Cross-reference**: This section must be bidirectionally consistent. If this system
+lists "depends on Combat", then the Combat GDD should list "depended on by [this
+system]". Flag any one-directional dependencies for correction.
+
+---
+
+### Section G: Tuning Knobs
+
+**Goal**: Every designer-adjustable value, with safe ranges and extreme behaviors.
+
+**Questions to ask**:
+- 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)
+
+**Agent delegation**: If formulas are complex, delegate to `systems-designer`
+to derive tuning knobs from the formula variables.
+
+**Cross-reference**: If a dependency GDD lists tuning knobs that affect this system,
+reference them here. Don't create duplicate knobs — point to the source of truth.
+
+---
+
+### Section H: Acceptance Criteria
+
+**Goal**: Testable conditions that prove the system works as designed.
+
+**Questions to ask**:
+- 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?
+
+**Cross-reference**: Include criteria that verify cross-system interactions work,
+not just this system in isolation.
+
+---
+
+### Optional Sections: Visual/Audio, UI Requirements, Open Questions
+
+These sections are included in the template but aren't part of the 8 required
+sections. Offer them after the required sections are done:
+
+Use `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"
+
+For **Visual/Audio**: Coordinate with `art-director` and `audio-director` if detail
+is needed. Often a brief note suffices at the GDD stage.
+
+For **UI Requirements**: Coordinate with `ux-designer` for complex UI systems.
+
+For **Open Questions**: Capture anything that came up during design that wasn't
+fully resolved. Each question should have an owner and target resolution date.
+
+---
+
+## 5. Post-Design Validation
+
+After all sections are written:
+
+### 5a: Self-Check
+
+Read back the complete GDD from file (not from conversation memory — the file is
+the source of truth). Verify:
+- 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
+
+### 5b: Offer Design Review
+
+Present a completion summary:
+
+> **GDD Complete: [System Name]**
+> - Sections written: [list]
+> - Provisional assumptions: [list any assumptions about undesigned dependencies]
+> - Cross-system conflicts found: [list or "none"]
+
+Use `AskUserQuestion`:
+- "Run `/design-review` now to validate the GDD?"
+  - Options: "Yes, run review now", "I'll review it myself first", "Skip review"
+
+If yes, invoke the design-review skill on the completed file.
+
+### 5c: Update Systems Index
+
+After the GDD is complete (and optionally reviewed):
+
+- 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
+
+Ask: "May I update the systems index at `design/gdd/systems-index.md`?"
+
+### 5d: Update Session State
+
+Update `production/session-state/active.md` with:
+- 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]
+
+### 5e: Suggest Next Steps
+
+Use `AskUserQuestion`:
+- "What's next?"
+  - Options:
+    - "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
+
+---
+
+## 6. Specialist Agent Routing
+
+This skill delegates to specialist agents for domain expertise. The main session
+orchestrates the overall flow; agents provide expert content.
+
+| System Category | Primary Agent | Supporting Agent(s) |
+|----------------|---------------|---------------------|
+| Combat, damage, health | `game-designer` | `systems-designer` (formulas), `ai-programmer` (enemy AI) |
+| Economy, loot, crafting | `economy-designer` | `systems-designer` (curves), `game-designer` (loops) |
+| Progression, XP, skills | `game-designer` | `systems-designer` (curves), `economy-designer` (sinks) |
+| Dialogue, quests, lore | `game-designer` | `narrative-director` (story), `writer` (content) |
+| UI systems (HUD, menus) | `game-designer` | `ux-designer` (flows), `ui-programmer` (feasibility) |
+| Audio systems | `game-designer` | `audio-director` (direction), `sound-designer` (specs) |
+| AI, pathfinding, behavior | `game-designer` | `ai-programmer` (implementation), `systems-designer` (scoring) |
+| Level/world systems | `game-designer` | `level-designer` (spatial), `world-builder` (lore) |
+| Camera, input, controls | `game-designer` | `ux-designer` (feel), `gameplay-programmer` (feasibility) |
+
+**When delegating via Task tool**:
+- 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
+
+---
+
+## 7. Recovery & Resume
+
+If the session is interrupted (compaction, crash, new session):
+
+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
+
+This is why incremental writing matters: every approved section survives any
+disruption.
+
+---
+
+## Collaborative Protocol
+
+This skill follows the collaborative design principle at every step:
+
+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
+
+**Never** auto-generate the full GDD and present it as a fait accompli.
+**Never** write a section without user approval.
+**Never** contradict an existing approved GDD without flagging the conflict.
+**Always** show where decisions come from (dependency GDDs, pillars, user choices).

.claude/skills/gate-check/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: gate-check
 description: "Validate readiness to advance between development phases. Produces a PASS/CONCERNS/FAIL verdict with specific blockers and required artifacts."
-argument-hint: "[target-phase: pre-production | production | alpha | beta | release]"
+argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash
+allowed-tools: Read, Glob, Grep, Bash, Write
 ---
 
 # Phase Gate Validation
@@ -14,6 +14,21 @@ phase. It checks for required artifacts, quality standards, and blockers.
 **Distinct from `/project-stage-detect`**: That skill is diagnostic ("where are we?").
 This skill is prescriptive ("are we ready to advance?" with a formal verdict).
 
+## Production Stages (7)
+
+The project progresses through these stages:
+
+1. **Concept** — Brainstorming, game concept document
+2. **Systems Design** — Mapping systems, writing GDDs
+3. **Technical Setup** — Engine config, architecture decisions
+4. **Pre-Production** — Prototyping, vertical slice validation
+5. **Production** — Feature development (Epic/Feature/Task tracking active)
+6. **Polish** — Performance, playtesting, bug fixing
+7. **Release** — Launch prep, certification
+
+**When a gate passes**, write the new stage name to `production/stage.txt`
+(single line, e.g. `Production`). This updates the status line immediately.
+
 ---
 
 ## 1. Parse Arguments
@@ -26,13 +41,11 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict).
 
 ## 2. Phase Gate Definitions
 
-### Gate: Concept → Pre-production
+### Gate: Concept → Systems Design
 
 **Required Artifacts:**
 - [ ] `design/gdd/game-concept.md` exists and has content
 - [ ] Game pillars defined (in concept doc or `design/gdd/game-pillars.md`)
-- [ ] Engine chosen (CLAUDE.md Technology Stack is not `[CHOOSE]`)
-- [ ] Technical preferences configured (`.claude/docs/technical-preferences.md` populated)
 
 **Quality Checks:**
 - [ ] Game concept has been reviewed (`/design-review` verdict not MAJOR REVISION NEEDED)
@@ -41,24 +54,48 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict).
 
 ---
 
-### Gate: Pre-production → Production
+### Gate: Systems Design → Technical Setup
 
 **Required Artifacts:**
-- [ ] At least 1 GDD in `design/gdd/` (beyond game-concept.md)
+- [ ] Systems index exists at `design/gdd/systems-index.md` with at least MVP systems enumerated
-- [ ] At least 1 Architecture Decision Record in `docs/architecture/`
+- [ ] At least 1 GDD in `design/gdd/` (beyond game-concept.md and systems-index.md)
-- [ ] At least 1 prototype in `prototypes/` with a README
-- [ ] Engine reference docs exist in `docs/engine-reference/`
-- [ ] First sprint plan exists in `production/sprints/`
 
 **Quality Checks:**
 - [ ] GDD(s) pass design review (8 required sections present)
-- [ ] Prototype validates the core loop hypothesis
+- [ ] System dependencies are mapped in the systems index
+- [ ] MVP priority tier is defined
+
+---
+
+### Gate: Technical Setup → Pre-Production
+
+**Required Artifacts:**
+- [ ] Engine chosen (CLAUDE.md Technology Stack is not `[CHOOSE]`)
+- [ ] Technical preferences configured (`.claude/docs/technical-preferences.md` populated)
+- [ ] At least 1 Architecture Decision Record in `docs/architecture/`
+- [ ] Engine reference docs exist in `docs/engine-reference/`
+
+**Quality Checks:**
 - [ ] Architecture decisions cover core systems (rendering, input, state management)
 - [ ] Technical preferences have naming conventions and performance budgets set
 
 ---
 
-### Gate: Production → Alpha
+### Gate: Pre-Production → Production
+
+**Required Artifacts:**
+- [ ] At least 1 prototype in `prototypes/` with a README
+- [ ] First sprint plan exists in `production/sprints/`
+- [ ] All MVP-tier GDDs from systems index are complete
+
+**Quality Checks:**
+- [ ] Prototype validates the core loop hypothesis
+- [ ] Sprint plan references real work items from GDDs
+- [ ] Vertical slice scope is defined
+
+---
+
+### Gate: Production → Polish
 
 **Required Artifacts:**
 - [ ] `src/` has active code organized into subsystems
@@ -75,7 +112,7 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict).
 
 ---
 
-### Gate: Alpha → Beta
+### Gate: Polish → Release
 
 **Required Artifacts:**
 - [ ] All features from milestone plan are implemented
@@ -83,28 +120,16 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict).
 - [ ] Localization strings are externalized (no hardcoded player-facing text in `src/`)
 - [ ] QA test plan exists
 - [ ] Balance data has been reviewed (`/balance-check` run)
-
-**Quality Checks:**
-- [ ] All tests passing
-- [ ] Performance targets met (frame rate, memory, load times)
-- [ ] No critical or high-severity bugs
-- [ ] Accessibility basics covered (remapping, text scaling if applicable)
-- [ ] Save/load system works reliably
-
----
-
-### Gate: Beta → Release
-
-**Required Artifacts:**
 - [ ] Release checklist completed (`/release-checklist` or `/launch-checklist` run)
 - [ ] Store metadata prepared (if applicable)
 - [ ] Changelog / patch notes drafted
-- [ ] Post-launch support plan exists
 
 **Quality Checks:**
 - [ ] Full QA pass signed off by `qa-lead`
+- [ ] All tests passing
 - [ ] Performance targets met across all target platforms
 - [ ] No known critical, high, or medium-severity bugs
+- [ ] Accessibility basics covered (remapping, text scaling if applicable)
 - [ ] Localization verified for all target languages
 - [ ] Legal requirements met (EULA, privacy policy, age ratings if applicable)
 - [ ] Build compiles and packages cleanly
@@ -181,10 +206,28 @@ For items that can't be automatically verified, **ask the user**:
 
 ---
 
-## 6. Follow-Up Actions
+## 6. Update Stage on PASS
+
+When the verdict is **PASS** and the user confirms they want to advance:
+
+1. Write the new stage name to `production/stage.txt` (single line, no trailing newline)
+2. This immediately updates the status line for all future sessions
+
+Example: if passing the "Pre-Production → Production" gate:
+```bash
+echo -n "Production" > production/stage.txt
+```
+
+**Always ask before writing**: "Gate passed. May I update `production/stage.txt` to 'Production'?"
+
+---
+
+## 7. Follow-Up Actions
 
 Based on the verdict, suggest specific next steps:
 
+- **No game concept?** → `/brainstorm` to create one
+- **No systems index?** → `/map-systems` to decompose the concept into systems
 - **Missing design docs?** → `/reverse-document` or delegate to `game-designer`
 - **Missing ADRs?** → `/architecture-decision`
 - **Tests failing?** → delegate to `lead-programmer` or `qa-tester`

.claude/skills/map-systems/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: map-systems
+description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and create the systems index."
+argument-hint: "[optional: 'next' to pick highest-priority undesigned system, or a system name to hand off to /design-system]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite
+---
+
+When this skill is invoked:
+
+## 1. Parse Arguments
+
+Two modes:
+
+- **No argument**: `/map-systems` — Run the full decomposition workflow (Phases 1-5)
+  to create or update the systems index.
+- **`next`**: `/map-systems next` — Pick the highest-priority undesigned system
+  from the index and hand off to `/design-system` (Phase 6).
+
+---
+
+## 2. Phase 1: Read Concept (Required Context)
+
+Read the game concept and any existing design work. This provides the raw material
+for systems decomposition.
+
+**Required:**
+- Read `design/gdd/game-concept.md` — **fail with a clear message if missing**:
+  > "No game concept found at `design/gdd/game-concept.md`. Run `/brainstorm` first
+  > to create one, then come back to decompose it into systems."
+
+**Optional (read if they exist):**
+- Read `design/gdd/game-pillars.md` — pillars constrain priority and scope
+- Read `design/gdd/systems-index.md` — if exists, **resume** from where it left off
+  (update, don't recreate from scratch)
+- Glob `design/gdd/*.md` — check which system GDDs already exist
+
+**If the systems index already exists:**
+- Read it and present current status to the user
+- Use `AskUserQuestion` to ask:
+  "The systems index already exists with [N] systems ([M] designed, [K] not started).
+  What would you like to do?"
+  - Options: "Update the index with new systems", "Design the next undesigned system",
+    "Review and revise priorities"
+
+---
+
+## 3. Phase 2: Systems Enumeration (Collaborative)
+
+Extract and identify all systems the game needs. This is the creative core of the
+skill — it requires human judgment because concept docs rarely enumerate every
+system explicitly.
+
+### Step 2a: Extract Explicit Systems
+
+Scan the game concept for directly mentioned systems and mechanics:
+- Core Mechanics section (most explicit)
+- Core Loop section (implies what systems drive each loop tier)
+- Technical Considerations section (networking, procedural generation, etc.)
+- MVP Definition section (required features = required systems)
+
+### Step 2b: Identify Implicit Systems
+
+For each explicit system, identify the **hidden systems** it implies. Games always
+need more systems than the concept doc mentions. Use this inference pattern:
+
+- "Inventory" implies: item database, equipment slots, weight/capacity rules,
+  inventory UI, item serialization for save/load
+- "Combat" implies: damage calculation, health system, hit detection, status effects,
+  enemy AI, combat UI (health bars, damage numbers), death/respawn
+- "Open world" implies: streaming/chunking, LOD system, fast travel, map/minimap,
+  point of interest tracking, world state persistence
+- "Multiplayer" implies: networking layer, lobby/matchmaking, state synchronization,
+  anti-cheat, network UI (ping, player list)
+- "Crafting" implies: recipe database, ingredient gathering, crafting UI,
+  success/failure mechanics, recipe discovery/learning
+- "Dialogue" implies: dialogue tree system, dialogue UI, choice tracking, NPC
+  state management, localization hooks
+- "Progression" implies: XP system, level-up mechanics, skill tree, unlock
+  tracking, progression UI, progression save data
+
+Explain in conversation text why each implicit system is needed (with examples).
+
+### Step 2c: User Review
+
+Present the enumeration organized by category. For each system, show:
+- Name
+- Category
+- Brief description (1 sentence)
+- Whether it was explicit (from concept) or implicit (inferred)
+
+Then use `AskUserQuestion` to capture feedback:
+- "Are there systems missing from this list?"
+- "Should any of these be combined or split?"
+- "Are there systems listed that this game does NOT need?"
+
+Iterate until the user approves the enumeration.
+
+---
+
+## 4. Phase 3: Dependency Mapping (Collaborative)
+
+For each system, determine what it depends on. A system "depends on" another if
+it cannot function without that other system existing first.
+
+### Step 3a: Map Dependencies
+
+For each system, list its dependencies. Use these dependency heuristics:
+- **Input/output dependencies**: System A produces data System B needs
+- **Structural dependencies**: System A provides the framework System B plugs into
+- **UI dependencies**: Every gameplay system has a corresponding UI system that
+  depends on it (but UI is designed after the gameplay system)
+
+### Step 3b: Sort by Dependency Order
+
+Arrange systems into layers:
+1. **Foundation**: Systems with zero dependencies (designed and built first)
+2. **Core**: Systems depending only on Foundation systems
+3. **Feature**: Systems depending on Core systems
+4. **Presentation**: UI and feedback systems that wrap gameplay systems
+5. **Polish**: Meta-systems, tutorials, analytics, accessibility
+
+### Step 3c: Detect Circular Dependencies
+
+Check for cycles in the dependency graph. If found:
+- Highlight them to the user
+- Propose resolutions (interface abstraction, simultaneous design, breaking the
+  cycle by defining a contract between the two systems)
+
+### Step 3d: Present to User
+
+Show the dependency map as a layered list. Highlight:
+- Any circular dependencies
+- Any "bottleneck" systems (many others depend on them — these are high-risk)
+- Any systems with no dependents (leaf nodes — lower risk, can be designed late)
+
+Use `AskUserQuestion` to ask: "Does this dependency ordering look right? Any
+dependencies I'm missing or that should be removed?"
+
+---
+
+## 5. Phase 4: Priority Assignment (Collaborative)
+
+Assign each system to a priority tier based on what milestone it's needed for.
+
+### Step 4a: Auto-Assign Based on Concept
+
+Use these heuristics for initial assignment:
+- **MVP**: Systems mentioned in the concept's "Required for MVP" section, plus their
+  Foundation-layer dependencies
+- **Vertical Slice**: Systems needed for a complete experience in one area
+- **Alpha**: All remaining gameplay systems
+- **Full Vision**: Polish, meta, and nice-to-have systems
+
+### Step 4b: User Review
+
+Present the priority assignments in a table. For each tier, explain why systems
+were placed there.
+
+Use `AskUserQuestion` to ask: "Do these priority assignments match your vision?
+Which systems should be higher or lower priority?"
+
+Explain reasoning in conversation: "I placed [system] in MVP because the core loop
+requires it — without [system], the 30-second loop can't function."
+
+### Step 4c: Determine Design Order
+
+Combine dependency sort + priority tier to produce the final design order:
+1. MVP Foundation systems first
+2. MVP Core systems second
+3. MVP Feature systems third
+4. Vertical Slice Foundation/Core systems
+5. ...and so on
+
+This is the order the team should write GDDs in.
+
+---
+
+## 6. Phase 5: Create Systems Index (Write)
+
+### Step 5a: Draft the Document
+
+Using the template at `.claude/docs/templates/systems-index.md`, populate the
+systems index with all data from Phases 2-4:
+- Fill the enumeration table
+- Fill the dependency map
+- Fill the recommended design order
+- Fill the high-risk systems
+- Fill progress tracker (all systems "Not Started" initially, unless GDDs already exist)
+
+### Step 5b: Approval
+
+Present a summary of the document:
+- Total systems count by category
+- MVP system count
+- First 3 systems in the design order
+- Any high-risk items
+
+Ask: "May I write the systems index to `design/gdd/systems-index.md`?"
+
+Wait for approval. Write the file only after "yes."
+
+### Step 5c: Update Session State
+
+After writing, update `production/session-state/active.md` with:
+- Task: Systems decomposition
+- Status: Systems index created
+- File: design/gdd/systems-index.md
+- Next: Design individual system GDDs
+
+---
+
+## 7. Phase 6: Design Individual Systems (Handoff to /design-system)
+
+This phase is entered when:
+- The user says "yes" to designing systems after creating the index
+- The user invokes `/map-systems [system-name]`
+- The user invokes `/map-systems next`
+
+### Step 6a: Select the System
+
+- If a system name was provided, find it in the systems index
+- If `next` was used, pick the highest-priority undesigned system (by design order)
+- If the user just finished the index, ask:
+  "Would you like to start designing individual systems now? The first system in
+  the design order is [name]. Or would you prefer to stop here and come back later?"
+
+Use `AskUserQuestion` for: "Start designing [system-name] now, pick a different
+system, or stop here?"
+
+### Step 6b: Hand Off to /design-system
+
+Once a system is selected, invoke the `/design-system [system-name]` skill.
+
+The `/design-system` skill handles the full GDD authoring process:
+- Gathers context from game concept, systems index, and dependency GDDs
+- Creates a file skeleton immediately
+- Walks through all 8 required sections one at a time (collaborative, incremental)
+- Cross-references existing docs to prevent contradictions
+- Routes to specialist agents for domain expertise
+- Writes each section to file as soon as it's approved
+- Runs `/design-review` when complete
+- Updates the systems index
+
+**Do not duplicate the /design-system workflow here.** This skill owns the systems
+*index*; `/design-system` owns individual system *GDDs*.
+
+### Step 6c: Loop or Stop
+
+After `/design-system` completes, use `AskUserQuestion`:
+- "Continue to the next system ([next system name])?"
+- "Pick a different system?"
+- "Stop here for this session?"
+
+If continuing, return to Step 6a.
+
+---
+
+## 8. Phase 7: Suggest Next Steps
+
+After the systems index is created (or after designing some systems), suggest
+the appropriate next actions:
+
+- "Run `/design-system [system-name]` to write the next system's GDD"
+- "Run `/design-review [path]` on each completed GDD to validate quality"
+- "Run `/gate-check pre-production` to check if you're ready to start building"
+- "Prototype the highest-risk system with `/prototype [system]`"
+- "Plan the first implementation sprint with `/sprint-plan new`"
+
+---
+
+## Collaborative Protocol
+
+This skill follows the collaborative design principle at every phase:
+
+1. **Question -> Options -> Decision -> Draft -> Approval** at every step
+2. **AskUserQuestion** at every decision point (Explain -> Capture pattern):
+   - Phase 2: "Missing systems? Combine or split?"
+   - Phase 3: "Dependency ordering correct?"
+   - Phase 4: "Priority assignments match your vision?"
+   - Phase 5: "May I write the systems index?"
+   - Phase 6: "Start designing, pick different, or stop?" then hand off to `/design-system`
+3. **"May I write to [filepath]?"** before every file write
+4. **Incremental writing**: Update the systems index after each system is designed
+5. **Handoff**: Individual GDD authoring is owned by `/design-system`, which handles
+   incremental section writing, cross-referencing, design review, and index updates
+6. **Session state updates**: Write to `production/session-state/active.md` after
+   each milestone (index created, system designed, priorities changed)
+
+**Never** auto-generate the full systems list and write it without review.
+**Never** start designing a system without user confirmation.
+**Always** show the enumeration, dependencies, and priorities for user validation.

.claude/skills/project-stage-detect/SKILL.md

@@ -25,7 +25,8 @@ Analyze project structure and content:
 
 **Design Documentation** (`design/`):
 - Count GDD files in `design/gdd/*.md`
-- Check for game-concept.md, game-pillars.md
+- Check for game-concept.md, game-pillars.md, systems-index.md
+- If systems-index.md exists, count total systems vs. designed systems
 - Analyze completeness (Overview, Detailed Design, Edge Cases, etc.)
 - Count narrative docs in `design/narrative/`
 - Count level designs in `design/levels/`
@@ -56,14 +57,19 @@ Analyze project structure and content:
 
 ### 2. Classify Project Stage
 
-Based on scanned artifacts, determine stage:
+Based on scanned artifacts, determine stage. Check `production/stage.txt` first —
+if it exists, use its value (explicit override from `/gate-check`). Otherwise,
+auto-detect using these heuristics (check from most-advanced backward):
 
 | Stage | Indicators |
 |-------|-----------|
-| **Concept** | No code or minimal prototype, maybe idea docs |
+| **Concept** | No game concept doc, brainstorming phase |
-| **Pre-production** | Design docs started, prototypes, no main src/ |
+| **Systems Design** | Game concept exists, systems index missing or incomplete |
-| **Production** | Active src/, sprint plans, growing systems |
+| **Technical Setup** | Systems index exists, engine not configured |
-| **Post-Launch** | Released, production/ has release history, maintenance focus |
+| **Pre-Production** | Engine configured, `src/` has <10 source files |
+| **Production** | `src/` has 10+ source files, active development |
+| **Polish** | Explicit only (set by `/gate-check` Production → Polish gate) |
+| **Release** | Explicit only (set by `/gate-check` Polish → Release gate) |
 
 ### 3. Collaborative Gap Identification
 
@@ -72,18 +78,19 @@ Based on scanned artifacts, determine stage:
 - "I see combat code (`src/gameplay/combat/`) but no `design/gdd/combat-system.md`. Was this prototyped first, or should we reverse-document?"
 - "You have 15 ADRs but no architecture overview. Should I create one to help new contributors?"
 - "No sprint plans in `production/`. Are you tracking work elsewhere (Jira, Trello, etc.)?"
+- "I found a game concept but no systems index. Have you decomposed the concept into individual systems yet, or should we run `/map-systems`?"
 - "Prototypes directory has 3 projects with no READMEs. Were these experiments, or do they need documentation?"
 
 ### 4. Generate Stage Report
 
-Use template: `docs/templates/project-stage-report.md`
+Use template: `.claude/docs/templates/project-stage-report.md`
 
 **Report structure**:
 ```markdown
 # Project Stage Analysis
 
 **Date**: [date]
-**Stage**: [Concept/Pre-production/Production/Post-Launch]
+**Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release]
 
 ## Completeness Overview
 - Design: [X%] ([N] docs, [gaps])
@@ -137,7 +144,7 @@ Recommended next steps:
 - [Priority 2]
 - [Priority 3]
 
-May I write the full stage analysis to docs/project-stage-report.md?
+May I write the full stage analysis to production/project-stage-report.md?
 ```
 
 Wait for user approval before creating the file.
@@ -163,6 +170,7 @@ Wait for user approval before creating the file.
 
 After generating the report, suggest relevant next steps:
 
+- **Concept exists but no systems index?** → `/map-systems` to decompose into systems
 - **Missing design docs?** → `/reverse-document design src/[system]`
 - **Missing architecture docs?** → `/architecture-decision` or `/reverse-document architecture`
 - **Prototypes need documentation?** → `/reverse-document concept prototypes/[name]`
@@ -179,6 +187,6 @@ This skill follows the collaborative design principle:
 2. **Present Options**: "Should I create X, or is it tracked elsewhere?"
 3. **User Decides**: Wait for direction
 4. **Show Draft**: Display report summary
-5. **Get Approval**: "May I write to docs/project-stage-report.md?"
+5. **Get Approval**: "May I write to production/project-stage-report.md?"
 
 **Never** silently write files. **Always** show findings and ask before creating artifacts.

.claude/skills/setup-engine/SKILL.md

@@ -291,9 +291,11 @@ Agent Config:    [verified]
 
 Next Steps:
 1. Review docs/engine-reference/<engine>/VERSION.md
-2. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop
+2. [If from /brainstorm] Run /map-systems to decompose your concept into individual systems
-3. [If fresh start] Run /brainstorm to discover your game concept
+3. [If from /brainstorm] Run /design-system to author per-system GDDs (guided, section-by-section)
-4. Create your first milestone: /sprint-plan new
+4. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop
+5. [If fresh start] Run /brainstorm to discover your game concept
+6. Create your first milestone: /sprint-plan new
 ```
 
 ---

.claude/skills/start/SKILL.md

@@ -3,7 +3,7 @@ name: start
 description: "First-time onboarding — asks where you are, then guides you to the right workflow. No assumptions."
 argument-hint: "[no arguments]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep
+allowed-tools: Read, Glob, Grep, AskUserQuestion
 ---
 
 # Guided Onboarding
@@ -77,6 +77,7 @@ technical setup — all of that comes later.
 4. Show the recommended path:
    - `/brainstorm` — discover your game concept
    - `/setup-engine` — configure the engine (brainstorm will recommend one)
+   - `/map-systems` — decompose the concept into systems and plan GDD writing order
    - `/prototype` — test the core mechanic
    - `/sprint-plan` — plan the first sprint
 
@@ -90,6 +91,7 @@ The user has a seed but needs help growing it into a concept.
 4. Show the recommended path:
    - `/brainstorm [hint]` — develop the idea into a full concept
    - `/setup-engine` — configure the engine
+   - `/map-systems` — decompose the concept into systems and plan GDD writing order
    - `/prototype` — test the core mechanic
    - `/sprint-plan` — plan the first sprint
 
@@ -109,6 +111,8 @@ The user knows what they want to make but hasn't documented it.
 3. Show the recommended path (adapted to their choice):
    - `/brainstorm` or `/setup-engine` (their pick)
    - `/design-review` — validate the concept doc
+   - `/map-systems` — decompose the concept into individual systems with dependencies and priorities
+   - `/design-system` — author per-system GDDs (guided, section-by-section)
    - `/architecture-decision` — make first technical decisions
    - `/sprint-plan` — plan the first sprint
 
@@ -124,6 +128,7 @@ The user has artifacts already. Figure out what exists and what's missing.
 4. Show the recommended path:
    - `/project-stage-detect` — full gap analysis
    - `/setup-engine` — if not configured
+   - `/design-system` — if systems index exists but GDDs are incomplete
    - `/gate-check` — validate readiness for next phase
    - `/sprint-plan` — organize the work
 

.claude/skills/team-audio/SKILL.md

@@ -3,10 +3,15 @@ name: team-audio
 description: "Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer for full audio pipeline from direction to implementation."
 argument-hint: "[feature or area to design audio for]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
 ---
 
-When this skill is invoked:
+When this skill is invoked, orchestrate the audio team through a structured pipeline.
+
+**Decision Points:** At each step transition, use `AskUserQuestion` to present
+the user with the subagent's proposals as selectable options. Write the agent's
+full analysis in conversation, then capture the decision with concise labels.
+The user must approve before moving to the next step.
 
 1. **Read the argument** for the target feature or area (e.g., `combat`,
    `main menu`, `forest biome`, `boss encounter`).

.claude/skills/team-combat/SKILL.md

@@ -3,10 +3,15 @@ name: team-combat
 description: "Orchestrate the combat team: coordinates game-designer, gameplay-programmer, ai-programmer, technical-artist, sound-designer, and qa-tester to design, implement, and validate a combat feature end-to-end."
 argument-hint: "[combat feature description]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
 ---
 When this skill is invoked, orchestrate the combat team through a structured pipeline.
 
+**Decision Points:** At each phase transition, use `AskUserQuestion` to present
+the user with the subagent's proposals as selectable options. Write the agent's
+full analysis in conversation, then capture the decision with concise labels.
+The user must approve before moving to the next phase.
+
 ## Team Composition
 - **game-designer** — Design the mechanic, define formulas and edge cases
 - **gameplay-programmer** — Implement the core gameplay code

.claude/skills/team-level/SKILL.md

@@ -3,11 +3,16 @@ name: team-level
 description: "Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation."
 argument-hint: "[level name or area to design]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
 ---
 
 When this skill is invoked:
 
+**Decision Points:** At each step transition, use `AskUserQuestion` to present
+the user with the subagent's proposals as selectable options. Write the agent's
+full analysis in conversation, then capture the decision with concise labels.
+The user must approve before moving to the next step.
+
 1. **Read the argument** for the target level or area (e.g., `tutorial`,
    `forest dungeon`, `hub town`, `final boss arena`).
 

.claude/skills/team-narrative/SKILL.md

@@ -3,10 +3,15 @@ name: team-narrative
 description: "Orchestrate the narrative team: coordinates narrative-director, writer, world-builder, and level-designer to create cohesive story content, world lore, and narrative-driven level design."
 argument-hint: "[narrative content description]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Task
+allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite
 ---
 When this skill is invoked, orchestrate the narrative team through a structured pipeline.
 
+**Decision Points:** At each phase transition, use `AskUserQuestion` to present
+the user with the subagent's proposals as selectable options. Write the agent's
+full analysis in conversation, then capture the decision with concise labels.
+The user must approve before moving to the next phase.
+
 ## Team Composition
 - **narrative-director** — Story arcs, character design, dialogue strategy, narrative vision
 - **writer** — Dialogue writing, lore entries, item descriptions, in-game text

.claude/skills/team-polish/SKILL.md

@@ -3,10 +3,15 @@ name: team-polish
 description: "Orchestrate the polish team: coordinates performance-analyst, technical-artist, sound-designer, and qa-tester to optimize, polish, and harden a feature or area for release quality."
 argument-hint: "[feature or area to polish]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
 ---
 When this skill is invoked, orchestrate the polish team through a structured pipeline.
 
+**Decision Points:** At each phase transition, use `AskUserQuestion` to present
+the user with the subagent's proposals as selectable options. Write the agent's
+full analysis in conversation, then capture the decision with concise labels.
+The user must approve before moving to the next phase.
+
 ## Team Composition
 - **performance-analyst** — Profiling, optimization, memory analysis, frame budget
 - **technical-artist** — VFX polish, shader optimization, visual quality

.claude/skills/team-release/SKILL.md

@@ -3,10 +3,15 @@ name: team-release
 description: "Orchestrate the release team: coordinates release-manager, qa-lead, devops-engineer, and producer to execute a release from candidate to deployment."
 argument-hint: "[version number or 'next']"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
 ---
 When this skill is invoked, orchestrate the release team through a structured pipeline.
 
+**Decision Points:** At each phase transition, use `AskUserQuestion` to present
+the user with the subagent's proposals as selectable options. Write the agent's
+full analysis in conversation, then capture the decision with concise labels.
+The user must approve before moving to the next phase.
+
 ## Team Composition
 - **release-manager** — Release branch, versioning, changelog, deployment
 - **qa-lead** — Test sign-off, regression suite, release quality gate

.claude/skills/team-ui/SKILL.md

@@ -3,10 +3,15 @@ name: team-ui
 description: "Orchestrate the UI team: coordinates ux-designer, ui-programmer, and art-director to design, implement, and polish a user interface feature from wireframe to final."
 argument-hint: "[UI feature description]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
 ---
 When this skill is invoked, orchestrate the UI team through a structured pipeline.
 
+**Decision Points:** At each phase transition, use `AskUserQuestion` to present
+the user with the subagent's proposals as selectable options. Write the agent's
+full analysis in conversation, then capture the decision with concise labels.
+The user must approve before moving to the next phase.
+
 ## Team Composition
 - **ux-designer** — User flows, wireframes, accessibility, input handling
 - **ui-programmer** — UI framework, screens, widgets, data binding, implementation

.claude/statusline.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Claude Code Game Studios — Status Line
+# Receives JSON on stdin, outputs a single-line status.
+#
+# Segments: ctx% | model | production stage [| Epic > Feature > Task]
+
+input=$(cat)
+
+# --- Parse JSON (jq with grep fallback) ---
+if command -v jq &>/dev/null; then
+  model=$(echo "$input" | jq -r '.model.display_name // "Unknown"')
+  used_pct=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
+  cwd=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // ""')
+else
+  model=$(echo "$input" | grep -oE '"display_name"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"//')
+  used_pct=$(echo "$input" | grep -oE '"used_percentage"\s*:\s*[0-9]+' | head -1 | sed 's/.*: *//')
+  cwd=$(echo "$input" | grep -oE '"current_dir"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"//')
+  [ -z "$model" ] && model="Unknown"
+fi
+
+# Normalize Windows paths
+cwd=$(echo "$cwd" | sed 's|\\|/|g')
+[ -z "$cwd" ] && cwd="."
+
+# --- Context usage ---
+if [ -n "$used_pct" ]; then
+  ctx_label="ctx: ${used_pct}%"
+else
+  ctx_label="ctx: --"
+fi
+
+# --- Production stage ---
+# Priority 1: Explicit stage from stage.txt
+stage_file="$cwd/production/stage.txt"
+stage=""
+if [ -f "$stage_file" ]; then
+  stage=$(head -1 "$stage_file" | tr -d '\r\n')
+fi
+
+# Priority 2: Auto-detect from artifacts
+if [ -z "$stage" ]; then
+  concept_file="$cwd/design/gdd/game-concept.md"
+  systems_file="$cwd/design/gdd/systems-index.md"
+  tech_prefs="$cwd/.claude/docs/technical-preferences.md"
+
+  has_concept=false
+  has_systems=false
+  engine_configured=false
+  src_count=0
+
+  [ -f "$concept_file" ] && has_concept=true
+  [ -f "$systems_file" ] && has_systems=true
+
+  # Check if engine is configured (not placeholder)
+  if [ -f "$tech_prefs" ]; then
+    engine_line=$(grep -m1 '^\*\*Engine\*\*:' "$tech_prefs" 2>/dev/null || true)
+    if [ -n "$engine_line" ] && ! echo "$engine_line" | grep -q "TO BE CONFIGURED"; then
+      engine_configured=true
+    fi
+  fi
+
+  # Count source files (language-agnostic)
+  if [ -d "$cwd/src" ]; then
+    src_count=$(find "$cwd/src" -type f \( -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.h" -o -name "*.py" -o -name "*.rs" -o -name "*.lua" -o -name "*.tscn" -o -name "*.tres" \) 2>/dev/null | wc -l | tr -d ' ')
+  fi
+
+  # Determine stage (check from most-advanced backward)
+  if [ "$src_count" -ge 10 ] 2>/dev/null; then
+    stage="Production"
+  elif [ "$engine_configured" = true ]; then
+    stage="Pre-Production"
+  elif [ "$has_systems" = true ]; then
+    stage="Technical Setup"
+  elif [ "$has_concept" = true ]; then
+    stage="Systems Design"
+  else
+    stage="Concept"
+  fi
+fi
+
+# --- Epic/Feature/Task breadcrumb (Production+ only) ---
+breadcrumb=""
+if [ "$stage" = "Production" ] || [ "$stage" = "Polish" ] || [ "$stage" = "Release" ]; then
+  state_file="$cwd/production/session-state/active.md"
+  if [ -f "$state_file" ]; then
+    # Parse structured STATUS block
+    in_block=false
+    epic="" feature="" task=""
+    while IFS= read -r line; do
+      case "$line" in
+        *"<!-- STATUS -->"*) in_block=true; continue ;;
+        *"<!-- /STATUS -->"*) break ;;
+      esac
+      if [ "$in_block" = true ]; then
+        case "$line" in
+          Epic:*) epic=$(echo "$line" | sed 's/^Epic: *//') ;;
+          Feature:*) feature=$(echo "$line" | sed 's/^Feature: *//') ;;
+          Task:*) task=$(echo "$line" | sed 's/^Task: *//') ;;
+        esac
+      fi
+    done < "$state_file"
+
+    # Build breadcrumb from whatever is set
+    parts=""
+    [ -n "$epic" ] && parts="$epic"
+    [ -n "$feature" ] && parts="${parts:+$parts > }$feature"
+    [ -n "$task" ] && parts="${parts:+$parts > }$task"
+    [ -n "$parts" ] && breadcrumb=" | $parts"
+  fi
+fi
+
+# --- Assemble ---
+printf "%s" "${ctx_label} | ${model} | ${stage}${breadcrumb}"

.gitignore

@@ -12,7 +12,9 @@ Desktop.ini
 # === Claude Code Local ===
 .claude/settings.local.json
 .claude/docs/UPGRADE-PLAN.md
+CLAUDE.local.md
 production/session-logs/
+production/session-state/*.md
 
 # === Internal Planning (not for public) ===
 docs/IMPROVEMENTS-PROPOSAL.md

CLAUDE.md

@@ -26,10 +26,6 @@ Each agent owns a specific domain, enforcing separation of concerns and quality.
 
 @.claude/docs/technical-preferences.md
 
-## Agent Roster
-
-@.claude/docs/agent-roster.md
-
 ## Coordination Rules
 
 @.claude/docs/coordination-rules.md
@@ -49,24 +45,10 @@ See `docs/COLLABORATIVE-DESIGN-PRINCIPLE.md` for full protocol and examples.
 > **First session?** If the project has no engine configured and no game concept,
 > run `/start` to begin the guided onboarding flow.
 
-## Coding Standards & Review
+## Coding Standards
 
 @.claude/docs/coding-standards.md
 
-@.claude/docs/review-workflow.md
-
 ## Context Management
 
 @.claude/docs/context-management.md
-
-## Active Hooks
-
-@.claude/docs/hooks-reference.md
-
-## Available Skills (Slash Commands)
-
-@.claude/docs/skills-reference.md
-
-## Path-Specific Rules
-
-@.claude/docs/rules-reference.md

README.md

@@ -3,14 +3,14 @@
   <p align="center">
     Turn a single Claude Code session into a full game development studio.
     <br />
-    48 agents. 35 workflows. One coordinated AI team.
+    48 agents. 37 workflows. One coordinated AI team.
   </p>
 </p>
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
   <a href=".claude/agents"><img src="https://img.shields.io/badge/agents-48-blueviolet" alt="48 Agents"></a>
-  <a href=".claude/skills"><img src="https://img.shields.io/badge/skills-35-green" alt="35 Skills"></a>
+  <a href=".claude/skills"><img src="https://img.shields.io/badge/skills-37-green" alt="37 Skills"></a>
   <a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-8-orange" alt="8 Hooks"></a>
   <a href=".claude/rules"><img src="https://img.shields.io/badge/rules-11-red" alt="11 Rules"></a>
   <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/built%20for-Claude%20Code-f5f5f5?logo=anthropic" alt="Built for Claude Code"></a>
@@ -35,6 +35,7 @@ The result: you still make every decision, but now you have a team that asks the
 - [Studio Hierarchy](#studio-hierarchy)
 - [Slash Commands](#slash-commands)
 - [Getting Started](#getting-started)
+- [Upgrading](#upgrading)
 - [Project Structure](#project-structure)
 - [How It Works](#how-it-works)
 - [Design Philosophy](#design-philosophy)
@@ -50,10 +51,10 @@ The result: you still make every decision, but now you have a team that asks the
 | Category | Count | Description |
 |----------|-------|-------------|
 | **Agents** | 48 | Specialized subagents across design, programming, art, audio, narrative, QA, and production |
-| **Skills** | 35 | Slash commands for common workflows (`/start`, `/sprint-plan`, `/code-review`, `/brainstorm`, etc.) |
+| **Skills** | 37 | Slash commands for common workflows (`/start`, `/sprint-plan`, `/code-review`, `/brainstorm`, etc.) |
 | **Hooks** | 8 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit, and gap detection |
 | **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more |
-| **Templates** | 28 | Document templates for GDDs, ADRs, sprint plans, economy models, faction design, and more |
+| **Templates** | 29 | Document templates for GDDs, ADRs, sprint plans, economy models, faction design, and more |
 
 ## Studio Hierarchy
 
@@ -91,7 +92,7 @@ The template includes agent sets for all three major engines. Use the set that m
 
 ## Slash Commands
 
-Type `/` in Claude Code to access all 35 skills:
+Type `/` in Claude Code to access all 37 skills:
 
 **Reviews & Analysis**
 `/design-review` `/code-review` `/balance-check` `/asset-audit` `/scope-check` `/perf-profile` `/tech-debt`
@@ -100,7 +101,7 @@ Type `/` in Claude Code to access all 35 skills:
 `/sprint-plan` `/milestone-review` `/estimate` `/retrospective` `/bug-report`
 
 **Project Management**
-`/start` `/project-stage-detect` `/reverse-document` `/gate-check`
+`/start` `/project-stage-detect` `/reverse-document` `/gate-check` `/map-systems` `/design-system`
 
 **Release**
 `/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix`
@@ -142,6 +143,12 @@ All hooks fail gracefully if optional tools are missing — nothing breaks, you
    - `/setup-engine godot 4.6` — configure your engine if you already know
    - `/project-stage-detect` — analyze an existing project
 
+## Upgrading
+
+Already using an older version of this template? See [UPGRADING.md](UPGRADING.md)
+for step-by-step migration instructions, a breakdown of what changed between
+versions, and which files are safe to overwrite vs. which need a manual merge.
+
 ## Project Structure
 
 ```
@@ -149,7 +156,7 @@ CLAUDE.md                           # Master configuration
 .claude/
   settings.json                     # Hooks, permissions, safety rules
   agents/                           # 48 agent definitions (markdown + YAML frontmatter)
-  skills/                           # 35 slash commands (subdirectory per skill)
+  skills/                           # 37 slash commands (subdirectory per skill)
   hooks/                            # 8 hook scripts (bash, cross-platform)
   rules/                            # 11 path-scoped coding standards
   docs/

UPGRADING.md

@@ -0,0 +1,384 @@
+# Upgrading Claude Code Game Studios
+
+This guide covers upgrading your existing game project repo from one version
+of the template to the next.
+
+**Find your current version** in your git log:
+```bash
+git log --oneline | grep -i "release\|setup"
+```
+Or check `README.md` for the version badge.
+
+---
+
+## Table of Contents
+
+- [Upgrade Strategies](#upgrade-strategies)
+- [v0.2.0 → v0.3.0](#v020--v030)
+- [v0.1.0 → v0.2.0](#v010--v020)
+
+---
+
+## Upgrade Strategies
+
+There are three ways to pull in template updates. Choose based on how your
+repo is set up.
+
+### Strategy A — Git Remote Merge (recommended)
+
+Best when: you cloned the template and have your own commits on top of it.
+
+```bash
+# Add the template as a remote (one-time setup)
+git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git
+
+# Fetch the new version
+git fetch template main
+
+# Merge into your branch
+git merge template/main --allow-unrelated-histories
+```
+
+Git will flag conflicts only in files that both the template *and* you have
+changed. Resolve each one — your game content goes in, structural improvements
+come along for the ride. Then commit the merge.
+
+**Tip:** The files most likely to conflict are `CLAUDE.md` and
+`.claude/docs/technical-preferences.md`, because you've filled them in with
+your engine and project settings. Keep your content; accept the structural changes.
+
+---
+
+### Strategy B — Cherry-pick specific commits
+
+Best when: you only want one specific feature (e.g., just the new skill, not
+the full update).
+
+```bash
+git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git
+git fetch template main
+
+# Cherry-pick the specific commit(s) you want
+git cherry-pick <commit-sha>
+```
+
+Commit SHAs for each version are listed in the version sections below.
+
+---
+
+### Strategy C — Manual file copy
+
+Best when: you didn't use git to set up the template (just downloaded a zip).
+
+1. Download or clone the new version alongside your repo.
+2. Copy the files listed under **"Safe to overwrite"** directly.
+3. For files under **"Merge carefully"**, open both versions side-by-side
+   and manually merge the structural changes while keeping your content.
+
+---
+
+## v0.2.0 → v0.3.0
+
+**Released:** 2026-03-09
+**Commit range:** `e289ce9..HEAD`
+**Key themes:** `/design-system` GDD authoring, `/map-systems` rename, custom status line
+
+### Breaking Changes
+
+#### `/design-systems` renamed to `/map-systems`
+
+The `/design-systems` skill was renamed to `/map-systems` for clarity
+(decomposing = *mapping*, not *designing*).
+
+**Action required:** Update any documentation, notes, or scripts that invoke
+`/design-systems`. The new invocation is `/map-systems`.
+
+### What Changed
+
+| Category | Changes |
+|----------|---------|
+| **New skills** | `/design-system` (guided GDD authoring, section-by-section) |
+| **Renamed skills** | `/design-systems` → `/map-systems` (breaking rename) |
+| **New files** | `.claude/statusline.sh`, `.claude/settings.json` statusline config |
+| **Skill updates** | `/gate-check` — writes `production/stage.txt` on PASS, new phase definitions |
+| **Skill updates** | `brainstorm`, `start`, `design-review`, `project-stage-detect`, `setup-engine` — cross-reference fixes |
+| **Bug fixes** | `log-agent.sh`, `validate-commit.sh` — hook execution fixed |
+| **Docs** | `UPGRADING.md` added, `README.md` updated, `WORKFLOW-GUIDE.md` updated |
+
+---
+
+### Files: Safe to Overwrite
+
+**New files to add:**
+```
+.claude/skills/design-system/SKILL.md
+.claude/statusline.sh
+```
+
+**Existing files to overwrite (no user content):**
+```
+.claude/skills/map-systems/SKILL.md      ← was design-systems/SKILL.md
+.claude/skills/gate-check/SKILL.md
+.claude/skills/brainstorm/SKILL.md
+.claude/skills/start/SKILL.md
+.claude/skills/design-review/SKILL.md
+.claude/skills/project-stage-detect/SKILL.md
+.claude/skills/setup-engine/SKILL.md
+.claude/hooks/log-agent.sh
+.claude/hooks/validate-commit.sh
+README.md
+docs/WORKFLOW-GUIDE.md
+UPGRADING.md
+```
+
+**Delete (replaced by rename):**
+```
+.claude/skills/design-systems/   ← entire directory; replaced by map-systems/
+```
+
+---
+
+### Files: Merge Carefully
+
+#### `.claude/settings.json`
+
+The new version adds a `statusLine` configuration block pointing to
+`.claude/statusline.sh`. If you haven't customized `settings.json`, overwriting
+is safe. Otherwise, add this block manually:
+
+```json
+"statusLine": {
+  "script": ".claude/statusline.sh"
+}
+```
+
+---
+
+### New Features
+
+#### Custom Status Line
+
+`.claude/statusline.sh` displays a 7-stage production pipeline breadcrumb in
+the terminal status line:
+
+```
+ctx: 42% | claude-sonnet-4-6 | Systems Design
+```
+
+In Production/Polish/Release stages, it also shows the active Epic/Feature/Task
+from `production/session-state/active.md` if a `<!-- STATUS -->` block is present:
+
+```
+ctx: 42% | claude-sonnet-4-6 | Production | Combat System > Melee Combat > Hitboxes
+```
+
+The current stage is auto-detected from project artifacts, or can be pinned by
+writing a stage name to `production/stage.txt`.
+
+#### `/gate-check` Stage Advancement
+
+When a gate PASS verdict is confirmed, `/gate-check` now writes the new stage
+name to `production/stage.txt`. This immediately updates the status line for all
+future sessions without requiring manual file edits.
+
+---
+
+### After Upgrading
+
+1. **Delete the old skill directory:**
+   ```bash
+   rm -rf .claude/skills/design-systems/
+   ```
+
+2. **Test the status line** by starting a Claude Code session — you should see
+   the stage breadcrumb in the terminal footer.
+
+3. **Verify hook execution** still works:
+   ```bash
+   bash .claude/hooks/log-agent.sh '{}' '{}'
+   bash .claude/hooks/validate-commit.sh '{}' '{}'
+   ```
+
+---
+
+## v0.1.0 → v0.2.0
+
+**Released:** 2026-02-21
+**Commit range:** `ad540fe..e289ce9`
+**Key themes:** Context Resilience, AskUserQuestion integration, `/map-systems` skill
+
+### What Changed
+
+| Category | Changes |
+|----------|---------|
+| **New skills** | `/start` (onboarding), `/map-systems` (systems decomposition), `/design-system` (guided GDD authoring) |
+| **New hooks** | `session-start.sh` (recovery), `detect-gaps.sh` (gap detection) |
+| **New templates** | `systems-index.md`, 3 collaborative-protocol templates |
+| **Context management** | Major rewrite — file-backed state strategy added |
+| **Agent updates** | 14 design/creative agents — AskUserQuestion integration |
+| **Skill updates** | All 7 `team-*` skills + `brainstorm` — AskUserQuestion at phase transitions |
+| **CLAUDE.md** | Slimmed from ~159 to ~60 lines; 5 doc imports instead of 10 |
+| **Hook updates** | All 8 hooks — Windows compatibility fixes, new features |
+| **Docs removed** | `docs/IMPROVEMENTS-PROPOSAL.md`, `docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md` |
+
+---
+
+### Files: Safe to Overwrite
+
+These are pure infrastructure — you have not customized them. Copy the new
+versions directly with no risk to your project content.
+
+**New files to add:**
+```
+.claude/skills/start/SKILL.md
+.claude/skills/map-systems/SKILL.md
+.claude/skills/design-system/SKILL.md
+.claude/docs/templates/systems-index.md
+.claude/docs/templates/collaborative-protocols/design-agent-protocol.md
+.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md
+.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md
+.claude/hooks/detect-gaps.sh
+.claude/hooks/session-start.sh
+production/session-state/.gitkeep
+docs/examples/README.md
+.github/ISSUE_TEMPLATE/bug_report.md
+.github/ISSUE_TEMPLATE/feature_request.md
+.github/PULL_REQUEST_TEMPLATE.md
+```
+
+**Existing files to overwrite (no user content):**
+```
+.claude/skills/brainstorm/SKILL.md
+.claude/skills/design-review/SKILL.md
+.claude/skills/gate-check/SKILL.md
+.claude/skills/project-stage-detect/SKILL.md
+.claude/skills/setup-engine/SKILL.md
+.claude/skills/team-audio/SKILL.md
+.claude/skills/team-combat/SKILL.md
+.claude/skills/team-level/SKILL.md
+.claude/skills/team-narrative/SKILL.md
+.claude/skills/team-polish/SKILL.md
+.claude/skills/team-release/SKILL.md
+.claude/skills/team-ui/SKILL.md
+.claude/hooks/log-agent.sh
+.claude/hooks/pre-compact.sh
+.claude/hooks/session-stop.sh
+.claude/hooks/validate-assets.sh
+.claude/hooks/validate-commit.sh
+.claude/hooks/validate-push.sh
+.claude/rules/design-docs.md
+.claude/docs/hooks-reference.md
+.claude/docs/skills-reference.md
+.claude/docs/quick-start.md
+.claude/docs/directory-structure.md
+.claude/docs/context-management.md
+docs/COLLABORATIVE-DESIGN-PRINCIPLE.md
+docs/WORKFLOW-GUIDE.md
+README.md
+```
+
+**Agent files to overwrite** (if you haven't written custom prompts into them):
+```
+.claude/agents/art-director.md
+.claude/agents/audio-director.md
+.claude/agents/creative-director.md
+.claude/agents/economy-designer.md
+.claude/agents/game-designer.md
+.claude/agents/level-designer.md
+.claude/agents/live-ops-designer.md
+.claude/agents/narrative-director.md
+.claude/agents/producer.md
+.claude/agents/systems-designer.md
+.claude/agents/technical-director.md
+.claude/agents/ux-designer.md
+.claude/agents/world-builder.md
+.claude/agents/writer.md
+```
+
+If you *have* customized agent prompts, see "Merge carefully" below.
+
+---
+
+### Files: Merge Carefully
+
+These files contain both template structure and your project-specific content.
+Do **not** overwrite them — merge the changes manually.
+
+#### `CLAUDE.md`
+
+The template version was slimmed from ~159 lines to ~60 lines. The key
+structural change: 5 doc imports were removed because they're auto-loaded
+by Claude Code anyway (agent-roster, skills-reference, hooks-reference,
+rules-reference, review-workflow).
+
+**What to keep from your version:**
+- The `## Technology Stack` section (your engine/language choices)
+- Any project-specific additions you made
+
+**What to adopt from the new version:**
+- Slimmer imports list (drop the 5 redundant `@` imports if present)
+- Updated collaboration protocol wording
+
+#### `.claude/docs/technical-preferences.md`
+
+If you ran `/setup-engine`, this file has your engine config, naming
+conventions, and performance budgets. Keep all of it. The template version
+is just the empty placeholder.
+
+#### `.claude/docs/templates/game-concept.md`
+
+Minor structural update — a `## Next Steps` section was added pointing to
+`/map-systems`. Add that section to your copy if you want the updated
+guidance, but it's not required.
+
+#### `.claude/settings.json`
+
+Check whether the new version adds any permission rules you want. The change
+was minor (schema update). If you haven't customized your `settings.json`,
+overwriting is safe.
+
+#### Customized agent files
+
+If you've added project-specific knowledge or custom behavior to any agent
+`.md` file, do a diff and manually add the new AskUserQuestion integration
+sections rather than overwriting. The change in each agent is a standardized
+collaborative protocol block at the end of the system prompt.
+
+---
+
+### Files: Delete
+
+These files were removed in v0.2.0. If present in your repo, you can safely
+delete them — they're replaced by better-organized alternatives.
+
+```
+docs/IMPROVEMENTS-PROPOSAL.md      → superseded by WORKFLOW-GUIDE.md
+docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md → content merged into context-management.md
+```
+
+---
+
+### After Upgrading
+
+1. **Run `/project-stage-detect`** to verify the system reads your project
+   correctly with the new detection logic.
+
+2. **Run `/start`** once if you haven't used it — it now correctly identifies
+   your stage and skips onboarding steps you've already done.
+
+3. **Check `production/session-state/`** exists and is gitignored:
+   ```bash
+   ls production/session-state/
+   cat .gitignore | grep session-state
+   ```
+
+4. **Test hook execution** — if you're on Windows, verify the new hooks run
+   without errors in Git Bash:
+   ```bash
+   bash .claude/hooks/detect-gaps.sh '{}' '{}'
+   bash .claude/hooks/session-start.sh '{}' '{}'
+   ```
+
+---
+
+*Each future version will have its own section in this file.*

docs/COLLABORATIVE-DESIGN-PRINCIPLE.md

@@ -329,6 +329,127 @@ Skill: "Writing design/concept.md..."
 
 ---
 
+## 🎛️ Structured Decision UI (AskUserQuestion)
+
+Use the `AskUserQuestion` tool to present decisions as a **selectable UI** instead
+of plain markdown text. This gives the user a clean interface to pick from options
+(or type "Other" for a custom answer).
+
+### The Explain → Capture Pattern
+
+Detailed reasoning doesn't fit in the tool's short descriptions. So use a two-step
+pattern:
+
+1. **Explain first** — Write your full expert analysis in conversation text:
+   detailed pros/cons, theory references, example games, pillar alignment. This is
+   where the reasoning lives.
+
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels
+   and short descriptions. The user picks from the UI or types a custom answer.
+
+### When to Use AskUserQuestion
+
+✅ **Use it for:**
+- Every decision point where you'd present 2-4 options
+- Initial clarifying questions with constrained answers
+- Batching up to 4 independent questions in one call
+- Next-step choices ("Draft formulas or refine rules first?")
+- Architecture decisions ("Static utility or singleton?")
+- Strategic choices ("Simplify scope, slip deadline, or cut feature?")
+
+❌ **Don't use it for:**
+- Open-ended discovery questions ("What excites you about roguelikes?")
+- Single yes/no confirmations ("May I write to file?")
+- When running as a Task subagent (tool may not be available)
+
+### Format Guidelines
+
+- **Labels**: 1-5 words (e.g., "Hybrid Discovery", "Full Randomized")
+- **Descriptions**: 1 sentence summarizing the approach and key trade-off
+- **Recommended**: Add "(Recommended)" to your preferred option's label
+- **Previews**: Use `markdown` field for comparing code structures or formulas
+- **Multi-select**: Use `multiSelect: true` when choices aren't mutually exclusive
+
+### Example — Multi-Question Batch (Clarifying Questions)
+
+After introducing the topic in conversation, batch constrained questions:
+
+```
+AskUserQuestion:
+  questions:
+    - question: "Should crafting recipes be discovered or learned?"
+      header: "Discovery"
+      options:
+        - label: "Experimentation"
+          description: "Players discover by trying combinations — high mystery"
+        - label: "NPC/Book Learning"
+          description: "Recipes taught explicitly — accessible, lower mystery"
+        - label: "Tiered Hybrid"
+          description: "Basic recipes learned, advanced discovered — best of both"
+    - question: "How punishing should failed crafts be?"
+      header: "Failure"
+      options:
+        - label: "Materials Lost"
+          description: "All consumed on failure — high stakes, risk/reward"
+        - label: "Partial Recovery"
+          description: "50% returned — moderate risk"
+        - label: "No Loss"
+          description: "Materials returned, only time spent — forgiving"
+```
+
+### Example — Design Decision (After Full Analysis)
+
+After writing the full pros/cons analysis in conversation text:
+
+```
+AskUserQuestion:
+  questions:
+    - question: "Which crafting approach fits your vision?"
+      header: "Approach"
+      options:
+        - label: "Hybrid Discovery (Recommended)"
+          description: "Discovery base with earned hints — balances exploration and accessibility"
+        - label: "Full Discovery"
+          description: "Pure experimentation — maximum mystery, risk of frustration"
+        - label: "Hint System"
+          description: "Progressive hints reveal recipes — accessible but less surprise"
+```
+
+### Example — Strategic Decision
+
+After presenting the full strategic analysis with pillar alignment:
+
+```
+AskUserQuestion:
+  questions:
+    - question: "How should we handle crafting scope for Alpha?"
+      header: "Scope"
+      options:
+        - label: "Simplify to Core (Recommended)"
+          description: "Recipe discovery only, 10 recipes — makes deadline, pillar visible"
+        - label: "Full Implementation"
+          description: "Complete system, 30 recipes — slips Alpha by 1 week"
+        - label: "Cut Entirely"
+          description: "Drop crafting, focus on combat — deadline met, pillar missing"
+```
+
+### Team Skill Orchestration
+
+In team skills, subagents return their analysis as text. The **orchestrator**
+(main session) calls `AskUserQuestion` at each decision point between phases:
+
+```
+[game-designer returns 3 combat approaches with analysis]
+
+Orchestrator uses AskUserQuestion:
+  question: "Which combat approach should we develop?"
+  options: [concise summaries of the 3 approaches]
+
+[User picks → orchestrator passes decision to next phase]
+```
+
+---
+
 ## 📄 File Writing Protocol
 
 ### NEVER Write Files Without Explicit Approval
@@ -352,6 +473,39 @@ Every file write must follow:
           [Returns to step 1]
 ```
 
+### Incremental Section Writing (Design Documents)
+
+For multi-section documents (design docs, lore entries, architecture docs), write
+each section to the file as it's approved instead of building the full document
+in conversation. This prevents context overflow during long iterative sessions.
+
+```
+1. Agent creates file with skeleton (all section headers, empty bodies)
+   Agent: "May I create design/gdd/crafting-system.md with the section skeleton?"
+   User: "Yes"
+
+2. For EACH section:
+   Agent: [Drafts section in conversation]
+   User: [Reviews, requests changes]
+   Agent: [Revises until approved]
+   Agent: "May I write this section to the file?"
+   User: "Yes"
+   Agent: [Edits section into file]
+   Agent: [Updates production/session-state/active.md with progress]
+   ─── Context for this section can now be safely compacted ───
+   ─── The decisions are IN THE FILE ───
+
+3. If session crashes or compacts mid-document:
+   Agent: [Reads the file — completed sections are all there]
+   Agent: [Reads production/session-state/active.md — knows what's next]
+   Agent: "Sections 1-4 are complete. Ready to work on section 5?"
+```
+
+Why this matters: A full design doc session with 8 sections and 2-3 revision
+cycles per section can accumulate 30-50k tokens of conversation. Incremental
+writing keeps the live context at ~3-5k tokens (only the current section's
+discussion), because completed sections are persisted to disk.
+
 ### Multi-File Writes
 
 When a change affects multiple files:
@@ -455,21 +609,6 @@ The orchestration is automated, but **decision points stay with the user**.
 
 ---
 
-## 🔧 Updating All Documentation
-
-This principle needs to be embedded in:
-
-### Files to Update:
-
-1. **CLAUDE.md** — Add "Collaboration Protocol" section
-2. **WORKFLOW-GUIDE.md** — Rewrite all "What happens" sections
-3. **Agent Roster** — Add "Questions to Ask" to each agent description
-4. **.claude/agents/*.md** — Update system prompts to enforce this
-5. **Skills** — Update all skills to ask before writing
-6. **README.md** — Clarify this is collaborative, not autonomous
-
----
-
 ## ✅ Quick Validation: Is Your Session Collaborative?
 
 After any agent interaction, check:
@@ -537,14 +676,13 @@ WHEN implementing:
 
 ---
 
-## 🚀 Next Steps
+## Implementation Status
 
-To fully implement this principle:
+This principle has been fully embedded across the project:
 
-1. **Update CLAUDE.md** with collaboration protocol
+- **CLAUDE.md** — Collaboration protocol section added
-2. **Update agent definitions** to enforce question-asking
+- **All 48 agent definitions** — Updated to enforce question-asking and approval
-3. **Update WORKFLOW-GUIDE.md** to show collaborative examples
+- **All skills** — Updated to require approval before writing
-4. **Update all skills** to require approval before writing
+- **WORKFLOW-GUIDE.md** — Rewritten with collaborative examples
-5. **Add /collaborative-check skill** to audit if sessions are collaborative
+- **README.md** — Clarifies collaborative (not autonomous) design
-
+- **AskUserQuestion tool** — Integrated into 10 skills for structured option UI
-Would you like me to implement these updates now?

docs/WORKFLOW-GUIDE.md

@@ -3,7 +3,7 @@
 > **How to go from zero to a shipped game using the Agent Architecture.**
 >
 > This guide walks you through every phase of game development using the
-> 48-agent system, 35 slash commands, and automated hooks. It assumes you
+> 48-agent system, 37 slash commands, and automated hooks. It assumes you
 > have Claude Code installed and are working from the project root.
 
 ---
@@ -252,7 +252,38 @@ Also define **anti-pillars** -- things your game intentionally avoids:
 You create all the design documents that define how your game works. Nothing
 gets coded yet -- this is pure design and architecture.
 
-### Step 2.1: Create the Game Design Document (GDD)
+### Step 2.1: Decompose Your Concept Into Systems
+
+Before writing individual GDDs, enumerate all the systems your game needs:
+
+```
+/map-systems
+```
+
+This creates `design/gdd/systems-index.md` — a master tracking document that:
+
+- Lists every system your game needs (combat, movement, UI, etc.)
+- Maps dependencies between systems
+- Assigns priority tiers (MVP, Vertical Slice, Alpha, Full Vision)
+- Determines design order (Foundation → Core → Feature → Presentation → Polish)
+
+Then design each system in dependency order:
+
+```
+/map-systems next
+```
+
+This picks the highest-priority undesigned system and hands off to `/design-system`,
+which guides you through creating its GDD section by section. Each completed GDD
+goes through `/design-review` before the next starts.
+
+You can also write a specific system's GDD directly:
+
+```
+/design-system combat-system
+```
+
+### Step 2.2: Create the Game Design Document (GDD)
 
 For each major system in your game, create a design document in `design/gdd/`.
 Use the template:
@@ -1690,7 +1721,7 @@ conflicts go to `producer`.
 |-------|----------|
 | **Onboarding** | `/start` |
 | **Ideation** | `/brainstorm` |
-| **Design** | `/design-review`, `/architecture-decision` |
+| **Design** | `/map-systems`, `/design-system`, `/design-review`, `/architecture-decision` |
 | **Sprint** | `/sprint-plan`, `/estimate`, `/scope-check`, `/retrospective` |
 | **Implementation** | `/code-review`, `/prototype`, `/tech-debt` |
 | **Testing** | `/balance-check`, `/playtest-report`, `/perf-profile` |
@@ -1712,7 +1743,8 @@ conflicts go to `producer`.
 3. Create a game concept doc (templates/game-concept.md)
 4. Define game pillars (templates/game-pillars.md)
 5. /design-review on your concept doc
-6. Start creating GDDs for each system
+6. /map-systems to decompose concept into systems with dependencies and priorities
+7. /design-system to author per-system GDDs (guided, section-by-section)
 ```
 
 ### Workflow 2: "I have a design and want to start coding"

docs/examples/README.md

@@ -91,6 +91,12 @@ All examples follow the **collaborative workflow pattern:**
 Question → Options → Decision → Draft → Approval
 ```
 
+> **Note:** These examples show the collaborative pattern as conversational text.
+> In practice, agents now use the `AskUserQuestion` tool at decision points to
+> present structured option pickers (with labels, descriptions, and multi-select).
+> The pattern is **Explain → Capture**: agents explain their analysis in
+> conversation first, then present a structured UI picker for the user's decision.
+
 ### ✅ **Collaborative Behaviors Shown:**
 
 1. **Agents Ask Before Assuming**