!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,system_overrides
Resolved above — use as-is; --review overrides review_mode. No block →
defaults in .claude/docs/config-resolution.md.
Design System
When this skill is invoked:
1. Parse Arguments & Validate
Read references/1-parse-arguments.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
2. Gather Context (Read Phase)
Read references/2-gather-context.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
3. Create File Skeleton
Read references/3-file-skeleton.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
4. Section-by-Section Design
Read references/4-section-design.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
5. Post-Design Validation
Read references/5-post-design.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
6. Specialist Agent Routing
This skill delegates to specialist agents for domain expertise. The main session
orchestrates the overall flow; agents provide expert content.
Rows here are finer-grained than the nine Category values on purpose — the
right specialist for combat is not the right specialist for pathfinding, and both
are Gameplay. Resolve in two steps: take the system's Category from
systems-index.md, then pick the row within it that matches what the system
actually does. Every category has at least one row, so nothing falls through.
Category | Rows below to choose from |
|---|
Gameplay | Combat/damage/health · AI/pathfinding/behavior · Animation/character movement · Character systems · Camera/input/controls |
Core | Foundation/Infrastructure · Camera/input/controls |
Persistence | Foundation/Infrastructure |
Economy | Economy/loot/crafting |
Progression | Progression/XP/skills |
UI | UI systems · Visual effects (when the system is HUD-adjacent VFX) |
Audio | Audio systems |
Narrative | Dialogue/quests/lore |
Meta | Foundation/Infrastructure (analytics, tutorial plumbing) · UI systems (accessibility options screens) |
If two rows fit, spawn the union of their Primary agents and say why.
| System type | Primary Agent | Supporting Agent(s) |
|---|
| Foundation/Infrastructure (event bus, save/load, scene mgmt, service locator) | systems-designer | gameplay-programmer (feasibility), engine-programmer (engine integration) |
| Combat, damage, health | game-designer | systems-designer (formulas), ai-programmer (enemy AI), art-director (hit feedback visual direction, VFX intent) |
| 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), art-director (character visual profiles, cinematic tone) |
| UI systems (HUD, menus) | game-designer | ux-designer (flows), ui-programmer (feasibility), art-director (visual style direction), technical-artist (render/shader constraints) |
| 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) |
| Animation, character movement | game-designer | art-director (animation style, pose language), technical-artist (rig/blend constraints), gameplay-programmer (feel) |
| Visual effects, particles, shaders | game-designer | art-director (VFX visual direction), technical-artist (performance budget, shader complexity), systems-designer (trigger/state integration) |
| Character systems (stats, archetypes) | game-designer | art-director (character visual archetype), narrative-director (character arc alignment), systems-designer (stat formulas) |
When delegating via the Agent 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):
- Read
production/session-state/active.md — it records the current system and
which sections are complete
- Read
design/gdd/[system-name].md — sections with real content are done;
sections with [To be designed] still need work
- 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
In collaborative mode (the default). For guided and autonomous
modes, see the per-mode rules in .claude/docs/automation-modes.md — the
"Never" lines below describe what collaborative mode requires, not what
applies universally.
This skill follows the collaborative design principle at every step:
- Question -> Options -> Decision -> Draft -> Approval for every section
- 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: "May I update the entity registry? May I update the systems
index? What's next?" — not "Run design review?": §5c forbids offering
/design-review inline, because the reviewing agent must not inherit this
session's design history. Phase 5c presents the hand-off; it never asks.
- "May I write to [filepath]?" before the skeleton and before each section write
- Incremental writing: Each section is written to file immediately after approval
- Session state updates: After every section write
- Cross-referencing: Every section checks existing GDDs for conflicts
- 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).
Context Window Awareness
This is a long-running skill. After writing each section, check if the status line
shows context at or above 70%. If so, append this notice to the response:
Context is approaching the limit (≥70%). Your progress is saved — all approved
sections are written to design/gdd/[system-name].md. When you're ready to continue,
open a fresh Claude Code session and run /design-system [system-name] — it will
detect which sections are complete and resume from the next one.
Recommended Next Steps
- Run
/design-review design/gdd/[system-name].md in a fresh session to validate the completed GDD independently
- Run
/consistency-check to verify this GDD's values don't conflict with other GDDs
- Run
/map-systems next to move to the next highest-priority undesigned system
- Run
/gate-check technical-setup when all MVP GDDs are authored and reviewed