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

* Add UPGRADING.md migration guide and link from README

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

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

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

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

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

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

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

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

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

* Add custom status line with 7-stage production pipeline

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

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

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

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

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

---------

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

.claude/docs/context-management.md

@@ -20,6 +20,24 @@ after each significant milestone:
 The state file should contain: current task, progress checklist, key decisions
 made, files being worked on, and open questions.
 
+### Status Line Block (Production+ only)
+
+When the project is in Production, Polish, or Release stage, include a structured
+status block in `active.md` that the status line script can parse:
+
+```markdown
+<!-- STATUS -->
+Epic: Combat System
+Feature: Melee Combat
+Task: Implement hitbox detection
+<!-- /STATUS -->
+```
+
+- All three fields (Epic, Feature, Task) are optional — include only what applies
+- Update this block when switching focus areas
+- The status line displays it as a breadcrumb: `Combat System > Melee Combat > Hitboxes`
+- Remove or empty the block when no active work focus exists
+
 After any disruption (compaction, crash, `/clear`), read the state file first.
 
 ### Incremental File Writing

.claude/docs/quick-start.md

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

.claude/docs/skills-reference.md

@@ -36,5 +36,6 @@
 | `/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 |
+| `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order, guide per-system GDDs |
+| `/design-system` | Guided, section-by-section GDD authoring for a single game system with cross-referencing and incremental writing |
 | `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs |

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

@@ -309,7 +309,7 @@ the combat-crafting loop engaging for 30+ minute sessions"]
 - [ ] Get concept approval from creative-director
 - [ ] 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)
+- [ ] Decompose concept into systems (`/map-systems` — maps dependencies, assigns priorities, guides per-system GDD writing)
 - [ ] Create first architecture decision record (`/architecture-decision`)
 - [ ] Prototype core loop (`/prototype [core-mechanic]`)
 - [ ] Validate core loop with playtest (`/playtest-report`)

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

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

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

@@ -140,7 +140,7 @@ These should be prototyped early regardless of priority tier.]
 ## Next Steps
 
 - [ ] Review and approve this systems enumeration
-- [ ] Design MVP-tier systems first (use `/design-systems [system-name]`)
+- [ ] Design MVP-tier systems first (use `/design-system [system-name]`)
 - [ ] Run `/design-review` on each completed GDD
 - [ ] Run `/gate-check pre-production` when MVP systems are designed
 - [ ] Prototype the highest-risk system early (`/prototype [system]`)

.claude/hooks/log-agent.sh

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

.claude/hooks/validate-commit.sh

@@ -33,7 +33,7 @@ DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/')
 if [ -n "$DESIGN_FILES" ]; then
     while IFS= read -r file; do
         if [[ "$file" == *.md ]] && [ -f "$file" ]; then
-            for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do
+            for section in "Overview" "Player Fantasy" "Detailed" "Formulas" "Edge Cases" "Dependencies" "Tuning Knobs" "Acceptance Criteria"; do
                 if ! grep -qi "$section" "$file"; then
                     WARNINGS="$WARNINGS\nDESIGN: $file missing required section: $section"
                 fi

.claude/settings.json

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

.claude/skills/brainstorm/SKILL.md

@@ -200,7 +200,8 @@ Ground the concept in reality:
    - "Run `/setup-engine [engine] [version]` to configure the engine and populate version-aware reference docs"
    - "Use `/design-review design/gdd/game-concept.md` to validate completeness"
    - "Discuss vision with the `creative-director` agent for pillar refinement"
-   - "Decompose the concept into individual systems with `/design-systems` — maps dependencies, assigns priorities, and guides per-system GDD creation"
+   - "Decompose the concept into individual systems with `/map-systems` — maps dependencies, assigns priorities, and creates the systems index"
+   - "Author per-system GDDs with `/design-system` — guided, section-by-section GDD writing"
    - "Prototype the core loop with `/prototype [core-mechanic]`"
    - "Playtest the prototype with `/playtest-report` to validate the hypothesis"
    - "If validated, plan the first sprint with `/sprint-plan new`"

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

@@ -67,10 +67,14 @@ When this skill is invoked:
    - 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`
