Section-by-section GDD authoring for one system — walks through each required section, cross-references dependencies.
复制下面这句话，粘贴给 Claude Code、Codex、Cursor 等 AI 编程工具，它会读取安装说明并在你确认后完成安装。
请阅读 https://ai.atlankj.com/install/asset/gh-design-system-bbdadcfee9a7 ，按照其中的说明把「design-system」安装到你（当前 AI 工具）中。执行前先告诉我将运行的命令和写入的位置，等我确认。
查看 AI 将读取的安装说明正在读取 GitHub 原文…
内容来自 GitHub 原始文件，由原作者维护。在 GitHub 查看
!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.
When this skill is invoked:
See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.
Every AskUserQuestion call follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
docs.density — it controls per-section depth, where workflow
controls which sections exist. modes.rigor sets both together; set
docs.density explicitly to vary depth alone: terse = bullet points, 2–5 lines per section,
skip rationale and preambles; balanced = paragraphs with light rationale
(default); thorough = full prose with rationale, examples, and alternatives
considered. Apply it to every section you author. Mandated structures (the
Formulas variable table, Given-When-Then acceptance criteria) are correctness
requirements at every density — terse trims the surrounding prose, never the
required structure itself.
A system name or retrofit path is required. If missing:
design/gdd/systems-index.md exists.AskUserQuestion:
[A] Yes — design [system-name] / [B] Pick a different system / [C] Stop here"Usage:
/design-system <system-name>— e.g.,/design-system movementOr to fill gaps in an existing GDD:/design-system retrofit design/gdd/[system-name].mdNo systems index found. Run/map-systemsfirst 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:
standard only 5 are, plus Formulas for math categories, and Player Fantasy
and Tuning Knobs are skipped by design. Report an absent section as a gap
only when the tier requires it; otherwise list it as available-to-add. Calling
all 8 required here reports two by-design-absent sections as gaps on every
standard project.[To be designed] or
equivalent — blank, a single line, or obviously incomplete).## 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
[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).
workflow for this system (per .claude/docs/workflow-modes.md) — use the
system_overrides row for this system if the block lists one, else the project
value.
The resolved tier determines which GDD sections are required (applied in §4).
## Summary is required at every tier and is not one of the 8 — §5-pre
authors it unconditionally ("This runs at every tier"), but it appeared in none
of the per-tier lists below, and these lists are what other skills and gates
apply. A GDD checked against a tier list alone would pass with no Summary, the
one section /review-all-gdds and the tiered-loading readers depend on. Read
every list below as "## Summary, plus:".
full — all 8 sections
standard — Overview, Detailed Design, Edge Cases, Dependencies, Acceptance
Criteria (5 required); Formulas conditional — required when the system
defines numeric rules: rates, curves, thresholds, costs, damage, drop
weights, or any value a balance pass would tune. Optional only when the system
defines no such value. The Category in systems-index.md is a hint, not
the test — Gameplay, Economy and Progression systems almost always
qualify, and a Core, UI or Persistence system that defines a numeric rule
qualifies too. If the Detailed Design states a quantity that is not a constant
of the engine, Formulas is required. Player Fantasy and Tuning Knobs skipped
unless workflow_overrides force them (tuning_knobs: true forces Tuning Knobs)
Do not gate this on a category token. A rule of the form "required when the system category is combat / economy / progression / AI" does not work: those four tokens are not what
/map-systemswrites —templates/systems-index.mddefines the categories asCore · Gameplay · Progression · Economy · Persistence · UI · Audio · Narrative · Metaand lists combat and AI as example systems underGameplay. A combat system categorised exactly as the template instructs matches none of the four, and Formulas would be dropped for the system most likely to need it.
minimal — a GDD is not required (the game brief replaces it). If invoked
voluntarily at minimal, author exactly the 5 standard sections (Overview,
Detailed Design, Edge Cases, Dependencies, Acceptance Criteria) — the
conditional Formulas rule does NOT re-apply at minimal — and tell the user
the GDD is optional at this workflow level.
Retrofit mode is unaffected — it fills whatever sections are missing regardless of tier.
Read all relevant context before asking the user anything. This is the skill's primary advantage over ad-hoc design — it arrives informed.
At
minimal(design-system is voluntary at this tier): readdesign/game-brief.mdin place of the game concept, and skip the systems-index read — neithergame-concept.mdnorsystems-index.mdexists atminimal. Author from the brief's relevant MVP feature and its core loop.This callout keys on the PROJECT tier, not this system's effective tier. The two differ whenever
workflow_overrides.system_overridesbumps one system above aminimalproject — the configuration.claude/docs/settings-guidance.mdadvertises as the reason the override exists ("bump one deep system"). Those two files are absent because the project isminimal; raising this system tostandardorfulldoes not create them. So on aminimalproject, take this branch even for an overridden system, and read the brief.The effective tier still governs everything downstream — the required section set (§1), the skeleton (§3), the section cycle (§4) and §5a. Only the required-reads branch here follows the project tier.
Then derive
Category,LayerandPriorityfrom the brief, once, here. Six later steps are keyed on the systems index you just skipped — §2e's engine domain, Section A's and Section B's recommended options, the Visual/Audio REQUIRED table, §6 specialist routing, and §5-pre's Quick reference — and none of them has an absent-index branch. An overridden system reaches all six atstandardorfull, so "skip the index" leaves them with no input at all. Derive from the brief instead:
Category— one of the nine intemplates/systems-index.md(Core · Gameplay · Progression · Economy · Persistence · UI · Audio · Narrative · Meta), chosen from what the brief says the system does.Layer—Foundationif other systems depend on it, elseFeature.Priority—MVPif the brief's build order lists it, elsePost-MVP.Carry all three for the rest of the run and treat them as the index's answer. Mark them inferred in §5-pre's Quick reference ("Category: Gameplay (inferred from the brief — no systems index at this tier)") so a later reader does not mistake a derivation for an indexed fact. Do write a systems index to hold them: owns that file (§5d).
design/gdd/game-concept.md — fail if missing:
"No game concept found. Run
/brainstormfirst."
design/gdd/systems-index.md — fail if missing:
"No systems index found. Run
/map-systemsfirst to map your systems."
"[system-name] is not in the systems index. Would you like to add it, or design it as an off-index system?"
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.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.From the systems index, identify:
For each dependency GDD that exists, read only the four sections that carry the cross-system contract — not the whole GDD:
Grep pattern="## (Dependencies|Formulas|Edge Cases|Tuning Knobs)" glob="design/gdd/[dep].md" output_mode="content" -A 20
Much of this is already in entities.yaml (loaded in 2a) — the registry's
formula_map/constant_map carry the owned values with their source:. Use the
registry first; the section grep fills what it does not hold.
design/gdd/game-pillars.md if it existsdesign/gdd/[system-name].md if it exists (resume, don't
restart from scratch)design/gdd/*.md hunting for
"thematically related" systems — there is no deterministic proxy for that and it
is the read the registry exists to replace. entities.yaml (2a) already holds
the cross-system facts a related GDD would supply. If a specific overlap is
known, treat it as a dependency above and section-grep it; otherwise rely on the
registry.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):
- [entity_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD])
- [item_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD])
- [formula_name]: variables=[list], output=[min–max] (owned by [source GDD])
- [constant_name]: [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."
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:
Keyed on the Category column of systems-index.md. All nine categories
templates/systems-index.md defines appear here; where a category spans several
engine domains, pick the row matching what the system actually does and say
which you picked.
Category | Engine Domain |
|---|---|
Gameplay | Physics for combat / collision / movement; Navigation for AI and pathfinding; Scripting for rule-only systems with no engine surface |
Core | Core — scene management, state, resource loading; Input for controls and keybinding |
UI | UI |
Audio | Audio |
Narrative | Scripting — dialogue, quests, cutscenes |
Progression | Scripting — save-adjacent rule logic, no dedicated domain |
Economy | Scripting — data and rule logic, no dedicated domain |
Persistence | Core — save/load, settings, serialization |
Meta | Core — analytics, tutorials, accessibility plumbing |
Animation, Rendering and Networking are engine domains with no category of their own: a system needing them will be
GameplayorCore. Name the domain you read the reference for, whichever row you came in on.
Step 2 — Read engine context (if available):
Identify the engine and version: read engine.name and engine.version from project.yaml. Resolve each field independently — if its key is absent or empty (including when project.yaml has no engine: block), fall back to .claude/docs/technical-preferences.md (a [TO BE CONFIGURED] value means not set)
If engine is configured, read docs/engine-reference/[engine]/VERSION.md
Read docs/engine-reference/[engine]/modules/[domain].md if it exists.
If it does not exist, say so by name — "no engine reference for [domain]
under docs/engine-reference/[engine]/modules/; feasibility not checked against
the pinned engine" — and carry that into §5-pre. A silent skip here is
indistinguishable from a feasibility check that ran and found nothing wrong,
which is the failure .claude/rules/skill-authoring.md obligation 3 exists to
stop.
This is not a rare branch. The domain table above names
ScriptingandCorefor five of the nine categories (Narrative,Progression,Economy→ Scripting;Persistence,Meta→ Core), plus a sub-row each underGameplayandCore. The Godot reference shipsanimation, audio, input, navigation, networking, physics, rendering, ui— there is noscripting.mdand nocore.md. So the majority of non-Gameplaysystems hit the absent branch every time, andif it existsturned that into silence. Either the reference gains those two files or the check reports it; until the former, do the latter.
Read docs/engine-reference/[engine]/breaking-changes.md for domain-relevant entries
Find the domain-matching ADRs without reading every ADR to learn the field you filter on — grep the Domain field first, then read only the matches:
Grep pattern="\*\*Domain\*\*" glob="docs/architecture/adr-*.md" output_mode="content"
Read only the ADRs whose Domain matches this system's category (its ## Decision
and ## Engine Compatibility sections); skip the rest.
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-enginebefore moving to architecture if you haven't already."
Step 4 — Ask before proceeding:
Use AskUserQuestion:
Use AskUserQuestion:
Once the user confirms, immediately create the GDD file with empty section headers. This ensures incremental writes have a target.
Scaffold only the sections required at the resolved tier (§1): at
standard, omit Player Fantasy and Tuning Knobs (and Formulas only when the
system defines no numeric rule — see §1; the category is a hint, not the test);
at full, scaffold all 8.
Only the sections §1 named as omitted are skipped — do not leave empty
[To be designed] placeholders for those. Every other section in the template
is scaffolded with its placeholder, including the ones §4 has not decided yet.
This sentence governs the three tier omissions above (Player Fantasy, Tuning
Knobs, and Formulas when no numeric rule exists) and nothing else: it is not a
licence to strip a section because it looks optional, and §4 cannot fill a
section §3 never created.
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]
> **Last Verified**: [today's date]
> **Implements Pillar**: [from context]
## Summary
[To be designed]
> **Quick reference** — Layer: `[Foundation | Core | Feature | Presentation]` · Priority: `[MVP | Vertical Slice | Alpha | Full Vision]` · Key deps: `[System names or "None"]`
## 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]
## Game Feel
[To be designed]
## UI Requirements
[To be designed]
## Cross-References
[To be designed]
## Acceptance Criteria
[To be designed]
## Open Questions
[To be designed]
This skeleton and the template must stay identical in section set and order. They diverged once and it was invisible: the skeleton omitted
## Game Feeland## Cross-References, so §3's own rule — "§4 cannot fill a section §3 never created" — made both unreachable at every tier,fullincluded, while §3's prose above still said "every other section in the template is scaffolded". Two agents authoring a combat GDD noticed the gap only by opening the template. If you add a section to one file, add it to the other in the same commit.
Ask: "May I create the skeleton file at design/gdd/[system-name].md?"
If the user declines: Stop with the following message:
"Verdict: BLOCKED — skeleton creation declined. The design session cannot proceed without the skeleton file, as all subsequent phases use it as the base. Re-run
/design-system [system]when ready to create the file." Do not proceed to Section A.
After writing, update production/session-state/active.md:
File content:
Author only the sections required at the resolved tier (§1). At standard,
the walk covers A (Overview), C (Detailed Design), E (Edge Cases),
F (Dependencies), H (Acceptance Criteria) — plus D (Formulas) when the system
defines numeric rules (see §1; the category is a hint, not the test); skip B (Player Fantasy) and
G (Tuning Knobs) unless workflow_overrides.tuning_knobs: true forces G. At
full, walk all eight (A–H). At minimal, the GDD is optional — if authoring
voluntarily, walk the standard set. Any system_overrides.<system> tier was
already folded into the resolved tier in §1.
Walk through each required section in order. For each section, follow this cycle:
Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write
Context: State what this section needs to contain, and surface any relevant decisions from dependency GDDs that constrain it.
Questions: Ask clarifying questions specific to this section. Use
AskUserQuestion for constrained questions, conversational text for open-ended
exploration.
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.
Decision: User picks an approach or provides custom direction.
Draft: Write the section content in conversation text for review. Flag any provisional assumptions about undesigned dependencies.
Approval: Per the resolved modes.automation mode
(.claude/docs/automation-modes.md):
In collaborative mode: Immediately after the draft — in the SAME
response — use AskUserQuestion. NEVER use plain text. NEVER skip
this step.
[A] Approve — write it to file / [B] Make changes — describe what to fix / [C] Start overThe 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 in collaborative mode.
In guided mode: Write the section immediately after the draft with
a brief one-line summary of what was decided. Skip the per-section widget;
the multi-section authoring rule (no per-section confirmation) applies.
In autonomous mode: Write the section directly and call
log_decision with Decision point: Approve [Section Name] section,
Chosen: [A] Approve, Category: minor.
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]"
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.
Each section has unique design considerations and may benefit from specialist agents:
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:
Category column (Core · Gameplay · Progression · Economy · Persistence · UI · Audio · Narrative · Meta). Player-facing — Gameplay, UI, Audio, Narrative → [C] Both recommended. Internal — Core, Persistence, Meta → [A] recommended. Mixed — Economy, Progression → [C] Both. Tiebreak, when Layer and Category disagree (a Foundation-layer Gameplay system is the common case): Category wins — the framing describes what the section is about, and a player-facing system stays player-facing wherever it sits in the dependency graph.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.[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:
[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[A] Yes — cite the ADR for implementation details / [B] No — keep the GDD at pure design level[A] Yes — players feel it directly / [B] No — pure infrastructure, players feel what it enablesUse the answers to shape the draft. In collaborative mode, do NOT answer
these questions yourself and auto-draft — the widget must appear. In guided
and autonomous, this is a MINOR framing decision: select the recommended
option derived above, state it in one line, and proceed (that is the whole
point of pre-deriving recommendations). Applies to every "ask BEFORE drafting"
widget in this section walk, not just this one.
Questions to ask:
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.
Goal: The emotional target — what the player should feel.
Derive recommended option before building the widget: Read the system's category and layer from Phase 2 context:
Keyed on the Category column (Core · Gameplay · Progression · Economy · Persistence · UI · Audio · Narrative · Meta):
Gameplay, UI, Audio, Narrative → [A] Direct recommendedCore, Persistence, Meta → [B] Indirect recommendedEconomy, Progression → [C] Both recommendedWhen Layer and Category disagree, Category wins — same tiebreak as the Framing tab above.
Append (Recommended) to the appropriate option text.
Framing question (ask BEFORE drafting): Use AskUserQuestion:
[A] Direct — player actively uses or feels this system / [B] Indirect — player experiences the effects, not the system / [C] Both — has a direct interaction layer and infrastructure beneath itUse the answer to frame the Player Fantasy section appropriately. Do NOT assume the answer.
Questions to ask:
Cross-reference: Must align with the game pillars. If the system serves a pillar, quote the relevant pillar text.
Review mode check (apply before spawning):
solo → skip this agent spawn. Draft the section without the specialist. Add a note: "creative-director not consulted — Solo mode. Review manually before production."lean → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent.full → spawn as described below.Agent delegation (MANDATORY): After the framing answer is given but before drafting,
spawn creative-director via Agent:
Do NOT draft Section B without first consulting creative-director. The framing
answer tells us what kind of fantasy it is; the creative-director shapes how it's
described — tone, language, the specific player moment to anchor to.
Goal: Unambiguous specification a programmer could implement without questions.
This is usually the largest section. Break it into sub-sections:
Questions to ask:
Review mode check (apply before spawning):
solo → skip this agent spawn. Draft the section without the specialist. Add a note: "Specialist agents not consulted — Solo mode. Review manually before production."lean → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent.full → spawn as described below.Agent delegation (MANDATORY): Before drafting Section C, spawn specialist agents via Agent in parallel:
AskUserQuestionDo NOT draft Section C without first consulting the appropriate specialists. A systems-designer reviewing rules and mechanics will catch design gaps the main session cannot.
Cross-reference: For each interaction listed, verify it matches what the dependency GDD specifies. If a dependency defines a value or formula and this system expects something different, flag the conflict.
Goal: Every mathematical formula, with variables defined, ranges specified, and edge cases noted.
Completion Steering — always begin each formula with this exact structure:
The [formula_name] formula is defined as:
`[formula_name] = [expression]`
**Variables:**
| Variable | Type | Range | Source | Description |
|----------|------|-------|--------|-------------|
| [name] | float/int | [min–max] | data file / calculated / constant | [what it represents] |
**Output Range:** [min] to [max] under normal play; [behaviour at extremes]
**Example:** [worked example with real numbers]
Do NOT write [Formula TBD] or describe a formula in prose without the variable
table. A formula without defined variables cannot be implemented without guesswork.
These columns must match
templates/game-design-document.mdexactly. They did not: this block saidSymbolwhere the template saysSource, so a correctly-authored GDD was wrong against whichever of the two its reader happened to hold.Sourceis the column that stays, because it is what carries the coding-standards rule "gameplay values must be data-driven (external config), never hardcoded" into the design document — a variable markeddata fileis a tuning knob, one markedconstantis a deliberate exception, and the distinction is invisible under aSymbolcolumn. Put a symbol, where one helps, in the expression itself.
Questions to ask:
Review mode check (apply before spawning):
solo → skip this agent spawn. Draft the section without the specialist. Add a note: "systems-designer not consulted — Solo mode. Review manually before production."lean → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent.full → spawn as described below.Agent delegation (MANDATORY): Before proposing any formulas or balance values, spawn specialist agents via Agent in parallel:
systems-designer: provide Core Rules from Section C, tuning goals from user, balance context from dependency GDDs. Ask them to propose formulas with variable tables and output ranges.economy-designer: provide placement costs, upgrade cost intent, and progression goals. Ask them to validate cost curves and ratios.AskUserQuestionCross-reference: If a dependency GDD defines a formula whose output feeds into this system, reference it explicitly. Don't reinvent — connect.
Goal: Explicitly handle unusual situations so they don't become bugs.
Completion Steering — format each edge case as:
Example (adapt terminology to the game's domain):
Do NOT write vague entries like "handle appropriately" — each must name the exact condition and the exact resolution. An edge case without a resolution is an open design question, not a specification.
Questions to ask:
Review mode check (apply before spawning):
solo → skip this agent spawn. Draft the section without the specialist. Add a note: "systems-designer not consulted — Solo mode. Review manually before production."lean → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent.full → spawn as described below.Agent delegation (MANDATORY): Spawn systems-designer via Agent before finalising edge cases. Provide: the completed Sections C and D, and ask them to identify edge cases from the formula and rule space that the main session may have missed. For narrative systems, also spawn narrative-director. Present their findings and ask the user which to include.
Cross-reference: Check edge cases against dependency GDDs. If a dependency defines a floor, cap, or resolution rule that this system could violate, flag it.
Goal: Map every system connection with direction and nature.
This section is partially pre-filled from the context gathering phase. Present the known dependencies from the systems index and ask:
Cross-reference: This section must be bidirectionally consistent. If this system lists "depends on Combat", then the Combat GDD should list "depended on by [this system]". Flag any one-directional dependencies for correction.
Goal: Every designer-adjustable value, with safe ranges and extreme behaviors.
Questions to ask:
Review mode check (apply before spawning):
solo → skip this agent spawn. Derive the knobs from Section D's variable table yourself. Add a note: "systems-designer not consulted — Solo mode. Review manually before production."lean → skip unless Section D defines a formula whose knobs interact (changing one makes another inert).full → delegate as described below.Agent delegation: If formulas are complex, delegate to systems-designer
to derive tuning knobs from the formula variables.
The guard above was missing here while Sections B, C, D, E and H all carried one — and this delegation names
systems-designer, the same agent Section D's guard has already told asolorun to skip. Read without it,soloskips the specialist for the formulas and then consults it for the knobs derived from those same formulas.
Cross-reference: If a dependency GDD lists tuning knobs that affect this system, reference them here. Don't create duplicate knobs — point to the source of truth.
Goal: Testable conditions that prove the system works as designed.
Completion Steering — format each criterion as Given-When-Then:
Example (adapt terminology to the game's domain):
Include at least: one criterion per core rule from Section C, and one per formula from Section D. Do NOT write "the system works as designed" — every criterion must be independently verifiable by a QA tester without reading the GDD.
When Section D was not authored (Formulas optional at this tier because the system defines no numeric rule), there are no formulas to cover and the criteria come from Section C alone — say so in one line rather than silently writing fewer criteria. If Section D was skipped but Section C states a quantity — a rate, threshold, cost or curve — that is the §1 test being met after the fact: stop, tell the user Formulas is required for this system, and author it before finalising the criteria. A criterion cannot verify a number the GDD never defines.
That escalation applies at
standardonly. It re-runs §1's conditional Formulas test, and §1 disables that conditional atminimaloutright — "the conditional Formulas rule does NOT re-apply at minimal". Atminimala Section C quantity is expected and does not pull Formulas back in: state the value inline in Core Rules so it stays implementable, and move on. Atfull, Section D is unconditionally required, so the case cannot arise. Read without this scope, the two rules contradict each other for anyminimalsystem that defines a rate — which is most of them.
Review mode check (apply before spawning):
solo → skip this agent spawn. Draft the section without the specialist. Add a note: "qa-lead not consulted — Solo mode. Review manually before production."lean → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent.full → spawn as described below.Agent delegation (MANDATORY): Spawn qa-lead via Agent before finalising acceptance criteria. Provide: the completed GDD sections C, D, E, and ask them to validate that the criteria are independently testable and cover all core rules and formulas. Surface any gaps or untestable criteria to the user.
Questions to ask:
Cross-reference: Include criteria that verify cross-system interactions work, not just this system in isolation.
These five are the template sections that are not among §1's eight. They are governed here, not by the tier: §1's per-tier lists decide the required set, and this block decides the rest independently. Adding a section here therefore never changes a tier's section count.
Visual/Audio and Game Feel are REQUIRED for some categories — not optional. Determine the requirement level before asking:
Keyed on the Category column of systems-index.md — the nine values
templates/systems-index.md defines. Every one of the nine appears below
exactly once, so nothing falls through:
Visual/Audio is REQUIRED (mandatory — do not offer to skip) for:
Gameplay — combat, AI, stealth, movement, interaction: everything the player
sees resolveUI — HUD, menus, inventory screens, dialogue UINarrative — dialogue, quests, cutscenes, lore deliveryAudio — by definition
Gameplayis the row this table was missing. It is the category/map-systemsassigns to combat, AI and movement — the largest bucket in most action games. If it appears in neither this list nor the "all other" list below, the skill has no defined behaviour for it and the author has to guess. All nine categories must be covered between the two lists.
For required systems: spawn art-director via Agent before drafting this section. Provide: system name, game concept, game pillars, art bible sections 1–4 if they exist. Ask them to specify: (1) VFX and visual feedback requirements for this system's events, (2) any animation or visual style constraints, (3) which art bible principles most directly apply to this system. Present their output; do NOT leave this section as [To be designed] for visual systems.
Review mode check (apply before spawning):
solo → skip this agent spawn. Draft the section without the specialist. Add a note: "art-director not consulted — Solo mode. Review manually before production."lean → skip unless this system's visual feedback is central to it (a Gameplay or UI system whose events the player reads to play). Otherwise draft without the agent.full → spawn as described above.Sections B, C, D, E and H each carry this block and this spawn did not, while being worded as mandatory ("do NOT leave this section as
[To be designed]"). Two agents insoloskipped it anyway, on the strength of the other five, and both flagged the guess.director-gates.md's "solo → no director gates anywhere" governs director gates, not specialist spawns, so it did not settle it — this block does.
Game Feel is REQUIRED (mandatory — do not offer to skip) for Gameplay and
UI — the categories whose systems the player directly operates, where
responsiveness, weight and snap are design targets rather than polish. It is
optional for the other seven. The template argues the point itself: feel "drives
animation budgets, input handling architecture, and hitbox timing. Retrofitting
feel targets after implementation is expensive."
Cross-References is REQUIRED whenever the Dependencies section names another
GDD. The rule is derived, not category-keyed: if this document references
another system's mechanic, value or rule anywhere, that reference belongs in the
table. Where Dependencies names nothing, write "None — this system references no
other GDD" rather than leaving the placeholder. /review-all-gdds Phase 2c
reads this table when it exists.
For the remaining five categories — Core, Progression, Economy,
Persistence, Meta — Visual/Audio is optional: offer the optional sections
after the required sections.
At
minimal, force nothing. §1 says a voluntaryminimalGDD is "exactly the 5 standard sections", which contradicts a category rule that makes Visual/Audio or Game Feel mandatory. §1 wins: atminimalboth drop to optional and the whole set goes through the widget below. The contradiction is real — an agent authoring aminimalinventory GDD hit it and had to choose.
Use AskUserQuestion:
"The required sections for this workflow tier are complete. Which of the remaining template sections do you want to define?"
autonomous needs a marked recommendation to pick —
the three options previously carried none, unlike the Section A/B widgets,
so an unattended run had nothing to choose by and defaulted to skipping.Do not state a section count here. The required set is tier-dependent
(§1: 8 at full, 5 + conditional Formulas at standard, 5 at a voluntary
minimal), so the previous hardcoded "8 required sections are complete" was
false on every run below full — it told a standard-tier user that 8
sections existed when 6 had been authored.
For Visual/Audio (non-required systems): Coordinate with art-director and audio-director if detail is needed. Often a brief note suffices at the GDD stage.
Asset Spec Flag: After the Visual/Audio section is written with real content, output this notice: "📌 Asset Spec — Visual/Audio requirements are defined. After the art bible is approved, run
/asset-spec system:[system-name]to produce per-asset visual descriptions, dimensions, and generation prompts from this section."
For UI Requirements: Coordinate with ux-designer for complex UI systems.
After writing this section, check whether it contains real content (not just
[To be designed] or a note that this system has no UI). If it does have real
UI requirements, output this flag immediately:
📌 UX Flag — [System Name]: This system has UI requirements. In Phase 4 (Pre-Production), run
/ux-designto create a UX spec for each screen or HUD element this system contributes to before writing epics. Stories that reference UI should citedesign/ux/[screen].md, not the GDD directly.Note this in the systems index for this system if you update it.
For Open Questions: Capture anything that came up during design that wasn't fully resolved. Each question should have an owner and target resolution date.
After all sections are written:
Write ## Summary and its > **Quick reference** line now — after the design
exists, so the summary distils real content rather than intentions. This runs
at every tier, including standard and a voluntary minimal GDD: the
Summary is what lets a later skill scan 20 GDDs and decide which to read in full
(/create-epics, /architecture-review, /review-all-gdds all grep it), so a
GDD without it silently forces those consumers back to full reads.
Layer and Priority from the systems index
(design/gdd/systems-index.md); Key deps from the Dependencies section just
written (system names, or None).Replace the [To be designed] Summary placeholder in the skeleton. Then apply
the section cycle's Write step as for any other section.
Read back the complete GDD from file (not from conversation memory — the file is the source of truth). Verify:
## Summary and its Quick reference are populated (not the placeholder)full, 5 + conditional Formulas at standard,
5 at a voluntary minimal. Do not verify against a fixed count of 8: below
full that reports a correctly-authored GDD as incomplete, which is the same
error already corrected in the optional-sections prompt aboveReview mode check — apply before spawning CD-GDD-ALIGN:
solo → skip. Note: "CD-GDD-ALIGN skipped — Solo mode." Proceed to Step 5b.lean → skip (not a PHASE-GATE). Note: "CD-GDD-ALIGN skipped — Lean mode." Proceed to Step 5b.full → spawn as normal.Before finalizing the GDD, spawn creative-director via Agent using gate CD-GDD-ALIGN (.claude/docs/director-gates/cd-gdd-align.md).
Pass: completed GDD file path, game pillars (from design/gdd/game-concept.md or design/gdd/game-pillars.md), MDA aesthetics target.
Handle verdict per the standard rules in director-gates.md. After resolution, record the verdict in the GDD Status header:
> **Creative Director Review (CD-GDD-ALIGN)**: APPROVED [date] / CONCERNS (accepted) [date] / REVISED [date]
Scan the completed GDD for cross-system facts that should be registered:
First check the registry exists — §2a reads it "if it exists", and this
step never carried the same guard. At standard and below the file is often
absent, and a grep against a missing path returns nothing, which is
indistinguishable from "no candidate is registered yet":
design/registry/entities.yaml does not exist. May I create it with these
[N] entries?" If the user declines, skip 5b and say the registry was not
written — do not treat the skip as a clean pass.[], or the only matches are inside
comment blocks. Treat it as present, register the candidates, but say which
state you found: "registry exists and is empty — all [N] entries are new."
The shipped template's comments carry fully-formed examples referencing
design/gdd/inventory.md with real-looking values (base_inventory_slots: 20,
gold_carry_limit: 9999), so §2a's prescribed
grep referenced_by.*[system-name] returns comment lines on an empty
registry — and §2d would then present those invented numbers to the user as
"These values are locked." Match entries under a live entities:/items:/
formulas:/constants: key, never a commented example.Grep pattern=" - name: [candidate_name]" path="design/registry/entities.yaml"
Present a summary:
Registry candidates from this GDD:
NEW (not yet registered):
- [entity_name] [entity]: [attribute]=[value], [attribute]=[value]
- [item_name] [item]: [attribute]=[value], [attribute]=[value]
- [formula_name] [formula]: variables=[list], output=[min–max]
ALREADY REGISTERED (referenced_by will be updated):
- [constant_name] [constant]: value=[N] ← matches registry ✅
Ask: "May I update design/registry/entities.yaml with these [N] new entries
and update referenced_by for the existing entries?" (If the file was absent
and the user approved creating it, the wording is create, not update, and
there are no referenced_by arrays to merge.)
If yes: append new entries and update referenced_by arrays. Never modify
existing value / attribute fields without surfacing it as a conflict first.
Present a completion summary:
GDD Complete: [System Name]
- Sections written: [list]
- Provisional assumptions: [list any assumptions about undesigned dependencies]
- Cross-system conflicts found: [list or "none"]
To validate this GDD, open a fresh Claude Code session and run:
/design-review design/gdd/[system-name].mdNever run
/design-reviewin the same session as/design-system. The reviewing agent must be independent of the authoring context. Running it here would inherit the full design history, making independent critique impossible.
NEVER offer to run /design-review inline. Always direct the user to a fresh window.
After the GDD is complete (and optionally reviewed):
First check the systems index exists. §2a skips it at minimal because it is
never written at that tier, and this step never carried the same guard — the same
class of bug §5b was patched for. It bites hardest on a minimal project with a
system_overrides bump, where the effective tier is standard or full and
nothing else in §5 hints the file may be absent.
Absent — say so in one line ("no design/gdd/systems-index.md at this
workflow tier; nothing to update") and skip to §5e. Do not offer to create
one: /map-systems owns that file, and a stub written here would be a systems
index listing exactly one system.
Present — continue:
Read the systems index
Update the target system's row:
design/gdd/[system-name].mdUpdate the Progress Tracker counts
Ask: "May I update the systems index at design/gdd/systems-index.md?"
Update production/session-state/active.md with:
/8, and the same reasoning applies to
recording it. Below full a correctly-authored GDD has fewer than 8 sections,
and writing "All 8 written" into session state makes the next reader believe
a complete GDD is incompleteUse AskUserQuestion:
/consistency-check — verify this GDD's values don't conflict with existing GDDs (recommended before designing the next system)"/gate-check" — if enough MVP systems are designedThis 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) |
When delegating via the Agent tool:
AskUserQuestionIf the session is interrupted (compaction, crash, new session):
production/session-state/active.md — it records the current system and
which sections are completedesign/gdd/[system-name].md — sections with real content are done;
sections with [To be designed] still need workThis is why incremental writing matters: every approved section survives any disruption.
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:
/design-review inline, because the reviewing agent must not inherit this
session's design history. Phase 5c presents the hand-off; it never asks.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).
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.
/design-review design/gdd/[system-name].md in a fresh session to validate the completed GDD independently/consistency-check to verify this GDD's values don't conflict with other GDDs/map-systems next to move to the next highest-priority undesigned system/gate-check pre-production when all MVP GDDs are authored and reviewed/map-systemsRead literally without this rule, an overridden system resolves to full, falls
through to the fail-fast reads below, and aborts with "No game concept found.
Run /brainstorm first" — killing the escape hatch on step one of the very
configuration it was built for.
Confirm the write.
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:
"Registry conflict: [name] is registered in [source GDD] as [registry_value]. This section just wrote [new_value]. Which is correct?"
| 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) |