Design System

When this skill is invoked:

1. Parse Arguments & Validate

Resolve the review mode (once, store for all gate spawns this run):

1. If --review [full|lean|solo] was passed → use that
2. Else read production/review-mode.txt → use that value
3. Else → default to lean

See .claude/docs/director-gates.md for the full check pattern.

A system name or retrofit path is required. If missing:

1. Check if design/gdd/systems-index.md exists.
2. If it exists: read it, find the highest-priority system with status "Not Started" or equivalent, and use AskUserQuestion:

• Prompt: "The next system in your design order is [system-name] ([priority] | [layer]). Start designing it?"
• Options: [A] Yes — design [system-name] / [B] Pick a different system / [C] Stop here
• If [A]: proceed with that system name. If [B]: ask which system to design (plain text). If [C]: exit.

1. If no systems index exists, fail with:

> "Usage: /design-system — e.g., /design-system movement > Or to fill gaps in an existing GDD: /design-system retrofit design/gdd/[system-name].md > No systems index found. Run /map-systems first to map your systems and get the design order."

Detect retrofit mode: If the argument starts with retrofit or the argument is a file path to an existing .md file in design/gdd/, enter retrofit mode:

1. Read the existing GDD file.
2. Identify which of the 8 required sections are present (scan for section headings).

Required sections: Overview, Player Fantasy, Detailed Design/Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.

1. Identify which sections contain only placeholder text ([To be designed] or

equivalent — blank, a single line, or obviously incomplete).

1. Present to the user before doing anything:

``` ## Retrofit: [System Name] File: design/gdd/[filename].md

Sections already written (will not be touched): ✓ [section name] ✓ [section name]

Missing or incomplete sections (will be authored): ✗ [section name] — missing ✗ [section name] — placeholder only ```

1. Ask: "Shall I fill the [N] missing sections? I will not modify any existing content."
2. If yes: proceed to Phase 2 (Gather Context) as normal, but in Phase 3

skip creating the skeleton (file already exists) and in Phase 4 skip sections that are already complete. Only run the section cycle for missing/ incomplete sections.

1. Never overwrite existing section content. Use Edit tool to replace only

[To be designed] placeholders or empty section bodies.

If NOT in retrofit mode, normalize the system name to kebab-case for the filename (e.g., "combat system" becomes combat-system).

---

2. Gather Context (Read Phase)

Read all relevant context before asking the user anything. This is the skill's primary advantage over ad-hoc design — it arrives informed.

2a: Required Reads

• Game concept: Read design/gdd/game-concept.md — fail if missing:

> "No game concept found. Run /brainstorm first."

• Systems index: Read design/gdd/systems-index.md — fail if missing:

> "No systems index found. Run /map-systems first to map your systems."

• Target system: Find the system in the index. If not listed, warn:

> "[system-name] is not in the systems index. Would you like to add it, or > design it as an off-index system?"

• Entity registry: Read design/registry/entities.yaml if it exists.

Extract all entries referenced by or relevant to this system (grep referenced_by.*[system-name] and source.*[system-name]). Hold these in context as known facts — values that other GDDs have already established and this GDD must not contradict.

• Reflexion log: Read docs/consistency-failures.md if it exists.

Extract entries whose Domain matches this system's category. These are recurring conflict patterns — present them under "Past failure patterns" in the Phase 2d context summary so the user knows where mistakes have occurred before in this domain.

2b: Dependency Reads

From the systems index, identify:

• Upstream dependencies: Systems this one depends on. Read their GDDs if they

exist (these contain decisions this system must respect).

• Downstream dependents: Systems that depend on this one. Read their GDDs if

they exist (these contain expectations this system must satisfy).

For each dependency GDD that exists, extract and hold in context:

• Key interfaces (what data flows between the systems)
• Formulas that reference this system's outputs
• Edge cases that assume this system's behavior
• Tuning knobs that feed into this system

2c: Optional Reads

• Game pillars: Read design/gdd/game-pillars.md if it exists
• Existing GDD: Read design/gdd/[system-name].md if it exists (resume, don't

restart from scratch)

