Decompose a game concept into individual systems, map dependencies, prioritize design order, and create the systems index.
When this skill is invoked:
Two modes:
/map-systems — Run the full decomposition workflow (Phases 1-5)
to create or update the systems index.next: /map-systems next — Pick the highest-priority undesigned system
from the index and hand off to /design-system (Phase 6).Also resolve the review mode (once, store for all gate spawns this run):
--review [full|lean|solo] was passed → use thatproduction/review-mode.txt → use that valueleanSee .claude/docs/director-gates.md for the full check pattern.
Read the game concept and any existing design work. This provides the raw material for systems decomposition.
Required:
design/gdd/game-concept.md — fail with a clear message if missing:
"No game concept found at
design/gdd/game-concept.md. Run/brainstormfirst to create one, then come back to decompose it into systems."
Optional (read if they exist):
design/gdd/game-pillars.md — pillars constrain priority and scopedesign/gdd/systems-index.md — if exists, resume from where it left off
(update, don't recreate from scratch)design/gdd/*.md — check which system GDDs already existIf the systems index already exists:
AskUserQuestion to ask:
"The systems index already exists with [N] systems ([M] designed, [K] not started).
What would you like to do?"
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.
Scan the game concept for directly mentioned systems and mechanics:
For each explicit system, identify the hidden systems it implies. Games always need more systems than the concept doc mentions. Use this inference pattern:
Explain in conversation text why each implicit system is needed (with examples).
Present the enumeration organized by category. For each system, show:
Then use AskUserQuestion to capture feedback:
Iterate until the user approves the enumeration.
For each system, determine what it depends on. A system "depends on" another if it cannot function without that other system existing first.
For each system, list its dependencies. Use these dependency heuristics:
Arrange systems into layers:
Check for cycles in the dependency graph. If found:
Show the dependency map as a layered list. Highlight:
Use AskUserQuestion to ask: "Does this dependency ordering look right? Any
dependencies I'm missing or that should be removed?"
Review mode check — apply before spawning TD-SYSTEM-BOUNDARY:
solo → skip. Note: "TD-SYSTEM-BOUNDARY skipped — Solo mode." Proceed to priority assignment.lean → skip (not a PHASE-GATE). Note: "TD-SYSTEM-BOUNDARY skipped — Lean mode." Proceed to priority assignment.full → spawn as normal.After dependency mapping is approved, spawn technical-director via Task using gate TD-SYSTEM-BOUNDARY (.claude/docs/director-gates.md) before proceeding to priority assignment.
Pass: the dependency map summary, layer assignments, bottleneck systems list, any circular dependency resolutions.
Present the assessment. If REJECT, revise the system boundaries with the user before moving to priority assignment. If CONCERNS, note them inline in the systems index and continue.
Assign each system to a priority tier based on what milestone it's needed for.
Use these heuristics for initial assignment:
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."
"Why" column guidance: When explaining why each system was placed in a priority tier, mix technical necessity with player-experience reasoning. Do not use purely technical justifications like "Combat needs damage math" — connect to player experience where relevant. Examples of good "Why" entries:
Pure technical necessity ("X depends on Y") is insufficient alone when the system directly shapes player experience.
Review mode check — apply before spawning PR-SCOPE:
solo → skip. Note: "PR-SCOPE skipped — Solo mode." Proceed to writing the systems index.lean → skip (not a PHASE-GATE). Note: "PR-SCOPE skipped — Lean mode." Proceed to writing the systems index.full → spawn as normal.After priorities are approved, spawn producer via Task using gate PR-SCOPE (.claude/docs/director-gates.md) before writing the index.
Pass: total system count per milestone tier, estimated implementation volume per tier (system count × average complexity), team size, stated project timeline.
Present the assessment. If UNREALISTIC, offer to revise priority tier assignments before writing the index. If CONCERNS, note them and continue.
Combine dependency sort + priority tier to produce the final design order:
This is the order the team should write GDDs in.
Using the template at .claude/docs/templates/systems-index.md, populate the
systems index with all data from Phases 2-4:
Present a summary of the document:
Ask: "May I write the systems index to design/gdd/systems-index.md?"
Wait for approval. Write the file only after "yes."
Review mode check — apply before spawning CD-SYSTEMS:
solo → skip. Note: "CD-SYSTEMS skipped — Solo mode." Proceed to Phase 7 next steps.lean → skip (not a PHASE-GATE). Note: "CD-SYSTEMS skipped — Lean mode." Proceed to Phase 7 next steps.full → spawn as normal.After the systems index is written, spawn creative-director via Task using gate CD-SYSTEMS (.claude/docs/director-gates.md).
Pass: systems index path, game pillars and core fantasy (from design/gdd/game-concept.md), MVP priority tier system list.
Present the assessment. If REJECT, revise the system set with the user before GDD authoring begins. If CONCERNS, record them in the systems index as a > **Creative Director Note** at the top of the relevant tier section.
After writing, create production/session-state/active.md if it does not exist, then update it with:
Verdict: COMPLETE — systems index written to design/gdd/systems-index.md.
If the user declined: Verdict: BLOCKED — user did not approve the write.
This phase is entered when:
/map-systems [system-name]/map-systems nextnext was used, pick the highest-priority undesigned system (by design order)Use AskUserQuestion for: "Start designing [system-name] now, pick a different
system, or stop here?"
Once a system is selected, invoke the /design-system [system-name] skill.
The /design-system skill handles the full GDD authoring process:
/design-review when completeDo not duplicate the /design-system workflow here. This skill owns the systems
index; /design-system owns individual system GDDs.
After /design-system completes, use AskUserQuestion:
If continuing, return to Step 6a.
After the systems index is created (or after designing some systems), present next actions using AskUserQuestion:
/design-system [first-system-in-order]creative-director or technical-director to validate the system set before committing to 10+ GDD sessionsThe director review option ([B]) is worth highlighting: having a Creative Director or Technical Director review the completed systems index before starting GDD authoring catches scope issues, missing systems, and boundary problems before they're locked in across many documents. It is optional but recommended for new projects.
After any individual GDD is completed:
/design-review design/gdd/[system].md in a fresh session to validate quality"/gate-check systems-design when all MVP GDDs are complete"This skill follows the collaborative design principle at every phase:
/design-system/design-system, which handles
incremental section writing, cross-referencing, design review, and index updatesproduction/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.
If context reaches or exceeds 70% at any point, append this notice:
Context is approaching the limit (≥70%). The systems index is saved to
design/gdd/systems-index.md. Open a fresh Claude Code session to continue designing individual GDDs — run/map-systems nextto pick up where you left off.
/design-system [first-system-in-order] to author the first GDD (use design order from the index)/map-systems next to always pick the highest-priority undesigned system automatically/design-review design/gdd/[system].md in a fresh session after each GDD is authored/gate-check pre-production when all MVP GDDs are authored and reviewed