design-system

!`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): 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. Read it by section: find the headings with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit. 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 **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: 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: "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. 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). ## 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