• Related GDDs: Glob design/gdd/*.md and read any that are thematically related

(e.g., if designing a system that overlaps with another in scope, read the related GDD even if it's not a formal dependency)

2d: Present Context Summary

Before starting design work, present a brief summary to the user:

> Designing: [System Name] > - Priority: [from index] | Layer: [from index] > - Depends on: [list, noting which have GDDs vs. undesigned] > - Depended on by: [list, noting which have GDDs vs. undesigned] > - Existing decisions to respect: [key constraints from dependency GDDs] > - Pillar alignment: [which pillar(s) this system primarily serves] > - Known cross-system facts (from registry): > - [entityname]: [attribute]=[value], [attribute]=[value] (owned by [source GDD]) > - [itemname]: [attribute]=[value], [attribute]=[value] (owned by [source GDD]) > - [formulaname]: variables=[list], output=[min–max] (owned by [source GDD]) > - [constantname]: [value] [unit] (owned by [source GDD]) > (These values are locked — if this GDD needs different values, surface > the conflict before writing. Do not silently use different numbers.) > > If no registry entries are relevant: omit the "Known cross-system facts" section.

If any upstream dependencies are undesigned, warn: > "[dependency] doesn't have a GDD yet. We'll need to make assumptions about > its interface. Consider designing it first, or we can define the expected > contract and flag it as provisional."

2e: Technical Feasibility Pre-Check

Before asking the user to begin designing, load engine context and surface any constraints or knowledge gaps that will shape the design.

Step 1 — Determine the engine domain for this system: Map the system's category (from systems-index.md) to an engine domain:

| System Category | Engine Domain | |----------------|--------------| | Combat, physics, collision | Physics | | Rendering, visual effects, shaders | Rendering | | UI, HUD, menus | UI | | Audio, sound, music | Audio | | AI, pathfinding, behavior trees | Navigation / Scripting | | Animation, IK, rigs | Animation | | Networking, multiplayer, sync | Networking | | Input, controls, keybinding | Input | | Save/load, persistence, data | Core | | Dialogue, quests, narrative | Scripting |

Step 2 — Read engine context (if available):

• Read .claude/docs/technical-preferences.md to identify the engine and version
• If engine is configured, read docs/engine-reference/[engine]/VERSION.md
• Read docs/engine-reference/[engine]/modules/[domain].md if it exists
• Read docs/engine-reference/[engine]/breaking-changes.md for domain-relevant entries
• Glob docs/architecture/adr-*.md and read any ADRs whose domain matches

(check the Engine Compatibility table's "Domain" field)

Step 3 — Present the Feasibility Brief:

If engine reference docs exist, present before starting design:

## Technical Feasibility Brief: [System Name]
Engine: [name + version]
Domain: [domain]

### Known Engine Capabilities (verified for [version])
- [capability relevant to this system]
- [capability 2]

### Engine Constraints That Will Shape This Design
- [constraint from engine-reference or existing ADR]

### Knowledge Gaps (verify before committing to these)
- [post-cutoff feature this design might rely on — mark HIGH/MEDIUM risk]

### Existing ADRs That Constrain This System
- ADR-XXXX: [decision summary] — means [implication for this GDD]
  (or "None yet")

If no engine reference docs exist (engine not yet configured), show a short note: > "No engine configured yet — skipping technical feasibility check. Run > /setup-engine before moving to architecture if you haven't already."

Step 4 — Ask before proceeding:

Use AskUserQuestion:

• "Any constraints to add before we begin, or shall we proceed with these noted?"
• Options: "Proceed with these noted", "Add a constraint first", "I need to check the engine docs — pause here"

---

Use AskUserQuestion:

• "Ready to start designing [system-name]?"
• Options: "Yes, let's go", "Show me more context first", "Design a dependency first"

---

3. Create File Skeleton

Once the user confirms, immediately create the GDD file with empty section headers. This ensures incremental writes have a target.

Use the template structure from .claude/docs/templates/game-design-document.md:

# [System Name]

> **Status**: In Design
> **Author**: [user + agents]
> **Last Updated**: [today's date]
> **Implements Pillar**: [from context]

## Overview

[To be designed]

## Player Fantasy

[To be designed]

## Detailed Design

### Core Rules

[To be designed]

### States and Transitions

[To be designed]

### Interactions with Other Systems

[To be designed]

## Formulas

[To be designed]

## Edge Cases

[To be designed]

## Dependencies

[To be designed]

## Tuning Knobs

[To be designed]

## Visual/Audio Requirements

[To be designed]

## UI Requirements

[To be designed]

## Acceptance Criteria

[To be designed]

## Open Questions

[To be designed]

Ask: "May I create the skeleton file at design/gdd/[system-name].md?"

After writing, update production/session-state/active.md:

• Use Glob to check if the file exists.
• If it does not exist: use the Write tool to create it. Never attempt Edit on a file that may not exist.
• If it already exists: use the Edit tool to update the relevant fields.

File content:

• Task: Designing [system-name] GDD
• Current section: Starting (skeleton created)
• File: design/gdd/[system-name].md

---

4. Section-by-Section Design

Walk through each section in order. For each section, follow this cycle:

The Section Cycle

Context  ->  Questions  ->  Options  ->  Decision  ->  Draft  ->  Approval  ->  Write

1. Context: State what this section needs to contain, and surface any relevant

decisions from dependency GDDs that constrain it.

1. Questions: Ask clarifying questions specific to this section. Use

AskUserQuestion for constrained questions, conversational text for open-ended exploration.

1. Options: Where the section involves design choices (not just documentation),

present 2-4 approaches with pros/cons. Explain reasoning in conversation text, then use AskUserQuestion to capture the decision.

1. Decision: User picks an approach or provides custom direction.

1. Draft: Write the section content in conversation text for review. Flag any

provisional assumptions about undesigned dependencies.

1. Approval: Immediately after the draft — in the SAME response — use

AskUserQuestion. NEVER use plain text. NEVER skip this step.

• Prompt: "Approve the [Section Name] section?"
• Options: [A] Approve — write it to file / [B] Make changes — describe what to fix / [C] Start over

The draft and the approval widget MUST appear together in one response. If the draft appears without the widget, the user is left at a blank prompt with no path forward — this is a protocol violation.

1. Write: Use the Edit tool to replace the placeholder with the approved content.

CRITICAL: Always include the section heading in the old_string to ensure uniqueness — never match [To be designed] alone, as multiple sections use the same placeholder and the Edit tool requires a unique match. Use this pattern: `` old_string: "## [Section Name]\n\n[To be designed]" new_string: "## [Section Name]\n\n[approved content]" `` Confirm the write.

1. Registry conflict check (Sections C and D only — Detailed Design and Formulas):

After writing, scan the section content for entity names, item names, formula names, and numeric constants that appear in the registry. For each match:

• Compare the value just written against the registry entry.
• If they differ: surface the conflict immediately before starting the next

section. Do not continue silently. > "Registry conflict: [name] is registered in [source GDD] as [registryvalue]. > This section just wrote [newvalue]. Which is correct?"

• If new (not in registry): flag it as a candidate for registry registration

(will be handled in Phase 5).

After writing each section, update production/session-state/active.md with the completed section name. Use Glob to check if the file exists — use Write to create it if absent, Edit to update it if present.

Section-Specific Guidance

Each section has unique design considerations and may benefit from specialist agents:

---

Section A: Overview

Goal: One paragraph a stranger could read and understand.

Derive recommended options before building the widget: Read the system's category and layer from the systems index (already in context from Phase 2), then determine the recommended option for each tab:

• Framing tab: Foundation/Infrastructure layer → [A] recommended. Player-facing categories (Combat, UI, Dialogue, Character, Animation, Visual Effects, Audio) → [C] Both recommended.
• ADR ref tab: Glob docs/architecture/adr-*.md and grep for the system name in the GDD Requirements section of any ADR. If a matching ADR is found → [A] Yes — cite the ADR recommended. If none found → [B] No recommended.
• Fantasy tab: Foundation/Infrastructure layer → [B] No recommended. All other categories → [A] Yes recommended.

Append (Recommended) to the appropriate option text in each tab.

Framing questions (ask BEFORE drafting): Use AskUserQuestion with a multi-tab widget:

• Tab "Framing" — "How should the overview frame this system?" Options: [A] As a data/infrastructure layer (technical framing) / [B] Through its player-facing effect (design framing) / [C] Both — describe the data layer and its player impact
• Tab "ADR ref" — "Should the overview reference the existing ADR for this system?" Options: [A] Yes — cite the ADR for implementation details / [B] No — keep the GDD at pure design level
• Tab "Fantasy" — "Does this system have a player fantasy worth stating?" Options: [A] Yes — players feel it directly / [B] No — pure infrastructure, players feel what it enables

Use the user's answers to shape the draft. Do NOT answer these questions yourself and auto-draft.

Questions to ask:

• What is this system in one sentence?
• How does a player interact with it? (active/passive/automatic)
• Why does this system exist — what would the game lose without it?

Cross-reference: Check that the description aligns with how the systems index describes it. Flag discrepancies.

Design vs. implementation boundary: Overview questions must stay at the behavior level — what the system does, not how it is built. If implementation questions arise during the Overview (e.g., "Should this use an Autoload singleton or a signal bus?"), note them as "→ becomes an ADR" and move on. Implementation patterns belong in /architecture-decision, not the GDD. The GDD describes behavior; the ADR describes the technical approach used to achieve it.

---

Section B: Player Fa

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IdoCohen560
• Source: IdoCohen560/claude-unity-game-studio
• License: MIT
• Homepage: https://idos-digital-portfolio.netlify.app/

Install and usage instructions live in the source repository linked above.