+       > "This concept is ready for systems decomposition. Run `/map-systems`
        > to break it down into individual systems with dependencies and priorities,
        > then write per-system GDDs."
    - If the document is an individual system GDD:
      - Check if the systems index references this system
-     - If so, suggest updating its status: "Update the systems index status for
+     - If verdict is APPROVED: suggest "Update the systems index status for
-       this system from 'In Design' to 'Designed'."
+       this system to 'Approved'."
+     - If verdict is NEEDS REVISION or MAJOR REVISION NEEDED: suggest "Update
+       the systems index status for this system to 'In Review'."
+     - Note: This skill is read-only. The user (or `/design-system`) must
+       perform the actual status update in the systems index.

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

@@ -0,0 +1,496 @@
+---
+name: design-system
+description: "Guided, section-by-section GDD authoring for a single game system. Gathers context from existing docs, walks through each required section collaboratively, cross-references dependencies, and writes incrementally to file."
+argument-hint: "<system-name> (e.g., 'combat-system', 'inventory', 'dialogue')"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite
+---
+
+When this skill is invoked:
+
+## 1. Parse Arguments & Validate
+
+A system name argument is **required**. If missing, fail with:
+> "Usage: `/design-system <system-name>` — e.g., `/design-system combat-system`
+> Run `/map-systems` first to create the systems index, then use this skill
+> to write individual system GDDs."
+
+Normalize the system name to kebab-case for the filename (e.g., "combat system"
+becomes `combat-system`).
+
+---
+
+## 2. Gather Context (Read Phase)
+
+Read all relevant context **before** asking the user anything. This is the skill's
+primary advantage over ad-hoc design — it arrives informed.
+
+### 2a: Required Reads
+
+- **Game concept**: Read `design/gdd/game-concept.md` — fail if missing:
+  > "No game concept found. Run `/brainstorm` first."
+- **Systems index**: Read `design/gdd/systems-index.md` — fail if missing:
+  > "No systems index found. Run `/map-systems` first to map your systems."
+- **Target system**: Find the system in the index. If not listed, warn:
+  > "[system-name] is not in the systems index. Would you like to add it, or
+  > design it as an off-index system?"
+
+### 2b: Dependency Reads
+
+From the systems index, identify:
+- **Upstream dependencies**: Systems this one depends on. Read their GDDs if they
+  exist (these contain decisions this system must respect).
+- **Downstream dependents**: Systems that depend on this one. Read their GDDs if
+  they exist (these contain expectations this system must satisfy).
+
+For each dependency GDD that exists, extract and hold in context:
+- Key interfaces (what data flows between the systems)
+- Formulas that reference this system's outputs
+- Edge cases that assume this system's behavior
+- Tuning knobs that feed into this system
+
+### 2c: Optional Reads
+
+- **Game pillars**: Read `design/gdd/game-pillars.md` if it exists
+- **Existing GDD**: Read `design/gdd/[system-name].md` if it exists (resume, don't
+  restart from scratch)
+- **Related GDDs**: Glob `design/gdd/*.md` and read any that are thematically related
+  (e.g., if designing "status-effects", also read "combat-system" even if it's not
+  a direct dependency)
+
+### 2d: Present Context Summary
+
+Before starting design work, present a brief summary to the user:
+
+> **Designing: [System Name]**
+> - Priority: [from index] | Layer: [from index]
+> - Depends on: [list, noting which have GDDs vs. undesigned]
+> - Depended on by: [list, noting which have GDDs vs. undesigned]
+> - Existing decisions to respect: [key constraints from dependency GDDs]
+> - Pillar alignment: [which pillar(s) this system primarily serves]
+
+If any upstream dependencies are undesigned, warn:
+> "[dependency] doesn't have a GDD yet. We'll need to make assumptions about
+> its interface. Consider designing it first, or we can define the expected
+> contract and flag it as provisional."
+
+Use `AskUserQuestion`:
+- "Ready to start designing [system-name]?"
+  - Options: "Yes, let's go", "Show me more context first", "Design a dependency first"
+
+---
+
+## 3. Create File Skeleton
+
+Once the user confirms, **immediately** create the GDD file with empty section
+headers. This ensures incremental writes have a target.
+
+Use the template structure from `.claude/docs/templates/game-design-document.md`:
+
+```markdown
+# [System Name]
+
+> **Status**: In Design
+> **Author**: [user + agents]
+> **Last Updated**: [today's date]
+> **Implements Pillar**: [from context]
+
+## Overview
+
+[To be designed]
+
+## Player Fantasy
+
+[To be designed]
+
+## Detailed Design
+
+### Core Rules
+
+[To be designed]
+
+### States and Transitions
+
+[To be designed]
+
+### Interactions with Other Systems
+
+[To be designed]
+
+## Formulas
+
+[To be designed]
+
+## Edge Cases
+
+[To be designed]
+
+## Dependencies
+
+[To be designed]
+
+## Tuning Knobs
+
+[To be designed]
+
+## Visual/Audio Requirements
+
+[To be designed]
+
+## UI Requirements
+
+[To be designed]
+
+## Acceptance Criteria
+
+[To be designed]
+
+## Open Questions
+
+[To be designed]
+```
+
+Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?"
+
+After writing, update `production/session-state/active.md` with:
+- Task: Designing [system-name] GDD
+- Current section: Starting (skeleton created)
+- File: design/gdd/[system-name].md
+
+---
+
+## 4. Section-by-Section Design
+
+Walk through each section in order. For **each section**, follow this cycle:
+
+### The Section Cycle
+
+```
+Context  ->  Questions  ->  Options  ->  Decision  ->  Draft  ->  Approval  ->  Write
+```
+
+1. **Context**: State what this section needs to contain, and surface any relevant
+   decisions from dependency GDDs that constrain it.
+
+2. **Questions**: Ask clarifying questions specific to this section. Use
+   `AskUserQuestion` for constrained questions, conversational text for open-ended
+   exploration.
+
+3. **Options**: Where the section involves design choices (not just documentation),
+   present 2-4 approaches with pros/cons. Explain reasoning in conversation text,
+   then use `AskUserQuestion` to capture the decision.
+
+4. **Decision**: User picks an approach or provides custom direction.
+
+5. **Draft**: Write the section content in conversation text for review. Flag any
+   provisional assumptions about undesigned dependencies.
+
+6. **Approval**: Ask "Approve this section, or would you like changes?"
+
+7. **Write**: Use the Edit tool to replace the `[To be designed]` placeholder with
+   the approved content. Confirm the write.
+
+After writing each section, update `production/session-state/active.md` with the
+completed section name.
+
+### Section-Specific Guidance
+
+Each section has unique design considerations and may benefit from specialist agents:
+
+---
+
+### Section A: Overview
+
+**Goal**: One paragraph a stranger could read and understand.
+
+**Questions to ask**:
+- What is this system in one sentence?
+- How does a player interact with it? (active/passive/automatic)
+- Why does this system exist — what would the game lose without it?
+
+**Cross-reference**: Check that the description aligns with how the systems index
+describes it. Flag discrepancies.
+
+---
+
+### Section B: Player Fantasy
+
+**Goal**: The emotional target — what the player should *feel*.
+
+**Questions to ask**:
+- What emotion or power fantasy does this serve?
+- What reference games nail this feeling? What specifically creates it?
+- Is this a "system you love engaging with" or "infrastructure you don't notice"?
+
+**Cross-reference**: Must align with the game pillars. If the system serves a pillar,
+quote the relevant pillar text.
+
+---
+
+### Section C: Detailed Design (Core Rules, States, Interactions)
+
+**Goal**: Unambiguous specification a programmer could implement without questions.
+
+This is usually the largest section. Break it into sub-sections:
+
+1. **Core Rules**: The fundamental mechanics. Use numbered rules for sequential
+   processes, bullets for properties.
+2. **States and Transitions**: If the system has states, map every state and
+   every valid transition. Use a table.
+3. **Interactions with Other Systems**: For each dependency (upstream and downstream),
+   specify what data flows in, what flows out, and who owns the interface.
+
+**Questions to ask**:
+- Walk me through a typical use of this system, step by step
+- What are the decision points the player faces?
+- What can the player NOT do? (Constraints are as important as capabilities)
+
+**Agent delegation**: For complex mechanics, use the Task tool to delegate to
+`game-designer` for high-level design review, or `systems-designer` for detailed
+mechanical modeling. Provide the full context gathered in Phase 2.
+
+**Cross-reference**: For each interaction listed, verify it matches what the
+dependency GDD specifies. If the dependency says "damage is calculated as X" and
+this system expects something different, flag the conflict.
+
+---
+
+### Section D: Formulas
+
+**Goal**: Every mathematical formula, with variables defined, ranges specified,
+and edge cases noted.
+
+**Questions to ask**:
+- What are the core calculations this system performs?
+- Should scaling be linear, logarithmic, or stepped?
+- What should the output ranges be at early/mid/late game?
+
+**Agent delegation**: For formula-heavy systems (combat, economy, progression),
+delegate to `systems-designer` via the Task tool. Provide:
+- The Core Rules from Section C (already written to file)
+- Tuning goals from the user
+- Balance context from dependency GDDs
+
+The agent should return proposed formulas with variable tables and expected output
+ranges. Present these to the user for review before approving.
+
+**Cross-reference**: If a dependency GDD defines a formula whose output feeds into
+this system, reference it explicitly. Don't reinvent — connect.
+
+---
+
+### Section E: Edge Cases
+
+**Goal**: Explicitly handle unusual situations so they don't become bugs.
+
+**Questions to ask**:
+- What happens at zero? At maximum? At negative values?
+- What happens when two effects trigger simultaneously?
+- What happens if the player tries to exploit this? (Identify degenerate strategies)
+
+**Agent delegation**: For systems with complex interactions, delegate to
+`systems-designer` to identify edge cases from the formula space. For narrative
+systems, consult `narrative-director` for story-breaking edge cases.
+
+**Cross-reference**: Check edge cases against dependency GDDs. If combat says
+"damage cannot go below 1" but this system can reduce damage to 0, that's a
+conflict to resolve.
+
+---
+
+### Section F: Dependencies
+
+**Goal**: Map every system connection with direction and nature.
+
+This section is partially pre-filled from the context gathering phase. Present the
+known dependencies from the systems index and ask:
+- Are there dependencies I'm missing?
+- For each dependency, what's the specific data interface?
+- Which dependencies are hard (system cannot function without it) vs. soft
+  (enhanced by it but works without it)?
+
+**Cross-reference**: This section must be bidirectionally consistent. If this system
+lists "depends on Combat", then the Combat GDD should list "depended on by [this
+system]". Flag any one-directional dependencies for correction.
+
+---
+
+### Section G: Tuning Knobs
+
+**Goal**: Every designer-adjustable value, with safe ranges and extreme behaviors.
+
+**Questions to ask**:
+- What values should designers be able to tweak without code changes?
+- For each knob, what breaks if it's set too high? Too low?
+- Which knobs interact with each other? (Changing A makes B irrelevant)
+
+**Agent delegation**: If formulas are complex, delegate to `systems-designer`
+to derive tuning knobs from the formula variables.
+
+**Cross-reference**: If a dependency GDD lists tuning knobs that affect this system,
+reference them here. Don't create duplicate knobs — point to the source of truth.
+
+---
+
+### Section H: Acceptance Criteria
+
+**Goal**: Testable conditions that prove the system works as designed.
+
+**Questions to ask**:
+- What's the minimum set of tests that prove this works?
+- What performance budget does this system get? (frame time, memory)
+- What would a QA tester check first?
+
+**Cross-reference**: Include criteria that verify cross-system interactions work,
+not just this system in isolation.
+
+---
+
+### Optional Sections: Visual/Audio, UI Requirements, Open Questions
+
+These sections are included in the template but aren't part of the 8 required
+sections. Offer them after the required sections are done:
+
+Use `AskUserQuestion`:
+- "The 8 required sections are complete. Do you want to also define Visual/Audio
+  requirements, UI requirements, or capture open questions?"
+  - Options: "Yes, all three", "Just open questions", "Skip — I'll add these later"
+
+For **Visual/Audio**: Coordinate with `art-director` and `audio-director` if detail
+is needed. Often a brief note suffices at the GDD stage.
+
+For **UI Requirements**: Coordinate with `ux-designer` for complex UI systems.
+
+For **Open Questions**: Capture anything that came up during design that wasn't
+fully resolved. Each question should have an owner and target resolution date.
+
+---
+
+## 5. Post-Design Validation
+
+After all sections are written:
+
+### 5a: Self-Check
+
+Read back the complete GDD from file (not from conversation memory — the file is
+the source of truth). Verify:
+- All 8 required sections have real content (not placeholders)
+- Formulas reference defined variables
+- Edge cases have resolutions
+- Dependencies are listed with interfaces
+- Acceptance criteria are testable
+
+### 5b: Offer Design Review
+
+Present a completion summary:
+
+> **GDD Complete: [System Name]**
+> - Sections written: [list]
+> - Provisional assumptions: [list any assumptions about undesigned dependencies]
+> - Cross-system conflicts found: [list or "none"]
+
+Use `AskUserQuestion`:
+- "Run `/design-review` now to validate the GDD?"
+  - Options: "Yes, run review now", "I'll review it myself first", "Skip review"
+
+If yes, invoke the design-review skill on the completed file.
+
+### 5c: Update Systems Index
+
+After the GDD is complete (and optionally reviewed):
+
+- Read the systems index
+- Update the target system's row:
+  - If design-review was run and verdict is APPROVED: Status → "Approved"
+  - If design-review was run and verdict is NEEDS REVISION: Status → "In Review"
+  - If design-review was skipped: Status → "Designed" (pending review)
+  - If the user chose "I'll review it myself first": Status → "Designed"
+  - Design Doc: link to `design/gdd/[system-name].md`
+- Update the Progress Tracker counts
+
+Ask: "May I update the systems index at `design/gdd/systems-index.md`?"
+
+### 5d: Update Session State
+
+Update `production/session-state/active.md` with:
+- Task: [system-name] GDD
+- Status: Complete (or In Review if design-review was run)
+- File: design/gdd/[system-name].md
+- Sections: All 8 written
+- Next: [suggest next system from design order]
+
+### 5e: Suggest Next Steps
+
+Use `AskUserQuestion`:
+- "What's next?"
+  - Options:
+    - "Design next system ([next-in-order])" — if undesigned systems remain
+    - "Fix review findings" — if design-review flagged issues
+    - "Stop here for this session"
+    - "Run `/gate-check`" — if enough MVP systems are designed
+
+---
+
+## 6. Specialist Agent Routing
+
+This skill delegates to specialist agents for domain expertise. The main session
+orchestrates the overall flow; agents provide expert content.
+
+| System Category | Primary Agent | Supporting Agent(s) |
+|----------------|---------------|---------------------|
+| Combat, damage, health | `game-designer` | `systems-designer` (formulas), `ai-programmer` (enemy AI) |
+| Economy, loot, crafting | `economy-designer` | `systems-designer` (curves), `game-designer` (loops) |
+| Progression, XP, skills | `game-designer` | `systems-designer` (curves), `economy-designer` (sinks) |
+| Dialogue, quests, lore | `game-designer` | `narrative-director` (story), `writer` (content) |
+| UI systems (HUD, menus) | `game-designer` | `ux-designer` (flows), `ui-programmer` (feasibility) |
+| Audio systems | `game-designer` | `audio-director` (direction), `sound-designer` (specs) |
+| AI, pathfinding, behavior | `game-designer` | `ai-programmer` (implementation), `systems-designer` (scoring) |
+| Level/world systems | `game-designer` | `level-designer` (spatial), `world-builder` (lore) |
+| Camera, input, controls | `game-designer` | `ux-designer` (feel), `gameplay-programmer` (feasibility) |
+
+**When delegating via Task tool**:
+- Provide: system name, game concept summary, dependency GDD excerpts, the specific
+  section being worked on, and what question needs expert input
+- The agent returns analysis/proposals to the main session
+- The main session presents the agent's output to the user via `AskUserQuestion`
+- The user decides; the main session writes to file
+- Agents do NOT write to files directly — the main session owns all file writes
+
+---
+
+## 7. Recovery & Resume
+
+If the session is interrupted (compaction, crash, new session):
+
+1. Read `production/session-state/active.md` — it records the current system and
+   which sections are complete
+2. Read `design/gdd/[system-name].md` — sections with real content are done;
+   sections with `[To be designed]` still need work
+3. Resume from the next incomplete section — no need to re-discuss completed ones
+
+This is why incremental writing matters: every approved section survives any
+disruption.
+
+---
+
+## Collaborative Protocol
+
+This skill follows the collaborative design principle at every step:
+
+1. **Question -> Options -> Decision -> Draft -> Approval** for every section
+2. **AskUserQuestion** at every decision point (Explain -> Capture pattern):
+   - Phase 2: "Ready to start, or need more context?"
+   - Phase 3: "May I create the skeleton?"
+   - Phase 4 (each section): Design questions, approach options, draft approval
+   - Phase 5: "Run design review? Update systems index? What's next?"
+3. **"May I write to [filepath]?"** before the skeleton and before each section write
+4. **Incremental writing**: Each section is written to file immediately after approval
+5. **Session state updates**: After every section write
+6. **Cross-referencing**: Every section checks existing GDDs for conflicts
+7. **Specialist routing**: Complex sections get expert agent input, presented to
+   the user for decision — never written silently
+
+**Never** auto-generate the full GDD and present it as a fait accompli.
+**Never** write a section without user approval.
+**Never** contradict an existing approved GDD without flagging the conflict.
+**Always** show where decisions come from (dependency GDDs, pillars, user choices).

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

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

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

