Claude-Code-Game-Studios/.claude/skills/design-systems/SKILL.md

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