diff --git a/.claude/docs/hooks-reference.md b/.claude/docs/hooks-reference.md index 9c8f483..d3d15b3 100644 --- a/.claude/docs/hooks-reference.md +++ b/.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` diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md index 966f5fe..31ed6a6 100644 --- a/.claude/docs/quick-start.md +++ b/.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) - 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 ``` diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md index 502a5db..2090a87 100644 --- a/.claude/docs/skills-reference.md +++ b/.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 | diff --git a/.claude/docs/technical-preferences.md b/.claude/docs/technical-preferences.md index 9861de6..94a91fb 100644 --- a/.claude/docs/technical-preferences.md +++ b/.claude/docs/technical-preferences.md @@ -10,6 +10,18 @@ - **Rendering**: [TO BE CONFIGURED] - **Physics**: [TO BE CONFIGURED] +## Input & Platform + + + + +- **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] diff --git a/.claude/docs/workflow-catalog.yaml b/.claude/docs/workflow-catalog.yaml index 4bca14a..d14fb0f 100644 --- a/.claude/docs/workflow-catalog.yaml +++ b/.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 diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md index e84abbd..e1ec007 100644 --- a/.claude/skills/design-system/SKILL.md +++ b/.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. diff --git a/.claude/skills/setup-engine/SKILL.md b/.claude/skills/setup-engine/SKILL.md index 974f615..128c5b5 100644 --- a/.claude/skills/setup-engine/SKILL.md +++ b/.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?) -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?" diff --git a/.claude/skills/ux-design/SKILL.md b/.claude/skills/ux-design/SKILL.md index 2d4a46c..f2568a6 100644 --- a/.claude/skills/ux-design/SKILL.md +++ b/.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 -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 diff --git a/.claude/skills/ux-review/SKILL.md b/.claude/skills/ux-review/SKILL.md index 3bb165f..48c31e9 100644 --- a/.claude/skills/ux-review/SKILL.md +++ b/.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 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 --- diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..8b120e8 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,16 @@ +# CODEOWNERS — auto-assigns reviewers to PRs by path +# Format: <@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 diff --git a/.gitignore b/.gitignore index ea2e1bc..823ee7b 100644 --- a/.gitignore +++ b/.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/ diff --git a/README.md b/README.md index 7b04622..e10c53a 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,15 @@

Turn a single Claude Code session into a full game development studio.
- 48 agents. 52 workflows. One coordinated AI team. + 48 agents. 66 workflows. One coordinated AI team.

MIT License 48 Agents - 52 Skills - 9 Hooks + 66 Skills + 12 Hooks 11 Rules Built for Claude Code Ko-fi @@ -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). diff --git a/UPGRADING.md b/UPGRADING.md index f621369..b662f7e 100644 --- a/UPGRADING.md +++ b/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 diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index f35cc0e..e164931 100644 --- a/docs/WORKFLOW-GUIDE.md +++ b/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 - -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 | --- diff --git a/docs/examples/skill-flow-diagrams.md b/docs/examples/skill-flow-diagrams.md index b5c1dda..0d1ded2 100644 --- a/docs/examples/skill-flow-diagrams.md +++ b/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 - ├── 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` |