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

Update docs, skill counts, and UX/setup-engine skills for v0.4.0

Browse Source 
- Update skill count to 66 and hook count to 12 across README, skills-reference, and badges
- Add QA & Testing section to README and skills-reference (qa-plan, smoke-check, soak-test, etc.)
- Add Input & Platform section to technical-preferences.md (populated by /setup-engine)
- Document post-compact, notify, and validate-skill-change hooks in hooks-reference
- Expand /setup-engine, /ux-design, /ux-review, /design-system skills with input/platform context
- Restructure workflow-catalog: move UX steps into pre-production phase, improve descriptions
- Expand UPGRADING.md and WORKFLOW-GUIDE.md with v0.4.0 guidance
- Add skill-flow-diagrams examples and CODEOWNERS

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-03-25 20:31:11 +11:00
parent 763ad1f0d1
commit 04ed5d5c36
15 changed files with 509 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.claude/docs/hooks-reference.md
View File

@@ -10,9 +10,12 @@ Hooks are configured in `.claude/settings.json` and fire automatically:
| `session-start.sh` | SessionStart | Session begins | Loads sprint context, milestone, git activity; detects and previews active session state file for recovery |
| `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect |
| `pre-compact.sh` | PreCompact | Context compression | Dumps session state (active.md, modified files, WIP design docs) into conversation before compaction so it survives summarization |
| `post-compact.sh` | PostCompact | After compaction | Reminds Claude to restore session state from `active.md` checkpoint |
| `notify.sh` | Notification | Notification event | Shows Windows toast notification via PowerShell |
| `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log |
| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail start — logs subagent invocation with timestamp |
| `log-agent-stop.sh` | SubagentStop | Agent stops | Audit trail stop — completes subagent record |
| `validate-skill-change.sh` | PostToolUse (Write/Edit) | Skill file changes | Advises running `/skill-test` after any `.claude/skills/` file is written or edited |
Hook reference documentation: `.claude/docs/hooks-reference/`
Hook input schema documentation: `.claude/docs/hooks-reference/hook-input-schemas.md`

6
.claude/docs/quick-start.md
View File

@@ -253,8 +253,8 @@ CLAUDE.md -- Master config (read this first, ~60 lines)
.claude/
settings.json -- Claude Code hooks and project settings
agents/ -- 48 agent definitions (YAML frontmatter)
skills/ -- 52 slash command definitions (YAML frontmatter)
hooks/ -- 9 hook scripts (.sh) wired by settings.json
skills/ -- 66 slash command definitions (YAML frontmatter)
hooks/ -- 12 hook scripts (.sh) wired by settings.json
rules/ -- 11 path-specific rule files
docs/
quick-start.md -- This file
@@ -266,5 +266,5 @@ CLAUDE.md -- Master config (read this first, ~60 lines)
workflow-catalog.yaml -- 7-phase pipeline definition (read by /help)
setup-requirements.md -- System prerequisites (Git Bash, jq, Python)
settings-local-template.md -- Personal settings.local.json guide
templates/ -- 36 document templates
templates/ -- 35 document templates
```

19
.claude/docs/skills-reference.md
View File

@@ -1,6 +1,6 @@
# Available Skills (Slash Commands)
52 slash commands organized by phase. Type `/` in Claude Code to access any of them.
66 slash commands organized by phase. Type `/` in Claude Code to access any of them.
## Onboarding & Navigation
@@ -66,6 +66,20 @@
| `/tech-debt` | Scan, track, prioritize, and report on technical debt |
| `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/FAIL) |
## QA & Testing
| Command | Purpose |
|---------|---------|
| `/qa-plan` | Generate a QA test plan for a sprint or feature |
| `/smoke-check` | Run critical path smoke test gate before QA hand-off |
| `/soak-test` | Generate a soak test protocol for extended play sessions |
| `/regression-suite` | Map test coverage to GDD critical paths, identify fixed bugs without regression tests |
| `/test-setup` | Scaffold the test framework and CI/CD pipeline for the project's engine |
| `/test-helpers` | Generate engine-specific test helper libraries for the test suite |
| `/test-evidence-review` | Quality review of test files and manual evidence documents |
| `/test-flakiness` | Detect non-deterministic (flaky) tests from CI run logs |
| `/skill-test` | Validate skill files for structural compliance and behavioral correctness |
## Production
| Command | Purpose |
@@ -73,6 +87,7 @@
| `/milestone-review` | Review milestone progress and generate status report |
| `/retrospective` | Run a structured sprint or milestone retrospective |
| `/bug-report` | Create a structured bug report |
| `/bug-triage` | Read all open bugs, re-evaluate priority vs. severity, assign owner and label |
| `/reverse-document` | Generate design or architecture docs from existing implementation |
| `/playtest-report` | Generate a structured playtest report or analyze existing playtest notes |
@@ -107,3 +122,5 @@ Coordinate multiple agents on a single feature area:
| `/team-polish` | performance-analyst + technical-artist + sound-designer + qa-tester |
| `/team-audio` | audio-director + sound-designer + technical-artist + gameplay-programmer |
| `/team-level` | level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester |
| `/team-live-ops` | live-ops-designer + economy-designer + community-manager + analytics-engineer |
| `/team-qa` | qa-lead + qa-tester + gameplay-programmer + producer |

12
.claude/docs/technical-preferences.md
View File

@@ -10,6 +10,18 @@
- **Rendering**: [TO BE CONFIGURED]
- **Physics**: [TO BE CONFIGURED]
## Input & Platform
<!-- Written by /setup-engine. Read by /ux-design, /ux-review, /test-setup, /team-ui, and /dev-story -->
<!-- to scope interaction specs, test helpers, and implementation to the correct input methods. -->
- **Target Platforms**: [TO BE CONFIGURED — e.g., PC, Console, Mobile, Web]
- **Input Methods**: [TO BE CONFIGURED — e.g., Keyboard/Mouse, Gamepad, Touch, Mixed]
- **Primary Input**: [TO BE CONFIGURED — the dominant input for this game]
- **Gamepad Support**: [TO BE CONFIGURED — Full / Partial / None]
- **Touch Support**: [TO BE CONFIGURED — Full / Partial / None]
- **Platform Notes**: [TO BE CONFIGURED — any platform-specific UX constraints]
## Naming Conventions
- **Classes**: [TO BE CONFIGURED]

18
.claude/docs/workflow-catalog.yaml
View File

