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

- 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>

.claude/docs/hooks-reference.md

@@ -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`

.claude/docs/quick-start.md

@@ -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)
+  skills/                          -- 66 slash command definitions (YAML frontmatter)
-  hooks/                           -- 9 hook scripts (.sh) wired by settings.json
+  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
 ```

.claude/docs/skills-reference.md

@@ -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 |

.claude/docs/technical-preferences.md

@@ -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]

.claude/docs/workflow-catalog.yaml

@@ -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

.claude/skills/design-system/SKILL.md

@@ -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.

.claude/skills/setup-engine/SKILL.md

@@ -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?)
+3. **Primary input method?** (keyboard/mouse, gamepad, touch, or mixed?)
-4. **Any strong language preferences?** (GDScript, C#, C++, visual scripting?)
+4. **Team size and experience?** (solo beginner, solo experienced, small team?)
-5. **Budget for engine licensing?** (free only, or commercial licenses OK?)
+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?"

.claude/skills/ux-design/SKILL.md

@@ -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
+Use the input methods loaded from `technical-preferences.md` in Phase 2h — do
-interaction map to those." Reference game concept for platform targets.
+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

.claude/skills/ux-review/SKILL.md

@@ -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 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
+5. The player journey map at `design/player-journey.md` (if it exists) for
    context-arrival validation
 
 ---

.github/CODEOWNERS

@@ -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

.gitignore

@@ -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/

README.md

@@ -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/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-9-orange" alt="9 Hooks"></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.) |
+| **Skills** | 66 | 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 |
+| **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)
+  skills/                           # 66 slash commands (subdirectory per skill)
-  hooks/                            # 9 hook scripts (bash, cross-platform)
+  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).
 

UPGRADING.md

@@ -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

docs/WORKFLOW-GUIDE.md

@@ -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
+### Step 3.5: Accessibility Requirements
-
-Three UX artifacts are required before leaving this phase:
-
-**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:**
+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.
-```
-/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.
 
 ### 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,25 +551,25 @@ etc.) with animation and sound standards.
 
 ### What Happens in This Phase
 
-You turn design documents into implementable stories, create prototypes to
+You create UX specs for key screens, prototype risky mechanics, turn design
-validate risky mechanics, plan your first sprint, and build a Vertical Slice
+documents into implementable stories, plan your first sprint, and build a
-that proves the core loop is fun.
+Vertical Slice that proves the core loop is fun.
 
 ### Phase 4 Pipeline
 
 ```
-/prototype  -->  /create-epics  -->  /create-stories  -->  /sprint-plan
+/ux-design  -->  /prototype  -->  /create-epics  -->  /create-stories  -->  /sprint-plan
-    |                  |                   |                       |
+    |                |                  |                   |                       |
-    v                  v                   v                       v
+    v                v                  v                   v                       v
-  Throwaway       Epic files in       Story files in          First sprint with
+  UX specs       Throwaway       Epic files in       Story files in          First sprint with
-  prototypes      production/         production/             prioritized stories
+  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                                                      v
-                                     /story-readiness
+ /ux-review                                          /story-readiness
-                                     (validates each story
+ (validates specs                                    (validates each story
-                                      before pickup)
+  before epics)                                       before pickup)
                                                            |
                                                            v
                                                        /dev-story
@@ -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-design` | Author UX specs (screen/flow, HUD, patterns) | 4 |
-| `/ux-review` | Validate UX specs for accessibility and GDD alignment | 3 |
+| `/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 |
 
 ---
 

docs/examples/skill-flow-diagrams.md

@@ -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
+                ├── READY → /dev-story → implement → /story-done
-                ├── NEEDS WORK → agent shows specific gaps → resolve → re-run readiness
+                ├── NEEDS WORK → resolve gaps → re-run
-                └── BLOCKED → ADR still Proposed, or upstream story incomplete
+                └── BLOCKED → fix upstream dependency first
-                        │
-                        ▼ (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
 ```
 
 ---
 
-## 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` |