Release v0.2.0: Context Resilience, AskUserQuestion, /design-systems

* Add context resilience: file-backed state, incremental writing, auto-recovery

Prevents "prompt too long" crashes from killing sessions by persisting work
to disk incrementally instead of relying on conversation memory.

Changes:
- pre-compact.sh: dumps session state before context compression
- session-start.sh: detects active.md for crash recovery
- session-stop.sh: archives and clears active.md on clean shutdown
- context-management.md: file-backed state as primary strategy
- 9 agents updated with incremental section writing protocol
  (game-designer, systems-designer, economy-designer, narrative-director,
   level-designer, world-builder, writer, art-director, audio-director)
- CLAUDE.md: trimmed redundant imports (10 → 5) to reduce token overhead
- design-docs.md rule: enforces incremental writing pattern
- .gitignore: excludes ephemeral session state files
- directory-structure.md: documents session-state/ and session-logs/
- COLLABORATIVE-DESIGN-PRINCIPLE.md: documents incremental writing pattern

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

* Add AskUserQuestion integration across collaborative protocols

Explicitly reference the AskUserQuestion tool in all collaborative agent
definitions, protocol templates, team orchestrator skills, and the master
principle doc. Introduces the Explain-then-Capture pattern: agents write
full expert analysis in conversation, then call AskUserQuestion with
concise labels to capture decisions via structured UI.

26 files updated:
- 3 protocol templates (design, leadership, implementation)
- 14 agent definitions (10 design + 3 leadership + writer)
- 8 orchestrator skills (brainstorm + 7 team-*)
- 1 master principle doc (COLLABORATIVE-DESIGN-PRINCIPLE.md)

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

* Add /design-systems skill: concept-to-GDD decomposition workflow

Bridges the gap between game concept and per-system design documents.
Professional studios use systems enumeration + dependency sorting between
concept and feature docs — skipping this step is one of the most expensive
mistakes (systems discovered during production cost 5-10x more to add).

New files:
- .claude/skills/design-systems/SKILL.md — 7-phase orchestration skill
  (enumerate systems, map dependencies, assign priorities, write GDDs)
- .claude/docs/templates/systems-index.md — master tracking template

Flow integration (7 existing skills updated):
- brainstorm, start, setup-engine, design-review, gate-check,
  project-stage-detect, game-concept template all reference /design-systems
  at the appropriate workflow touchpoints

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

* Fix cross-platform bugs, add missing tool permissions, and update docs for v0.2.0

Hooks: fix \s → [[:space:]] in grep -E fallbacks (3 files), fix detect-gaps.sh
empty-variable bug, fix log-agent.sh field name (agent_name → agent_type),
harden validate-push.sh with explicit $MATCHED_BRANCH, convert for-in loops
to while-read for space-safe iteration, add POSIX head -n syntax, increase
PreCompact timeout, widen session-stop log window.

Skills: add AskUserQuestion to 10 skills and TodoWrite to 8 multi-phase skills.
Fix project-stage-detect template/output paths, tech-artist → technical-artist.

Docs: add /design-systems to all references (README, quick-start, workflow guide,
skills-reference), update skill count 35 → 36, remove stale AI artifacts from
COLLABORATIVE-DESIGN-PRINCIPLE.md, add AskUserQuestion note to examples README.

Co-Authored-By: Claude Opus 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,71 @@
 # 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.
+
+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 +73,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,7 @@ 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 |
+| `/design-systems` | Decompose concept into systems, map dependencies, guide per-system GDDs |
 | `/team-combat` | Orchestrate full combat team pipeline |
 | `/team-narrative` | Orchestrate full narrative team pipeline |
 | `/team-ui` | Orchestrate full UI team pipeline |