@@ -86,7 +86,7 @@ phases:
technical-setup:
label: "Technical Setup"
description: "Architecture decisions, UX foundations, engine validation"
description: "Architecture decisions, accessibility foundations, engine validation"
next_phase: pre-production
steps:
- id: create-architecture
@@ -128,8 +128,13 @@ phases:
required: true
artifact:
glob: "design/accessibility-requirements.md"
description: "Commit accessibility tier (Basic/Standard/Comprehensive/Exemplary) and feature matrix"
description: "Commit accessibility tier (Basic/Standard/Comprehensive/Exemplary) and feature matrix. UX specs (Phase 4) reference this tier."
pre-production:
label: "Pre-Production"
description: "UX specs, prototype the core mechanic, define stories, validate fun"
next_phase: production
steps:
- id: ux-design
name: "UX Specs (key screens)"
command: /ux-design
@@ -138,19 +143,14 @@ phases:
artifact:
glob: "design/ux/*.md"
min_count: 1
description: "Author UX specs for main menu, core gameplay HUD, and pause screen"
description: "Author UX specs for main menu, core gameplay HUD, and interaction patterns. Reads input method and platform from technical-preferences.md."
- id: ux-review
name: "UX Review"
command: /ux-review
required: true
description: "Validate all key screen UX specs for accessibility and GDD alignment"
description: "Validate all key screen UX specs for GDD alignment and accessibility tier compliance. Run before creating epics."
pre-production:
label: "Pre-Production"
description: "Prototype the core mechanic, define stories, validate fun"
next_phase: production
steps:
- id: prototype
name: "Prototype"
command: /prototype

10
.claude/skills/design-system/SKILL.md
View File

@@ -457,6 +457,16 @@ For **Visual/Audio**: Coordinate with `art-director` and `audio-director` if det
is needed. Often a brief note suffices at the GDD stage.
For **UI Requirements**: Coordinate with `ux-designer` for complex UI systems.
After writing this section, check whether it contains real content (not just
`[To be designed]` or a note that this system has no UI). If it does have real
UI requirements, output this flag immediately:
> **📌 UX Flag — [System Name]**: This system has UI requirements. In Phase 4
> (Pre-Production), run `/ux-design` to create a UX spec for each screen or
> HUD element this system contributes to **before** writing epics. Stories that
> reference UI should cite `design/ux/[screen].md`, not the GDD directly.
>
> Note this in the systems index for this system if you update it.
For **Open Questions**: Capture anything that came up during design that wasn't
fully resolved. Each question should have an owner and target resolution date.

40
.claude/skills/setup-engine/SKILL.md
View File