@@ -1,7 +1,7 @@
 ---
-name: design-systems
+name: map-systems
-description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and guide creation of per-system GDDs."
+description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and create the systems index."
-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]"
+argument-hint: "[optional: 'next' to pick highest-priority undesigned system, or a system name to hand off to /design-system]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite
 ---
@@ -10,14 +10,12 @@ When this skill is invoked:
 
 ## 1. Parse Arguments
 
-Three modes:
+Two modes:
 
-- **No argument / `map`**: `/design-systems` or `/design-systems map` — Run the full
+- **No argument**: `/map-systems` — Run the full decomposition workflow (Phases 1-5)
-  decomposition workflow (Phases 1-5) to create or update the systems index.
+  to create or update the systems index.
-- **System name**: `/design-systems combat` — Jump directly to Phase 6 to design
+- **`next`**: `/map-systems next` — Pick the highest-priority undesigned system
-  a specific system's GDD. Requires the systems index to exist already.
+  from the index and hand off to `/design-system` (Phase 6).
-- **`next`**: `/design-systems next` — Pick the highest-priority undesigned system
-  from the index and start designing it (Phase 6).
 
 ---
 
@@ -212,12 +210,12 @@ After writing, update `production/session-state/active.md` with:
 
 ---
 
-## 7. Phase 6: Design Individual Systems (Optional, Iterative)
+## 7. Phase 6: Design Individual Systems (Handoff to /design-system)
 
 This phase is entered when:
 - The user says "yes" to designing systems after creating the index
