Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/authoring/design-system.md

Skill Test Spec: /design-system

Skill Summary

/design-system <system-name> authors a Game Design Document for one system at design/gdd/[system-name].md. Which sections are required depends on the resolved workflow tier (a system_overrides row wins for that system): all 8 at full (Overview, Player Fantasy, Detailed Design, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria); 5 plus conditional Formulas at standard; 5 at a voluntary minimal. ## Summary is authored at every tier, after the other sections.

The skill reads context first (game concept, systems index, entity registry, dependency GDD sections, engine reference), presents a context summary and a Technical Feasibility Brief, then asks "May I create the skeleton file at design/gdd/[system-name].md?". Each section then runs the cycle Context → Questions → Options → Decision → Draft → Approval → Write: in collaborative mode the draft and the "Approve the [Section Name] section?" widget appear in the same response, and the approved section is written immediately with Edit. Specialist agents are consulted per section, subject to per-section review-mode checks.

After all sections are written, the CD-GDD-ALIGN gate runs once in full mode only. retrofit <path> fills only the missing or placeholder sections of an existing GDD. The skill never offers /design-review inline — it directs the user to a fresh session.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: APPROVED, CONCERNS, BLOCKED
• Contains "May I write" / "May I create" collaborative protocol language (skeleton and per-section approval)
• Has a next-step handoff at the end
• Documents skeleton-first approach (file created with headers before content, after approval)
• Documents CD-GDD-ALIGN gate: runs in full mode only; skipped in lean and solo with a named note
• Documents retrofit mode for existing GDD files

---

Director Gate Checks

Review mode comes from the resolved review_mode (modes.review_mode in project.yaml); --review full|lean|solo overrides it for one run.

CD-GDD-ALIGN (creative-director) runs once, in Step 5a-bis, after every section and the Summary are written and the self-check has read the GDD back from file. It is passed the GDD path, the game pillars, the MDA aesthetics target and the GDD's Player Fantasy section (or a statement that the tier did not author one). The verdict is recorded in the GDD Status header as > **Creative Director Review (CD-GDD-ALIGN)**: APPROVED [date] / CONCERNS (accepted) [date] / REVISED [date] / NOT ASSESSED [date] — [missing input].

• full → spawned.
• lean → skipped (not a PHASE-GATE). Note: "CD-GDD-ALIGN skipped — Lean mode."
• solo → skipped. Note: "CD-GDD-ALIGN skipped — Solo mode."

Per-section specialist spawns (not director gates) have their own checks: solo skips them all; lean skips them except for Sections D (Formulas) and H (Acceptance Criteria), Section G (Tuning Knobs) when Section D defines a formula whose knobs interact, and Visual/Audio when the system's visual feedback is central to it (a Gameplay or UI system whose events the player reads to play); full spawns them. Every skipped spawn prints the section's note naming the agent and the mode, e.g. "creative-director not consulted — Lean mode. Review manually before production."

---

Test Cases

Case 1: Happy Path — New combat GDD, full mode, full workflow

Fixture:

• design/gdd/game-concept.md and design/gdd/systems-index.md exist; combat is listed with Category: Gameplay
• No design/gdd/combat.md
• project.yaml has engine.name: Godot, modes.review_mode: full, modes.workflow: full, modes.automation: collaborative; docs/engine-reference/godot/ has VERSION.md and modules/physics.md (combat maps to the Physics domain)
• CD-GDD-ALIGN returns APPROVE

Input: /design-system combat

Expected behavior:

