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:

• Foundation: Systems with zero dependencies (designed and built first)

• Core: Systems depending only on Foundation systems

• Feature: Systems depending on Core systems

• Presentation: UI and feedback systems that wrap gameplay systems

• 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:

• MVP Foundation systems first

• MVP Core systems second

• MVP Feature systems third

• Vertical Slice Foundation/Core systems

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

• Question -> Options -> Decision -> Draft -> Approval at every step

• 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?"

• "May I write to [filepath]?" before every file write

• Incremental writing: Update the systems index after each system is designed

• Design review loop: Every completed GDD passes /design-review before the next system starts — holes are caught early, not downstream

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