-- The user invokes `/design-systems [system-name]`
+- The user invokes `/map-systems [system-name]`
-- The user invokes `/design-systems next`
+- The user invokes `/map-systems next`
 
 ### Step 6a: Select the System
 
@@ -230,70 +228,26 @@ This phase is entered when:
 Use `AskUserQuestion` for: "Start designing [system-name] now, pick a different
 system, or stop here?"
 
-### Step 6b: Delegate to Agents
+### Step 6b: Hand Off to /design-system
 
-Use the Task tool to delegate GDD writing to the appropriate agent(s):
+Once a system is selected, invoke the `/design-system [system-name]` skill.
 
-**For most gameplay systems:**
+The `/design-system` skill handles the full GDD authoring process:
-Delegate to `game-designer` with this context in the Task prompt:
+- Gathers context from game concept, systems index, and dependency GDDs
-- The system name and description from the systems index
+- Creates a file skeleton immediately
-- The game concept summary (elevator pitch, pillars, core loop)
+- Walks through all 8 required sections one at a time (collaborative, incremental)
-- The dependency list (what this system depends on, what depends on it)
+- Cross-references existing docs to prevent contradictions
-- Any existing related GDDs (read and summarize for context)
+- Routes to specialist agents for domain expertise
-- The GDD template to follow (`.claude/docs/templates/game-design-document.md`)
+- Writes each section to file as soon as it's approved
-- The 8 required sections per coding standards
+- Runs `/design-review` when complete
-- Instruction to follow the collaborative protocol and use incremental file writing
+- Updates the systems index
 