1. Phase 2 reads the concept, systems index, entity registry (if present) and dependency GDD sections before asking anything, then presents the "Designing: Combat" context summary and the Technical Feasibility Brief with its AskUserQuestion
2. "Ready to start designing combat?" is asked
3. "May I create the skeleton file at design/gdd/combat.md?" — on yes, the skeleton is written with all 8 required sections plus the template's other sections, each holding [To be designed]; production/session-state/active.md is updated
4. Sections A–H are walked in order; each draft is followed in the same response by "Approve the [Section Name] section?" with [A] Approve — write it to file / [B] Make changes — describe what to fix / [C] Start over
5. Section B consults creative-director; Section C spawns the Combat row's game-designer plus supporting agents in parallel; Section D spawns systems-designer; Section E systems-designer; Section H qa-lead
6. Each approved section is written immediately by an Edit whose old_string includes the section heading; active.md is updated after each
7. Visual/Audio and Game Feel are treated as required (Gameplay category) — not offered as skippable
8. ## Summary is authored after the other sections; Step 5a reads the GDD back from file
9. CD-GDD-ALIGN spawns once and returns APPROVE; the Status header records APPROVED [date]
10. The completion summary directs the user to run /design-review design/gdd/combat.md in a fresh session

Assertions:

• The skeleton is written only after the "May I create the skeleton file" approval, and contains all 8 required section headers
• Every section draft is followed in the same response by the "Approve the [Section Name] section?" widget
• Each section is written individually, immediately after its approval, by an Edit anchored on its heading
• Section C's specialists come from the routing table's Combat row and are spawned in parallel before drafting
• CD-GDD-ALIGN spawns once, after all sections and the Summary are written — not per section
• The verdict is recorded as > **Creative Director Review (CD-GDD-ALIGN)**: APPROVED [date]
• /design-review is directed to a fresh session and never offered inline

---

Case 2: Retrofit Mode — Fill only the incomplete sections at standard tier

Fixture:

• project.yaml has engine.name: Godot, modes.workflow: standard, modes.review_mode: lean
• design/gdd/game-concept.md and design/gdd/systems-index.md exist; inventory is listed with Category: Economy (engine domain Scripting)
• docs/engine-reference/godot/ has VERSION.md and modules/, but no modules/scripting.md
• design/gdd/inventory.md exists with Overview, Detailed Design and Formulas fully written; its ## Summary holds only [To be designed]
• ## Edge Cases and ## Acceptance Criteria contain only [To be designed]; ## Dependencies has an empty body
• The file has no Player Fantasy or Tuning Knobs section

Input: /design-system retrofit design/gdd/inventory.md

Expected behavior:

1. The skill reads the existing GDD and identifies which sections are present, placeholder-only or empty
2. It presents the "Retrofit: Inventory" block: written sections (will not be touched) and missing or incomplete sections (will be authored)
3. Player Fantasy and Tuning Knobs are listed as available to add, not as gaps, because standard does not require them
4. It asks: "Shall I fill the 3 missing sections? I will not modify any existing content."
5. On yes, Phase 2 runs as normal; §2e names the missing module — "no engine reference for Scripting under docs/engine-reference/godot/modules/; feasibility not checked against the pinned engine" — and carries it into §5-pre
6. No skeleton is created; only Edge Cases, Dependencies and Acceptance Criteria run the section cycle, then §5-pre replaces the Summary placeholder
7. Each write replaces only the placeholder or empty body; Overview, Detailed Design and Formulas are not modified

Assertions:

• The retrofit block is shown before any change is made
• Sections the tier does not require are not reported as gaps
• The skill asks "Shall I fill the 3 missing sections? I will not modify any existing content."
• The absent scripting.md module is named in the output, not skipped silently as if feasibility had been checked
• No skeleton is created and complete sections are not re-authored or overwritten
• Each filled section still goes through the per-section approval before its write

---

Case 3: Director Gate — CD-GDD-ALIGN returns CONCERNS, REJECT or NOT ASSESSED

Fixture:

• design/gdd/game-concept.md (pillars include "Fearless Exploration") and design/gdd/systems-index.md exist; stamina is listed with Category: Gameplay
• project.yaml has modes.review_mode: full and modes.workflow: full
• All eight sections, Player Fantasy included, and the Summary are written for design/gdd/stamina.md
• Scenario (a): CD-GDD-ALIGN returns CONCERNS: "Detailed Design's stamina drain undercuts the 'Fearless Exploration' pillar"
• Scenario (b): CD-GDD-ALIGN returns REJECT: "stamina exhaustion strands the player mid-exploration, which the 'Fearless Exploration' pillar rules out"
• Scenario (c): CD-GDD-ALIGN returns NOT ASSESSED — no MDA aesthetics target was available to check the GDD against