@@ -35,9 +35,10 @@ If no engine is specified, run an interactive engine selection process:
### If the user wants to pick without a concept, ask:
1. **What kind of game?** (2D, 3D, or both?)
2. **What platforms?** (PC, mobile, console, web?)
3. **Team size and experience?** (solo beginner, solo experienced, small team?)
4. **Any strong language preferences?** (GDScript, C#, C++, visual scripting?)
5. **Budget for engine licensing?** (free only, or commercial licenses OK?)
3. **Primary input method?** (keyboard/mouse, gamepad, touch, or mixed?)
4. **Team size and experience?** (solo beginner, solo experienced, small team?)
5. **Any strong language preferences?** (GDScript, C#, C++, visual scripting?)
6. **Budget for engine licensing?** (free only, or commercial licenses OK?)
### Produce a recommendation
@@ -135,6 +136,39 @@ engine-appropriate defaults. Read the existing template first, then fill in:
- Booleans: `b` prefix (e.g., `bIsAlive`)
- Files: Match class without prefix (e.g., `PlayerController.h`)
### Input & Platform Section
Populate `## Input & Platform` using the answers gathered in Section 2 (or extracted
from the game concept). Derive the values using this mapping:
| Platform target | Gamepad Support | Touch Support |
|-----------------|-----------------|---------------|
| PC only | Partial (recommended) | None |
| Console | Full | None |
| Mobile | None | Full |
| PC + Console | Full | None |
| PC + Mobile | Partial | Full |
| Web | Partial | Partial |
For **Primary Input**, use the dominant input for the game genre:
- Action/RPG/platformer targeting console → Gamepad
- Strategy/point-and-click/RTS → Keyboard/Mouse
- Mobile game → Touch
- Cross-platform → ask the user
Present the derived values and ask the user to confirm or adjust before writing.
Example filled section:
```markdown
## Input & Platform
- **Target Platforms**: PC, Console
- **Input Methods**: Keyboard/Mouse, Gamepad
- **Primary Input**: Gamepad
- **Gamepad Support**: Full
- **Touch Support**: None
- **Platform Notes**: All UI must support d-pad navigation. No hover-only interactions.
```
### Remaining Sections
- Performance Budgets: Leave as `[TO BE CONFIGURED]` with a suggestion:
> "Typical targets: 60fps / 16.6ms frame budget. Want to set these now?"

29
.claude/skills/ux-design/SKILL.md
View File

@@ -90,7 +90,28 @@ already made.
Check for `design/accessibility-requirements.md`. If found, read it. The spec
must satisfy the accessibility tier committed to there.
### 2h: Present Context Summary
### 2h: Input Method (from Project Config)
Read `.claude/docs/technical-preferences.md` and extract the `## Input & Platform`
section. Store these values for use throughout the skill — they drive the
Interaction Map and inform accessibility requirements:
- **Input Methods** — e.g., Keyboard/Mouse, Gamepad, Touch, Mixed
- **Primary Input** — the dominant input for this game
- **Gamepad Support** — Full / Partial / None
- **Touch Support** — Full / Partial / None
- **Target Platforms** — for safe zone and aspect ratio decisions
If the section is unconfigured (`[TO BE CONFIGURED]`), ask once:
> "Input methods aren't configured yet. What does this game target?"
> Options: "Keyboard/Mouse only", "Gamepad only", "Both (PC + Console)", "Touch (mobile)", "All of the above"
>
> (Run `/setup-engine` to save this permanently so you won't be asked again.)
Store the answer for the rest of this session. Do **not** ask again per section
or per screen.
### 2i: Present Context Summary
Before any design work, present a brief summary to the user:
@@ -101,6 +122,7 @@ Before any design work, present a brief summary to the user:
> - Related screens already specced: [list, or "none yet"]
> - Known patterns available: [count, or "no pattern library yet"]
> - Accessibility tier: [from requirements doc, or "not yet defined"]
> - Input methods: [from technical-preferences.md, or "asked above"]
Then ask: "Anything else I should read before we start, or shall we proceed?"
@@ -427,8 +449,9 @@ For each interactive component identified in the Layout Specification, define:
- The immediate feedback (visual, audio, haptic)
- The outcome (navigation target, state change, data write)
Ask up front: "Which input methods does this game target? I'll tailor the
interaction map to those." Reference game concept for platform targets.
Use the input methods loaded from `technical-preferences.md` in Phase 2h — do
not ask the user again. State them upfront: "Mapping interactions for:
[Input Methods from tech-prefs]. Covering [Gamepad Support] gamepad support."
Work through components one at a time rather than asking for all at once.
For navigation actions (going to another screen), verify the target matches

12
.claude/skills/ux-review/SKILL.md
View File

@@ -47,12 +47,16 @@ full detail for each.
Before validating any spec, load:
1. The accessibility tier committed to in `design/accessibility-requirements.md`
1. **Input & Platform config**: Read `.claude/docs/technical-preferences.md` and
extract `## Input & Platform`. This is the authoritative source for which input
methods the game supports — use it to drive the Input Method Coverage checks in
Phase 3A, not the spec's own header. If unconfigured, fall back to the spec header.
2. The accessibility tier committed to in `design/accessibility-requirements.md`
(if it exists)
2. The interaction pattern library at `design/ux/interaction-patterns.md` (if
3. The interaction pattern library at `design/ux/interaction-patterns.md` (if
it exists)
3. The GDDs referenced in the spec's header (read their UI Requirements sections)
4. The player journey map at `design/player-journey.md` (if it exists) for
4. The GDDs referenced in the spec's header (read their UI Requirements sections)
5. The player journey map at `design/player-journey.md` (if it exists) for
context-arrival validation
---

16
.github/CODEOWNERS vendored Normal file
View File

@@ -0,0 +1,16 @@
# CODEOWNERS — auto-assigns reviewers to PRs by path
# Format: <pattern> <@github-username or @org/team>
# Last match wins. Docs: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
# Default owner for everything
* @Donchitos
# Core configuration — owner review required
CLAUDE.md @Donchitos
.claude/ @Donchitos
settings.json @Donchitos
# Skills and agents — high-impact, review carefully
.claude/skills/ @Donchitos
.claude/agents/ @Donchitos
.claude/hooks/ @Donchitos

5
.gitignore vendored
View File

@@ -11,14 +11,13 @@ Desktop.ini
# === Claude Code Local ===
.claude/settings.local.json
.claude/docs/UPGRADE-PLAN.md
CLAUDE.local.md
production/session-logs/
production/session-state/*.md
# === Internal Planning (not for public) ===
docs/IMPROVEMENTS-PROPOSAL.md
docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md
expansions/
# === Build Output ===
build/

32
README.md
View File

@@ -3,15 +3,15 @@
<p align="center">
Turn a single Claude Code session into a full game development studio.
<br />
48 agents. 52 workflows. One coordinated AI team.
48 agents. 66 workflows. One coordinated AI team.
</p>
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
<a href=".claude/agents"><img src="https://img.shields.io/badge/agents-48-blueviolet" alt="48 Agents"></a>
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-52-green" alt="52 Skills"></a>
<a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-9-orange" alt="9 Hooks"></a>
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-66-green" alt="66 Skills"></a>
<a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-12-orange" alt="12 Hooks"></a>
<a href=".claude/rules"><img src="https://img.shields.io/badge/rules-11-red" alt="11 Rules"></a>
<a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/built%20for-Claude%20Code-f5f5f5?logo=anthropic" alt="Built for Claude Code"></a>
<a href="https://ko-fi.com/donchitos"><img src="https://img.shields.io/badge/Ko--fi-Support%20this%20project-ff5e5b?logo=ko-fi&logoColor=white" alt="Ko-fi"></a>
@@ -51,10 +51,10 @@ The result: you still make every decision, but now you have a team that asks the
| Category | Count | Description |
|----------|-------|-------------|
| **Agents** | 48 | Specialized subagents across design, programming, art, audio, narrative, QA, and production |
| **Skills** | 65 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) |
| **Hooks** | 9 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection |
| **Skills** | 66 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) |
| **Hooks** | 12 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection |
| **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more |
| **Templates** | 36 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more |
| **Templates** | 35 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more |
## Studio Hierarchy
@@ -92,7 +92,7 @@ The template includes agent sets for all three major engines. Use the set that m
## Slash Commands
Type `/` in Claude Code to access all 65 skills:
Type `/` in Claude Code to access all 66 skills:
**Onboarding & Navigation**
`/start` `/help` `/project-stage-detect` `/setup-engine` `/adopt`
@@ -112,8 +112,11 @@ Type `/` in Claude Code to access all 65 skills:
**Reviews & Analysis**
`/design-review` `/code-review` `/balance-check` `/asset-audit` `/content-audit` `/scope-check` `/perf-profile` `/tech-debt` `/gate-check`
**QA & Testing**
`/qa-plan` `/smoke-check` `/soak-test` `/regression-suite` `/test-setup` `/test-helpers` `/test-evidence-review` `/test-flakiness` `/skill-test`
**Production**
`/milestone-review` `/retrospective` `/bug-report` `/reverse-document` `/playtest-report`
`/milestone-review` `/retrospective` `/bug-report` `/bug-triage` `/reverse-document` `/playtest-report`
**Release**
`/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix`
@@ -122,7 +125,7 @@ Type `/` in Claude Code to access all 65 skills:
`/prototype` `/onboard` `/localize`
**Team Orchestration** (coordinate multiple agents on a single feature)
`/team-combat` `/team-narrative` `/team-ui` `/team-release` `/team-polish` `/team-audio` `/team-level`
`/team-combat` `/team-narrative` `/team-ui` `/team-release` `/team-polish` `/team-audio` `/team-level` `/team-live-ops` `/team-qa`
## Getting Started
@@ -168,12 +171,12 @@ CLAUDE.md # Master configuration
.claude/
settings.json # Hooks, permissions, safety rules
agents/ # 48 agent definitions (markdown + YAML frontmatter)
skills/ # 52 slash commands (subdirectory per skill)
hooks/ # 9 hook scripts (bash, cross-platform)
skills/ # 66 slash commands (subdirectory per skill)
hooks/ # 12 hook scripts (bash, cross-platform)
rules/ # 11 path-scoped coding standards
docs/
workflow-catalog.yaml # 7-phase pipeline definition (read by /help)
templates/ # 36 document templates
templates/ # 35 document templates
src/ # Game source code
assets/ # Art, audio, VFX, shaders, data files
design/ # GDDs, narrative docs, level designs
@@ -219,10 +222,13 @@ You stay in control. The agents provide structure and expertise, not autonomy.
| `validate-assets.sh` | File writes in `assets/` | Validates naming conventions and JSON structure |
| `session-start.sh` | Session open | Loads sprint context and recent git activity |
| `detect-gaps.sh` | Session open | Detects fresh projects (suggests `/start`) and missing documentation when code/prototypes exist |
| `pre-compact.sh` | Context compression | Preserves session progress notes |
| `pre-compact.sh` | Before compaction | Preserves session progress notes |
| `post-compact.sh` | After compaction | Reminds Claude to restore session state from `active.md` |
| `notify.sh` | Notification event | Shows Windows toast notification via PowerShell |
| `session-stop.sh` | Session close | Logs accomplishments |
| `log-agent.sh` | Agent spawned | Audit trail start — logs subagent invocation |
| `log-agent-stop.sh` | Agent stops | Audit trail stop — completes subagent record |
| `validate-skill-change.sh` | Skill file written | Advises running `/skill-test` after any `.claude/skills/` change |
**Permission rules** in `settings.json` auto-allow safe operations (git status, test runs) and block dangerous ones (force push, `rm -rf`, reading `.env` files).

76
UPGRADING.md
View File

@@ -80,16 +80,17 @@ Best when: you didn't use git to set up the template (just downloaded a zip).
## v0.3.0 → v0.4.0
**Released:** 2026-03-09
**Released:** 2026-03-21
**Commit range:** `b1cad29..HEAD`
**Key themes:** Full UX/UI pipeline, complete story lifecycle, brownfield adoption, pipeline integrity, 15 new skills
**Key themes:** Full UX/UI pipeline, complete story lifecycle, brownfield adoption, comprehensive QA/testing framework, pipeline integrity, 29 new skills
### What Changed
| Category | Changes |
|----------|---------|
| **New skills (17)** | `/ux-design`, `/ux-review`, `/help`, `/quick-design`, `/review-all-gdds`, `/story-readiness`, `/story-done`, `/sprint-status`, `/adopt`, `/create-architecture`, `/create-control-manifest`, `/create-epics`, `/create-stories`, `/dev-story`, `/propagate-design-change`, `/content-audit`, `/architecture-review` |
| **New hook** | `log-agent-stop.sh` — completes agent audit trail (stop event to match start) |
| **New skills QA (12)** | `/qa-plan`, `/smoke-check`, `/soak-test`, `/regression-suite`, `/test-setup`, `/test-helpers`, `/test-evidence-review`, `/test-flakiness`, `/skill-test`, `/bug-triage`, `/team-live-ops`, `/team-qa` |
| **New hooks (4)** | `log-agent-stop.sh` — agent audit trail stop; `notify.sh` — Windows toast notifications; `post-compact.sh` — session recovery reminder after compaction; `validate-skill-change.sh` — advises `/skill-test` after skill edits |
| **New templates (8)** | `ux-spec.md`, `hud-design.md`, `accessibility-requirements.md`, `interaction-pattern-library.md`, `player-journey.md`, `difficulty-curve.md`, and 2 adoption plan templates |
| **New infrastructure** | `workflow-catalog.yaml` (7-phase pipeline, read by `/help`), `docs/architecture/tr-registry.yaml` (stable TR-IDs), `production/sprint-status.yaml` schema |
| **Skill updates** | `/gate-check` — 3 gates now require UX artifacts; Pre-Production gate requires vertical slice (HARD gate) |
@@ -99,6 +100,8 @@ Best when: you didn't use git to set up the template (just downloaded a zip).
| **Skill updates** | `/team-ui` — full UX pipeline (ux-design → ux-review → team phases) |
| **Agent updates** | 14 specialist agents — `memory: project` added |
| **Agent updates** | `prototyper` — `isolation: worktree` (throwaway work in isolated git branch) |
| **Model routing** | Haiku/Sonnet/Opus tier assignments documented in coordination rules; skills declare their tier in frontmatter |
| **Directory CLAUDE.md** | Scaffolded `design/CLAUDE.md`, `src/CLAUDE.md`, `docs/CLAUDE.md` — path-scoped instructions for each directory |
| **Pipeline integrity** | TR-ID stability, manifest versioning, ADR status gates, TR-ID reference not quote |
| **GDD template** | `## Game Feel` section added (input responsiveness, animation targets, impact moments) |
@@ -125,7 +128,22 @@ Best when: you didn't use git to set up the template (just downloaded a zip).
.claude/skills/propagate-design-change/SKILL.md
.claude/skills/content-audit/SKILL.md
.claude/skills/architecture-review/SKILL.md
.claude/skills/qa-plan/SKILL.md
.claude/skills/smoke-check/SKILL.md
.claude/skills/soak-test/SKILL.md
.claude/skills/regression-suite/SKILL.md
.claude/skills/test-setup/SKILL.md
.claude/skills/test-helpers/SKILL.md
.claude/skills/test-evidence-review/SKILL.md
.claude/skills/test-flakiness/SKILL.md
.claude/skills/skill-test/SKILL.md
.claude/skills/bug-triage/SKILL.md
.claude/skills/team-live-ops/SKILL.md
.claude/skills/team-qa/SKILL.md
.claude/hooks/log-agent-stop.sh
.claude/hooks/notify.sh
.claude/hooks/post-compact.sh
.claude/hooks/validate-skill-change.sh
.claude/docs/workflow-catalog.yaml
.claude/docs/templates/ux-spec.md
.claude/docs/templates/hud-design.md
@@ -133,6 +151,9 @@ Best when: you didn't use git to set up the template (just downloaded a zip).
.claude/docs/templates/interaction-pattern-library.md
.claude/docs/templates/player-journey.md
.claude/docs/templates/difficulty-curve.md
design/CLAUDE.md
src/CLAUDE.md
docs/CLAUDE.md
```
**Existing files to overwrite (no user content):**
@@ -174,7 +195,12 @@ UPGRADING.md
#### `.claude/settings.json`
The new version registers `log-agent-stop.sh` as a hook for the `PostToolUse` (agent stop) event. If you haven't customized `settings.json`, overwriting is safe. Otherwise, add the new hook entry for `SubagentStop` manually.
Four new hooks are registered in this version. If you haven't customized `settings.json`, overwriting is safe. Otherwise, add the following hook entries manually:
- `log-agent-stop.sh` — `SubagentStop` event (agent audit trail stop)
- `notify.sh` — `Notification` event (Windows toast notification)
- `post-compact.sh` — `PostCompact` event (session recovery reminder)
- `validate-skill-change.sh` — `PostToolUse` event filtered to `.claude/skills/` writes
#### Customized agent files
@@ -219,11 +245,49 @@ Also: `/design-system retrofit [path]` and `/architecture-decision retrofit [pat
`/help` reads your current stage and in-progress work, checks which artifacts are complete, and tells you exactly what to do next — one primary required step, plus optional opportunities. Distinct from `/start` (first-time only) and `/project-stage-detect` (full audit).
#### Comprehensive QA and Testing Framework
Nine new QA/testing skills covering the full testing lifecycle:
- **`/test-setup`** — scaffolds the test framework and CI/CD pipeline for your engine
- **`/test-helpers`** — generates engine-specific test helper libraries (GDUnit4, NUnit, etc.)
- **`/qa-plan`** — generates a QA test plan for a sprint or feature, classifying stories by test type
- **`/smoke-check`** — runs the critical path smoke test gate before QA hand-off
- **`/soak-test`** — generates a soak test protocol for extended play sessions (stability, memory leaks)
- **`/regression-suite`** — maps test coverage to GDD critical paths, identifies fixed bugs lacking regression tests
- **`/test-evidence-review`** — quality review of test files and manual evidence documents
- **`/test-flakiness`** — detects non-deterministic tests by reading CI run logs
- **`/skill-test`** — validates skill files for structural compliance and behavioral correctness (three modes: lint, spec, catalog)
Also new: **`/bug-triage`** re-evaluates all open bugs for priority, severity, and ownership.
#### Skill Validator (`/skill-test`)
`/skill-test` is a meta-skill for validating the harness itself. Run it after editing any skill file. Three modes:
- `lint` — validates YAML frontmatter and required fields
- `spec [skill-name]` — runs behavioral spec tests against a specific skill
- `catalog` — checks that all skills in `.claude/skills/` are indexed in the catalog
The new `validate-skill-change.sh` hook reminds you to run `/skill-test` automatically when a skill file is modified.
#### Team Live-Ops and Team QA Orchestration
- **`/team-live-ops`** — coordinates live-ops-designer + economy-designer + community-manager + analytics-engineer for post-launch content planning (seasonal events, battle pass, retention)
- **`/team-qa`** — orchestrates qa-lead + qa-tester + gameplay-programmer + producer through a full QA cycle: strategy, execution, coverage, and sign-off
#### Model Tier Routing
Skills are now explicitly assigned to Haiku, Sonnet, or Opus tiers based on task complexity. Read-only status checks use Haiku; complex multi-document synthesis uses Opus; everything else defaults to Sonnet. Tier assignments are documented in `.claude/docs/coordination-rules.md`.
#### Directory CLAUDE.md Files
Three new directory-scoped CLAUDE.md files (`design/`, `src/`, `docs/`) provide path-specific instructions to agents working in those directories. These load automatically when Claude Code reads files in that directory.
---
### After Upgrading
1. **Verify new hooks** are registered in `.claude/settings.json` — check for `log-agent-stop.sh`.
1. **Verify new hooks** are registered in `.claude/settings.json` — check for all four: `log-agent-stop.sh`, `notify.sh`, `post-compact.sh`, `validate-skill-change.sh`.
2. **Test the audit trail** by spawning any subagent — both start and stop events should appear in `production/session-logs/`.
@@ -234,6 +298,8 @@ Also: `/design-system retrofit [path]` and `/architecture-decision retrofit [pat
4. **Run `/adopt`** if you have existing GDDs or ADRs that predate this template version — it will identify which sections need to be added without overwriting your content.
5. **Validate your skills** after any skill edits with `/skill-test` — the new `validate-skill-change.sh` hook will automatically remind you to do this.
---
## v0.2.0 → v0.3.0

166
docs/WORKFLOW-GUIDE.md
View File

@@ -3,7 +3,7 @@
> **How to go from zero to a shipped game using the Agent Architecture.**
>
> This guide walks you through every phase of game development using the
> 48-agent system, 52 slash commands, and 9 automated hooks. It assumes you
> 48-agent system, 66 slash commands, and 12 automated hooks. It assumes you
> have Claude Code installed and are working from the project root.
>
> The pipeline has 7 phases. Each phase has a formal gate (`/gate-check`)
@@ -522,40 +522,14 @@ This contains Required patterns, Forbidden patterns, and Guardrails organized
by code layer. Stories created later embed the manifest version date so
staleness can be detected.
### Step 3.5: UX Foundations
Three UX artifacts are required before leaving this phase:
**Accessibility Requirements:**
### Step 3.5: Accessibility Requirements
Create `design/accessibility-requirements.md` using the template. Commit to a
tier (Basic / Standard / Comprehensive / Exemplary) and fill the 4-axis feature
matrix (visual, motor, cognitive, auditory).
**UX Specs for Key Screens:**
```
/ux-design main-menu
/ux-design core-gameplay-hud
```
Three modes: screen/flow, HUD, and interaction patterns. Output goes to
`design/ux/`. Each spec includes: player need, layout zones, states,
interaction map, data requirements, events fired, accessibility, localization.
**UX Review:**
```
/ux-review
```
Validates UX specs for GDD alignment and accessibility tier compliance.
**Interaction Pattern Library:**
Create `design/ux/interaction-patterns.md` -- 16 standard controls plus
game-specific patterns (inventory slot, ability icon, HUD bar, dialogue box,
etc.) with animation and sound standards.
This document is required in Phase 3 because UX specs (written in Phase 4)
reference this tier — it is a design prerequisite, not a UX deliverable.
### Phase 3 Gate
@@ -570,8 +544,6 @@ etc.) with animation and sound standards.
- Architecture review report exists
- `docs/architecture/control-manifest.md` exists
- `design/accessibility-requirements.md` exists
- At least 1 UX spec reviewed in `design/ux/`
- UX review completed
---
@@ -579,30 +551,30 @@ etc.) with animation and sound standards.
### What Happens in This Phase
You turn design documents into implementable stories, create prototypes to
validate risky mechanics, plan your first sprint, and build a Vertical Slice
that proves the core loop is fun.
You create UX specs for key screens, prototype risky mechanics, turn design
documents into implementable stories, plan your first sprint, and build a
Vertical Slice that proves the core loop is fun.
### Phase 4 Pipeline
```
/prototype --> /create-epics --> /create-stories --> /sprint-plan
| | | |
v v v v
Throwaway Epic files in Story files in First sprint with
prototypes production/ production/ prioritized stories
in prototypes/ epics/*/EPIC.md epics/*/story-*.md production/sprints/
(one per module) (one per behaviour) sprint-*.md
|
v
/story-readiness
(validates each story
before pickup)
|
v
/dev-story
(implements the story,
routes to right agent)
/ux-design --> /prototype --> /create-epics --> /create-stories --> /sprint-plan
| | | | |
v v v v v
UX specs Throwaway Epic files in Story files in First sprint with
design/ux/ prototypes production/ production/ prioritized stories
in prototypes/ epics/*/EPIC.md epics/*/story-*.md production/sprints/
(one per module) (one per behaviour) sprint-*.md
| |
v v
/ux-review /story-readiness
(validates specs (validates each story
before epics) before pickup)
|
v
/dev-story
(implements the story,
routes to right agent)
|
v
Vertical Slice
@@ -610,7 +582,49 @@ that proves the core loop is fun.
3 unguided sessions)
```
### Step 4.1: Prototype Risky Mechanics
### Step 4.1: UX Specs for Key Screens
Before writing epics, create UX specs so that story authors know what screens
exist and what player interactions they must support.
**UX Specs:**
```
/ux-design main-menu
/ux-design core-gameplay-hud
```
Three modes: screen/flow, HUD, and interaction patterns. Output goes to
`design/ux/`. Each spec includes: player need, layout zones, states,
interaction map, data requirements, events fired, accessibility, localization.
Reads your `accessibility-requirements.md` (written in Phase 3) and your
input method config from `technical-preferences.md` to drive accessibility
and input coverage checks — no need to re-specify them per screen.
> **Tip:** `/design-system` emits a 📌 UX Flag for every system with UI
> requirements. Use those flags as a checklist for which screens need specs.
**Interaction Pattern Library:**
```
/ux-design interaction-patterns
```
Create `design/ux/interaction-patterns.md` — 16 standard controls plus
game-specific patterns (inventory slot, ability icon, HUD bar, dialogue box,
etc.) with animation and sound standards.
**UX Review:**
```
/ux-review all
```
Validates UX specs for GDD alignment and accessibility tier compliance.
Produces APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED verdict.
### Step 4.2: Prototype Risky Mechanics
Not everything needs a prototype. Prototype when:
- A mechanic is novel and you are not sure it is fun
@@ -630,7 +644,7 @@ pollutes `src/`.
hardcoded values OK, no tests required -- but a README with hypothesis and
findings is mandatory.
### Step 4.2: Create Epics and Stories From Design Artifacts
### Step 4.3: Create Epics and Stories From Design Artifacts
```
/create-epics layer: foundation
@@ -651,7 +665,7 @@ implementable story files in `production/epics/[slug]/`. Each story embeds:
Once stories exist, run `/dev-story [story-path]` to implement one — it routes
automatically to the correct programmer agent.
### Step 4.3: Validate Stories Before Pickup
### Step 4.4: Validate Stories Before Pickup
```
/story-readiness production/stories/combat-damage-calc.md
@@ -660,7 +674,7 @@ automatically to the correct programmer agent.
Checks: Design completeness, Architecture coverage, Scope clarity, Definition
of Done. Verdict: READY / NEEDS WORK / BLOCKED.
### Step 4.4: Effort Estimation
### Step 4.5: Effort Estimation
```
/estimate production/stories/combat-damage-calc.md
@@ -668,7 +682,7 @@ of Done. Verdict: READY / NEEDS WORK / BLOCKED.
Provides effort estimates with risk assessment.
### Step 4.5: Plan Your First Sprint
### Step 4.6: Plan Your First Sprint
```
/sprint-plan new
@@ -681,7 +695,7 @@ Provides effort estimates with risk assessment.
- Creates `production/sprints/sprint-01.md`
- Populates `production/sprint-status.yaml` (machine-readable story tracking)
### Step 4.6: Vertical Slice (Hard Gate)
### Step 4.7: Vertical Slice (Hard Gate)
Before advancing to Production, you must build and playtest a Vertical Slice:
@@ -701,6 +715,8 @@ played the build unguided.
**Requirements to pass:**
- At least 1 UX spec reviewed in `design/ux/`
- UX review completed (APPROVED or NEEDS REVISION with documented risks)
- At least 1 prototype with README
- Story files exist in `production/stories/`
- At least 1 sprint plan exists
@@ -1186,16 +1202,19 @@ Tier 3 (Specialists): gameplay-programmer, engine-programmer,
### Automated Hooks (Safety Net)
The system has 9 hooks that run automatically:
The system has 12 hooks that run automatically:
| Hook | Trigger | What It Does |
|------|---------|-------------|
| `session-start.sh` | Session start | Shows branch, recent commits, detects active.md for recovery |
| `detect-gaps.sh` | Session start | Detects fresh projects (no engine, no concept) and suggests `/start` |
| `pre-compact.sh` | Before compaction | Dumps session state into conversation for auto-recovery |
| `post-compact.sh` | After compaction | Reminds Claude to restore session state from `active.md` |
| `notify.sh` | Notification event | Shows Windows toast notification via PowerShell |
| `validate-commit.sh` | Before commit | Checks for design doc references, valid JSON, no hardcoded values |
| `validate-push.sh` | Before push | Warns on pushes to main/develop |
| `validate-assets.sh` | Before commit | Checks asset naming and size |
| `validate-skill-change.sh` | Skill file written | Advises running `/skill-test` after `.claude/skills/` changes |
| `log-agent.sh` | Agent start | Logs agent invocations for audit trail |
| `log-agent-stop.sh` | Agent stop | Completes agent audit trail (start + stop) |
| `session-stop.sh` | Session end | Final session logging |
@@ -1364,7 +1383,7 @@ conflicts go to `producer`.
## Appendix B: Slash Command Quick-Reference
### All 52 Commands by Category
### All 66 Commands by Category
#### Onboarding and Navigation (5)
@@ -1391,8 +1410,8 @@ conflicts go to `producer`.
| Command | Purpose | Phase |
|---------|---------|-------|
| `/ux-design` | Author UX specs (screen/flow, HUD, patterns) | 3 |
| `/ux-review` | Validate UX specs for accessibility and GDD alignment | 3 |
| `/ux-design` | Author UX specs (screen/flow, HUD, patterns) | 4 |
| `/ux-review` | Validate UX specs for accessibility and GDD alignment | 4 |
#### Architecture (4)
@@ -1403,7 +1422,7 @@ conflicts go to `producer`.
| `/architecture-review` | Validate all ADRs, dependency ordering | 3 |
| `/create-control-manifest` | Flat programmer rules from Accepted ADRs | 3 |
#### Stories and Sprints (6)
#### Stories and Sprints (8)
| Command | Purpose | Phase |
|---------|---------|-------|
@@ -1431,13 +1450,28 @@ conflicts go to `producer`.
| `/gate-check` | Formal phase gate with PASS/CONCERNS/FAIL | All transitions |
| `/reverse-document` | Generate design docs from existing code | Any |
#### Production Management (5)
#### QA and Testing (9)
| Command | Purpose | Phase |
|---------|---------|-------|
| `/qa-plan` | Generate QA test plan for a sprint or feature | 5 |
| `/smoke-check` | Critical path smoke test gate before QA hand-off | 5-6 |
| `/soak-test` | Soak test protocol for extended play sessions | 6 |
| `/regression-suite` | Map test coverage, identify fixed bugs lacking regression tests | 5-6 |
| `/test-setup` | Scaffold test framework and CI/CD pipeline | 4 |
| `/test-helpers` | Generate engine-specific test helper libraries | 4-5 |
| `/test-evidence-review` | Quality review of test files and manual evidence | 5 |
| `/test-flakiness` | Detect non-deterministic tests from CI logs | 5-6 |
| `/skill-test` | Validate skill files for structural and behavioral correctness | Any |
#### Production Management (6)
| Command | Purpose | Phase |
|---------|---------|-------|
| `/milestone-review` | Milestone progress and go/no-go | 5 |
| `/retrospective` | Sprint retrospective analysis | 5 |
| `/bug-report` | Structured bug report creation | 5+ |
| `/bug-triage` | Re-evaluate open bugs for priority, severity, and owner | 5+ |
| `/playtest-report` | Structured playtest session report | 4-6 |
| `/onboard` | Onboard a new team member | Any |
@@ -1458,7 +1492,7 @@ conflicts go to `producer`.
| `/prototype` | Throwaway prototype in isolated worktree | 4 |
| `/localize` | String extraction and validation | 6-7 |
#### Team Orchestration (7)
#### Team Orchestration (9)
| Command | Purpose | Phase |
|---------|---------|-------|
@@ -1469,6 +1503,8 @@ conflicts go to `producer`.
| `/team-audio` | Audio: direction through implemented events | 5-6 |
| `/team-polish` | Coordinated polish: perf + art + audio + QA | 6 |
| `/team-release` | Release coordination: build + QA + deployment | 7 |
| `/team-live-ops` | Live-ops planning: seasonal events, battle pass, retention | 7+ |
| `/team-qa` | Full QA cycle: strategy, execution, coverage, sign-off | 6-7 |
---

194
docs/examples/skill-flow-diagrams.md
View File

@@ -37,8 +37,15 @@ PHASE 3: TECHNICAL SETUP
│
▼
PHASE 4: PRE-PRODUCTION
[UX — before epics, so specs exist when stories are written]
/ux-design [screen/hud/patterns] ────────────────────────────► design/ux/*.md
/ux-review ──────────────────────────────────────────────────► UX specs approved
/ux-review ──────────────────────────────────────────────────► UX specs approved (HARD gate for /team-ui)
[Test infrastructure — scaffold before stories reference tests]
/test-setup ─────────────────────────────────────────────────► test framework + CI/CD pipeline
/test-helpers ───────────────────────────────────────────────► tests/helpers/[engine-specific].gd
[Stories + prototype]
/create-epics [layer] ───────────────────────────────────────► production/epics/*/EPIC.md
/create-stories [epic-slug] ─────────────────────────────────► production/epics/*/story-*.md
/prototype [core-mechanic] ──────────────────────────────────► prototypes/[name]/
@@ -51,7 +58,27 @@ PHASE 5: PRODUCTION (repeating sprint loop)
/sprint-status ──────────────────────────────────────────────► sprint snapshot
/story-readiness [story] ────────────────────────────────────► story validated READY
│
▼ implement (gameplay-programmer, etc.)
▼ (pick up and implement)
/dev-story [story] ──────────────────────────────────────────► routes to correct programmer agent
│
▼ (during implementation, as needed)
/code-review ────────────────────────────────────────────────► code review report
/scope-check ────────────────────────────────────────────────► scope creep detected / clear
/content-audit ──────────────────────────────────────────────► GDD content gaps identified
/bug-report ─────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
/bug-triage ─────────────────────────────────────────────────► bugs re-prioritized + assigned
[Team skills for feature areas — spawn when working a full feature]
/team-combat / /team-narrative / /team-ui / /team-level / /team-audio
[QA cycle per sprint]
/qa-plan ────────────────────────────────────────────────────► production/qa/qa-plan-sprint-NN.md
/smoke-check ────────────────────────────────────────────────► smoke test gate (PASS/FAIL)
/regression-suite ───────────────────────────────────────────► coverage gaps + missing regression tests
/test-evidence-review ───────────────────────────────────────► evidence quality report
/test-flakiness ─────────────────────────────────────────────► flaky test report
│
▼
/story-done [story] ─────────────────────────────────────────► story closed + next surfaced
/sprint-plan [next] ─────────────────────────────────────────► next sprint
│
@@ -63,8 +90,12 @@ PHASE 5: PRODUCTION (repeating sprint loop)
PHASE 6: POLISH
/perf-profile ───────────────────────────────────────────────► perf report + fixes
/balance-check ──────────────────────────────────────────────► balance report + fixes
/asset-audit ────────────────────────────────────────────────► asset compliance report
/tech-debt ──────────────────────────────────────────────────► docs/tech-debt-register.md
/soak-test ──────────────────────────────────────────────────► soak test protocol + results
/localize ───────────────────────────────────────────────────► localization readiness report
/team-polish ────────────────────────────────────────────────► polish sprint orchestrated
/team-qa ────────────────────────────────────────────────────► full QA cycle sign-off
/gate-check ─────────────────────────────────────────────────► PASS → advance to release
│
▼
@@ -74,6 +105,10 @@ PHASE 7: RELEASE
/changelog ──────────────────────────────────────────────────► CHANGELOG.md
/patch-notes ────────────────────────────────────────────────► player-facing notes
/team-release ───────────────────────────────────────────────► release pipeline orchestrated
│
▼ (post-launch, ongoing)
/hotfix ─────────────────────────────────────────────────────► emergency fix with audit trail
/team-live-ops ──────────────────────────────────────────────► live-ops content plan
```
---
@@ -113,12 +148,82 @@ upstream GDDs (input, if any)
---
## Skill Chain: Story Lifecycle in Detail
## Skill Chain: UX / UI Pipeline in Detail
How a story gets from backlog to closed:
UX specs are authored in Phase 4 (Pre-Production), before epics are written, so
that story acceptance criteria can reference specific UX artifacts.
```
/create-epics [layer: foundation]
design/gdd/*.md (UI/UX requirements extracted)
design/player-journey.md (emotional arc, if authored)
│
▼
/ux-design hud → design/ux/hud.md
/ux-design screen [name] → design/ux/screens/[name].md
/ux-design patterns → design/ux/interaction-patterns.md
│
▼
/ux-review design/ux/
│
├── APPROVED → UX specs ready, proceed to /create-epics
├── NEEDS REVISION → blocking issues listed → fix → re-run review
└── MAJOR REVISION → fundamental UX problems → redesign before epics
│
▼ (after APPROVED — in Phase 5 when implementing UI features)
/team-ui
│
├── Phase 1: /ux-design (if any specs still missing) + /ux-review
├── Phase 2: visual design (art-director)
├── Phase 3: layout implementation (ui-programmer)
├── Phase 4: accessibility audit (accessibility-specialist)
└── Phase 5: final review
Note: /ux-design and /ux-review belong in Phase 4 (Pre-Production).
/team-ui belongs in Phase 5 (Production) when a UI feature is being built.
```
---
## Skill Chain: Dev Story Flow in Detail
How a story moves from backlog to closed:
```
/story-readiness [story]
│
├── READY → Status: ready-for-dev → pick up for implementation
├── NEEDS WORK → agent shows specific gaps → resolve → re-run readiness
└── BLOCKED → ADR still Proposed, or upstream story incomplete
│
▼ (after READY)
/dev-story [story]
│
├── Reads: story file, linked GDD requirement, ADR decisions, control manifest
├── Routes to: gameplay-programmer / engine-programmer / ui-programmer / etc.
│
└── Implementation begins
│
▼ (optional, during/after implementation)
/code-review → architectural review of changeset
/scope-check → verify no scope creep vs. original story criteria
/test-evidence-review → validate test files and manual evidence quality
│
▼
/story-done [story]
│
├── COMPLETE → Status: Complete, sprint-status.yaml updated, next story surfaced
├── COMPLETE WITH NOTES → complete but some criteria deferred (logged)
└── BLOCKED → acceptance criteria cannot be verified → investigate blocker
```
---
## Skill Chain: Story Lifecycle (Backlog to Closed)
How a story gets from backlog to closed (summary view):
```
/create-epics [layer]
│
└── Output: production/epics/[slug]/EPIC.md
│
@@ -131,24 +236,68 @@ How a story gets from backlog to closed:
▼
/story-readiness [story]
│
├── READY → Status: ready-for-dev → pick up for implementation
├── NEEDS WORK → agent shows specific gaps → resolve → re-run readiness
└── BLOCKED → ADR still Proposed, or upstream story incomplete
│
▼ (after READY)
Implementation (gameplay-programmer, etc.)
│
▼
/story-done [story]
│
├── COMPLETE → Status: Complete, sprint-status.yaml updated, next story surfaced
├── COMPLETE WITH NOTES → complete but some criteria deferred (logged)
└── BLOCKED → acceptance criteria cannot be verified → investigate blocker
├── READY → /dev-story → implement → /story-done
├── NEEDS WORK → resolve gaps → re-run
└── BLOCKED → fix upstream dependency first
```
---
## Skill Chain: UX Pipeline in Detail
## Skill Chain: QA Pipeline in Detail
```
[Phase 4 — one-time infrastructure setup]
/test-setup ────────────────────────────────────────────────────► test framework scaffolded + CI/CD wired
/test-helpers ──────────────────────────────────────────────────► tests/helpers/[engine].gd (GDUnit4, NUnit, etc.)
[Phase 5 — per-sprint QA cycle]
/qa-plan [sprint or feature]
│
├── Reads: story files, GDDs, acceptance criteria
├── Classifies each story by test type:
│ Logic → automated unit test (BLOCKING)
│ Integration → integration test or documented playtest (BLOCKING)
│ Visual/Feel → screenshot + lead sign-off (ADVISORY)
│ UI → manual walkthrough or interaction test (ADVISORY)
│ Config/Data → smoke check (ADVISORY)
└── Output: production/qa/qa-plan-sprint-NN.md
│
▼
/smoke-check
│
├── PASS → QA hand-off cleared
└── FAIL → block sprint close → fix critical paths first
│
▼
/regression-suite
│
└── Coverage gaps + list of fixed bugs without regression tests
│
▼
/test-evidence-review
│
└── Validates evidence quality, not just existence
│
▼ (if CI run history available)
/test-flakiness
│
└── Flaky test report + fix recommendations
[Phase 6 — extended stability testing]
/soak-test ─────────────────────────────────────────────────────► soak test protocol + observed results
/team-qa ───────────────────────────────────────────────────────► full QA cycle sign-off for release gate
[Ongoing — bug management]
/bug-report ────────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
/bug-triage ────────────────────────────────────────────────────► open bugs re-prioritized + assigned
[Meta — harness validation]
/skill-test [lint|spec|catalog] ────────────────────────────────► skill file structural + behavioral check
```
---
## Skill Chain: UX Pipeline in Detail (Legacy Reference)
```
design/gdd/*.md (UX requirements extracted)
@@ -227,7 +376,12 @@ For projects with existing work (use `/start` option D or run directly):
| Mid-systems design | `/design-system [next system]` or `/map-systems next` |
| All GDDs done | `/review-all-gdds` → `/gate-check` |
| In technical setup | `/create-architecture` → `/architecture-decision` |
| Have stories, ready to code | `/story-readiness [story]` |
| Starting UX design | `/ux-design screen [name]` or `/ux-design hud` |
| Scaffolding tests | `/test-setup` → `/test-helpers` |
| Have stories, ready to code | `/story-readiness [story]` → `/dev-story [story]` |
| Story done | `/story-done [story]` |
| Running QA for a sprint | `/qa-plan` → `/smoke-check` → `/regression-suite` |
| Bug backlog needs sorting | `/bug-triage` |
| Extended stability testing | `/soak-test` |
| Not sure | `/help` |
| Existing project | `/adopt` |