-**For formula-heavy systems (combat, economy, progression):**
+**Do not duplicate the /design-system workflow here.** This skill owns the systems
-Also delegate to `systems-designer` for detailed mathematical modeling. The
+*index*; `/design-system` owns individual system *GDDs*.
-`game-designer` handles the high-level design; the `systems-designer` fills in
-formulas, interaction matrices, and tuning knobs.
 
-**For narrative systems (dialogue, quests, lore):**
+### Step 6c: Loop or Stop
-Coordinate with `narrative-director` in addition to `game-designer`.
 
-**For UI systems:**
+After `/design-system` completes, use `AskUserQuestion`:
-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?"
@@ -307,13 +261,7 @@ If continuing, return to Step 6a.
 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):
+- "Run `/design-system [system-name]` to write the next system's GDD"
-  - 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]`"
@@ -331,11 +279,11 @@ This skill follows the collaborative design principle at every phase:
    - 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?"
+   - Phase 6: "Start designing, pick different, or stop?" then hand off to `/design-system`
 3. **"May I write to [filepath]?"** before every file write
 4. **Incremental writing**: Update the systems index after each system is designed
-5. **Design review loop**: Every completed GDD passes `/design-review` before the
+5. **Handoff**: Individual GDD authoring is owned by `/design-system`, which handles
-   next system starts — holes are caught early, not downstream
+   incremental section writing, cross-referencing, design review, and index updates
 6. **Session state updates**: Write to `production/session-state/active.md` after
    each milestone (index created, system designed, priorities changed)
 

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

@@ -57,14 +57,19 @@ Analyze project structure and content:
 
 ### 2. Classify Project Stage
 
-Based on scanned artifacts, determine stage:
+Based on scanned artifacts, determine stage. Check `production/stage.txt` first —
+if it exists, use its value (explicit override from `/gate-check`). Otherwise,
+auto-detect using these heuristics (check from most-advanced backward):
 
 | Stage | Indicators |
 |-------|-----------|
-| **Concept** | No code or minimal prototype, maybe idea docs |
+| **Concept** | No game concept doc, brainstorming phase |
-| **Pre-production** | Design docs started, prototypes, no main src/ |
+| **Systems Design** | Game concept exists, systems index missing or incomplete |
-| **Production** | Active src/, sprint plans, growing systems |
+| **Technical Setup** | Systems index exists, engine not configured |
-| **Post-Launch** | Released, production/ has release history, maintenance focus |
+| **Pre-Production** | Engine configured, `src/` has <10 source files |
+| **Production** | `src/` has 10+ source files, active development |
+| **Polish** | Explicit only (set by `/gate-check` Production → Polish gate) |
+| **Release** | Explicit only (set by `/gate-check` Polish → Release gate) |
 
 ### 3. Collaborative Gap Identification
 
@@ -73,7 +78,7 @@ 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`?"
+- "I found a game concept but no systems index. Have you decomposed the concept into individual systems yet, or should we run `/map-systems`?"
 - "Prototypes directory has 3 projects with no READMEs. Were these experiments, or do they need documentation?"
 
 ### 4. Generate Stage Report