Input: /design-system stamina (reaching Step 5a-bis)

Expected behavior:

1. creative-director is spawned with gate CD-GDD-ALIGN and passed the GDD path, the game pillars, the MDA aesthetics target and the GDD's Player Fantasy section
2. (a) The CONCERNS are surfaced via AskUserQuestion with the standard options: Revise flagged items / Accept and proceed / Discuss further
3. (a) If "Revise flagged items": Detailed Design runs its section cycle again — its specialists consulted first — and is approved through "Approve the Detailed Design section?" before it is written; the Status header records REVISED [date]
4. (a) If "Accept and proceed": the Status header records CONCERNS (accepted) [date]
5. (b) The blockers are shown; the flagged section is re-drafted and re-approved the same way before anything else is written, and the Status header records REVISED [date], never APPROVED
6. (c) The missing input is named; the user can supply it and re-run the gate, or the Status header records NOT ASSESSED [date] — [missing input], never APPROVED
7. Only after the verdict is recorded does the skill continue to the entity registry step (5b)

Assertions:

• CD-GDD-ALIGN receives the completed GDD path, the pillars, the MDA target and the Player Fantasy section
• (a) CONCERNS are shown to the user with the three standard options, not auto-accepted
• A revised section re-runs its section cycle and is re-approved before it is written
• The Status header records REVISED [date] or CONCERNS (accepted) [date] to match the user's choice
• (b) After a REJECT, no later step (5b registry, 5d systems index) runs until the flagged section has been revised
• (c) NOT ASSESSED is never recorded or reported as an approval

---

Case 4: Lean and Solo Modes — Gate skipped once; specialist spawns follow their own checks

Fixture:

• design/gdd/game-concept.md and design/gdd/systems-index.md exist; the system is stamina (Category: Gameplay); no design/gdd/stamina.md
• project.yaml has engine.name: Godot and modes.workflow: full
• Section D's stamina formula has no knobs that interact; the stamina bar is feedback the player reads to play
• Scenario (a): modes.review_mode: lean
• Scenario (b): modes.review_mode: solo

Input: /design-system stamina

Expected behavior:

1. (a) Sections B, C, E and G are drafted without specialist spawns, and each prints its note with the mode, e.g. "creative-director not consulted — Lean mode. Review manually before production."
2. (a) Section D still spawns systems-designer, Section H qa-lead, and Visual/Audio art-director — stamina's feedback is central to play
3. (a) At Step 5a-bis: "CD-GDD-ALIGN skipped — Lean mode." — printed once, not per section
4. (b) No specialist or director agent is spawned; each section whose spawn was skipped carries its note, e.g. "creative-director not consulted — Solo mode. Review manually before production."
5. (b) At Step 5a-bis: "CD-GDD-ALIGN skipped — Solo mode."
6. In both scenarios every section still requires the "Approve the [Section Name] section?" approval before it is written

Assertions:

• (a) In lean mode Sections B, C, E and G are drafted without their specialists, while Sections D and H and Visual/Audio still spawn theirs
• (a) Each lean-skipped spawn prints a "not consulted — Lean mode" note naming its agent — none is skipped silently
• (a) The CD-GDD-ALIGN skip note appears once, at Step 5a-bis
• (b) In solo mode no agent is spawned, and each skipped specialist leaves a "not consulted — Solo mode" note
• (b) The skip note reads "CD-GDD-ALIGN skipped — Solo mode."
• Per-section user approval is required in both modes

---

Case 5: Missing Input and Declined Skeleton

Fixture:

• project.yaml has modes.workflow: standard in every scenario — the systems index is required at this tier, so pointing at /map-systems is correct
• Scenario (a): no argument; design/gdd/systems-index.md lists stamina as the highest-priority "Not Started" system (MVP, Core layer)
• Scenario (b): no argument; no systems index
• Scenario (c): /design-system stamina with concept and index present; the user declines the skeleton

