ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-10-16 10:17:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Release 1.1.2 — the default path works end to end

Browse Source 
Fix release for 1.1.1: the minimal path end to end, engine commands that
run on Godot, Unity and Unreal, hook warnings you can see, and verdicts
that say when they could not check. Details in CHANGELOG.md; upgrade
steps in UPGRADING.md (v1.1.1 → v1.1.2).

Fixes #67
Fixes #131

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
This commit is contained in:
Donchitos
2026-09-29 21:32:19 +10:00
co-authored by Claude Opus 5.5
parent 7ed2c3e9c4
commit b21fa0f7f2
383 changed files with 22888 additions and 10618 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CCGS Skill Testing Framework/skills/authoring/architecture-decision.md
+174 -112
View File
@@ -2,196 +2,258 @@
## Skill Summary
`/architecture-decision` guides the user through section-by-section authoring of
a new Architecture Decision Record (ADR). Required sections are: Status, Context,
Decision, Consequences, Alternatives, and Related ADRs. The skill also stamps the
engine version reference from `docs/engine-reference/` into the ADR for traceability.
`/architecture-decision` authors one Architecture Decision Record (ADR). It has
three entry modes: normal authoring (`/architecture-decision [title]`),
`retrofit <path>` (adds missing sections to an existing ADR without touching the
rest), and `accept <ADR-id>` (the only path that moves an ADR from `Proposed` to
`Accepted`). When retrofit asks for a missing Status and the user answers
`Accepted`, it writes `Proposed` and hands the ADR to acceptance mode.
In `full` review mode, TD-ADR (technical-director) and LP-FEASIBILITY
(lead-programmer) gate agents spawn after the draft is complete. If both gates
return APPROVED, the ADR status is set to Accepted. In `lean` or `solo` mode,
both gates are skipped and the ADR is written with Status: Proposed. The skill
asks "May I write" per section during authoring. ADRs are written to
`docs/architecture/adr-NNN-[name].md`.
Normal authoring loads engine context first (`docs/engine-reference/[engine]/VERSION.md`,
plus a knowledge-gap warning for MEDIUM/HIGH-risk domains), picks the next ADR
number, checks `docs/registry/architecture.yaml` for binding stances, then
presents its assumptions as a confirm/adjust `AskUserQuestion` (Status is always
`Proposed` and is never asked). It then drafts the whole ADR from its template in
one pass, has the primary engine specialist validate it (Step 5.5), runs the
TD-ADR gate in `full` review mode only (Step 5.6), runs a GDD sync check that
always reports, and asks once — "May I write it?" — before writing
`docs/architecture/adr-[NNNN]-[slug].md`. A separate approval covers the registry
update. The closing output tells the user to run `/architecture-review` in a
fresh session and `/architecture-decision accept ADR-NNNN` when the decision is
settled. Authoring never sets `Accepted` and never unblocks stories.
---
## Static Assertions (Structural)
Verified automatically by `/skill-test static` — no fixture needed.
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: ACCEPTED, PROPOSED, CONCERNS
- [ ] Contains "May I write" collaborative protocol language (per-section approval)
- [ ] Has a next-step handoff at the end
- [ ] Documents gate behavior: TD-ADR + LP-FEASIBILITY in full mode; skipped in lean/solo
- [ ] Documents that ADR status is Accepted (full, gates approve) or Proposed (otherwise)
- [ ] Mentions engine version stamp from `docs/engine-reference/`
- [ ] Contains status/verdict keywords: `Proposed`, `Accepted`, and the TD-ADR outcomes `CONCERNS` / `REJECT`
- [ ] Contains "May I write" collaborative protocol language (whole-ADR write approval and registry approval)
- [ ] Has a next-step handoff at the end (`/architecture-review`, `accept ADR-NNNN`)
- [ ] Documents gate behavior: engine specialist validation, then TD-ADR in full mode; TD-ADR skipped in lean/solo with a named note
- [ ] Documents that authoring always produces `Proposed` and only acceptance mode sets `Accepted` — retrofit's `Accepted` answer is routed through it
- [ ] Mentions the engine version stamp from `docs/engine-reference/` (Engine Compatibility table)
---
## Director Gate Checks
In `full` mode: TD-ADR (technical-director) and LP-FEASIBILITY (lead-programmer)
spawn after the ADR draft is complete. If both return APPROVED, ADR Status is set
to Accepted. If either returns CONCERNS or FAIL, ADR stays Proposed.
Review mode comes from the resolved `review_mode` (`modes.review_mode` in
`project.yaml`); `--review full|lean|solo` overrides it for one run.
In `lean` mode: both gates are skipped. ADR is written with Status: Proposed.
Output notes: "TD-ADR skipped — lean mode" and "LP-FEASIBILITY skipped — lean mode".
In `full` mode: after the draft is generated, the primary engine specialist
validates it (Step 5.5), then `technical-director` spawns with gate TD-ADR
(Step 5.6). The two run in that order, not in parallel. On CONCERNS the
concerns are shown verbatim and the user picks `Revise flagged items` /
`Accept and proceed` / `Discuss further`; on REJECT the draft is revised before
the write approval. No verdict changes the ADR's Status.
In `solo` mode: both gates are skipped. ADR is written with Status: Proposed.
In `lean` mode: TD-ADR is skipped (it is not a PHASE-GATE). Output notes
"TD-ADR skipped — Lean mode." The engine specialist validation still runs.
In `solo` mode: TD-ADR is skipped. Output notes "TD-ADR skipped — Solo mode."
The engine specialist validation still runs.
In every mode the written ADR has `Status: Proposed`.
---
## Test Cases
### Case 1: Happy Path — New ADR for rendering approach, full mode, gates approve
### Case 1: Happy Path — New rendering ADR, full mode, TD-ADR approves
**Fixture:**
- `docs/architecture/` exists with no existing ADR for rendering
- `docs/engine-reference/[engine]/VERSION.md` exists
- `production/session-state/review-mode.txt` contains `full`
- `project.yaml` has `engine.name: Godot` and `modes.review_mode: full`
- `docs/engine-reference/godot/VERSION.md` exists and marks the pinned version HIGH risk; `breaking-changes.md` lists a Rendering change
- `docs/architecture/` contains `adr-0001-*.md` and `adr-0002-*.md`; none covers rendering
- `docs/registry/architecture.yaml` exists with no stance touching rendering
- `design/gdd/visual-effects.md` exists; the user confirms it as the GDD driving the decision, and its names match the ADR's Key Interfaces
- The engine specialist finds only minor notes; TD-ADR returns APPROVE
**Input:** `/architecture-decision rendering-approach`
**Expected behavior:**
1. Skill guides user through each required section (Status, Context, Decision, Consequences, Alternatives, Related ADRs)
2. Engine version is stamped into the ADR from `docs/engine-reference/`
3. For each section: draft shown, "May I write this section?" asked, approved
4. After all sections: TD-ADR and LP-FEASIBILITY gates spawn in parallel
5. Both gates return APPROVED
6. ADR Status is set to Accepted
7. Skill writes `docs/architecture/adr-NNN-rendering-approach.md`
8. `docs/architecture/tr-registry.yaml` updated if new TR-IDs are defined
1. Step 1 reads `VERSION.md` first and displays the ENGINE KNOWLEDGE GAP WARNING for the Rendering domain
2. Step 2 scans `docs/architecture/` and assigns ADR-0003
3. Step 3a reads the registry before any existing ADR
4. Step 4 presents assumptions (problem, 2–3 alternatives, GDD linkage, dependencies, `Status: Proposed`) as a confirm/adjust `AskUserQuestion`; no ADR is generated until the user confirms
5. Step 5 drafts the full template, including the Engine Compatibility table (engine, domain, knowledge risk, references consulted)
6. `godot-specialist` validates the draft; minor notes go into the Risks section
7. `technical-director` then spawns with gate TD-ADR and returns APPROVE
8. GDD sync check prints `GDD sync: checked 1 referenced GDD(s), no naming inconsistencies.` — never silent
9. "ADR draft is complete. May I write it?" — on yes, writes `docs/architecture/adr-0003-rendering-approach.md` with `Status: Proposed`
10. Registry candidates are shown and "May I update `docs/registry/architecture.yaml` with these [N] new stances?" is asked separately
11. Closing output includes the fixed notice to run `/architecture-review` in a fresh session, and "Run `/architecture-decision accept ADR-0003` when the decision is settled"
**Assertions:**
- [ ] All 6 required sections are authored and written
- [ ] Engine version reference is stamped in the ADR
- [ ] TD-ADR and LP-FEASIBILITY spawn in parallel (not sequentially)
- [ ] ADR Status is Accepted when both gates return APPROVED in full mode
- [ ] "May I write" is asked per section during authoring
- [ ] File is written to `docs/architecture/adr-NNN-[name].md`
- [ ] `VERSION.md` is read before any other step, and the knowledge-gap warning is shown for the HIGH-risk domain
- [ ] Assumptions are confirmed via `AskUserQuestion` before the ADR is generated; Status is shown as `Proposed`, never asked
- [ ] The engine specialist validation runs before TD-ADR (sequential, not parallel)
- [ ] One "May I write" approval covers the whole ADR; the file is `docs/architecture/adr-0003-rendering-approach.md`
- [ ] The written ADR has `Status: Proposed` even though TD-ADR returned APPROVE
- [ ] The GDD sync check reports the clean result for `visual-effects.md` in one line
- [ ] The registry update has its own approval prompt, separate from the ADR write
- [ ] Closing output contains the fresh-session `/architecture-review` notice and the `accept ADR-0003` command
---
### Case 2: Failure Path — TD-ADR returns CONCERNS
**Fixture:**
- ADR draft is complete (all sections filled)
- `production/session-state/review-mode.txt` contains `full`
- TD-ADR gate returns CONCERNS: "The decision does not address [specific concern]"
- Same as Case 1, but TD-ADR returns CONCERNS: "Alternatives do not address the mobile renderer"
- One point stays unresolved after revision (which renderer to target on mobile)
**Input:** `/architecture-decision [topic]`
**Input:** `/architecture-decision rendering-approach`
**Expected behavior:**
1. TD-ADR gate spawns and returns CONCERNS with specific feedback
2. Skill surfaces the concerns to the user
3. ADR Status remains Proposed (not Accepted)
4. User is asked: revise the decision to address concerns, or accept as Proposed
5. ADR is written with Status: Proposed if concerns are not resolved
1. TD-ADR spawns with the draft, engine version, domain and related ADRs
2. The CONCERNS are shown to the user verbatim with the standard options from `director-gates.md`: `Revise flagged items` / `Accept and proceed` / `Discuss further`
3. The user picks `Revise flagged items`; only then are the Decision or Alternatives sections revised (Step 5.6)
4. The unresolved point is presented as its own `AskUserQuestion` with options from the review plus "Different approach — I'll describe it"
5. The write approval is still asked; nothing is written before it
6. The ADR is written with `Status: Proposed`
**Assertions:**
- [ ] TD-ADR concerns are shown to the user verbatim
- [ ] ADR Status is Proposed (not Accepted) when TD-ADR returns CONCERNS
- [ ] Skill does NOT set Status: Accepted while CONCERNS are unresolved
- [ ] User is given the option to revise and re-run the gate
- [ ] TD-ADR receives the ADR draft/path, engine version and domain as context
- [ ] The CONCERNS are shown verbatim and the user chooses Revise / Accept / Discuss — the draft is not revised before that choice
- [ ] Each unresolved decision is a separate `AskUserQuestion` with a free-text escape option
- [ ] The ADR is written only after the "May I write" approval, with `Status: Proposed`
---
### Case 3: Lean Mode — Both gates skipped; ADR written as Proposed
### Case 3: Lean and Solo Modes — TD-ADR skipped; checks that cannot run say so
**Fixture:**
- `production/session-state/review-mode.txt` contains `lean`
- ADR draft is authored for a new technical decision
- Scenario (a): `project.yaml` has `modes.review_mode: lean` and `engine.name: Godot`
- Scenario (b): same project, invoked with `--review solo`
- Scenario (c): invoked with `--review solo` on a project with no engine configured — `engine.name` unset and `.claude/docs/technical-preferences.md` still `[TO BE CONFIGURED]`; at Step 1's prompt the user carries on without running `/setup-engine`
- `design/gdd/` holds no GDD, so the ADR's GDD Requirements Addressed names none
**Input:** `/architecture-decision [topic]`
**Input:** (a) `/architecture-decision save-format` (b) and (c) `/architecture-decision save-format --review solo`
**Expected behavior:**
1. Skill guides user through all 6 sections
2. After draft is complete: both TD-ADR and LP-FEASIBILITY are skipped
3. Output notes: "TD-ADR skipped — lean mode" and "LP-FEASIBILITY skipped — lean mode"
4. ADR is written with Status: Proposed (not Accepted, since gates did not approve)
5. "May I write" is still asked before the final file write
1. (a) and (b): the engine specialist validation (Step 5.5) runs
2. (a) Output notes "TD-ADR skipped — Lean mode." and proceeds to the GDD sync check
3. (b) and (c): Output notes "TD-ADR skipped — Solo mode." and proceeds to the GDD sync check
4. (c) No engine specialist is spawned, and the output records `Engine validation: NOT ASSESSED — no engine configured (engine.name unset in project.yaml)`
5. The GDD sync check prints `GDD sync: NOT ASSESSED — [the ADR names no GDDs]`, not the clean one-line result
6. "May I write it?" is still asked before the file is written
7. The ADR is written with `Status: Proposed`
**Assertions:**
- [ ] Both gate skip notes appear in output
- [ ] ADR Status is Proposed (not Accepted) in lean mode
- [ ] "May I write" is still asked before writing the file
- [ ] Skill writes the ADR after user approval
- [ ] `technical-director` is not spawned in lean or solo mode
- [ ] The skip note names the gate and the mode ("TD-ADR skipped — Lean mode." / "— Solo mode.")
- [ ] The `--review solo` argument overrides the resolved `review_mode` for the run
- [ ] (a) and (b): the engine specialist validation still runs
- [ ] (c) With no engine configured, the output says engine validation was NOT ASSESSED instead of passing silently
- [ ] With no GDD named, the GDD sync check reports NOT ASSESSED, not a clean result
- [ ] "May I write" is asked before the file is written, and Status is `Proposed`
---
### Case 4: Edge Case — ADR already exists for this topic
### Case 4: Edge Case — Proposed decision contradicts a registered stance
**Fixture:**
- `docs/architecture/` contains an existing ADR covering the same topic
- The existing ADR has Status: Accepted
- `docs/registry/architecture.yaml` records an interface contract: `damage_delivery → signal pattern (ADR-0003)`
- ADR-0003 is Accepted
- The user states the proposal when invoking the skill, before Step 1: the decision is to deliver damage by direct method calls
**Input:** `/architecture-decision [same-topic]`
**Input:** `/architecture-decision damage-pipeline`, with that description in the same message
**Expected behavior:**
1. Skill detects an existing ADR covering the same topic
2. Skill asks: "An ADR for [topic] already exists ([filename]). Update it, or create a new superseding ADR?"
3. User selects update or supersede
4. Skill does NOT silently create a duplicate ADR
1. Step 3a reads the registry before opening any existing ADR, and presents the relevant stances as locked constraints under "Existing Architectural Stances (must not contradict)"
2. Still in Step 3a — right after the stances, before Step 4's assumptions prompt — the skill surfaces the conflict: "⚠️ Conflict: This ADR proposes [X], but ADR-0003 established that [Y]…"
3. It offers three options: (1) align with the existing stance, (2) supersede ADR-0003 with an explicit replacement, (3) explain why this case is an exception
4. It does not proceed to Step 4 until the conflict is resolved or accepted as an intentional exception
5. If the user chooses to supersede: at the registry step the old entry is set to `status: superseded_by: ADR-[NNNN]` and the new entry is added — the existing entry is not otherwise modified
**Assertions:**
- [ ] Skill detects the existing ADR before authoring begins
- [ ] User is offered update or supersede options — no silent duplicate
- [ ] If update: skill opens the existing ADR for section-by-section revision
- [ ] If supersede: new ADR references the superseded one in Related ADRs section
- [ ] The registry is read before any existing ADR file
- [ ] The conflict warning names ADR-0003 and offers exactly the three options above
- [ ] The confirm/adjust assumptions prompt (Step 4) does not appear until the conflict is resolved
- [ ] On supersede, the old registry entry is marked `superseded_by`, not edited or deleted
---
### Case 5: Director Gate — Status set correctly based on mode and gate outcome
### Case 5: Acceptance Mode — Status moves to Accepted only through `accept`
**Fixture:**
- ADR draft is complete
- Two scenarios: (a) full mode, both gates APPROVED; (b) full mode, one gate CONCERNS
- `docs/architecture/adr-0005-physics-layers.md` exists with `Status: Proposed`
- Scenario (a): its `## ADR Dependencies` lists `Depends On: ADR-0002`, and ADR-0002 is `Proposed`
- Scenario (b): its only dependency is ADR-0001, which is `Accepted`; three files under `production/epics/*/story-*.md` name `ADR-0005` and are Blocked — two in the header form `/create-stories` writes (`> **Status**: Blocked`), one as `**Status:** Blocked`
- `modes.automation` is `autonomous`
**Full mode, both APPROVED:**
- ADR Status is set to Accepted
**Input:** `/architecture-decision accept ADR-0005`
**Assertions (both approved):**
- [ ] ADR frontmatter/header shows `Status: Accepted`
- [ ] Both TD-ADR and LP-FEASIBILITY appear as APPROVED in output
**Expected behavior:**
1. The skill globs `docs/architecture/adr-0005-*.md` and reads the single match
2. (a) It refuses and names the blocker: ADR-0005 depends on ADR-0002, which is still Proposed; no file is edited
3. (b) It finds the stories to unblock before asking, then asks "Accept ADR-0005 — [title]? …" with the count ("3 stories become Ready"), options `[A] Yes — accept it` / `[B] Not yet — leave it Proposed`
4. (b) The prompt fires even though automation is `autonomous`
5. (b) On yes: edits `## Status` to `Accepted`, leaves an existing `## Date` unchanged (adding one only if absent), moves the three stories from `Blocked` to `Ready`, and reports the ADR and each story that moved
**Full mode, one gate returns CONCERNS:**
- ADR Status stays Proposed
**Assertions:**
- [ ] (a) Acceptance is refused when a dependency is not `Accepted`, naming ADR-0002; nothing is written
- [ ] (b) The confirmation prompt states how many stories will become Ready
- [ ] (b) The confirmation prompt appears in `autonomous` automation mode
- [ ] (b) Status becomes `Accepted` and the three stories move to `Ready` only after the user confirms
- [ ] Stories are matched only under `production/epics/`
- [ ] (b) All three stories are found — the Blocked grep matches `> **Status**: Blocked` and `**Status:** Blocked`, not only the literal `Status: Blocked`
**Assertions (CONCERNS):**
- [ ] ADR frontmatter/header shows `Status: Proposed`
- [ ] Concerns are listed in output
- [ ] Skill does NOT set Status: Accepted when any gate returns CONCERNS
---
**Lean/solo mode:**
- ADR Status is always Proposed regardless of content quality
### Case 6: Retrofit — Missing Status answered `Accepted`
**Assertions (lean/solo):**
- [ ] ADR Status is Proposed in lean mode
- [ ] ADR Status is Proposed in solo mode
- [ ] No gate output appears in lean or solo mode
**Fixture:**
- `docs/architecture/adr-0004-input-mapping.md` exists with Context, Decision, Consequences, Engine Compatibility and GDD Requirements Addressed, but no `## Status` and no `## ADR Dependencies`
- ADR-0001 is `Accepted`
- One file under `production/epics/*/story-*.md` names `ADR-0004` and has `> **Status**: Blocked`
**Input:** `/architecture-decision retrofit docs/architecture/adr-0004-input-mapping.md`
**Expected behavior:**
1. The retrofit block lists Status (BLOCKING), ADR Dependencies (HIGH) and Date (MEDIUM — the fixture has no `## Date` and no `## Last Verified`) as missing, then asks "Shall I add the 3 missing sections? I will not modify any existing content."
2. Asked for the current status, the user answers "Accepted" — the decision is already in force; asked for dependencies, the user answers "Depends On: ADR-0001"
3. The skill appends `## Status` as `Proposed`, the ADR Dependencies section and `## Date` (today, noted as the retrofit date); no existing section changes
4. It then runs acceptance mode on ADR-0004: the dependency check passes (ADR-0001 is Accepted), the blocked story is found, and "Accept ADR-0004 — [title]? …" is asked with "1 story becomes Ready"
5. On yes: `## Status` becomes `Accepted`, the `## Date` the retrofit added is kept, and the story moves from `Blocked` to `Ready`
**Assertions:**
- [ ] Only the missing sections are appended; existing sections are untouched
- [ ] The retrofit answer `Accepted` is never written straight into `## Status`; `Accepted` appears only after acceptance mode's dependency check and confirmation
- [ ] The confirmation prompt names the story count, as in Case 5
- [ ] Variant — the user declines "Shall I add the 3 missing sections?": no section is written, `## Date` included
---
## Protocol Compliance
- [ ] All 6 required sections authored before gate review
- [ ] Engine version stamped in ADR from `docs/engine-reference/`
- [ ] "May I write" asked per section during authoring
- [ ] TD-ADR and LP-FEASIBILITY spawn in parallel in full mode
- [ ] Skipped gates noted by name and mode in lean/solo output
- [ ] ADR Status: Accepted only when full mode AND both gates APPROVED
- [ ] Ends with next-step handoff: `/architecture-review` or `/create-control-manifest`
- [ ] Engine context (`VERSION.md`) is loaded first and stamped into the Engine Compatibility table
- [ ] Assumptions are confirmed via `AskUserQuestion` before the ADR is generated
- [ ] "May I write" is asked once for the whole ADR before writing; the registry update has its own approval
- [ ] TD-ADR runs only in full mode; lean/solo print a skip note naming the gate and mode
- [ ] TD-ADR CONCERNS are shown verbatim with `Revise flagged items` / `Accept and proceed` / `Discuss further`, never revised without the user's choice
- [ ] A TD-ADR `NOT ASSESSED` answer names the missing input and is never presented as an approval
- [ ] Authoring always writes `Status: Proposed`; `Accepted` is set only by acceptance mode after its dependency check and explicit user confirmation — directly through `accept`, or when retrofit hands it an `Accepted` answer
- [ ] Engine validation and the GDD sync check each report `NOT ASSESSED` when they cannot run, never a silent pass
- [ ] Authoring does not unblock stories; it lists the stories still waiting on the ADR
- [ ] Ends with next-step handoff: `/architecture-review` in a fresh session, and `/architecture-decision accept ADR-NNNN`
---
## Coverage Notes
- ADR numbering (auto-incrementing NNN) is not independently fixture-tested —
the skill reads existing ADR filenames to assign the next number.
- Related ADRs section linking (supersedes / related-to) is tested structurally
via Case 4 but not all link types are individually verified.
- The TR-registry update (when new TR-IDs are defined in the ADR) is part of the
write phase — tested implicitly via Case 1.
- Retrofit is fixture-tested only for a missing Status answered `Accepted`
(Case 6); the other answers (`Proposed`, `Deprecated`, `Superseded`) and the
retrofit of Engine Compatibility and GDD Requirements Addressed are not.
- The acceptance-mode refusals for a missing `## Status`, an absent or `UNKNOWN`
dependency section, and an already-Accepted or Superseded ADR are not
individually fixture-tested.
- Of the GDD sync check's three outcomes, the one-line clean result (Case 1)
and `NOT ASSESSED` (Case 3) are tested; the warning block and its
three-option write approval are not.
- `team.size` and `docs.density` variations are not tested.
- ADR numbering is not independently fixture-tested beyond Case 1.
CCGS Skill Testing Framework/skills/authoring/art-bible.md
+155 -99
View File
@@ -2,184 +2,240 @@
## Skill Summary
`/art-bible` is a guided, section-by-section art bible authoring skill. It
produces a comprehensive visual direction document covering: Visual Style overview,
Color Palette, Typography, Character Design Rules, Environment Style, and UI
Visual Language. The skill follows the skeleton-first pattern: creates the file
with all section headers immediately, then fills each section through discussion
and writes each to disk after user approval.
`/art-bible` authors the art bible at `design/art/art-bible.md` in nine
sections: 1 Visual Identity Statement, 2 Mood & Atmosphere, 3 Shape Language,
4 Color System, 5 Character Design Direction, 6 Environment Design Language,
7 UI/HUD Visual Direction, 8 Asset Standards, 9 Reference Direction.
In `full` review mode, the AD-ART-BIBLE director gate (art director) runs after
the draft is complete and before any section is written. In `lean` and `solo`
modes, AD-ART-BIBLE is skipped and only user approval is required. The verdict
is COMPLETE when all sections are written.
It first reads `design/gdd/game-concept.md` (or `design/game-brief.md` at
`rigor: minimal`) and stops if neither exists. A two-tab `AskUserQuestion`
frames the session: **Scope** (with the option the resolved `workflow` tier
requires marked Recommended) and **References** (free text). Authoring is
progressive: every section's draft comes from a spawned specialist
(`art-director`; plus `ux-designer` for section 7 and `technical-artist` for
section 8), is presented to the user, approved, and written to the file
immediately before the next section starts. Sections 2–4 share one
`art-director` call, as do 5–6, but their approvals and writes stay one section
at a time. The first write asks "May I create `design/art/art-bible.md` from the
art bible template?"; each section is written only after an approval whose
option names the write (`[A] Lock this in and write it to design/art/art-bible.md`).
Only the sections in the chosen scope are authored, and the close names the
sections left out and why.
If the file already exists, the skill builds a section status table from two
Greps (headings and placeholder markers) without reading the document, and
authors only Empty or Placeholder sections.
After the scoped sections are written, Phase 5 runs the AD-ART-BIBLE sign-off in
`full` review mode only and records the verdict in the art bible's status
header. Phase 6 closes with an `AskUserQuestion` of next steps filtered by
project state.
---
## Static Assertions (Structural)
Verified automatically by `/skill-test static` — no fixture needed.
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 keyword: COMPLETE
- [ ] Contains "May I write" language per section
- [ ] Contains gate verdict keywords recorded in the status header: `APPROVED`, `CONCERNS`
- [ ] Contains ask-before-write language: "May I create `design/art/art-bible.md` from the art bible template?" before the file exists, and a per-section approval option that names the write (`Lock this in and write it to design/art/art-bible.md`)
- [ ] Documents the AD-ART-BIBLE director gate and its mode behavior
- [ ] Has a next-step handoff (e.g., `/asset-spec` or `/design-system`)
- [ ] Has a next-step handoff (e.g., `/map-systems`, `/create-architecture`)
---
## Director Gate Checks
| Gate ID | Trigger condition | Mode guard |
|--------------|--------------------------------|-----------------------|
| AD-ART-BIBLE | After draft is complete | full only (not lean/solo) |
| Gate ID | Trigger condition | Mode guard |
|--------------|----------------------------------------------------------|------------|
| AD-ART-BIBLE | Phase 5 — after all sections in the Phase 1 scope are written | full only; lean notes "AD-ART-BIBLE skipped — Lean mode.", solo notes "AD-ART-BIBLE skipped — Solo mode." |
The gate is spawned as the agent its definition names
(`.claude/docs/director-gates/ad-art-bible.md`: `art-director`) and is passed the
four items that definition lists: the art bible path, the game pillars and core
fantasy, the platform and performance constraints (`platform.*` and
`performance.*`), and the visual identity anchor. From a one-page brief it passes
the brief's pitch and "what they feel" line as the pillars and fantasy, and its
"Art & audio direction" line as the anchor.
The section-drafting delegation to `art-director` (and to `ux-designer` /
`technical-artist`) is not a gate: it is mandatory and runs in every review mode.
---
## Test Cases
### Case 1: Happy Path — Full mode, art bible drafted, AD-ART-BIBLE approves
### Case 1: Happy Path — Full mode, full workflow, all nine sections, AD-ART-BIBLE approves
**Fixture:**
- No existing `design/art-bible.md`
- `production/session-state/review-mode.txt` contains `full`
- `design/gdd/game-concept.md` exists with visual tone described
- No `design/art/art-bible.md`
- `design/gdd/game-concept.md` exists with pillars and a Visual Identity Anchor section
- `project.yaml` has `modes.review_mode: full` and `modes.workflow: full`
- AD-ART-BIBLE returns APPROVE
**Input:** `/art-bible`
**Expected behavior:**
1. Skill creates skeleton `design/art-bible.md` with all section headers
2. Skill discusses and drafts each section with user collaboration
3. After all sections are drafted, AD-ART-BIBLE gate is invoked (art director review)
4. AD-ART-BIBLE returns APPROVED
5. Skill asks "May I write section [N] to `design/art-bible.md`?" per section
6. All sections written after approval; verdict is COMPLETE
1. Phase 0 reads the game concept and extracts title, pitch, pillars, the Visual Identity Anchor and platform
2. Phase 1 asks one `AskUserQuestion` with a Scope tab (Full bible marked Recommended, because `full` requires all 9 sections) and a free-text References tab, and notes the anchor it found
3. Section 1: `art-director` drafts it; the user picks from `[A] Lock this in and write it to design/art/art-bible.md` / `[B] Revise the one-liner` / `[C] Revise a supporting principle` / `[D] Describe my own direction`; after "May I create `design/art/art-bible.md` from the art bible template?", the file is created from `.claude/docs/templates/art-bible.md` and the approved section replaces Section 1's `[To be designed]` line
4. Sections 2–4: one `art-director` call returns three labelled blocks; Section 2 is presented, approved with the option that names the write, and written before Section 3 is presented, and so on
5. Sections 5–6: one `art-director` call; presented, approved and written one at a time
6. Section 7: `art-director` and `ux-designer` spawn in parallel; Section 8: `art-director` and `technical-artist` spawn in parallel; Section 9: `art-director`
7. Phase 5: AD-ART-BIBLE spawns after the ninth section is written, with the art bible path, the pillars and core fantasy, the platform and performance constraints, and the visual identity anchor
8. The status header records `> **Art Director Sign-Off (AD-ART-BIBLE)**: APPROVED [date]`
9. Phase 6: `AskUserQuestion` of next steps that always includes `/create-architecture` and "Stop here"
**Assertions:**
- [ ] Skeleton file is created first (before any section content is written)
- [ ] AD-ART-BIBLE gate is invoked in full mode after draft is complete
- [ ] Gate approval precedes the "May I write" section asks
- [ ] All sections are present in the final file
- [ ] Verdict is COMPLETE
- [ ] The Scope tab marks "Full bible — all 9 sections" as Recommended and says why
- [ ] Every section's content comes from a spawned specialist, never from the orchestrator's own drafting
- [ ] Sections 2–4 come from a single `art-director` call but are presented, approved and written one section at a time
- [ ] No section is written before an approval whose option names the write (`Lock this in and write it to design/art/art-bible.md`), and each is written immediately after it
- [ ] The file is created from `.claude/docs/templates/art-bible.md` only after "May I create `design/art/art-bible.md` from the art bible template?" — an ask that names the file — so its nine `## N. Name` headings are the ones retrofit mode (Case 4) reads
- [ ] AD-ART-BIBLE spawns only after all nine sections are written, as `art-director` (the agent its gate definition names)
- [ ] AD-ART-BIBLE is passed all four context items: the art bible path, the pillars and core fantasy, the platform and performance constraints, and the visual identity anchor
- [ ] The APPROVE verdict is recorded in the art bible's status header line
- [ ] The closing options include `/create-architecture` and "Stop here"
---
### Case 2: AD-ART-BIBLE Returns CONCERNS — Section revised before writing
### Case 2: AD-ART-BIBLE Returns CONCERNS or NOT ASSESSED
**Fixture:**
- Art bible draft complete
- `production/session-state/review-mode.txt` contains `full`
- AD-ART-BIBLE gate returns CONCERNS: "Color palette clashes with the dark
atmospheric tone described in the game concept"
- All nine sections have been written to `design/art/art-bible.md`
- `project.yaml` has `modes.review_mode: full` and `modes.workflow: full`
- Scenario (a): AD-ART-BIBLE returns CONCERNS: "Color System does not match the Mood & Atmosphere targets for combat"
- Scenario (b): AD-ART-BIBLE returns NOT ASSESSED — no platform or performance constraints were available to check the asset standards against
**Input:** `/art-bible`
**Input:** `/art-bible` (reaching Phase 5)
**Expected behavior:**
1. AD-ART-BIBLE gate returns CONCERNS with specific feedback about palette
2. Skill surfaces feedback to user: "Art director has concerns about the color palette"
3. Skill returns to the Color Palette section for revision
4. User and skill revise the palette to align with game concept tone
5. AD-ART-BIBLE is not re-invoked (user decides to proceed after revision)
6. Revised section is written after "May I write" approval; verdict is COMPLETE
1. (a) The CONCERNS are surfaced to the user via `AskUserQuestion` with the standard options from `director-gates.md`: `Revise flagged items` / `Accept and proceed` / `Discuss further`
2. (a) If "Accept and proceed": the status header records `CONCERNS (accepted) [date]`
3. (a) If "Revise flagged items": `art-director` — the Color System's own specialist — re-drafts Section 4; it is shown to the user and approved with the option that names the write before it is written; the status header then records `REVISED [date]`
4. (b) The missing input is named, and the status header records `NOT ASSESSED [date] — [missing input]`, never `APPROVED`
5. Phase 6 runs only after the verdict is recorded
**Assertions:**
- [ ] CONCERNS are shown to user before any section is written
- [ ] Skill returns to the affected section for revision (not all sections)
- [ ] Revised content (not original) is written to file
- [ ] Verdict is COMPLETE after revision and approval
- [ ] (a) CONCERNS are shown to the user with the three standard options, not auto-accepted
- [ ] (a) "Accept and proceed" records `CONCERNS (accepted) [date]` in the status header
- [ ] (a) The flagged section is re-drafted by its specialist, not by the orchestrator, and approved before it is written; the header records `REVISED [date]`
- [ ] (b) NOT ASSESSED is recorded as such, naming the missing input — not as an approval
- [ ] Phase 6 next steps are not presented before the verdict is recorded
---
### Case 3: Lean Mode — AD-ART-BIBLE Skipped, Written With User Approval Only
### Case 3: Lean Mode, Standard Workflow — Core sections only, gate skipped
**Fixture:**
- No existing art bible
- `production/session-state/review-mode.txt` contains `lean`
- `design/gdd/game-concept.md` exists
- `project.yaml` has `modes.review_mode: lean` and `modes.workflow: standard`
- User picks the Recommended scope
**Input:** `/art-bible`
**Expected behavior:**
1. Skill reads review mode — determines `lean`
2. Skill drafts all sections with user collaboration
3. AD-ART-BIBLE gate is skipped: output notes "[AD-ART-BIBLE] skipped — lean mode"
4. Skill asks user for direct approval of each section
5. Sections are written after user confirmation; verdict is COMPLETE
1. The Scope tab marks "Visual identity core (sections 1–4 only)" as Recommended and says "Sections 1–4 are what `standard` requires; 5–9 are available if you want them."
2. Sections 1–4 are drafted by `art-director`, each approved and written before the next
3. Phases 3 and 4 (sections 5–9) are not run, because they are outside the chosen scope
4. Phase 5 does not spawn AD-ART-BIBLE and prints "AD-ART-BIBLE skipped — Lean mode."
5. Phase 6 first names sections 5–9 as not authored this run (outside the chosen scope), then presents next steps
**Assertions:**
- [ ] AD-ART-BIBLE gate is NOT invoked in lean mode
- [ ] Skip is explicitly noted: "[AD-ART-BIBLE] skipped — lean mode"
- [ ] User approval is still required per section (gate skip ≠ approval skip)
- [ ] Verdict is COMPLETE
- [ ] The Scope recommendation is sections 1–4, with the `standard` explanation
- [ ] Only sections 1–4 are authored
- [ ] The close names sections 5–9 as not authored and says why, so the four-section bible does not read as complete
- [ ] AD-ART-BIBLE is not spawned in lean mode, and the skip note reads "AD-ART-BIBLE skipped — Lean mode."
- [ ] Per-section user approval is still required before each write
---
### Case 4: Existing Art Bible — Retrofit Mode
### Case 4: Existing Art Bible — Retrofit of incomplete sections only
**Fixture:**
- `design/art-bible.md` already exists with all sections populated
- User wants to update the Character Design Rules section
- `design/art/art-bible.md` exists with sections 1–4 fully written
- Section 5's heading is followed by `[To be designed]`
- Sections 6–9 have headings with nothing between them
- `design/gdd/game-concept.md` exists; `project.yaml` has `modes.workflow: full` and `modes.review_mode: full`
- At the Scope tab the user picks `Resume — fill in missing sections`
- AD-ART-BIBLE returns APPROVE
**Input:** `/art-bible`
**Expected behavior:**
1. Skill reads existing art bible and detects all sections populated
2. Skill offers retrofit: "Art bible exists — which section would you like to update?"
3. User selects Character Design Rules
4. Skill drafts updated content; in full mode, AD-ART-BIBLE is invoked for the
revised section before writing
5. Skill asks "May I write Character Design Rules to `design/art-bible.md`?"
6. Only that section is updated; other sections preserved; verdict is COMPLETE
1. Phase 0 Globs `design/art/art-bible.md` and finds it
2. The skill runs two Greps — `^## ` headings and placeholder markers (`[To be designed]`, `[TBD]`, `[To be written]`, `TODO`) — and does not read the whole document; an ambiguous section is read by line range only
3. It builds a status table (sections 1–4 Complete, 5 Placeholder, 6–9 Empty) and says: "Found existing art bible at `design/art/art-bible.md`. 4 sections are complete, 5 need content. I'll work on the incomplete sections only — existing content will not be touched."
4. Only sections 5–9 are authored, approved and written; sections 1–4 are not re-authored or rewritten
5. After the ninth section is written, Phase 5 spawns AD-ART-BIBLE — a retrofit still ends in the sign-off in `full` review mode — and the status header records `APPROVED [date]`
6. Phase 6 names sections 1–4 as not authored this run (already complete)
**Assertions:**
- [ ] Existing art bible is detected and retrofit is offered
- [ ] Only the selected section is updated
- [ ] In full mode: AD-ART-BIBLE gate runs even for single-section retrofit
- [ ] Other sections are preserved
- [ ] Verdict is COMPLETE
- [ ] Section status comes from the two Greps, not from a full read of the file
- [ ] The retrofit message states the complete and incomplete counts and that existing content will not be touched
- [ ] Only Empty and Placeholder sections are authored; Complete sections are left unchanged
- [ ] The status table rows use the section names the skill authors (e.g., `Mood & Atmosphere`, `Shape Language`, `Reference Direction`)
- [ ] AD-ART-BIBLE runs after the retrofitted sections are written, as it does after a fresh run
---
### Case 5: Solo Mode — AD-ART-BIBLE Skipped, Noted in Output
### Case 5: Solo Mode and Missing Concept
**Fixture:**
- No existing art bible
- `production/session-state/review-mode.txt` contains `solo`
- Scenario (a): no `design/gdd/game-concept.md`; `design/game-brief.md` exists; `project.yaml` has `modes.review_mode: solo` and `modes.workflow: minimal`
- Scenario (b): neither `design/gdd/game-concept.md` nor `design/game-brief.md` exists
**Input:** `/art-bible`
**Expected behavior:**
1. Skill reads review mode — determines `solo`
2. Art bible is drafted and written with only user approval
3. AD-ART-BIBLE gate is skipped: output notes "[AD-ART-BIBLE] skipped — solo mode"
4. No director agents are spawned
5. Verdict is COMPLETE
1. (a) Phase 0 reads the one-page brief (working title, pitch, "what they feel" line, "Art & audio direction" line) in place of the concept
2. (a) Before the Scope question, the skill says no art bible is required at `minimal` and offers sections 1–4 rather than defaulting to all 9
3. (a) `art-director` is still spawned to draft each authored section — the solo review mode skips the sign-off, not the authoring delegation
4. (a) Phase 5 prints "AD-ART-BIBLE skipped — Solo mode." and no gate agent is spawned; on "May I record the skipped sign-off in `design/art/art-bible.md`'s header?" answered yes, the status header records `> **Art Director Sign-Off (AD-ART-BIBLE)**: SKIPPED [date] — solo mode`
5. (a) Phase 6, at `workflow: minimal`, offers `/create-stories`, `/dev-story [next story]` and Stop here — not `/create-architecture` or the GDD/`/map-systems` pool
6. (b) The skill stops with: "No game concept found. Run `/brainstorm` first — the art bible is authored after the game concept is approved." No file is created and no agent is spawned
**Assertions:**
- [ ] AD-ART-BIBLE gate is NOT invoked in solo mode
- [ ] Skip is explicitly noted with "solo mode" label
- [ ] No director agents of any kind are spawned
- [ ] Verdict is COMPLETE
- [ ] (a) The game brief is used when the game concept is absent
- [ ] (a) The skill states no art bible is required at `minimal` before asking the Scope question
- [ ] (a) `art-director` still drafts the sections in solo mode
- [ ] (a) AD-ART-BIBLE is not spawned; the skip note reads "AD-ART-BIBLE skipped — Solo mode.", and the header records the SKIPPED sign-off line with the mode and date
- [ ] (a) The Phase 6 option pool is the `workflow: minimal` set, not the `standard`/`full` GDD pool
- [ ] (b) The skill stops with the `/brainstorm` message and writes nothing
---
## Protocol Compliance
- [ ] Creates skeleton file immediately with all section headers
- [ ] Discusses and drafts one section at a time
- [ ] AD-ART-BIBLE gate runs in full mode after all sections are drafted
- [ ] AD-ART-BIBLE is skipped in lean and solo modes — noted by name
- [ ] Asks "May I write section [N]" per section
- [ ] Verdict is COMPLETE when all sections are written
- [ ] Reads the game concept (or game brief) before authoring; stops with the `/brainstorm` message if neither exists
- [ ] Every section is drafted by a specialist agent; the orchestrator never drafts content itself
- [ ] Each section is presented, approved and written one at a time — approvals and writes are never batched
- [ ] The file is created only after the "May I create `design/art/art-bible.md`…" ask, and each section is written only after an approval option that names the write
- [ ] Only the sections in the chosen scope are authored, and the close names every section left out and why
- [ ] Conflicts between `art-director` and `ux-designer` or `technical-artist` are surfaced to the user, never silently resolved
- [ ] AD-ART-BIBLE runs only in full mode, after the scoped sections are written; lean and solo print a skip note naming the gate and mode
- [ ] Ends with an `AskUserQuestion` of next steps filtered by project state — at `standard`/`full` always including `/create-architecture` and "Stop here"; at `workflow: minimal`, `/create-stories` or `/dev-story [next story]` plus Stop here
---
## Coverage Notes
- The case where AD-ART-BIBLE returns REJECT (not just CONCERNS) is not
separately tested; the skill would block writing and ask the user how to
proceed (revise or override).
- The Typography section is listed as a required art bible section but its
specific content requirements are not assertion-tested here.
- The art bible feeds into `/asset-spec` — this relationship is noted in the
handoff but not tested as part of this skill's spec.
- An AD-ART-BIBLE REJECT verdict is not separately tested; per the standard
verdict rules the skill surfaces the blockers and does not advance until they
are resolved, the flagged sections re-drafted by their specialist and
re-approved as in Case 2 (a).
- At `workflow: standard` the art bible is required only when visual asset
stories exist. That condition is not fixture-tested; Case 3 covers only the
`standard` scope recommendation.
- The Section 7 (`art-director` vs `ux-designer`) and Section 8
(`art-director` vs `technical-artist`) conflict handling is covered only by
Protocol Compliance, not by a dedicated fixture.
- The "Asset standards only (section 8)" scope option is not fixture-tested
(Case 4 covers "Resume").
- `docs.density` depth variations and `guided` / `autonomous` automation modes
are not tested.
- The Phase 6 option filtering (skip `/map-systems` when
`design/gdd/systems-index.md` exists, etc.) is not individually tested.
CCGS Skill Testing Framework/skills/authoring/create-architecture.md
+197 -101
View File
@@ -2,186 +2,282 @@
## Skill Summary
`/create-architecture` guides the user through section-by-section authoring of a
technical architecture document. It uses a skeleton-first approach — the file is
created with all required section headers before any content is filled. Each
section is discussed, drafted, and written individually after user approval. If an
architecture document already exists, the skill offers retrofit mode to update
specific sections.
`/create-architecture` produces the master architecture document,
`docs/architecture/architecture.md`. Phase 0 loads context and stops early when
a prerequisite is missing: the engine reference docs (no engine → `/setup-engine`),
`design/gdd/systems-index.md` (absent at `standard`/`full` → `/map-systems`),
and `design/gdd/game-concept.md` (absent → `/brainstorm`; at `minimal` the
one-page `design/game-brief.md` stands in). It extracts a Technical Requirements
Baseline (`TR-[gdd-slug]-[NNN]`) from the requirement-bearing sections of every
GDD, inventories existing ADRs from their headers, and shows an Engine Knowledge
Gap Inventory with an `AskUserQuestion` before authoring.
In `full` review mode, TD-ARCHITECTURE (technical-director) and LP-FEASIBILITY
(lead-programmer) spawn after the complete draft is finished. In `lean` or `solo`
mode, both gates are skipped. The skill writes to `docs/architecture/architecture.md`.
Phases 1–4 (layer map, module ownership, data flow, API boundaries) are each
presented and approved. Phase 5 audits existing ADRs and maps every baseline
requirement to ADR coverage; uncovered requirements become Required New ADRs.
Phase 7 asks "All sections approved. May I write the master architecture
document?" with `[A]/[B]/[C]` options. Phase 7b collects the TD-ARCHITECTURE and
LP-FEASIBILITY reviews, presents them side by side, and asks before recording
the sign-off in the Document Status section. Phase 8 updates
`production/session-state/active.md` and prints a fixed handoff template.
An existing `docs/architecture/architecture.md` is never replaced unasked:
Phase 0e offers to update chosen sections in place (raising the document's
version), to rewrite it, or to stop. Focus-area arguments (`layers`,
`data-flow`, `api-boundaries`, `adr-audit`) are that update with one section
chosen; with no document yet, they offer the full walkthrough instead.
---
## Static Assertions (Structural)
Verified automatically by `/skill-test static` — no fixture needed.
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, NEEDS REVISION, MAJOR REVISION NEEDED
- [ ] Contains "May I write" collaborative protocol language (per-section approval)
- [ ] Has a next-step handoff at the end (`/architecture-review` or `/create-control-manifest`)
- [ ] Documents skeleton-first approach
- [ ] Documents gate behavior: TD-ARCHITECTURE + LP-FEASIBILITY in full mode; skipped in lean/solo
- [ ] Documents retrofit mode for existing architecture documents
- [ ] Contains sign-off verdict keywords in the gates' own words: `APPROVE`, `CONCERNS`, `FEASIBLE`, and the `REVISED after …` records
- [ ] Contains ask-before-write language: write approvals via `AskUserQuestion` ("May I write the master architecture document?", "May I update the Document Status section…")
- [ ] Has a next-step handoff at the end (`/architecture-decision`, `/architecture-review`, `/create-control-manifest`)
- [ ] Documents one consistent write model for `docs/architecture/architecture.md` — when the file is first created and when each approved section is written
- [ ] Documents gate behavior: TD-ARCHITECTURE + LP-FEASIBILITY in full mode; each skipped in lean/solo with a named note
- [ ] Documents the stop branches for a missing engine, systems index and game concept
- [ ] Documents retrofit: an existing `docs/architecture/architecture.md` is detected, and updating chosen sections is offered before any rewrite
---
## Director Gate Checks
In `full` mode: TD-ARCHITECTURE (technical-director) and LP-FEASIBILITY
(lead-programmer) spawn in parallel after all sections are drafted and before
any final approval write.
Review mode comes from the resolved `review_mode` (`modes.review_mode` in
`project.yaml`); `--review full|lean|solo` overrides it for one run.
In `lean` mode: both gates are skipped. Output notes:
"TD-ARCHITECTURE skipped — lean mode" and "LP-FEASIBILITY skipped — lean mode".
In `full` mode: after `docs/architecture/architecture.md` is written, TD-ARCHITECTURE
(`technical-director`) and LP-FEASIBILITY (`lead-programmer`) review it. Each is
a spawned agent that reads its own gate file
(`.claude/docs/director-gates/td-architecture.md`, `lp-feasibility.md`); their
inputs are independent, so they spawn together and both verdicts are collected
before Step 3 presents them. The parent never reads those files: it passes
TD-ARCHITECTURE the document path, the Technical Requirements Baseline (TR-IDs
and count), the ADR list with statuses and the Engine Knowledge Gap Inventory.
In `solo` mode: both gates are skipped with equivalent notes.
In `lean` mode: neither is a PHASE-GATE, so both are skipped. Output notes
"TD-ARCHITECTURE and LP-FEASIBILITY skipped — Lean mode."
In `solo` mode: both are skipped with "TD-ARCHITECTURE and LP-FEASIBILITY
skipped — Solo mode."
---
## Test Cases
### Case 1: Happy Path — New architecture doc, skeleton-first, full mode gates approve
### Case 1: Happy Path — New architecture document, full mode, reviews approve
**Fixture:**
- No existing `docs/architecture/architecture.md`
- `docs/architecture/` contains Accepted ADRs for reference
- `production/session-state/review-mode.txt` contains `full`
- `project.yaml` has `engine.name: Godot`, `modes.review_mode: full`, `modes.workflow: full`
- `docs/engine-reference/godot/` has `VERSION.md`, `breaking-changes.md`, `deprecated-apis.md`, `current-best-practices.md` and `modules/`
- `design/gdd/game-concept.md` and `design/gdd/systems-index.md` exist with real content
- `design/gdd/combat.md` and `design/gdd/inventory.md` follow the GDD template
- `docs/architecture/adr-0001-event-bus.md` exists (`Status: Accepted`)
- No `docs/architecture/architecture.md`
- TD-ARCHITECTURE returns APPROVE; LP-FEASIBILITY returns FEASIBLE
**Input:** `/create-architecture`
**Expected behavior:**
1. Skill creates skeleton `docs/architecture/architecture.md` with all required section headers
2. For each section: drafts content, shows draft, asks "May I write [section]?", writes after approval
3. After all sections are drafted: TD-ARCHITECTURE and LP-FEASIBILITY spawn in parallel
4. Both gates return APPROVED
5. Final "May I confirm architecture is complete?" asked
6. Session state updated
1. Phase 0a reads the four engine docs and only the `modules/` docs matching domains in the systems index
2. Phase 0b Greps the requirement-bearing sections of each GDD (Detailed Rules/Design, Formulas, Dependencies, Tuning Knobs, Acceptance Criteria) and presents the Technical Requirements Baseline with IDs such as `TR-combat-001`
3. Phase 0c builds the ADR inventory from `## Status`/`## Summary` and `**Domain**` Greps, not full reads
4. Phase 0d shows the Engine Knowledge Gap Inventory and asks `[A] Proceed — flag HIGH RISK domains…` / `[B] Let me check the engine reference first…` / `[C] Show me which domains are HIGH RISK and why`
5. Phases 1–4: each proposal (layer map, ownership map, each data-flow scenario, API boundaries) is shown and approved before the next, and each approval is recorded in `production/session-state/active.md` — nothing is written to the architecture document before Phase 7
6. Phase 7: a one-paragraph summary, then "All sections approved. May I write the master architecture document?" with `[A] Yes — write…` / `[B] Show me the full draft inline first…` / `[C] Not yet…`
7. Phase 7b: TD-ARCHITECTURE (passed the document path, the TR baseline, the ADR list with statuses and the knowledge gap inventory) and LP-FEASIBILITY review the written document; both assessments are shown side by side; the user chooses `Accept — proceed to handoff`
8. The proposed Document Status block is shown, then "May I update the Document Status section with the sign-off results?"
9. Phase 8 writes a summary to `production/session-state/active.md` and prints the handoff with the headings "Architecture Complete", "Run These ADRs Next", "Gate-Check Readiness"; its **Then:** line names `/architecture-review`, then `/create-control-manifest` once the review passes, and the readiness block names `/gate-check pre-production`
**Assertions:**
- [ ] Skeleton file is created with all section headers before any content is written
- [ ] "May I write [section]?" asked per section during authoring
- [ ] TD-ARCHITECTURE and LP-FEASIBILITY spawn in parallel (not sequentially)
- [ ] Both gates complete before the final completion confirmation
- [ ] Verdict is APPROVED when both gates return APPROVED
- [ ] Next-step handoff to `/architecture-review` or `/create-control-manifest` is present
- [ ] The baseline uses `TR-[gdd-slug]-[NNN]` IDs and is built from the scanned GDD sections, not whole-file reads
- [ ] The knowledge gap inventory and its three-option `AskUserQuestion` come before Phase 1
- [ ] Each section is shown before its approval is asked
- [ ] The master document is written only after the Phase 7 `AskUserQuestion` approval
- [ ] TD-ARCHITECTURE and LP-FEASIBILITY are each spawned as agents (`technical-director`, `lead-programmer`) after the document is written, and both verdicts are collected before Step 3
- [ ] TD-ARCHITECTURE is passed its four context items by name; the parent session does not read the gate file
- [ ] The Document Status sign-off is written only after the "May I update" approval
- [ ] The handoff uses the fixed template headings, with no trailing commentary
- [ ] The handoff names `/gate-check pre-production` — never a `[stage]` placeholder, which while this skill runs would resolve to the gate already passed
- [ ] `docs/architecture/architecture.md` is not written, even in part, before the Phase 7 ask; Phases 2–4 approvals go to the session state
---
### Case 2: Failure Path — TD-ARCHITECTURE returns MAJOR REVISION
### Case 2: Review Concerns — LP-FEASIBILITY returns CONCERNS
**Fixture:**
- Architecture doc is fully drafted (all sections)
- `production/session-state/review-mode.txt` contains `full`
- TD-ARCHITECTURE gate returns MAJOR REVISION: "[specific structural issue]"
- Same as Case 1, up to Phase 7b
- LP-FEASIBILITY returns CONCERNS: "Save/load path has no owning module for serialisation"
- Scenario (a): TD-ARCHITECTURE returns APPROVE
- Scenario (b): TD-ARCHITECTURE returns NOT ASSESSED, naming a context item it could not read
**Input:** `/create-architecture`
**Expected behavior:**
1. All sections are drafted and written
2. TD-ARCHITECTURE gate runs and returns MAJOR REVISION with specific feedback
3. Skill surfaces the feedback to the user
4. Architecture is NOT marked as finalized
5. User is asked: revise the flagged sections, or accept the document as a draft
1. Step 3 shows the Technical Director assessment and the Lead Programmer verdict side by side, including the specific concern
2. `AskUserQuestion`: `Accept — proceed to handoff` / `Revise flagged items first` / `Discuss specific concerns`
3. If Accept: the proposed Document Status reads `LP-FEASIBILITY: [date] — CONCERNS (accepted)`, and is applied only after "May I update the Document Status section…" is answered yes
4. If Revise: the flagged section is re-drafted and approved as in Phases 1–4, the revised document is written once through Phase 7's ask, and the status then reads `LP-FEASIBILITY: [date] — REVISED after CONCERNS`
5. The skill does not record `FEASIBLE` for a review that returned CONCERNS
6. (b) Step 4 proposes `TD-ARCHITECTURE: [date] — NOT ASSESSED — [missing input]`, never `APPROVE`, and the handoff's first line says `NOT ASSESSED`
**Assertions:**
- [ ] Architecture is NOT marked finalized when TD-ARCHITECTURE returns MAJOR REVISION
- [ ] Gate feedback is shown to the user with specific issue descriptions
- [ ] User is given the option to revise specific sections
- [ ] Skill does NOT auto-finalize despite MAJOR REVISION feedback
- [ ] The concern text is shown to the user alongside the TD assessment
- [ ] The user is offered Accept / Revise flagged items first / Discuss specific concerns
- [ ] Accepting records `CONCERNS (accepted)`, not `FEASIBLE`
- [ ] A revision records `REVISED after CONCERNS`, and the revised document is written once, after its sections are approved
- [ ] No Document Status change is written without the "May I update" approval
- [ ] (b) A NOT ASSESSED review is recorded with its missing input and never as an approval
---
### Case 3: Lean Mode — Both gates skipped; architecture written with user approval only
### Case 3: Lean and Solo Modes — Both reviews skipped, written with user approval only
**Fixture:**
- No existing architecture doc
- `production/session-state/review-mode.txt` contains `lean`
- Same project as Case 1, but scenario (a): `project.yaml` has `modes.review_mode: lean`
- Scenario (b): same project, invoked with `--review solo`
**Input:** `/create-architecture`
**Input:** (a) `/create-architecture` (b) `/create-architecture --review solo`
**Expected behavior:**
1. Skeleton file is created
2. All sections are authored and written per-section with user approval
3. After completion: TD-ARCHITECTURE and LP-FEASIBILITY are skipped
4. Output notes: "TD-ARCHITECTURE skipped — lean mode" and "LP-FEASIBILITY skipped — lean mode"
5. Architecture is considered complete based on user approval alone
1. Phases 0–7 run as in Case 1; the document is written after the Phase 7 approval
2. At Phase 7b neither review runs; output notes (a) "TD-ARCHITECTURE and LP-FEASIBILITY skipped — Lean mode." (b) "TD-ARCHITECTURE and LP-FEASIBILITY skipped — Solo mode."
3. Step 4 shows the Document Status block with both lines `skipped — [mode] mode` and
asks before applying it; the skill then proceeds to the Phase 8 handoff without
blocking on the skipped reviews
**Assertions:**
- [ ] Both gate skip notes appear in output
- [ ] Architecture document is written with only user approval in lean mode
- [ ] Skill does NOT block completion because gates were skipped
- [ ] Next-step handoff is still present
- [ ] Neither `technical-director` nor `lead-programmer` is spawned, and no TD-ARCHITECTURE review is applied in lean or solo mode
- [ ] The skip note names both gates and the mode
- [ ] (b) The `--review solo` argument overrides the resolved `review_mode` for the run
- [ ] The document is written on user approval alone, and completion is not blocked
- [ ] Document Status records both reviews as skipped in that mode (after its ask), so the document says why it has no sign-off
- [ ] The Phase 8 handoff is still printed
---
### Case 4: Retrofit Mode — Existing architecture doc, user updates a section
### Case 3b: Review Rejects — Accept Is Not Offered
**Fixture:**
- `docs/architecture/architecture.md` already exists with all sections populated
- Same project as Case 1 in `full` mode; `technical-director` returns
`TD-ARCHITECTURE: REJECT` (a Core system depends on a Presentation-layer module);
`lead-programmer` returns `LP-FEASIBILITY: FEASIBLE`
**Input:** `/create-architecture`
**Expected behavior:**
1. Skill detects existing architecture doc and reads its current content
2. Skill offers retrofit mode: "Architecture doc already exists. Which section would you like to update?"
3. User selects a section
4. Skill authors only that section, asks "May I write [section]?"
5. Only the selected section is updated — other sections unchanged
1. Both reviews are spawned in parallel at Phase 7b
2. Step 3 shows `TD-ARCHITECTURE: REJECT` and `LP-FEASIBILITY: FEASIBLE` side by side
3. The `AskUserQuestion` offers `Revise flagged items first` and `Discuss specific concerns` — **not** `Accept`
4. On `Revise flagged items first`, the flagged sections are re-drafted and approved as in Phases 1–4, and the revised document is written once, through Phase 7's ask
5. Nothing is recorded as approved; Step 4 records `REVISED after REJECT`, and the handoff's first line carries the same value
**Assertions:**
- [ ] Skill detects and reads the existing architecture doc before offering retrofit
- [ ] User is asked which section to update — not asked to rewrite the whole document
- [ ] Only the selected section is updated
- [ ] Other sections are not modified during a retrofit session
- [ ] `technical-director` and `lead-programmer` calls are issued before either result is awaited
- [ ] `Accept — proceed to handoff` is not an option while a REJECT stands
- [ ] The revised document is written once, after the re-drafted sections are approved — not section by section
- [ ] Document Status never shows TD-ARCHITECTURE as APPROVE for this run; the handoff line says `REVISED after REJECT`
---
### Case 5: Director Gate — Architecture references a Proposed ADR; flagged as risk
### Case 4: Edge Case — Systems index missing or empty
**Fixture:**
- Architecture doc is being authored
- One section references or depends on an ADR that has `Status: Proposed`
- `production/session-state/review-mode.txt` contains `full`
- Engine configured; `design/gdd/game-concept.md` exists
- Scenario (a): `modes.workflow: standard`, no `design/gdd/systems-index.md`
- Scenario (b): `modes.workflow: standard`, `design/gdd/systems-index.md` exists but contains only template placeholders
- Scenario (c): `modes.workflow: minimal`, no systems index, no game concept, `design/game-brief.md` exists
**Input:** `/create-architecture`
**Expected behavior:**
1. Skill authors all sections
2. During authoring, skill detects a reference to a Proposed ADR
3. Skill flags: "Note: [section] references ADR-NNN which is Proposed — this is a risk until the ADR is accepted"
4. Risk flag is embedded in the relevant section's content
5. TD-ARCHITECTURE and LP-FEASIBILITY still run — they are informed of the Proposed ADR risk
1. The skill checks both design files exist before reading either
2. (a) Stops with: "No systems index found. Run `/map-systems` first…" — no baseline is built, no file is written
3. (b) Treats the placeholder-only index as absent and stops the same way
4. (c) Says the systems index is not required at `minimal`, reads `design/game-brief.md` in place of the concept, and proceeds
**Assertions:**
- [ ] Proposed ADR reference is detected and flagged during section authoring
- [ ] Risk note is embedded in the architecture document section
- [ ] TD-ARCHITECTURE and LP-FEASIBILITY still spawn (the risk does not block the gates)
- [ ] Risk flag names the specific ADR number and title
- [ ] (a) The skill stops with the `/map-systems` message and writes nothing
- [ ] (b) A present-but-placeholder systems index is treated as absent
- [ ] (c) At `minimal` the skill says the index is not required and proceeds from the game brief
- [ ] At `standard` (a, b), no run continues past Phase 0b with a missing design file; at `minimal` (c) the brief stands in for both, and the run stops only if it is absent too
---
### Case 5: ADR Audit — Proposed ADRs and uncovered requirements
**Fixture:**
- Same as Case 1, plus `docs/architecture/adr-0002-save-format.md` with `Status: Proposed`
- Also `design/gdd/crafting.md`, written before the GDD template, with none of the scanned section headings
- Baseline requirement `TR-combat-002` (combo state machine) is not covered by any ADR's GDD Requirements Addressed section or decision text
**Input:** `/create-architecture`
**Expected behavior:**
1. Phase 0b's section Grep matches nothing in `crafting.md`, so the skill full-reads it, says so, and its requirements enter the baseline as `TR-crafting-NNN` — a zero-match GDD is never treated as having no requirements
2. Phase 0c lists ADR-0001 (Accepted) and ADR-0002 (Proposed) with their domains
3. Phase 5 shows the ADR quality table and the traceability table, marking `TR-combat-002` as `❌ GAP`, with a covered/gap count
4. The gap is listed under Required New ADRs, grouped by layer with Foundation first, as `/architecture-decision [title] → covers: TR-combat-002`
5. Phase 8's "Gate-Check Readiness" lists ADR-0002 under "Accept ADRs" and the unwritten ADRs under "Write ADRs"
6. "Run These ADRs Next" lists at most three ADRs from Phase 6, in priority order
**Assertions:**
- [ ] `crafting.md`, which matched no scanned section, is full-read and reported, and contributes TR-IDs to the baseline
- [ ] ADR statuses come from the header scan and ADR-0002 is reported as Proposed
- [ ] `TR-combat-002` is marked as a GAP and becomes a Required New ADR naming the TR-ID it covers
- [ ] Required New ADRs are grouped by layer, Foundation first
- [ ] "Gate-Check Readiness" lists ADR-0002 under "Accept ADRs"
- [ ] "Run These ADRs Next" lists no more than three entries
---
### Case 6: Existing Architecture Document — Update in place, never overwritten unasked
**Fixture:**
- Same project as Case 1, but `project.yaml` has `modes.review_mode: lean`
- Scenario (a): `docs/architecture/architecture.md` exists at `Version: 2` with every section written; the user picks `[A] Update chosen sections in place` and chooses Data Flow
- Scenario (b): no `docs/architecture/architecture.md`; the input is `/create-architecture layers`
**Input:** (a) `/create-architecture` (b) `/create-architecture layers`
**Expected behavior:**
1. (a) Phase 0e finds the document, reads its Document Status and headings, and asks "An architecture document already exists (v2, [last updated]). What should this run do?" with `[A] Update chosen sections in place` / `[B] Rewrite the whole document — replaces the existing file` / `[C] Stop`
2. (a) Only Phase 3 (Data Flow) is authored; the output says which phases were skipped
3. (a) Phase 7's ask names the Data Flow section and the change from v2 to v3; on yes, only `## Data Flow` is replaced, with `Edit`, and `Version` becomes 3
4. (a) Every other section of the document is unchanged, and the handoff names v3
5. (b) The skill says there is no architecture document for the `layers` focus area to update, and offers the full walkthrough instead; nothing is written before the user answers
**Assertions:**
- [ ] (a) The existing document is detected before any authoring, and replacing it is only ever the user's explicit `[B]` choice
- [ ] (a) Only the chosen section is re-authored and written; the other sections are left as they were
- [ ] (a) The version is raised, not reset to v1.0
- [ ] (b) A focus-area run with no document writes nothing and offers the full walkthrough
---
## Protocol Compliance
- [ ] Skeleton file created with all section headers before any content is written
- [ ] "May I write [section]?" asked per section during authoring
- [ ] TD-ARCHITECTURE and LP-FEASIBILITY spawn in parallel in full mode
- [ ] Skipped gates noted by name and mode in lean/solo output
- [ ] Proposed ADR references flagged as risks in the document
- [ ] Ends with next-step handoff: `/architecture-review` or `/create-control-manifest`
- [ ] Stops before authoring when the engine is missing, or on a `standard`/`full` project when the systems index or game concept is missing; at `minimal` it proceeds from `design/game-brief.md` and stops only when that is absent too
- [ ] Every section is shown in full before its approval is asked
- [ ] Write approvals use `AskUserQuestion` with labeled options, not plain-text asks
- [ ] Follows one consistent write model for `docs/architecture/architecture.md`, and never replaces an existing one without the user choosing to
- [ ] TD-ARCHITECTURE and LP-FEASIBILITY run only in full mode; lean/solo print a skip note naming each gate and the mode
- [ ] The Document Status sign-off is recorded only after the "May I update" approval
- [ ] Ends with the fixed handoff template and next steps (`/architecture-decision`, `/architecture-review`, `/create-control-manifest`)
---
## Coverage Notes
- The required section list for architecture documents is defined in the skill
body and in the `/architecture-review` skill — not re-enumerated here.
- Engine version stamping in the architecture doc (parallel to ADR stamping)
is part of the authoring workflow — tested implicitly via Case 1.
- The retrofit mode for updating multiple sections in one session follows the
same per-section approval pattern — not independently tested for multi-section
retrofits.
- Of the focus-area arguments, only `layers` with no existing document is
fixture-tested (Case 6 b). A focus-area run against an existing document
follows Case 6 (a)'s update path but is not tested on its own.
- The "no engine configured" stop is asserted structurally only.
- `workflow: standard` (a system layer map and the critical ADR list only) is
not fixture-tested past Phase 0b; Case 4 exercises only its stop branches.
- `docs.density` depth variations and `guided` / `autonomous` automation modes
are not tested.
CCGS Skill Testing Framework/skills/authoring/design-system.md
+189 -108
View File
@@ -2,191 +2,272 @@
## Skill Summary
`/design-system` guides the user through section-by-section authoring of a Game
Design Document (GDD) for a single game system. All 8 required sections must be
authored: Overview, Player Fantasy, Detailed Rules, Formulas, Edge Cases,
Dependencies, Tuning Knobs, and Acceptance Criteria. The skill uses a
skeleton-first approach — it creates the GDD file with all 8 section headers
before filling any content — and writes each section individually after approval.
`/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 CD-GDD-ALIGN gate (creative-director) runs in both `full` AND `lean` modes.
It is only skipped in `solo` mode. If an existing GDD file is found, the skill
offers a retrofit mode to update specific sections rather than rewriting the whole
document.
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)
Verified automatically by `/skill-test static` — no fixture needed.
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, NEEDS REVISION, MAJOR REVISION
- [ ] Contains "May I write" collaborative protocol language (per-section approval)
- [ ] 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)
- [ ] Documents CD-GDD-ALIGN gate: active in full AND lean mode; skipped in solo only
- [ ] 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
In `full` mode: CD-GDD-ALIGN (creative-director) gate runs after each section is
drafted, before writing. If MAJOR REVISION is returned, the section must be
rewritten before proceeding.
Review mode comes from the resolved `review_mode` (`modes.review_mode` in
`project.yaml`); `--review full|lean|solo` overrides it for one run.
In `lean` mode: CD-GDD-ALIGN still runs (this gate is NOT skipped in lean mode —
it runs in both full and lean). Only solo mode skips it.
**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]`.
In `solo` mode: CD-GDD-ALIGN is skipped. Output notes:
"CD-GDD-ALIGN skipped — solo mode". Sections are written with only user approval.
- `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 GDD, skeleton-first, CD-GDD-ALIGN in lean mode
### Case 1: Happy Path — New combat GDD, full mode, full workflow
**Fixture:**
- No existing GDD for the target system in `design/gdd/`
- `production/session-state/review-mode.txt` contains `lean`
- `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 [system-name]`
**Input:** `/design-system combat`
**Expected behavior:**
1. Skill creates skeleton file `design/gdd/[system-name].md` with all 8 section headers (empty bodies)
2. For each section: discusses with user, drafts content, shows draft
3. CD-GDD-ALIGN gate runs on each section draft (lean mode — gate is active)
4. Gate returns APPROVED for each section
5. "May I write [section]?" asked after gate approval
6. Section written to file after user approval
7. Process repeats for all 8 sections
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:**
- [ ] Skeleton file is created with all 8 section headers before any content is written
- [ ] CD-GDD-ALIGN runs on each section in lean mode (not skipped)
- [ ] "May I write" is asked per section (not once for all sections)
- [ ] Each section is written individually after gate + user approval
- [ ] All 8 sections are present in the final GDD file
- [ ] 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 — Existing GDD, update specific section
### Case 2: Retrofit Mode — Fill only the incomplete sections at standard tier
**Fixture:**
- `design/gdd/[system-name].md` already exists with all 8 sections populated
- `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 [system-name]`
**Input:** `/design-system retrofit design/gdd/inventory.md`
**Expected behavior:**
1. Skill detects existing GDD file and reads its current content
2. Skill offers retrofit mode: "GDD already exists. Which section would you like to update?"
3. User selects a specific section (e.g., Formulas)
4. Skill authors only that section, runs CD-GDD-ALIGN, asks "May I write?"
5. Only the selected section is updated — other sections are not modified
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:**
- [ ] Skill detects and reads existing GDD before offering retrofit mode
- [ ] User is asked which section to update — not asked to rewrite the whole document
- [ ] Only the selected section is rewritten — others remain unchanged
- [ ] CD-GDD-ALIGN still runs on the updated section
- [ ] "May I write" is asked before updating the section
- [ ] 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 MAJOR REVISION
### Case 3: Director Gate — CD-GDD-ALIGN returns CONCERNS, REJECT or NOT ASSESSED
**Fixture:**
- New GDD being authored
- `production/session-state/review-mode.txt` contains `lean`
- CD-GDD-ALIGN gate returns MAJOR REVISION on the Player Fantasy section
- `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 [system-name]`
**Input:** `/design-system stamina` (reaching Step 5a-bis)
**Expected behavior:**
1. Player Fantasy section is drafted
2. CD-GDD-ALIGN gate runs and returns MAJOR REVISION with specific feedback
3. Skill surfaces the feedback to the user
4. Section is NOT written to file while MAJOR REVISION is unresolved
5. User rewrites the section in collaboration with the skill
6. CD-GDD-ALIGN runs again on the revised section
7. If revised section passes, "May I write?" is asked and section is written
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:**
- [ ] Section is NOT written when CD-GDD-ALIGN returns MAJOR REVISION
- [ ] Gate feedback is shown to the user before requesting revision
- [ ] CD-GDD-ALIGN runs again after the section is revised
- [ ] Skill does NOT auto-proceed to the next section while MAJOR REVISION is unresolved
- [ ] 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: Solo Mode — CD-GDD-ALIGN skipped; sections written with user approval only
### Case 4: Lean and Solo Modes — Gate skipped once; specialist spawns follow their own checks
**Fixture:**
- New GDD being authored
- `production/session-state/review-mode.txt` contains `solo`
- `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 [system-name]`
**Input:** `/design-system stamina`
**Expected behavior:**
1. Skeleton file is created with 8 section headers
2. For each section: drafted, shown to user
3. CD-GDD-ALIGN is skipped — noted per section: "CD-GDD-ALIGN skipped — solo mode"
4. "May I write [section]?" asked after user reviews draft
5. Section written after user approval
6. No gate review at any stage
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:**
- [ ] "CD-GDD-ALIGN skipped — solo mode" noted for each section
- [ ] Sections are written after user approval alone (no gate required)
- [ ] Skill does NOT spawn any CD-GDD-ALIGN gate in solo mode
- [ ] Full GDD is written with only user approval in solo mode
- [ ] (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: Director Gate — Empty sections not written to file
### Case 5: Missing Input and Declined Skeleton
**Fixture:**
- GDD authoring in progress
- User and skill discuss one section but do not produce any approved content
(e.g., discussion ends without a decision, or user says "skip for now")
- `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:** `/design-system [system-name]`
**Input:** (a) `/design-system` (b) `/design-system` (c) `/design-system stamina`
**Expected behavior:**
1. Section discussion produces no approved content
2. Skill does NOT write an empty or placeholder body to the section
3. The section header remains in the skeleton file but the body stays empty
4. Skill moves to the next section without writing the empty one
5. At the end, incomplete sections are listed and user is reminded to return to them
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:**
- [ ] Empty or unapproved sections are NOT written to the file
- [ ] Skeleton section header remains (preserves structure)
- [ ] Skill tracks and lists incomplete sections at the end of the session
- [ ] Skill does NOT write "TBD" or placeholder content without user approval
- [ ] (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
- [ ] Skeleton file created with all 8 headers before any content is written
- [ ] CD-GDD-ALIGN runs in both full AND lean mode (not just full)
- [ ] CD-GDD-ALIGN skipped only in solo mode — noted per section
- [ ] "May I write [section]?" asked per section (not once for the whole document)
- [ ] MAJOR REVISION from CD-GDD-ALIGN blocks section write until resolved
- [ ] Only approved, non-empty sections are written to the file
- [ ] Ends with next-step handoff: `/review-all-gdds` or `/map-systems next`
- [ ] 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
- The 8 required sections are validated against the project's design document
standards defined in `CLAUDE.md` — not re-enumerated here.
- The skill's internal section-ordering logic (which section to author first) is
not independently tested — the order follows the standard GDD template.
- Pillar alignment checking within CD-GDD-ALIGN is evaluated holistically by
the gate agent — specific pillar checks are not fixture-tested here.
- `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.
CCGS Skill Testing Framework/skills/authoring/quick-design.md
+134 -94
View File
@@ -2,175 +2,215 @@
## Skill Summary
`/quick-design` produces a lightweight design spec for features too small to
warrant a full 8-section GDD. The target scope is under 4 hours of design time
for a single-system feature. Instead of the full 8-section GDD format, the
quick-design spec uses a streamlined 3-section format: Overview, Rules, and
Acceptance Criteria.
`/quick-design [brief description of the change]` produces a lightweight Quick
Design Spec for a change too small for a full GDD. It first classifies the
change as **Tuning**, **Tweak**, **Addition** or **New Small System** and
confirms the classification with an `AskUserQuestion` whose option `[F]`
redirects to `/design-system`. A change that introduces a system with
significant cross-system dependencies, needs more than about a week of work, or
alters a system's core rules is redirected to `/design-system` instead (verdict
`REDIRECTED`).
The skill has no director gates — adding gate overhead would defeat the purpose
of a lightweight design tool. The skill asks "May I write" before writing the
design note to `design/quick-notes/[name].md`. If the feature scope is too large
for a quick-design, the skill redirects to `/design-system` instead.
It then scans context (the relevant GDD in `design/gdd/`, the systems index if
present, prior specs in `design/quick-specs/` — each named, whether it agrees or
conflicts — and `assets/data/` for Tuning),
drafts the spec in the format for its category, presents it in full with
Approve / Revise / redirect options, and on approval asks "May I write this
Quick Design Spec to `design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md`?".
Any GDD edit the spec requires is asked for separately, showing old vs. new
text. It ends with a handoff block and verdict `COMPLETE`.
The skill has no director gates and does not resolve `review_mode`; quick specs
bypass `/design-review` and `/review-all-gdds` by design.
---
## Static Assertions (Structural)
Verified automatically by `/skill-test static` — no fixture needed.
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: CREATED, BLOCKED, REDIRECTED
- [ ] Contains "May I write" collaborative protocol language (for quick-note file)
- [ ] Contains verdict keywords: `COMPLETE`, `REDIRECTED`
- [ ] Contains "May I write" collaborative protocol language (for the quick spec file, and separately for any GDD update)
- [ ] Has a next-step handoff at the end
- [ ] Explicitly notes: no director gates (lightweight skill by design)
- [ ] Mentions scope check: redirects to `/design-system` if scope exceeds sub-4h threshold
- [ ] States that quick specs bypass `/design-review` and `/review-all-gdds` by design, and lists when to redirect to the full pipeline
- [ ] Documents the scope check that redirects oversized changes to `/design-system`
---
## Director Gate Checks
No director gates — this skill spawns no director gate agents. The lightweight
nature of quick-design means director gate overhead is intentionally absent.
Full GDD review is not needed for sub-4-hour single-system features.
None. The skill resolves only `automation` and `workflow` (not `review_mode`),
has no `Agent` tool in `allowed-tools`, and spawns no director or specialist
agent. The review mode setting has no effect on it.
---
## Test Cases
### Case 1: Happy Path — Small UI change produces a 3-section spec
### Case 1: Happy Path — Tweak to an existing system
**Fixture:**
- No existing quick-note for the target feature
- Feature is clearly scoped: a single UI element change with no cross-system impact
- `design/gdd/movement.md` exists and describes dash invincibility in its Detailed Rules
- `design/gdd/systems-index.md` exists
- `design/quick-specs/dash-cooldown-tuning-[earlier-date].md` tuned the dash cooldown in movement and does not touch invincibility
**Input:** `/quick-design [feature-name]`
**Input:** `/quick-design make dash invincible on frame 1`
**Expected behavior:**
1. Skill asks scoping questions: what system, what change, what is the acceptance signal
2. Skill determines scope is within the sub-4h threshold
3. Skill drafts a 3-section spec: Overview, Rules, Acceptance Criteria
4. Draft is shown to user
5. "May I write `design/quick-notes/[name].md`?" is asked
6. File is written after approval
1. The skill classifies the change as Tweak and asks "I've classified this as **Tweak** — [reason]. Is that correct?" with options `[A]`–`[F]`
2. The context scan reads the relevant section of `design/gdd/movement.md`, the systems index and `design/quick-specs/`, and reports "Found GDD at `design/gdd/movement.md`. Relevant section: [section]. Prior quick specs for this system: `design/quick-specs/dash-cooldown-tuning-[earlier-date].md` — agrees."
3. It drafts the Tweak/Addition format: Change Summary, Motivation, Design Delta (quoting the current GDD rule), New Rules / Values, Affected Systems, Acceptance Criteria, GDD Update Required?
4. It presents the full draft, then asks with `[A] Approve — write it as shown` / `[B] Revise — I'll describe what to change` / `[C] This grew too large — redirect to /design-system instead`
5. On `[A]`: "May I write this Quick Design Spec to `design/quick-specs/dash-invincibility-tweak-[YYYY-MM-DD].md`?" — on yes, creates `design/quick-specs/` if needed and writes the file
6. Because the spec changes a rule in `movement.md`, it then asks separately "May I update `design/gdd/movement.md` — specifically the [section] section?", showing old vs. new text first
7. It prints the handoff block (path, type, system, GDD update status) and "Verdict: **COMPLETE**"
**Assertions:**
- [ ] Spec contains exactly 3 sections: Overview, Rules, Acceptance Criteria
- [ ] Draft is shown to user before "May I write" ask
- [ ] "May I write `design/quick-notes/[name].md`?" is asked before writing
- [ ] File is written to the correct path: `design/quick-notes/[name].md`
- [ ] Verdict is CREATED after successful write
- [ ] The classification is confirmed via `AskUserQuestion` before any context scan or drafting
- [ ] The prior dash-cooldown spec is named in the context report even though it does not conflict
- [ ] The draft uses the Tweak/Addition format, and its Design Delta quotes the current GDD text
- [ ] The full draft is shown before the write approval is asked
- [ ] The file path is `design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md` with today's date
- [ ] The GDD edit is asked for separately, after the quick spec is written, with old vs. new text shown
- [ ] The run ends with the handoff block and verdict `COMPLETE`
---
### Case 2: Failure Path — Scope check fails; redirected to /design-system
### Case 2: Failure Path — Scope too large; redirected to /design-system
**Fixture:**
- Feature described spans multiple systems or would take more than 4 hours of design time
(e.g., "redesign the entire combat system" or "new progression mechanic affecting all classes")
- Scenario (a): the request is "redesign the entire combat system"
- Scenario (b): a Tweak is drafted, and at the approval step the user picks `[C] This grew too large — redirect to /design-system instead`
**Input:** `/quick-design [large-feature]`
**Input:** (a) `/quick-design redesign the entire combat system` (b) `/quick-design allow combo to cancel into roll`
**Expected behavior:**
1. Skill asks scoping questions
2. Skill determines scope exceeds the sub-4h / single-system threshold
3. Skill outputs: "This feature is too large for a quick-design. Use `/design-system [name]` for a full GDD."
4. Skill does NOT write a quick-note file
5. Verdict is REDIRECTED
1. (a) The change alters a system's core rules, so the skill stops before drafting and redirects to `/design-system` — directly, or via option `[F]` of the classification prompt
2. (b) The skill stops at the approval step
3. In both scenarios: "Verdict: **REDIRECTED** — use `/design-system` for this change."
4. No file is written under `design/quick-specs/`
**Assertions:**
- [ ] Skill detects the scope excess and stops before drafting
- [ ] Message explicitly names `/design-system` as the correct alternative
- [ ] No quick-note file is written
- [ ] Verdict is REDIRECTED (not CREATED or BLOCKED)
- [ ] (a) The scope excess is detected and the skill stops before drafting
- [ ] (a) The verdict line is printed even when the skill stops before the classification widget, not only via `[F]`
- [ ] The message names `/design-system` as the alternative
- [ ] No quick spec file is written
- [ ] The verdict is `REDIRECTED`, not `COMPLETE`
---
### Case 3: Edge Case — File already exists; offered to update
### Case 3: Edge Case — Tuning change outside the documented knob range
**Fixture:**
- `design/quick-notes/[name].md` already exists from a previous session
- `design/gdd/player-controller.md` has a Tuning Knobs entry `jump_height` with documented range 3–5
- `assets/data/player.json` holds `jump_height: 5`
- An earlier quick spec, `design/quick-specs/jump-height-tuning-[earlier-date].md`, previously set `jump_height` to 5
**Input:** `/quick-design [name]`
**Input:** `/quick-design increase jump height from 5 to 6 units`
**Expected behavior:**
1. Skill detects existing quick-note file and reads its current content
2. Skill asks: "[name].md already exists. Update it, or create a new version?"
3. User selects update
4. Skill shows the existing spec and asks which section to revise
5. Updated spec is shown, "May I write?" asked, file updated after approval
1. The skill classifies the change as Tuning and confirms it
2. The context scan also checks `assets/data/` for the data file holding the value, and names the prior quick spec that touched this parameter, marked as conflicting — it set the value this change replaces
3. The draft uses the Tuning format: a single Change table (Parameter, Old Value, New Value, Rationale), a Tuning Knob Mapping, and Acceptance Criteria
4. The Tuning Knob Mapping states the new value is outside the documented range and explains why the range should be extended
5. The acceptance criteria reference reading the value from `assets/data/[file]`
**Assertions:**
- [ ] Skill detects and reads the existing file before offering to update
- [ ] User is offered update or create-new options — not auto-overwritten
- [ ] Only the revised section is updated (or the whole spec if user chooses full rewrite)
- [ ] "May I write" is asked before overwriting the existing file
- [ ] `assets/data/` is checked for the data file because the change is Tuning
- [ ] The prior quick spec touching `jump_height` is reported, not silently contradicted
- [ ] The draft uses the single-table Tuning format, not the Tweak/Addition sections
- [ ] The Tuning Knob Mapping says the value is outside the documented range and explains the extension
---
### Case 4: Edge Case — No argument provided
### Case 4: Edge Case — No argument and no systems index
**Fixture:**
- `design/quick-notes/` directory may or may not exist
- No `design/gdd/systems-index.md`
- `design/quick-specs/` may or may not exist
**Input:** `/quick-design` (no argument)
**Expected behavior:**
1. Skill detects no argument is provided
2. Skill outputs a usage error: "No feature name specified. Usage: /quick-design [feature-name]"
3. Skill provides an example: `/quick-design pause-menu-settings`
4. No file is created
1. The skill asks the user to describe the change with a plain-text prompt
2. It does not show the classification widget, pick a change, or write anything until the user has described the change
3. After the description, it classifies and confirms as usual
4. The context scan notes "No systems index found — skipping dependency tier check." and continues
**Assertions:**
- [ ] Skill outputs a usage error when no argument is given
- [ ] A usage example is shown with the correct format
- [ ] No quick-note file is written
- [ ] Skill does NOT silently pick a feature name or default to any action
- [ ] With no argument, the skill asks for a description in plain text rather than guessing a change
- [ ] Classification happens only after the user describes the change
- [ ] The missing systems index is noted with the documented line, and the run continues
- [ ] No file is written before the approval step
---
### Case 5: Director Gate — No gate spawned; explicitly noted for sub-4h features
### Case 5: No Director Gates — Review mode has no effect
**Fixture:**
- Feature is within scope for quick-design
- `production/session-state/review-mode.txt` exists with `full`
- The change is within scope (an Addition: "add a parry window to the block mechanic")
- `design/gdd/combat.md` exists (a GDD written voluntarily at this tier) and describes the block mechanic
- `project.yaml` has `modes.review_mode: full` and `modes.workflow: minimal`
**Input:** `/quick-design [feature-name]`
**Input:** `/quick-design add a parry window to the block mechanic`
**Expected behavior:**
1. Skill asks scoping questions and determines scope is within threshold
2. Skill does NOT read `production/session-state/review-mode.txt`
3. Skill does NOT spawn any director gate agent
4. Spec is drafted, "May I write" asked, file written after approval
5. Output explicitly notes: "No director gate review — quick-design is for sub-4h features"
1. The skill runs its normal flow; `review_mode` is not among the keys it resolves, and nothing branches on it
2. No agent of any kind is spawned (the skill has no `Agent` tool)
3. The spec is drafted, approved and written after "May I write"
4. The Pipeline Notes state that quick specs bypass `/design-review` and `/review-all-gdds` by design, and list when to redirect to `/design-system`
5. At `workflow: minimal`, the handoff says to go straight to `/dev-story` rather than `/story-readiness`
**Assertions:**
- [ ] No director gate agents are spawned (no CD-, TD-, PR-, AD- prefixed gates)
- [ ] Skill does NOT read `production/session-state/review-mode.txt`
- [ ] Output contains a note explaining why no gate review is needed
- [ ] Review mode has no effect on this skill's behavior
- [ ] Full GDD review path (`/design-system`) is mentioned as the alternative for larger features
- [ ] No director gate or other agent is spawned
- [ ] `modes.review_mode: full` does not change the skill's behavior
- [ ] The output explains that quick specs bypass `/design-review` and `/review-all-gdds`, and names `/design-system` for larger changes
- [ ] The handoff points to `/dev-story` directly at `workflow: minimal`
---
### Case 6: Edge Case — No GDD for the system (the default tier)
**Fixture:**
- `project.yaml` has `modes.rigor: minimal`; `design/gdd/` holds no system GDD
- `design/game-brief.md` describes the jump; `production/epics/movement/story-002-jump.md` implements it with a jump height of 5
**Input:** `/quick-design increase jump height from 5 to 6 units`
**Expected behavior:**
1. Classified as Tuning and confirmed
2. The context scan finds no GDD and reports "No GDD for movement — using the brief and `production/epics/movement/story-002-jump.md`"
3. The spec is drafted with `design/game-brief.md` as its GDD Reference, shown, and written after "May I write"
4. No GDD update is proposed (there is no GDD to update); the handoff goes to `/dev-story`
**Assertions:**
- [ ] The skill does not stop, and does not redirect to `/design-system`, because there is no GDD
- [ ] The report names the brief and the story it used in place of a GDD
- [ ] The spec's GDD Reference is `design/game-brief.md`
- [ ] Nothing is written before the "May I write" approval
---
## Protocol Compliance
- [ ] Scope check runs before drafting (redirects to `/design-system` if scope too large)
- [ ] 3-section format used (Overview, Rules, Acceptance Criteria) — NOT the 8-section GDD format
- [ ] Draft shown to user before "May I write" ask
- [ ] "May I write `design/quick-notes/[name].md`?" asked before writing
- [ ] No director gates — no review-mode.txt read
- [ ] Ends with next-step handoff (e.g., proceed to implementation or `/dev-story`)
- [ ] The change is classified and confirmed before drafting; oversized changes redirect to `/design-system`
- [ ] The spec format matches the confirmed category (Tuning table; Tweak/Addition sections; New Small System trimmed GDD)
- [ ] The full draft is shown before the "May I write" ask
- [ ] "May I write this Quick Design Spec to `design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md`?" is asked before writing
- [ ] GDD edits are asked for separately, with old vs. new text, and never made without approval
- [ ] No director gates; review mode is not read
- [ ] Ends with the handoff block and next steps (`/story-readiness`, or `/dev-story` at `minimal`)
---
## Coverage Notes
- The scope threshold heuristic (sub-4h, single-system) is a judgment call —
the skill's internal check is the authoritative definition and is not
independently tested by counting hours.
- The `design/quick-notes/` directory is created automatically if it does not
exist — this filesystem behavior is not independently tested here.
- Integration with the story pipeline (can a quick-design generate a story
directly?) is out of scope for this spec — quick-designs are standalone.
- The New Small System format (Overview, Core Rules, Tuning Knobs, Acceptance
Criteria, Systems Index) is not fixture-tested.
- The `[B] Revise` loop at the approval step is not individually tested.
- `guided` and `autonomous` automation modes are not tested.
- The scope threshold is a judgment call; the skill's category definitions and
redirect list are the authoritative definition and are not tested by
counting hours.
CCGS Skill Testing Framework/skills/authoring/ux-design.md
+123 -93
View File
@@ -2,175 +2,205 @@
## Skill Summary
`/ux-design` is a guided, section-by-section UX spec authoring skill. It produces
user flow diagrams (described textually), interaction state definitions, wireframe
descriptions, and accessibility notes for a specified screen or HUD element. The
skill follows the skeleton-first pattern: it creates the file with all section
headers immediately, then fills each section through discussion and writes each
section to disk after user approval.
`/ux-design` authors UX documents section by section. The argument picks the
mode and output file: `hud` → `design/ux/hud.md`; `patterns` →
`design/ux/interaction-patterns.md`; `accessibility` →
`design/accessibility-requirements.md` (the only mode that writes outside
`design/ux/`); any other value → a screen/flow spec at `design/ux/[kebab-name].md`.
With no argument it asks "What are we designing today?" instead of failing.
The skill has no inline director gates — `/ux-review` is the separate review step.
Each section requires a "May I write section [N] to [filepath]?" ask. If a UX spec
already exists for the named screen, the skill offers to retrofit individual sections
rather than replace. Verdict is COMPLETE when all sections are written.
Phase 2 reads context before asking anything: the game concept (or game brief),
the player journey, GDD UI Requirements, existing UX specs, the pattern library
catalog, the art bible, accessibility requirements, and the input methods from
the `project.yaml` `platform` block. If the output file already exists, the
skill enters retrofit mode and fills only Empty or Placeholder sections.
Otherwise it asks "May I create the skeleton file at [path]?" and writes the
mode's skeleton.
Each section then runs Context → Questions → Options → Decision → Draft →
Approval → Write: "Does this capture the [section name] correctly?", then "May I
write the [section name] section to `[filepath]`?", then an Edit replacing the
placeholder. Of the per-mode guidance files, only the active mode's is loaded,
and a template guide is read one section at a time. After a
cross-reference check, the handoff says the spec must pass `/ux-review` and
ends with verdict `COMPLETE`. There are no director gates.
---
## Static Assertions (Structural)
Verified automatically by `/skill-test static` — no fixture needed.
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 keyword: COMPLETE
- [ ] Contains "May I write" language per section
- [ ] Has a next-step handoff (e.g., `/ux-review` to validate the completed spec)
- [ ] Contains verdict keyword: `COMPLETE`
- [ ] Contains "May I write" language per section, and "May I create" for the skeleton
- [ ] Has a next-step handoff (`/ux-review` to validate the completed spec)
- [ ] Documents the four modes and their output paths, including `design/accessibility-requirements.md` for `accessibility`
---
## Director Gate Checks
None. `/ux-design` has no inline director gates. `/ux-review` is the separate
review skill invoked after this skill completes.
None. `/ux-design` resolves only `automation`, `workflow` and `docs.density`
(not `review_mode`) and spawns no director gate. `/ux-review` is the separate
validation step. Specialists (`art-director`, `ui-programmer`, `game-designer`,
`narrative-director`) may be consulted for sub-topics; their output is presented
to the user, and this session owns every file write.
---
## Test Cases
### Case 1: Happy Path — New HUD spec, all sections authored and written
### Case 1: Happy Path — New HUD design
**Fixture:**
- No existing HUD UX spec in `design/ux/`
- Engine and rendering preferences configured
- No `design/ux/hud.md`
- `design/gdd/combat.md` and `design/gdd/stamina.md` have `## UI Requirements` sections; `design/gdd/save-system.md` has none
- `project.yaml` has a `platform` block (`targets: [PC]`, `gamepad_support: Full`)
- `design/gdd/game-concept.md` and `design/player-journey.md` exist
**Input:** `/ux-design hud`
**Expected behavior:**
1. Skill creates a skeleton file `design/ux/hud.md` with all section headers
2. Skill discusses and drafts each section: User Flows, Interaction States
(normal/hover/focus/disabled), Wireframe Description, Accessibility Notes
3. After each section is drafted and user confirms, skill asks "May I write
section [N] to `design/ux/hud.md`?"
4. Each section is written in sequence after approval
5. After all sections are written, verdict is COMPLETE
6. Skill suggests running `/ux-review` as the next step
1. Mode is HUD design; output file `design/ux/hud.md`
2. UI Requirements are collected with one Grep across `design/gdd/*.md`; the skill counts the three system GDDs — `game-concept.md` sits in `design/gdd/` but is not one — lists `save-system.md` as unmatched, and confirms with the user it is headless before excluding it
3. Input methods are derived from the `platform` block (keyboard/mouse and gamepad) — the user is not asked
4. The context summary is shown, then "Anything else I should read before we start, or shall we proceed?"
5. No existing file, so: "May I create the skeleton file at `design/ux/hud.md`?" — on yes, writes the HUD skeleton and updates `production/session-state/active.md`. The skeleton carries every section `/ux-review`'s HUD checklist requires, so the finished spec can pass that review
6. Phase 4 reads `.claude/skills/ux-design/references/sections-hud.md` and never the other two per-mode files (`sections-ux-spec.md`, `sections-patterns.md`); if a section needs depth, the HUD design guide is read one section at a time, never whole
7. Each section: draft → "Does this capture the [section name] correctly?" → "May I write the [section name] section to `design/ux/hud.md`?" → Edit replacing that section's placeholder
8. Phase 5 presents the Cross-Reference Check results
9. Phase 6 states the spec should be validated with `/ux-review` before implementation, then asks with four options (run `/ux-review` now / design another screen / update the pattern library / stop); verdict `COMPLETE`
**Assertions:**
- [ ] Skeleton file is created first (with empty section bodies)
- [ ] "May I write section [N]" is asked per section (not once at the end)
- [ ] All required sections are present: User Flows, Interaction States,
Wireframe Description, Accessibility Notes
- [ ] Handoff to `/ux-review` is at the end
- [ ] Verdict is COMPLETE
- [ ] A GDD without a UI Requirements section is listed and confirmed with the user, not silently excluded
- [ ] `game-concept.md` is not counted as a system GDD, so it is not listed as unmatched
- [ ] Input methods come from the `project.yaml` `platform` block, without asking the user
- [ ] The skeleton is written only after the "May I create the skeleton file at `design/ux/hud.md`?" approval
- [ ] The HUD skeleton includes the sections `/ux-review` Phase 3B checks for: HUD Philosophy, Information Architecture, Layout Zones, HUD element specifications, HUD States by Gameplay Context, Information Hierarchy, Visual Budget, Feedback & Notification Systems, Platform Adaptation, Tuning Knobs, Acceptance Criteria
- [ ] Of the three per-mode guidance files only `sections-hud.md` is loaded, and no guide is read whole
- [ ] Each section is approved and then gets its own "May I write the [section name] section…" ask before it is written
- [ ] The handoff names `/ux-review` as required before implementation, and the verdict is `COMPLETE`
---
### Case 2: Existing UX Spec — Retrofit: user picks section to update
### Case 2: Existing Document — Retrofit of incomplete sections only
**Fixture:**
- `design/ux/hud.md` already exists with all sections populated
- User wants to update only the Accessibility Notes section
- Scenario (a): `design/ux/main-menu.md` exists, built from the UX spec skeleton; Purpose & Player Need, Player Context on Arrival, Navigation Position and Entry & Exit Points have real content; every other section is `[To be designed]`
- Scenario (b): `design/accessibility-requirements.md` exists, built from the accessibility skeleton; Accessibility Tier Definition commits the Standard tier; every other section is `[To be designed]`
**Input:** `/ux-design hud`
**Input:** (a) `/ux-design main-menu` (b) `/ux-design accessibility`
**Expected behavior:**
1. Skill reads existing `design/ux/hud.md` and detects all sections are populated
2. Skill reports: "UX spec already exists for HUD — offering to retrofit"
3. Skill lists all sections and asks which to update
4. User selects Accessibility Notes
5. Skill drafts updated accessibility content and asks "May I write section
Accessibility Notes to `design/ux/hud.md`?"
6. Only that section is updated; other sections are preserved; verdict is COMPLETE
1. Before any skeleton step, the skill Globs the output path — in (b) `design/accessibility-requirements.md`, not a path under `design/ux/` — and finds the file
2. It reads the file, classifies each section as Complete / Empty / Placeholder, and shows the status table, ending "I'll work on the [N] incomplete sections only — existing content will not be overwritten."
3. Skeleton creation is skipped
4. Phase 4 authors only the Empty/Placeholder sections, filling each placeholder in place with Edit after its "May I write" approval
5. (a) The four complete sections are not changed; (b) the committed tier is not changed
**Assertions:**
- [ ] Existing spec is detected and retrofit is offered
- [ ] User selects which section(s) to update
- [ ] Only the selected section is updated — other sections unchanged
- [ ] "May I write" is asked for the updated section
- [ ] Verdict is COMPLETE
- [ ] The existing file is detected and no skeleton is written
- [ ] The status table and the "incomplete sections only" message are shown before authoring
- [ ] Only Empty or Placeholder sections are authored; complete sections are not overwritten
- [ ] Each filled section is written with Edit after its own "May I write" approval
- [ ] (a) The status table rows use the section names of the UX spec skeleton (e.g., `Purpose & Player Need`, `Layout Specification`, `States & Variants`, `Input Method Completeness Checklist`)
- [ ] (b) The status table rows use the accessibility skeleton's section names (e.g., `Accessibility Tier Definition`, `Visual Accessibility`, `Motor Accessibility`), and the file stays at `design/accessibility-requirements.md`
---
### Case 3: Dependency Gap — Spec references a system with no design doc
### Case 3: Missing Context — No game concept and no player journey
**Fixture:**
- User is authoring a UX spec for the inventory screen
- `design/gdd/inventory.md` does not exist
- No `design/gdd/game-concept.md` and no `design/game-brief.md`
- No `design/player-journey.md`
- No `design/ux/inventory.md`
**Input:** `/ux-design inventory-screen`
**Input:** `/ux-design inventory`
**Expected behavior:**
1. Skill begins authoring the inventory screen UX spec
2. During the User Flows section, skill attempts to reference inventory system rules
3. Skill detects: "No GDD found for inventory system — UX spec has a DEPENDENCY GAP"
4. The dependency gap is flagged in the spec (noted inline: "DEPENDENCY GAP: inventory GDD")
5. Skill continues authoring with placeholder notes for the missing rules
6. Verdict is COMPLETE with advisory note about the dependency gap
1. The skill warns: "No game concept found. Run `/brainstorm` first to establish the game's foundation before designing UX." and continues only if the user asks
2. It notes the missing journey: "No player journey map found at `design/player-journey.md`. Designing without it means we'll be making assumptions about player context…"
3. The context summary shows "Journey phase(s): unknown — no journey map"
4. The spec's Open Questions section records: "Player journey map not yet created. Author it from the template at `.claude/docs/templates/player-journey.md`…"
5. The skill never tells the user to run `/ux-design` Phase 2b to create the journey map
**Assertions:**
- [ ] DEPENDENCY GAP label appears in the spec for the missing system doc
- [ ] Skill does NOT block on the missing GDD — it continues with placeholders
- [ ] Dependency gap is also noted in the skill output (not just in the file)
- [ ] Handoff suggests both `/ux-review` and writing the missing GDD
- [ ] The missing concept produces the `/brainstorm` warning, and the skill proceeds only on the user's say-so
- [ ] The missing player journey is noted in the conversation and recorded in Open Questions with the template path
- [ ] The remediation points at the template, never back at `/ux-design`
- [ ] The context summary marks the journey phase as unknown
---
### Case 4: No Argument Provided — Usage error
### Case 4: No Argument Provided — Ask instead of failing
**Fixture:**
- No argument provided with the skill invocation
- No argument
- Neither `design/ux/main-menu.md` nor `design/accessibility-requirements.md` exists, so both scenarios author fresh files
- Scenario (a): the user types "Main Menu"
- Scenario (b): the user picks "The project-wide accessibility requirements"
**Input:** `/ux-design`
**Expected behavior:**
1. Skill detects no screen name or argument provided
2. Skill outputs a usage error: "Screen name required. Usage: `/ux-design [screen-name]`"
3. Skill provides examples: `/ux-design hud`, `/ux-design main-menu`, `/ux-design inventory`
4. No file is created; no "May I write" is asked
1. The skill does not fail; it asks "What are we designing today?" with: "A specific screen or flow (I'll name it)", "The game HUD", "The interaction pattern library", "The project-wide accessibility requirements", "I'm not sure — help me figure it out"
2. (a) The name is normalized to kebab-case; the output file is `design/ux/main-menu.md`
3. (b) The output file is `design/accessibility-requirements.md`, and the skeleton ask names that path, not a path under `design/ux/`
4. (b) The Accessibility Tier Definition section is authored first
5. No file is created before the skeleton approval
**Assertions:**
- [ ] Usage error is clearly stated
- [ ] Example invocations are provided
- [ ] No file is created
- [ ] Skill does not attempt to proceed without an argument
- [ ] No usage error; the "What are we designing today?" question is asked with the five options
- [ ] (a) A typed screen name becomes a kebab-case filename under `design/ux/`
- [ ] (b) Accessibility mode writes to `design/accessibility-requirements.md`
- [ ] (b) The tier definition is authored before the other accessibility sections
- [ ] No file is written before the skeleton approval
---
### Case 5: Director Gate Check — No gate; ux-review is the separate review skill
### Case 5: No Director Gate — `/ux-review` is the separate review
**Fixture:**
- New screen spec with argument provided
- `project.yaml` has `modes.review_mode: full` and a `platform` block (`targets: [PC, Console]`, `gamepad_support: Full`)
- No `design/ux/settings-menu.md`
**Input:** `/ux-design settings-menu`
**Expected behavior:**
1. Skill authors all sections of the settings menu UX spec
2. No director agents are spawned
3. No gate IDs appear in output during authoring
1. The skill authors the screen spec as usual; the review mode is not resolved and nothing branches on it
2. The UX spec skeleton's header carries `> **Platform Target**:` filled from Phase 2h — PC and Console, keyboard/mouse and gamepad — the line `/ux-review` checks for
3. No director gate agent is spawned, and no gate ID or skip note appears
4. If a specialist is consulted (e.g., `ui-programmer` on feasibility), its output is shown to the user, and the session — not the agent — writes the file
5. The run ends with the `/ux-review` statement and verdict `COMPLETE`
**Assertions:**
- [ ] No director gate is invoked during ux-design
- [ ] No gate skip messages appear
- [ ] Verdict is COMPLETE without any gate check
- [ ] The skeleton header's Platform Target line names the targets and input methods from the `platform` block
- [ ] No director gate is invoked and no gate skip messages appear
- [ ] `modes.review_mode: full` does not change the skill's behavior
- [ ] Specialist output is presented to the user; agents never write files
- [ ] The verdict is `COMPLETE`, with `/ux-review` named as the validation step
---
## Protocol Compliance
- [ ] Creates skeleton file with all section headers before discussing content
- [ ] Discusses and drafts one section at a time
- [ ] Asks "May I write section [N]" after each section is approved
- [ ] Detects existing spec and offers retrofit path
- [ ] Ends with handoff to `/ux-review`
- [ ] Verdict is COMPLETE when all sections are written
- [ ] Once the mode is known — with no argument, the mode question comes first (Case 4) — reads context before asking the user anything else
- [ ] Checks for an existing output file before creating a skeleton; retrofit fills only Empty or Placeholder sections
- [ ] The skeleton is created only after "May I create the skeleton file at [path]?"
- [ ] Sections are drafted one at a time; each is approved, then "May I write the [section name] section to `[filepath]`?" is asked before the write
- [ ] Loads the per-mode guidance file for the active mode and never the other two; a template guide is read one section at a time, never whole
- [ ] Ends with the `/ux-review` handoff and verdict `COMPLETE`
---
## Coverage Notes
- Interaction state enumeration (normal/hover/focus/disabled/error) is a core
requirement of each spec; the `/ux-review` skill checks for completeness.
- Wireframe descriptions are text-only (no images); image references may be
added manually by a designer after the fact.
- Responsive layout concerns (different screen sizes) are noted as optional
content and not assertion-tested here.
- Pattern-library mode (`patterns`) is not fixture-tested.
- The input-methods question when neither `project.yaml` nor
`technical-preferences.md` configures the platform is not tested.
- The Phase 5 prompt for a pattern not yet in the pattern library is not
individually tested.
- `guided` and `autonomous` automation modes, `docs.density` depth, and
recovery after an interrupted session are not tested.
CCGS Skill Testing Framework/skills/authoring/ux-review.md
+134 -114
View File
@@ -2,175 +2,195 @@
## Skill Summary
`/ux-review` validates an existing UX spec or HUD design document against
accessibility and interaction standards. It checks for required sections
(User Flows, Interaction States, Wireframe Description, Accessibility Notes),
completeness of interaction state definitions (hover, focus, disabled, error),
accessibility compliance (keyboard navigation, color contrast notes, screen
reader considerations), and consistency with the art bible or design system
if those documents exist.
`/ux-review` validates UX documents before they enter the implementation
pipeline. It takes a file path, `hud` (`design/ux/hud.md`), `patterns`
(`design/ux/interaction-patterns.md`), `all` (every file in `design/ux/`, with a
summary table first), or no argument (it asks which spec).
The skill is read-only — it produces no file writes. Verdicts: APPROVED
(all checks pass), NEEDS REVISION (fixable issues found), or MAJOR REVISION
NEEDED (structural or accessibility failures). No director gates apply —
`/ux-review` IS the review gate for UX specs.
Phase 2 loads cross-reference context: input methods from the `project.yaml`
`platform` block (the authority for input coverage checks), the accessibility
tier committed in `design/accessibility-requirements.md`, the pattern library,
the UI Requirements of GDDs named in the spec header, and the player journey.
It then runs the checklist for the document type — Phase 3A for a UX spec
(15 completeness items plus quality checks), 3B for a HUD design, 3C for the
pattern library — and outputs a structured report. The type comes from the
file's `> **Template**:` header line (which `/ux-design` writes); a file without
one is classified by name (`hud.md` → 3B, `interaction-patterns.md` → 3C, else
3A), and the report says which checklist was assumed.
Verdicts: **APPROVED**, **NOT ASSESSED** (the spec could not be read, or a
dimension had no criterion — e.g., no committed accessibility tier), **NEEDS
REVISION**, **MAJOR REVISION NEEDED**. The skill is read-only
(`allowed-tools: Read, Glob, Grep`, plus the one `resolve_config` call that
resolves `workflow` for the Pattern Library rule), spawns no agents, and its
verdict is advisory. Handoffs: APPROVED → `/team-ui` Phase 2; NEEDS REVISION → fix and
re-run `/ux-review`; MAJOR REVISION NEEDED → back to `/ux-design`.
---
## Static Assertions (Structural)
Verified automatically by `/skill-test static` — no fixture needed.
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, NEEDS REVISION, MAJOR REVISION NEEDED
- [ ] Does NOT contain "May I write" language (skill is read-only)
- [ ] Has a next-step handoff (e.g., back to `/ux-design` for revision, or proceed to implementation)
- [ ] Contains verdict keywords: `APPROVED`, `NOT ASSESSED`, `NEEDS REVISION`, `MAJOR REVISION NEEDED`
- [ ] Does NOT contain "May I write" language, and `allowed-tools` has no Write or Edit (skill is read-only)
- [ ] Has a verdict-specific next-step handoff (`/team-ui`, the missing input for NOT ASSESSED, re-run `/ux-review`, `/ux-design`)
---
## Director Gate Checks
None. `/ux-review` is itself the review gate for UX specs. No additional director
gates are invoked within this skill.
None. `/ux-review` is itself the review step for UX specs; it has no `Agent`
tool and invokes no director gate.
---
## Test Cases
### Case 1: Happy Path — Complete UX spec with all required sections, APPROVED
### Case 1: Happy Path — Complete UX spec, APPROVED
**Fixture:**
- `design/ux/hud.md` exists with all required sections populated:
- User Flows: complete player flow diagrams
- Interaction States: normal, hover, focus, disabled, error all defined
- Wireframe Description: layout described
- Accessibility Notes: keyboard nav, contrast ratios, screen reader notes
- `design/ux/inventory.md` follows `.claude/docs/templates/ux-spec.md`: header with Status, Author, Platform Target (PC, Console), Related GDDs (`design/gdd/inventory.md`), Accessibility Tier and `> **Template**: UX Spec`; every section populated, including States & Variants (loading, empty, populated, error), keyboard and d-pad navigation with focus order, an Input Method Completeness Checklist block for keyboard/mouse and for gamepad with every item ticked, and at least 5 testable acceptance criteria
- `design/accessibility-requirements.md` commits the Standard tier
- `design/ux/interaction-patterns.md` exists, and every interactive component in the spec names a pattern from it
- `project.yaml` `platform` block: `targets: [PC, Console]`, `gamepad_support: Full`
- `design/gdd/inventory.md` UI Requirements are all addressed by the spec
**Input:** `/ux-review hud`
**Input:** `/ux-review design/ux/inventory.md`
**Expected behavior:**
1. Skill reads `design/ux/hud.md`
2. Skill checks all 4 required sections — all present and non-empty
3. Skill checks interaction states — all 5 states defined
4. Skill checks accessibility notes — keyboard, contrast, and screen reader covered
5. Skill outputs: checklist of all passed checks
6. Verdict is APPROVED
1. Phase 2 derives input methods (keyboard/mouse, gamepad) from the `platform` block, reads the committed tier, the pattern library if present, and the UI Requirements of `design/gdd/inventory.md`
2. Phase 3A runs the completeness items and quality checks
3. The report names Phase 3A as the checklist (from the Template line) and shows "Completeness: [X/Y sections present]", Quality Issues, "GDD Alignment: ALIGNED", "Accessibility: COMPLIANT" against the Standard tier, and "Pattern Library: CONSISTENT"
4. Verdict: APPROVED — "This spec is ready for handoff to `/team-ui` Phase 2 (Visual Design)."
5. Phase 5 suggests running `/team-ui`
**Assertions:**
- [ ] All 4 required sections are checked
- [ ] All 5 interaction states are verified present
- [ ] Verdict is APPROVED
- [ ] Input method coverage is checked against the `project.yaml` platform block, not only the spec header
- [ ] The UX spec checklist (Phase 3A) is used, including States & Variants, Interaction Map coverage and the Input Method Completeness Checklist item
- [ ] Every review dimension has something to check against — the committed tier, the pattern library, the referenced GDD — so none is NOT ASSESSED
- [ ] Accessibility is checked against the tier committed in `design/accessibility-requirements.md`
- [ ] Verdict is APPROVED with the `/team-ui` handoff
- [ ] No files are written
---
### Case 2: Missing Accessibility Section — NEEDS REVISION
### Case 2: Empty Accessibility Section — NEEDS REVISION
**Fixture:**
- `design/ux/hud.md` exists but the Accessibility Notes section is empty
- All other sections are fully populated
- Same as Case 1, but the spec's Accessibility section is empty
- `design/accessibility-requirements.md` commits the Standard tier
**Input:** `/ux-review hud`
**Input:** `/ux-review design/ux/inventory.md`
**Expected behavior:**
1. Skill reads the file and checks all sections
2. Accessibility Notes section is empty — check fails
3. Skill outputs: "NEEDS REVISION — Accessibility Notes section is empty"
4. Skill lists specific items to add: keyboard navigation, color contrast ratios,
screen reader labels
5. Verdict is NEEDS REVISION
6. Handoff suggests returning to `/ux-design hud` to fill in the section
1. The Accessibility Requirements completeness item fails, and the Standard-tier text-contrast check cannot be met; the focus-order check still passes, because the spec still defines keyboard and d-pad focus order (Case 1's fixture)
2. Each finding is listed as a numbered quality issue with BLOCKING/ADVISORY, "What's wrong", "Where" and "Fix"
3. Verdict: NEEDS REVISION — "Address the [N] blocking issues above, then re-run `/ux-review`."
4. The skill offers to help draft the missing content but does not edit the file; it waits for the user
**Assertions:**
- [ ] NEEDS REVISION verdict is returned (not APPROVED or MAJOR REVISION NEEDED)
- [ ] Specific missing content items are listed
- [ ] Handoff points back to `/ux-design hud` for revision
- [ ] NEEDS REVISION is returned (not APPROVED or MAJOR REVISION NEEDED)
- [ ] Findings name the section and give a specific fix
- [ ] The handoff is to fix the issues and re-run `/ux-review`
- [ ] The skill offers help but does not auto-fix, and no files are written
---
### Case 3: Incomplete States — NEEDS REVISION outranks NOT ASSESSED
**Fixture:**
- `design/ux/settings-menu.md` follows the UX spec template, carries `> **Template**: UX Spec`, and is otherwise complete
- Its States & Variants section documents only the populated state — no loading, empty or error state; the screen fetches its data asynchronously
- `design/ux/interaction-patterns.md` exists and the spec's components name patterns from it
- No `design/accessibility-requirements.md`, so there is no committed tier
**Input:** `/ux-review design/ux/settings-menu.md`
**Expected behavior:**
1. The States & Variants completeness item fails ("at minimum: loading, empty/populated, and error states")
2. The Completeness list marks it, e.g. "States & Variants — MISSING: error state not documented", and names each missing state (loading, empty, error)
3. The report shows "Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent)" and lists it under "Dimensions not assessed"
4. The verdict is NEEDS REVISION: a gap that was found outranks a dimension that could not be checked. It is not NOT ASSESSED, and not MAJOR REVISION NEEDED for this fixable gap
5. The handoff is to fix the gaps and re-run `/ux-review`
**Assertions:**
- [ ] NEEDS REVISION is returned, not NOT ASSESSED — NOT ASSESSED ranks below the revision verdicts
- [ ] The not-assessed Accessibility dimension is still named in the report
- [ ] The missing loading, empty and error states are each named in the output
- [ ] MAJOR REVISION NEEDED is not returned for this fixable gap
- [ ] The handoff is to re-run `/ux-review` after the fix
---
### Case 4: Nothing to Assess Against — NOT ASSESSED
**Fixture:**
- Scenario (a): `design/ux/inventory-screen.md` does not exist
- Scenario (b): `design/ux/inventory.md` is complete (as in Case 1), but `design/accessibility-requirements.md` does not exist; the spec header states "Accessibility Tier: Standard"
**Input:** (a) `/ux-review design/ux/inventory-screen.md` (b) `/ux-review design/ux/inventory.md`
**Expected behavior:**
1. (a) The spec cannot be read: the verdict is NOT ASSESSED, the missing path is named, and no checklist is produced
2. (b) The report shows "Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent)" — never COMPLIANT
3. (b) The header's Standard tier is carried forward and stated as an assumption, not a commitment
4. (b) `/ux-design accessibility` is recommended to establish the tier
5. The verdict is NOT ASSESSED, the dimensions not assessed are named with what would make them checkable, and handoff to `/team-ui` is not recommended
**Assertions:**
- [ ] (a) A missing spec yields NOT ASSESSED naming the path, with no checklist output
- [ ] (b) Accessibility is reported NOT ASSESSED, not COMPLIANT, when no tier is committed
- [ ] (b) `/ux-design accessibility` is recommended
- [ ] The report does not recommend handing off to `/team-ui` on a NOT ASSESSED result
- [ ] No files are written
---
### Case 3: Interaction States Incomplete — NEEDS REVISION
### Case 5: `all` Argument and No Director Gate
**Fixture:**
- `design/ux/settings-menu.md` exists
- Interaction States section only defines: normal and hover
- Missing: focus, disabled, error states
- `design/ux/` contains `hud.md` (written by `/ux-design hud`, header line `> **Template**: HUD Design`), `inventory.md` (written by `/ux-design inventory`, `> **Template**: UX Spec`) and `pause-menu.md` (hand-written from `.claude/docs/templates/ux-spec.md`, with no Template line)
- `project.yaml` has `modes.review_mode: full`
**Input:** `/ux-review settings-menu`
**Input:** `/ux-review all`
**Expected behavior:**
1. Skill reads the file and checks interaction states
2. Only 2 of 5 required states are defined
3. Skill reports: "NEEDS REVISION — Interaction states incomplete: missing focus, disabled, error"
4. Verdict is NEEDS REVISION with specific missing states named
1. The skill finds every file in `design/ux/` and outputs a summary table first (file | verdict | primary issue), then the full report for each
2. `hud.md` is checked with the HUD checklist (Phase 3B) and `inventory.md` with the UX spec checklist (Phase 3A), each from its Template line
3. `pause-menu.md` has no Template line and is not `hud.md` or `interaction-patterns.md`, so it gets Phase 3A, and its report says the checklist was assumed from the file name
4. No agent is spawned and no gate ID or gate skip message appears; the review mode has no effect
5. Each verdict is one of APPROVED / NOT ASSESSED / NEEDS REVISION / MAJOR REVISION NEEDED
**Assertions:**
- [ ] NEEDS REVISION verdict returned
- [ ] All 3 missing states are named explicitly in the output
- [ ] Skill does not return MAJOR REVISION NEEDED for a fixable gap
- [ ] Handoff suggests returning to `/ux-design settings-menu`
---
### Case 4: File Not Found — Error with remediation
**Fixture:**
- `design/ux/inventory-screen.md` does not exist
**Input:** `/ux-review inventory-screen`
**Expected behavior:**
1. Skill attempts to read `design/ux/inventory-screen.md` — file not found
2. Skill outputs: "UX spec not found: design/ux/inventory-screen.md"
3. Skill suggests running `/ux-design inventory-screen` to create the spec first
4. No review is performed; no verdict is issued
**Assertions:**
- [ ] Error message names the missing file with full path
- [ ] `/ux-design inventory-screen` is suggested as the remediation
- [ ] No review checklist is produced
- [ ] No verdict is issued (error state, not APPROVED/NEEDS REVISION)
---
### Case 5: Director Gate Check — No gate; ux-review is itself the review
**Fixture:**
- Valid UX spec file
**Input:** `/ux-review hud`
**Expected behavior:**
1. Skill performs the review and issues a verdict
2. No additional director agents are spawned
3. No gate IDs appear in output
**Assertions:**
- [ ] No director gate is invoked
- [ ] No gate skip messages appear
- [ ] Verdict is APPROVED, NEEDS REVISION, or MAJOR REVISION NEEDED — no gate verdict
- [ ] A summary table (file | verdict | primary issue) comes before the per-file detail
- [ ] Each document's checklist comes from its Template line (HUD vs UX spec)
- [ ] A file without a Template line is classified by name, and the report says which checklist was assumed
- [ ] No director gate is invoked and no gate skip messages appear
- [ ] Every verdict comes from the skill's four-verdict set
---
## Protocol Compliance
- [ ] Checks all 4 required sections (User Flows, Interaction States, Wireframe,
Accessibility Notes)
- [ ] Checks all 5 interaction states (normal, hover, focus, disabled, error)
- [ ] Checks accessibility coverage (keyboard nav, contrast, screen reader)
- [ ] Does not write any files
- [ ] Issues specific, actionable feedback when verdict is not APPROVED
- [ ] Ends with next-step handoff to `/ux-design` for revision or implementation
- [ ] Loads cross-reference context (platform config, accessibility tier, pattern library, referenced GDDs, player journey) before validating
- [ ] Uses the checklist that matches the document type (UX spec, HUD, pattern library) — from the Template line, or by file name with the assumption stated
- [ ] Checks accessibility against the committed tier, and reports NOT ASSESSED — never COMPLIANT — when no tier is committed
- [ ] Ranks NOT ASSESSED above APPROVED and below NEEDS REVISION and MAJOR REVISION NEEDED
- [ ] Does not write or edit any files
- [ ] Gives specific findings (What's wrong / Where / Fix, BLOCKING or ADVISORY) for NEEDS REVISION and MAJOR REVISION NEEDED; for NOT ASSESSED, names each dimension not assessed and the input that would make it checkable
- [ ] Ends with the verdict-specific handoff: `/team-ui` (APPROVED), the missing input per dimension and no `/team-ui` handoff (NOT ASSESSED), re-run `/ux-review` (NEEDS REVISION), `/ux-design` (MAJOR REVISION NEEDED)
---
## Coverage Notes
- MAJOR REVISION NEEDED is triggered when structural sections are entirely
absent (not just empty) or when fundamental interaction flows are missing
entirely; not tested with a separate fixture here.
- Art bible / design system consistency check (color palette alignment) is
mentioned as a capability but not separately fixture-tested.
- The case where an existing spec was written for a now-renamed screen is
not tested; the skill would review the file by path regardless of the name.
- MAJOR REVISION NEEDED (fundamental issues with scope, player need or
completeness) is not tested with a dedicated fixture.
- The pattern library checklist (Phase 3C, `patterns` argument) is not
fixture-tested.
- The no-argument prompt ("which spec to validate") is not tested.
- The fallback to `.claude/docs/technical-preferences.md`, and then to the spec
header, when `project.yaml` has no `platform` block is not tested.