@@ -85,7 +90,7 @@ Use template: `.claude/docs/templates/project-stage-report.md`
 # Project Stage Analysis
 
 **Date**: [date]
-**Stage**: [Concept/Pre-production/Production/Post-Launch]
+**Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release]
 
 ## Completeness Overview
 - Design: [X%] ([N] docs, [gaps])
@@ -165,7 +170,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
+- **Concept exists but no systems index?** → `/map-systems` to decompose into systems
 - **Missing design docs?** → `/reverse-document design src/[system]`
 - **Missing architecture docs?** → `/architecture-decision` or `/reverse-document architecture`
 - **Prototypes need documentation?** → `/reverse-document concept prototypes/[name]`

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

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

.claude/skills/start/SKILL.md

@@ -77,7 +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
+   - `/map-systems` — decompose the concept into systems and plan GDD writing order
    - `/prototype` — test the core mechanic
    - `/sprint-plan` — plan the first sprint
 
@@ -91,7 +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
+   - `/map-systems` — decompose the concept into systems and plan GDD writing order
    - `/prototype` — test the core mechanic
    - `/sprint-plan` — plan the first sprint
 
@@ -111,7 +111,8 @@ The user knows what they want to make but hasn't documented it.
 3. Show the recommended path (adapted to their choice):
    - `/brainstorm` or `/setup-engine` (their pick)
    - `/design-review` — validate the concept doc