Input: (a) /design-system (b) /design-system (c) /design-system stamina

Expected behavior:

1. (a) AskUserQuestion: "The next system in your design order is stamina (MVP | Core). Start designing it?" with [A] Yes — design stamina / [B] Pick a different system / [C] Stop here
2. (b) The skill stops with the usage message ("Usage: /design-system <system-name> …"), the retrofit example, and "No systems index found. Run /map-systems first to map your systems and get the design order."
3. (c) The skill stops with: "Verdict: BLOCKED — skeleton creation declined. …" and does not proceed to Section A
4. In none of the three scenarios is a GDD file written before an approval

Assertions:

• (a) The next system is proposed from the systems index with the three options
• (b) The usage message and the /map-systems pointer are printed; nothing is written
• (c) Declining the skeleton produces the BLOCKED verdict and stops before Section A
• No GDD file is created without an approval

---

Case 6: Minimal Project, One System Raised by system_overrides

Fixture:

• project.yaml has modes.workflow: minimal, modes.review_mode: solo and workflow_overrides.system_overrides.combat: standard
• design/game-brief.md exists; its MVP features describe combat (a damage rule and a stagger threshold), and its build order lists combat first
• No design/gdd/game-concept.md, no design/gdd/systems-index.md, no design/gdd/combat.md

Input: /design-system combat

Expected behavior:

1. The effective tier for combat is standard (the override); the project tier is minimal
2. §2a takes the minimal branch because it keys on the project tier: it reads design/game-brief.md and skips the systems-index read, and does not stop with "No game concept found" or "No systems index found"
3. It derives Category, Layer and Priority from the brief once (e.g. Gameplay, Foundation or Feature, MVP)
4. The skeleton and the section walk follow standard: A, C, D (combat defines numeric rules), E, F, H — no Player Fantasy or Tuning Knobs
5. §5-pre's Quick reference marks the derived values, e.g. "Category: Gameplay (inferred from the brief — no systems index at this tier)"
6. §5d says "no design/gdd/systems-index.md at this workflow tier; nothing to update" and writes no systems index

Assertions:

• The run reads the brief and does not stop for the missing concept or systems index
• The required section set is standard's (the effective tier) — not the project tier's
• Category, Layer and Priority are derived from the brief and marked inferred in the Quick reference
• No systems index is created; §5d reports nothing to update

---

Protocol Compliance

• Reads context before asking anything; stops with the /brainstorm or /map-systems message when the game concept or systems index is missing on a standard/full project (a minimal project reads the brief instead, even for a system system_overrides raises)
• The skeleton is created only after "May I create the skeleton file at design/gdd/[system-name].md?"
• In collaborative mode every section draft is followed by its approval widget, and no section is written without approval
• Sections are written incrementally, and production/session-state/active.md is updated after each
• Specialist spawns follow the per-section review-mode checks; every skipped spawn leaves a "not consulted" note naming the agent and the mode, in lean as in solo
• CD-GDD-ALIGN runs once in full mode after all sections; lean and solo print a skip note naming the gate and mode
• /design-review is directed to a fresh session and never run or offered inline
• Ends with a next-step AskUserQuestion and Recommended Next Steps (/consistency-check, /map-systems next, /design-review in a fresh session)

---

Coverage Notes

• guided and autonomous automation modes (write without the per-section widget; log_decision in autonomous) are not fixture-tested.
• A voluntary GDD on a minimal project with no override (the 5 standard sections from design/game-brief.md, Formulas never pulled back in) is not fixture-tested; Case 6 covers a minimal project whose system an override raises. The no-argument prompt on a minimal project, where no systems index exists by design, is not tested either.
• The registry conflict check after Sections C and D, and the Step 5b entity registry update, are not individually tested.
• The Step 5d systems index update and the context-window (≥70%) notice are not tested.
• Recovery and resume after an interrupted session is not tested.