@@ -207,7 +208,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/                          -- 36 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,16 @@
 | `/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) |
+| `/design-systems` | Decompose game concept into systems, map dependencies, prioritize design order, guide per-system GDDs |
 | `/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 (`/design-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/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-systems [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,15 +3,15 @@
 # Tracks which agents are being used and when
 #
 # Input schema (SubagentStart):
-# { "agent_name": "game-designer", "model": "sonnet", ... }
+# { "agent_id": "agent-abc123", "agent_type": "game-designer", ... }
 
 INPUT=$(cat)
 
-# Parse agent name -- use jq if available, fall back to grep
+# Parse agent type -- use jq if available, fall back to grep
 if command -v jq >/dev/null 2>&1; then
-    AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_name // "unknown"' 2>/dev/null)
+    AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_type // "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_type"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"agent_type"[[: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,7 +31,7 @@ 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
                 if ! grep -qi "$section" "$file"; then
@@ -39,7 +39,7 @@ if [ -n "$DESIGN_FILES" ]; then
                 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

@@ -81,7 +81,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,7 @@ 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 `/design-systems` — maps dependencies, assigns priorities, and guides per-system GDD creation"
    - "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,15 @@ 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 `/design-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 so, suggest updating its status: "Update the systems index status for
+       this system from 'In Design' to 'Designed'."

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

@@ -0,0 +1,344 @@
+---
+name: design-systems
+description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and guide creation of per-system GDDs."
+argument-hint: "[optional: 'map' to create/update the systems index, system-name to design a specific system, or 'next' for the highest-priority undesigned system]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite
+---
+
+When this skill is invoked:
+
+## 1. Parse Arguments
+
+Three modes:
+
+- **No argument / `map`**: `/design-systems` or `/design-systems map` — Run the full
+  decomposition workflow (Phases 1-5) to create or update the systems index.
+- **System name**: `/design-systems combat` — Jump directly to Phase 6 to design
+  a specific system's GDD. Requires the systems index to exist already.
+- **`next`**: `/design-systems next` — Pick the highest-priority undesigned system
+  from the index and start designing it (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 (Optional, Iterative)
+
+This phase is entered when:
+- The user says "yes" to designing systems after creating the index
+- The user invokes `/design-systems [system-name]`
+- The user invokes `/design-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: Delegate to Agents
+
+Use the Task tool to delegate GDD writing to the appropriate agent(s):
+
+**For most gameplay systems:**
+Delegate to `game-designer` with this context in the Task prompt:
+- The system name and description from the systems index
+- The game concept summary (elevator pitch, pillars, core loop)
+- The dependency list (what this system depends on, what depends on it)
+- Any existing related GDDs (read and summarize for context)
+- The GDD template to follow (`.claude/docs/templates/game-design-document.md`)
+- The 8 required sections per coding standards
+- Instruction to follow the collaborative protocol and use incremental file writing
+
+**For formula-heavy systems (combat, economy, progression):**
+Also delegate to `systems-designer` for detailed mathematical modeling. The
+`game-designer` handles the high-level design; the `systems-designer` fills in
+formulas, interaction matrices, and tuning knobs.
+
+**For narrative systems (dialogue, quests, lore):**
+Coordinate with `narrative-director` in addition to `game-designer`.
+
+**For UI systems:**
+Coordinate with `ux-designer` in addition to `game-designer`.
+
+**For audio systems:**
+Coordinate with `audio-director` and `sound-designer`.
+
+**For economy systems:**
+Coordinate with `economy-designer`.
+
+Present the agent's output to the user for review and approval before writing.
+
+### Step 6c: Write the GDD
+
+After user approval, write the GDD to `design/gdd/[system-name].md`.
+(The delegated agent handles this, following the collaborative protocol.)
+
+### Step 6d: Run Design Review
+
+After the GDD is written, run `/design-review design/gdd/[system-name].md` to
+validate:
+- All 8 required sections are present and complete
+- Formulas are internally consistent
+- Dependencies match what other GDDs expect
+- Edge cases don't contradict other systems
+- Rules are precise enough for a programmer to implement
+
+If the review finds issues:
+- Present them to the user
+- Fix the identified holes before proceeding to the next system
+- Re-run the review after fixes to confirm resolution
+
+### Step 6e: Update the Systems Index
+
+After each GDD passes review:
+- Update the system's Status in the enumeration table (Not Started -> Approved)
+- Update the Design Doc path column
+- Update the Progress Tracker counts
+- Ask: "May I update the systems index at `design/gdd/systems-index.md`?"
+
+### Step 6f: Loop or Stop
+
+After each system, 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:
+
+- For each undesigned MVP system, recommend the right agent(s):
+  - Gameplay mechanics: `game-designer` + `systems-designer`
+  - UI systems: `game-designer` + `ux-designer`
+  - Audio systems: `audio-director` + `sound-designer`
+  - Narrative systems: `game-designer` + `narrative-director`
+  - Economy systems: `economy-designer`
+  - Level design: `level-designer`
+- "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?"
+3. **"May I write to [filepath]?"** before every file write
+4. **Incremental writing**: Update the systems index after each system is designed
+5. **Design review loop**: Every completed GDD passes `/design-review` before the
+   next system starts — holes are caught early, not downstream
+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/gate-check/SKILL.md

@@ -44,7 +44,8 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict).
 ### Gate: Pre-production → Production
 
 **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 GDD in `design/gdd/` (beyond game-concept.md and systems-index.md)
 - [ ] At least 1 Architecture Decision Record in `docs/architecture/`
 - [ ] At least 1 prototype in `prototypes/` with a README
 - [ ] Engine reference docs exist in `docs/engine-reference/`
@@ -185,6 +186,7 @@ For items that can't be automatically verified, **ask the user**:
 
 Based on the verdict, suggest specific next steps:
 
+- **No systems index?** → `/design-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/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/`
@@ -72,11 +73,12 @@ 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 `/design-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
@@ -137,7 +139,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 +165,7 @@ Wait for user approval before creating the file.
 
 After generating the report, suggest relevant next steps:
 
+- **Concept exists but no systems index?** → `/design-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 +182,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,10 @@ 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 /design-systems to decompose your concept into individual systems
-3. [If fresh start] Run /brainstorm to discover your game concept
+3. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop
-4. Create your first milestone: /sprint-plan new
+4. [If fresh start] Run /brainstorm to discover your game concept
+5. 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)
+   - `/design-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
+   - `/design-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,7 @@ 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
+   - `/design-systems` — decompose the concept into individual systems with dependencies and priorities
    - `/architecture-decision` — make first technical decisions
    - `/sprint-plan` — plan the first sprint
 

.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

.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. 36 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-36-green" alt="36 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>
@@ -50,7 +50,7 @@ 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** | 36 | 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 |
@@ -91,7 +91,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 36 skills:
 
 **Reviews & Analysis**
 `/design-review` `/code-review` `/balance-check` `/asset-audit` `/scope-check` `/perf-profile` `/tech-debt`
@@ -100,7 +100,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` `/design-systems`
 
 **Release**
 `/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix`
@@ -149,7 +149,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/                           # 36 slash commands (subdirectory per skill)
   hooks/                            # 8 hook scripts (bash, cross-platform)
   rules/                            # 11 path-scoped coding standards
   docs/

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, 36 slash commands, and automated hooks. It assumes you
 > have Claude Code installed and are working from the project root.
 
 ---
@@ -252,7 +252,31 @@ 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:
+
+```
+/design-systems map
+```
+
+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:
+
+```
+/design-systems next
+```
+
+This picks the highest-priority undesigned system and guides you through creating
+its GDD. Each completed GDD goes through `/design-review` before the next starts.
+
+### 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 +1714,7 @@ conflicts go to `producer`.
 |-------|----------|
 | **Onboarding** | `/start` |
 | **Ideation** | `/brainstorm` |
-| **Design** | `/design-review`, `/architecture-decision` |
+| **Design** | `/design-systems`, `/design-review`, `/architecture-decision` |
 | **Sprint** | `/sprint-plan`, `/estimate`, `/scope-check`, `/retrospective` |
 | **Implementation** | `/code-review`, `/prototype`, `/tech-debt` |
 | **Testing** | `/balance-check`, `/playtest-report`, `/perf-profile` |

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**