-   - `/design-systems` — decompose the concept into individual systems with dependencies and priorities
+   - `/map-systems` — decompose the concept into individual systems with dependencies and priorities
+   - `/design-system` — author per-system GDDs (guided, section-by-section)
    - `/architecture-decision` — make first technical decisions
    - `/sprint-plan` — plan the first sprint
 
@@ -127,6 +128,7 @@ The user has artifacts already. Figure out what exists and what's missing.
 4. Show the recommended path:
    - `/project-stage-detect` — full gap analysis
    - `/setup-engine` — if not configured
+   - `/design-system` — if systems index exists but GDDs are incomplete
    - `/gate-check` — validate readiness for next phase
    - `/sprint-plan` — organize the work
 

.claude/statusline.sh

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

README.md

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

UPGRADING.md

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

docs/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, 36 slash commands, and automated hooks. It assumes you
+> 48-agent system, 37 slash commands, and automated hooks. It assumes you
 > have Claude Code installed and are working from the project root.
 
 ---
@@ -257,7 +257,7 @@ gets coded yet -- this is pure design and architecture.
 Before writing individual GDDs, enumerate all the systems your game needs:
 
 ```
-/design-systems map
+/map-systems
 ```
 
 This creates `design/gdd/systems-index.md` — a master tracking document that:
@@ -270,11 +270,18 @@ This creates `design/gdd/systems-index.md` — a master tracking document that:
 Then design each system in dependency order:
 
 ```
-/design-systems next
+/map-systems next
 ```
 
-This picks the highest-priority undesigned system and guides you through creating
+This picks the highest-priority undesigned system and hands off to `/design-system`,
-its GDD. Each completed GDD goes through `/design-review` before the next starts.
+which guides you through creating its GDD section by section. Each completed GDD
+goes through `/design-review` before the next starts.
+
+You can also write a specific system's GDD directly:
+
+```
+/design-system combat-system
+```
 
 ### Step 2.2: Create the Game Design Document (GDD)
 
@@ -1714,7 +1721,7 @@ conflicts go to `producer`.
 |-------|----------|
 | **Onboarding** | `/start` |
 | **Ideation** | `/brainstorm` |
-| **Design** | `/design-systems`, `/design-review`, `/architecture-decision` |
+| **Design** | `/map-systems`, `/design-system`, `/design-review`, `/architecture-decision` |
 | **Sprint** | `/sprint-plan`, `/estimate`, `/scope-check`, `/retrospective` |
 | **Implementation** | `/code-review`, `/prototype`, `/tech-debt` |
 | **Testing** | `/balance-check`, `/playtest-report`, `/perf-profile` |
@@ -1736,7 +1743,8 @@ conflicts go to `producer`.
 3. Create a game concept doc (templates/game-concept.md)
 4. Define game pillars (templates/game-pillars.md)
 5. /design-review on your concept doc
-6. Start creating GDDs for each system
+6. /map-systems to decompose concept into systems with dependencies and priorities
+7. /design-system to author per-system GDDs (guided, section-by-section)
 ```
 
 ### Workflow 2: "I have a design and want to start coding"