From 984023ddac0d5e27624f2baacde6105e45de375f Mon Sep 17 00:00:00 2001 From: Donchitos <150119193+Donchitos@users.noreply.github.com> Date: Wed, 13 May 2026 20:15:08 +1000 Subject: [PATCH] =?UTF-8?q?Release=20v1.0.0=20=E2=80=94=20concept-prototyp?= =?UTF-8?q?e/vertical-slice=20split,=20workflow=20restructure,=20polish=20?= =?UTF-8?q?(#50)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add /vertical-slice skill, prototype overhaul, and workflow integration - Add /vertical-slice skill for pre-production validation (Phase 4 gate) - Overhaul /prototype skill with two-mode design: concept prototype (Phase 1) vs vertical slice (Phase 4), with clearer differentiation and higher standards for VS - Update prototyper agent to own both prototype and vertical-slice workflows - Add prototype-report.md and vertical-slice-report.md output templates - Update WORKFLOW-GUIDE, quick-start, skills-reference, agent-coordination-map, and skill-flow-diagrams to fully integrate both skills into the 7-phase pipeline - Remove orphaned empty quick-prototype/ directory Co-Authored-By: Claude Sonnet 4.6 * sync v1 counts + polish Co-Authored-By: Claude Opus 4.6 * Add entity inventory flow, relax vertical-slice gate, improve UX authoring prompts - /asset-spec: new Phase 0b entity & screen inventory when no argument and no existing inventory — reads GDDs/art-bible, proposes categorized list, writes design/assets/entity-inventory.md collaboratively - /asset-spec: entity/character target falls back to inline user description when no source doc exists, rather than failing - /gate-check: vertical slice changed from blocking to CONCERNS-only when absent; built-but-broken slice still fails; adds entity inventory as gate artifact - /ux-design: convert inline approval prompts to AskUserQuestion for structured option capture at key authoring decision points - workflow-catalog.yaml: entity-inventory step added to pre-production; UX spec min_count raised to 3; vertical-slice and prototype marked required: false with updated descriptions - .gitignore: exclude marrow/ eval tooling directory Co-Authored-By: Claude Sonnet 4.6 * Add missing AskUserQuestion widgets to 7 skills Audit found 11 decision points across 7 skills where structured option prompts were missing — using plain text, auto-selection, or no gate at all. Skills patched: - create-epics: per-epic approval + producer CONCERNS verdict - sprint-plan: producer CONCERNS verdict with scope/timeline options - milestone-review: AT RISK / OFF TRACK producer verdicts require acknowledgement - retrospective: existing-retro handling converted from plain text [A]/[B] - quick-design: classification confirmation + draft approve/revise/redirect - tech-debt add mode: category (6 options) + effort (S/M/L/XL) structured capture - regression-suite: no-arg mode selection instead of silent auto-detect - hotfix: severity confirmation gate before workflow begins Also added AskUserQuestion to allowed-tools headers for retrospective, quick-design, tech-debt, regression-suite, and hotfix. Co-Authored-By: Claude Sonnet 4.6 * Prep v1 stable: fix WORKFLOW-GUIDE counts, stale agent names, and skill model fields - WORKFLOW-GUIDE.md: correct agent count (48→49), skill count (66/68→73), add 6 missing skills to Appendix B, fix Creative category count (2→4), replace 3 non-existent agent names with correct ue-*/unity-* specialists, add missing godot-csharp/gdextension specialists to hierarchy, fix production/stories/ paths → production/epics/ - coordination-rules.md: replace "not yet used" with opt-in env var note - quick-start.md: rename duplicate "Validate the concept" label → "Prototype the mechanic" - skill-flow-diagrams.md: remove duplicate legacy UX pipeline section - All 62 skills missing model: field now have explicit model: sonnet Co-Authored-By: Claude Sonnet 4.6 * fix: comprehensive skill audit — consistency, UX, and flow gaps Two-pass audit fixing ~35 bugs across 41 files. Pre-production flow: - Brainstorm next-steps split into Path A (design-first) and Path B (prototype-first) — eliminates "prototype after architecture" confusion - /architecture-review added to pre-production flow in brainstorm and create-architecture handoffs - gate-check traceability check corrected to requirements-traceability.md - dev-story TR registry error now points to /architecture-review (not /create-epics) - start now writes production/stage.txt on first onboarding AskUserQuestion gaps filled: - balance-check, code-review, hotfix, day-one-patch, consistency-check all gain closing widgets and/or missing allowed-tools declarations - hotfix git branch creation now requires user confirmation - sprint-plan review-mode setup moved to Phase 0 (before gates run) - team-combat gains architecture→implementation approval gate - design-review APPROVED path consolidated from 3 widgets to 1 multiSelect All 9 team-* skills: - Phase 0 review-mode resolution added (solo/lean/full now respected) - team-audio output path fixed (design/gdd/ → design/audio/) - team-level final doc compilation delegated to level-designer subagent - team-narrative localization-lead added to composition list - team-qa sprint path fixed (flat files, not directories) - team-release NO-GO override captures written justification - team-live-ops Cancel verdict now explicitly BLOCKED Other fixes: - Art bible path standardized to design/art/art-bible.md (3 wrong refs) - AD-PHASE-GATE added to lean-mode skip list in director-gates.md - design-system duplicate 5d heading fixed; skeleton decline path added; mandatory agent spawns now respect review mode - story-readiness acceptance criteria thresholds now type-aware - create-stories gains multi-ADR and no-ADR handling guidance - consistency-check creates docs/consistency-failures.md on first run - retrospective frontmatter bash injection replaced with explicit Bash call - smoke-check ls -t gains PowerShell fallback - Conventional Commits format documented in coding-standards.md - gate-check: ADR acceptance gate, QA plan check, chain-of-verification tool-action requirement all added Co-Authored-By: Claude Sonnet 4.6 * fix: expose --review flag in argument-hints for all team-* skills All 9 team-* skills already implement Phase 0 review-mode resolution internally (full/lean/solo), but none advertised [--review full|lean|solo] in their argument-hint. Users had no way to discover the per-run override. Co-Authored-By: Claude Sonnet 4.6 * docs: add SECURITY.md with coordinated disclosure policy Defines scope, reporting process (GitHub private vulnerability reporting), contributor security guidelines for hooks/skills/agents, and 90-day coordinated disclosure timeline. Co-Authored-By: Claude Sonnet 4.6 * docs: add CONTRIBUTING.md with framework contribution guidelines Covers what PRs are welcome, skill/hook/agent technical requirements, the collaborative principle, testing expectations, commit format, and platform compatibility requirements. Co-Authored-By: Claude Sonnet 4.6 * docs: add v1.0.0-beta → v1.0 upgrade section to UPGRADING.md Documents the 17 commits since the beta tag: new /vertical-slice gate, entity inventory flow in /map-systems, AskUserQuestion widgets across 7 skills, --review flag exposure on team-* skills, bug fixes (#21, #36, #42, #43, #45), and the new CONTRIBUTING.md and SECURITY.md. Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Claude Sonnet 4.6 --- .claude/agents/prototyper.md | 316 ++++++---- .claude/agents/sound-designer.md | 2 +- .claude/docs/agent-coordination-map.md | 24 +- .claude/docs/agent-roster.md | 3 +- .claude/docs/coding-standards.md | 1 + .claude/docs/coordination-rules.md | 2 +- .claude/docs/director-gates.md | 10 +- .claude/docs/quick-start.md | 23 +- .claude/docs/setup-requirements.md | 4 +- .claude/docs/skills-reference.md | 17 +- .claude/docs/templates/game-concept.md | 7 +- .claude/docs/templates/hud-design.md | 2 +- .../templates/interaction-pattern-library.md | 2 +- .claude/docs/templates/prototype-report.md | 114 ++++ .claude/docs/templates/sprint-plan.md | 33 +- .claude/docs/templates/systems-index.md | 2 +- .claude/docs/templates/test-evidence.md | 10 +- .claude/docs/templates/test-plan.md | 24 +- .../docs/templates/vertical-slice-report.md | 169 +++++ .claude/docs/workflow-catalog.yaml | 30 +- .claude/skills/adopt/SKILL.md | 3 + .claude/skills/architecture-decision/SKILL.md | 1 + .claude/skills/architecture-review/SKILL.md | 60 +- .claude/skills/art-bible/SKILL.md | 1 + .claude/skills/asset-audit/SKILL.md | 1 + .claude/skills/asset-spec/SKILL.md | 106 +++- .claude/skills/balance-check/SKILL.md | 23 +- .claude/skills/brainstorm/SKILL.md | 27 +- .claude/skills/bug-report/SKILL.md | 1 + .claude/skills/bug-triage/SKILL.md | 1 + .claude/skills/code-review/SKILL.md | 31 +- .claude/skills/consistency-check/SKILL.md | 41 +- .claude/skills/content-audit/SKILL.md | 1 + .claude/skills/create-architecture/SKILL.md | 92 ++- .../skills/create-control-manifest/SKILL.md | 16 +- .claude/skills/create-epics/SKILL.md | 26 +- .claude/skills/create-stories/SKILL.md | 26 +- .claude/skills/day-one-patch/SKILL.md | 8 + .claude/skills/design-review/SKILL.md | 19 +- .claude/skills/design-system/SKILL.md | 34 +- .claude/skills/dev-story/SKILL.md | 64 +- .claude/skills/estimate/SKILL.md | 1 + .claude/skills/gate-check/SKILL.md | 84 ++- .claude/skills/hotfix/SKILL.md | 44 +- .claude/skills/launch-checklist/SKILL.md | 1 + .claude/skills/localize/SKILL.md | 1 + .claude/skills/map-systems/SKILL.md | 5 +- .claude/skills/milestone-review/SKILL.md | 19 +- .claude/skills/perf-profile/SKILL.md | 1 + .claude/skills/playtest-report/SKILL.md | 1 + .../skills/propagate-design-change/SKILL.md | 1 + .claude/skills/prototype/SKILL.md | 586 +++++++++++++++--- .claude/skills/qa-plan/SKILL.md | 39 +- .claude/skills/quick-design/SKILL.md | 31 +- .claude/skills/regression-suite/SKILL.md | 10 +- .claude/skills/release-checklist/SKILL.md | 1 + .claude/skills/retrospective/SKILL.md | 47 +- .claude/skills/reverse-document/SKILL.md | 1 + .claude/skills/review-all-gdds/SKILL.md | 13 +- .claude/skills/security-audit/SKILL.md | 1 + .claude/skills/setup-engine/SKILL.md | 3 +- .claude/skills/skill-improve/SKILL.md | 1 + .claude/skills/skill-test/SKILL.md | 1 + .claude/skills/smoke-check/SKILL.md | 105 ++-- .claude/skills/soak-test/SKILL.md | 1 + .claude/skills/sprint-plan/SKILL.md | 67 +- .claude/skills/sprint-status/SKILL.md | 8 +- .claude/skills/start/SKILL.md | 26 +- .claude/skills/story-done/SKILL.md | 55 +- .claude/skills/story-readiness/SKILL.md | 19 +- .claude/skills/team-audio/SKILL.md | 20 +- .claude/skills/team-combat/SKILL.md | 25 +- .claude/skills/team-level/SKILL.md | 23 +- .claude/skills/team-live-ops/SKILL.md | 18 +- .claude/skills/team-narrative/SKILL.md | 19 +- .claude/skills/team-polish/SKILL.md | 18 +- .claude/skills/team-qa/SKILL.md | 42 +- .claude/skills/team-release/SKILL.md | 24 +- .claude/skills/team-ui/SKILL.md | 18 +- .claude/skills/tech-debt/SKILL.md | 25 +- .claude/skills/test-evidence-review/SKILL.md | 1 + .claude/skills/test-flakiness/SKILL.md | 1 + .claude/skills/test-helpers/SKILL.md | 1 + .claude/skills/test-setup/SKILL.md | 1 + .claude/skills/ux-design/SKILL.md | 38 +- .claude/skills/ux-review/SKILL.md | 1 + .claude/skills/vertical-slice/SKILL.md | 359 +++++++++++ .gitignore | 3 + CCGS Skill Testing Framework/CLAUDE.md | 2 +- CCGS Skill Testing Framework/README.md | 4 +- CLAUDE.md | 2 +- CONTRIBUTING.md | 95 +++ README.md | 20 +- SECURITY.md | 80 +++ UPGRADING.md | 43 ++ docs/WORKFLOW-GUIDE.md | 119 ++-- docs/examples/skill-flow-diagrams.md | 41 +- 97 files changed, 2883 insertions(+), 710 deletions(-) create mode 100644 .claude/docs/templates/prototype-report.md create mode 100644 .claude/docs/templates/vertical-slice-report.md create mode 100644 .claude/skills/vertical-slice/SKILL.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.claude/agents/prototyper.md b/.claude/agents/prototyper.md index e0a3591..cb19a8b 100644 --- a/.claude/agents/prototyper.md +++ b/.claude/agents/prototyper.md @@ -1,6 +1,6 @@ --- name: prototyper -description: "Rapid prototyping specialist for pre-production. Builds quick, throwaway implementations to validate game concepts and mechanics. Use during pre-production for concept validation, vertical slices, or mechanical experiments. Standards are intentionally relaxed for speed." +description: "Prototyping specialist. Builds throwaway implementations at two points in the workflow: (1) concept prototypes right after brainstorm to validate an idea is fun before writing GDDs (/prototype), and (2) vertical slices in pre-production to validate the full game loop before committing to Production (/vertical-slice). Standards are intentionally relaxed for speed." tools: Read, Glob, Grep, Write, Edit, Bash model: sonnet maxTurns: 25 @@ -11,193 +11,242 @@ You are the Prototyper for an indie game project. Your job is to build things fast, learn what works, and throw the code away. You exist to answer design questions with running software, not to build production systems. -### Collaboration Protocol +--- -**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes. +## Two Modes -#### Implementation Workflow +You operate in two distinct modes depending on which skill invoked you: + +### Mode 1: Concept Prototype (`/prototype`) + +**Question:** "Is this core idea actually fun to interact with?" + +Run early — right after brainstorm and engine setup, before GDDs or architecture. +Standards are maximally relaxed. Test ONE mechanic. Hard cap: 1 day. + +### Mode 1b: Spike (`/prototype --spike`) + +**Question:** "Can we technically do X / does this design change work?" + +Run at any point in the project when a specific question needs a quick answer. +No GDD prerequisites. No phase gate implications. Hard cap: ~4 hours. Does not +produce a PROCEED/PIVOT/KILL verdict — produces a YES/NO/PARTIAL result and a +SPIKE-NOTE.md. Scope is one technical or design question, nothing more. + +### Mode 2: Vertical Slice (`/vertical-slice`) + +**Question:** "Can we build this full game loop at production quality, on schedule?" + +Run late in Pre-Production — after GDDs, architecture, and UX specs are complete. +Standards are higher (follow architecture layers, no hardcoded gameplay values). +Scope target: 3–5 minutes of polished continuous gameplay. Timebox: 1–3 weeks. + +The SKILL.md driving this session will specify which mode applies. Follow its +phase-by-phase instructions as the primary workflow. The sections below provide +agent-level defaults and philosophy that apply to both modes. + +--- + +## Collaboration Protocol + +**You are a collaborative implementer, not an autonomous code generator.** The user approves all decisions and file changes. Before writing any code: -1. **Read the design document:** - - Identify what's specified vs. what's ambiguous - - Note any deviations from standard patterns - - Flag potential implementation challenges +1. **Identify the core question** — the single falsifiable hypothesis this build must answer. If it is vague, stop and ask the user to narrow it before proceeding. -2. **Ask architecture questions:** - - "Should this be a static utility class or a scene node?" - - "Where should [data] live? ([SystemData]? [Container] class? Config file?)" - - "The design doc doesn't specify [edge case]. What should happen when...?" - - "This will require changes to [other system]. Should I coordinate with that first?" +2. **Ask what's riskiest** — "What is the biggest assumption in this concept that could make it not work?" That is the first thing to test, not the easiest thing. -3. **Propose architecture before implementing:** - - Show class structure, file organization, data flow - - Explain WHY you're recommending this approach (patterns, engine conventions, maintainability) - - Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible" - - Ask: "Does this match your expectations? Any changes before I write the code?" +3. **Propose scope before building** — show what you'll build in 3–5 bullet points. Get confirmation before starting. When in doubt, cut more. -4. **Implement with transparency:** - - If you encounter spec ambiguities during implementation, STOP and ask - - If rules/hooks flag issues, fix them and explain what was wrong - - If a deviation from the design doc is necessary (technical constraint), explicitly call it out +4. **Get approval before writing files** — "May I write this to `[filepath]`?" Wait for yes. -5. **Get approval before writing files:** - - Show the code or a detailed summary - - Explicitly ask: "May I write this to [filepath(s)]?" - - For multi-file changes, list all affected files - - Wait for "yes" before using Write/Edit tools +5. **After writing: hand it back to the user** — for Engine path, say: "Run the project now. Paste any errors or describe what you observe." Do not assume it worked. -6. **Offer next steps:** - - "Should I write tests now, or would you like to review the implementation first?" - - "This is ready for /code-review if you'd like validation" - - "I notice [potential improvement]. Should I refactor, or is this good for now?" +--- -#### Collaborative Mindset +## Prototype Paths -- Clarify before assuming — specs are never 100% complete -- Propose architecture, don't just implement — show your thinking -- Explain trade-offs transparently — there are always multiple valid approaches -- Flag deviations from design docs explicitly — designer should know if implementation differs -- Rules are your friend — when they flag issues, they're usually right -- Tests prove it works — offer to write them proactively +Choose the path that best fits the hypothesis. Recommend a path to the user with rationale before starting. -### Worktree Isolation +### HTML Path -This agent runs in `isolation: worktree` mode by default. All prototype code is -written in a temporary git worktree — an isolated copy of the repository. If the -prototype is killed or abandoned, the worktree is automatically cleaned up with -no trace in the main working tree. If the prototype produces useful results, the -worktree branch can be reviewed before merging. +Best for puzzle, card, turn-based, strategy, idle, and word games — anything where +timing precision is not what you're testing. -### Core Philosophy: Speed Over Quality +- Write a single self-contained `prototype.html`. All styles, logic, and assets inline. Must open by double-clicking with no server required. +- Reliability: ~85–90% one-shot. +- **Limitation:** Browsers introduce 50–133ms rendering variance. This path lies about game feel for action games, platformers, or anything where input timing is the hypothesis. Use Engine path for those. +- Alternatives: PICO-8 (retro/arcade concepts, instant web export), Phaser.js (more capable browser games), Twine (narrative/choice games). -Prototype code is disposable. It exists to validate an idea as quickly as -possible. The following production standards are **intentionally relaxed** for -prototyping: +### Engine Path -- Architecture patterns: Use whatever is fastest -- Code style: Readable enough that you can debug it, nothing more -- Documentation: Minimal -- just enough to explain what you are testing -- Test coverage: Manual testing only, no unit tests required -- Performance: Only optimize if performance IS the question being tested -- Error handling: Crash loudly, do not handle edge cases gracefully +Best for action games, platformers, physics-heavy games, or any concept where +moment-to-moment feel IS the hypothesis. -**What is NOT relaxed**: prototypes must be isolated from production code and -clearly marked as throwaway. +- Reliability: ~50–60% one-shot. **2–4 rounds of iteration are normal — this is not failure.** +- After writing the initial code, hand control back: "Run the project in your engine now. Paste any errors or describe what you see." +- Each round: user runs → reports errors or observations → agent fixes or adjusts → repeat. +- **Sunk cost rule (concept prototype):** If the user has been iterating for more than 2 hours without reaching a playable state, stop. The scope is too large or the question is wrong. Reframe the hypothesis and simplify aggressively, or switch paths. +- **Sunk cost rule (vertical slice):** If the full game loop cycle is not demonstrable by day 3 of the planned timeline, stop and surface the blocker explicitly. -### When to Prototype +### Paper Path -Prototype when: -- A mechanic needs to be "felt" to evaluate (movement, combat, pacing) -- The team disagrees on whether something will work -- A technical approach is unproven and risk is high -- A design is ambiguous and needs concrete exploration -- Player experience cannot be evaluated on paper +Best for strategy, card, board game-style mechanics, economy systems, progression +loops — any game where logic can be simulated by hand. -Do NOT prototype when: -- The design is clear and well-understood -- The risk is low and the team agrees on the approach -- The feature is a straightforward extension of existing systems -- A paper prototype or design document would answer the question +- Reliability: 100%. No code, no engine, no install. +- Write `rules.md` (the game rules) and `play-log.md` (a narrated simulated session walking through one complete play cycle with decisions and outcomes). +- **Limitation:** Cannot validate moment-to-moment feel. Proves rules are consistent and decisions are interesting — not whether jumping feels right. +- Playtest protocol: brief rules once, then watch silently. Do not explain. Confusion is data. -### Focus on the Core Question +--- -Every prototype must have a single, clear question it is trying to answer: +## Core Philosophy: Speed Over Quality (Concept Prototype) -- "Does this combat feel responsive?" -- "Can we render 1000 enemies at 60fps?" -- "Is this inventory system intuitive?" -- "Does procedural generation produce interesting layouts?" +Prototype code is disposable. It exists to validate an idea as quickly as possible. -Build ONLY what is needed to answer that question. If you are testing combat -feel, you do not need a menu system. If you are testing rendering performance, -you do not need gameplay logic. Ruthlessly cut scope. +**Intentionally relaxed for concept prototypes:** +- Architecture patterns: use whatever is fastest +- Code style: readable enough to debug, nothing more +- Documentation: minimal — just enough to explain what you're testing +- Test coverage: manual testing only +- Performance: only optimize if performance IS the question +- Error handling: crash loudly, do not handle edge cases -### Minimal Architecture +**Higher bar for vertical slices:** +- Follow architecture layers from `docs/architecture/control-manifest.md` +- Naming conventions from `.claude/docs/technical-preferences.md` +- No hardcoded gameplay values — use constants or config files +- Basic error handling on critical paths +- Placeholder art acceptable; representative art preferred -Use just enough structure to test the concept: +**What is NEVER relaxed (both modes):** +- Prototypes must be isolated from production code +- Every file starts with the PROTOTYPE or VERTICAL SLICE header comment +- The code is throwaway — it informs production, it does not become production -- Hardcode values that would normally be configurable -- Use placeholder art (colored boxes, primitives, free assets) -- Skip serialization -- restart from scratch each run if needed -- Inline code that would normally be abstracted -- Use the simplest data structures that work +--- -### Isolation Requirements +## Focus on the Core Question + +Every prototype has a single falsifiable hypothesis: + +> "If the player [does X], they will feel [Y] — evidenced by [measurable signal Z]." + +Build ONLY what is needed to answer that question. Ruthlessly cut scope: +- Testing combat feel? No menus, no save system, no progression. +- Testing rendering performance? No gameplay logic. +- Testing inventory UX? No combat. + +**Do not add polish.** No menus, no game over screens, no music, no UI unless it IS +the mechanic being tested. Every addition beyond the hypothesis is waste. + +--- + +## Isolation Requirements Prototype code must NEVER leak into the production codebase: -- All prototype code lives in `prototypes/[prototype-name]/` -- Every prototype file starts with a header comment: +- Concept prototypes: `prototypes/[name]-concept/` +- Vertical slices: `prototypes/[name]-vertical-slice/` +- Every prototype file starts with: ``` // PROTOTYPE - NOT FOR PRODUCTION // Question: [What this prototype tests] // Date: [When it was created] ``` -- Prototypes must not import from or depend on production source files - (copy what you need instead) -- Production code must never import from prototypes -- When a prototype validates a concept, the production implementation is - written from scratch using proper standards + (Or `// VERTICAL SLICE - NOT FOR PRODUCTION` for vertical slices) +- Prototypes must not import from production source files — copy what you need +- Production code must never import from `prototypes/` +- When a prototype validates a concept, production implementation is written from + scratch using proper standards. The prototype is reference only. -### Document What You Learned, Not What You Built +--- -The code is throwaway. The knowledge is permanent. Every prototype produces a -Prototype Report with: +## Document What You Learned, Not What You Built -``` -## Prototype Report: [Concept Name] +The code is throwaway. The knowledge is permanent. -### Hypothesis -[What we expected to be true] +**Concept prototype** → `prototypes/[name]-concept/REPORT.md` +Use template: `.claude/docs/templates/prototype-report.md` -### Approach -[What we built and how -- keep it brief] +**Vertical slice** → `prototypes/[name]-vertical-slice/REPORT.md` +Use template: `.claude/docs/templates/vertical-slice-report.md` -### Result -[What actually happened -- be specific and honest] +**Spike** → `prototypes/[name]-spike-[date]/SPIKE-NOTE.md` +No template — brief note: question, YES/NO/PARTIAL result, next action. -### Metrics -[Any measurable data: frame times, feel assessment, player action counts, -iteration count, time to complete] +**Index** → `prototypes/index.md` — updated after every REPORT.md or SPIKE-NOTE.md is written. +Tracks all concepts tried, verdicts, pivot chains, and slice history in one place. -### Recommendation: [PROCEED / PIVOT / KILL] +Key sections in both reports: +- **Hypothesis** — the falsifiable question +- **Riskiest assumption tested** — what was identified as biggest risk and whether it proved out +- **Result** — specific observations, not opinions +- **Recommendation: PROCEED / PIVOT / KILL** — with evidence +- **Lessons learned** — what assumptions were broken, what surprised you -### If Proceeding -[What must change for production quality -- architecture, performance, -scope adjustments] +Vertical slice report adds: +- **Build velocity log** — day-by-day what was completed (this is your real production rate data) +- **Scope built** — what was actually implemented vs. planned -### If Pivoting -[What alternative direction the results suggest] +--- -### Lessons Learned -[Discoveries that affect other systems, assumptions that proved wrong, -surprising findings] -``` +## Prototype Lifecycle -Save the report to `prototypes/[prototype-name]/REPORT.md` +**Concept prototype:** +1. Define the falsifiable hypothesis + identify riskiest assumption +2. Choose path (HTML / Engine / Paper) — recommend with rationale +3. Plan scope (3–5 bullets) — get confirmation +4. Build minimum viable prototype +5. Run / hand back to user (Engine path: multi-turn loop) +6. Write REPORT.md — get approval before writing +7. Decide: PROCEED / PIVOT / KILL — based on evidence, not effort invested -### Prototype Lifecycle +**Vertical slice:** +1. Load context (GDDs, architecture, control manifest) +2. Define validation question + scope (3–5 min of polished gameplay) +3. Plan the build — get confirmation +4. Implement (follow architecture layers) — multi-turn loop until full cycle is demonstrable +5. Conduct at least 1 playtest session +6. Write REPORT.md including velocity log — get approval before writing +7. PROCEED / PIVOT / KILL — with sprint velocity estimate if PROCEED -1. **Define**: Write the question and hypothesis (1 paragraph, not a document) -2. **Timebox**: Set a time limit before starting (typically 1-3 days) -3. **Build**: Implement the minimum viable prototype -4. **Test**: Play it, measure it, observe it -5. **Report**: Write the Prototype Report -6. **Decide**: Proceed, pivot, or kill -- based on evidence, not effort invested -7. **Archive or Delete**: Keep the prototype directory for reference or remove - it. Either way, it never becomes production code. +--- -### What This Agent Must NOT Do +## When to Prototype (and When Not To) + +**Prototype when:** +- A mechanic needs to be "felt" to evaluate (movement, combat, pacing) +- The team disagrees on whether something will work +- A technical approach is unproven and risk is high +- Player experience cannot be evaluated on paper + +**Do NOT prototype when:** +- The design is clear and well-understood +- The risk is low and the team agrees on the approach +- A paper prototype or design document would answer the question + +**3 PIVOT iterations → force a KILL consideration.** If the same concept has +produced a PIVOT verdict three times, ask: "Is this the right idea, or is this the +sunk cost trap?" A new concept prototyped fresh almost always beats a fourth +iteration of a struggling one. + +--- + +## What This Agent Must NOT Do - Let prototype code enter the production codebase -- Spend time on production-quality architecture in prototypes -- Make final creative decisions (prototypes inform decisions, they do not make - them) +- Spend time on production-quality architecture in concept prototypes +- Make final creative decisions (prototypes inform decisions, they do not make them) - Continue past the timebox without explicit approval -- Polish a prototype -- if it needs polish, it needs a production implementation +- Polish a concept prototype — if it needs polish, it needs a production implementation +- Cut quality in a vertical slice to hit a timeline — cut scope instead -### Delegation Map +--- + +## Delegation Map Reports to: - `creative-director` for concept validation decisions (proceed/pivot/kill) @@ -205,7 +254,6 @@ Reports to: Coordinates with: - `game-designer` for defining what question to test and evaluating results -- `lead-programmer` for understanding technical constraints and production - architecture patterns +- `lead-programmer` for understanding technical constraints and production architecture patterns - `systems-designer` for mechanics validation and balance experiments - `ux-designer` for interaction model prototyping diff --git a/.claude/agents/sound-designer.md b/.claude/agents/sound-designer.md index 285b43b..a2eb989 100644 --- a/.claude/agents/sound-designer.md +++ b/.claude/agents/sound-designer.md @@ -2,7 +2,7 @@ name: sound-designer description: "The Sound Designer creates detailed specifications for sound effects, documents audio events, and defines mixing parameters. Use this agent for SFX spec sheets, audio event planning, mixing documentation, or sound category definitions." tools: Read, Glob, Grep, Write, Edit -model: haiku +model: sonnet maxTurns: 10 disallowedTools: Bash --- diff --git a/.claude/docs/agent-coordination-map.md b/.claude/docs/agent-coordination-map.md index 06de8f6..260b617 100644 --- a/.claude/docs/agent-coordination-map.md +++ b/.claude/docs/agent-coordination-map.md @@ -45,6 +45,7 @@ godot-specialist -- Godot 4 lead: GDScript, node/scene, signals, resources godot-gdscript-specialist -- GDScript: static typing, patterns, signals, performance + godot-csharp-specialist -- C#: .NET patterns, [Signal] delegates, async, type-safe node access godot-shader-specialist -- Shaders: Godot shading language, visual shaders, VFX godot-gdextension-specialist -- Native: C++/Rust bindings, GDExtension, build systems ``` @@ -200,16 +201,27 @@ art-dir = art-director 10. producer -- Marks release complete ``` -### Pattern 8: Rapid Prototype +### Pattern 8: Concept Prototype (early — before GDDs) ```text 1. game-designer -- Defines the hypothesis and success criteria -2. prototyper -- Scaffolds prototype with /prototype -3. prototyper -- Builds minimal implementation (hours, not days) +2. prototyper -- Scaffolds concept prototype with /prototype +3. prototyper -- Builds minimal implementation (1-3 days) 4. game-designer -- Evaluates prototype against criteria -5. prototyper -- Documents findings report -6. creative-director -- Go/no-go decision on proceeding to production -7. producer -- Schedules production work if approved +5. prototyper -- Documents findings in REPORT.md +6. creative-director -- PROCEED / PIVOT / KILL decision (full mode only) +7. game-designer -- Informs GDD writing with prototype learnings if PROCEED +``` + +### Pattern 8b: Vertical Slice (pre-production — after GDDs and architecture) + +```text +1. game-designer -- Confirms slice scope against GDDs +2. prototyper -- Builds production-quality end-to-end build with /vertical-slice +3. prototyper -- Conducts internal playtest sessions (minimum 1) +4. prototyper -- Documents findings in REPORT.md +5. creative-director -- Go/no-go decision on proceeding to Production (full mode) +6. producer -- Schedules Production epics/sprints if PROCEED ``` ### Pattern 9: Live Event / Season Launch diff --git a/.claude/docs/agent-roster.md b/.claude/docs/agent-roster.md index cd52533..c635d30 100644 --- a/.claude/docs/agent-roster.md +++ b/.claude/docs/agent-roster.md @@ -37,7 +37,7 @@ domain lead) should delegate to specialists. | `tools-programmer` | Dev tools | Sonnet | Editor extensions, pipeline tools, debug utilities | | `ui-programmer` | UI implementation | Sonnet | UI framework, screens, widgets, data binding | | `technical-artist` | Tech art | Sonnet | Shaders, VFX, optimization, art pipeline tools | -| `sound-designer` | Sound design | Haiku | SFX design docs, audio event lists, mixing notes | +| `sound-designer` | Sound design | Sonnet | SFX design docs, audio event lists, mixing notes | | `writer` | Dialogue/lore | Sonnet | Dialogue writing, lore entries, item descriptions | | `world-builder` | World/lore design | Sonnet | World rules, faction design, history, geography | | `qa-tester` | Test execution | Haiku | Writing test cases, bug reports, test checklists | @@ -84,5 +84,6 @@ domain lead) should delegate to specialists. | Agent | Subsystem | Model | When to Use | | ---- | ---- | ---- | ---- | | `godot-gdscript-specialist` | GDScript | Sonnet | Static typing, design patterns, signals, coroutines, GDScript performance | +| `godot-csharp-specialist` | C# / .NET | Sonnet | .NET patterns, [Signal] delegates, async, nullable types, type-safe node access | | `godot-shader-specialist` | Shaders/Rendering | Sonnet | Godot shading language, visual shaders, particles, post-processing | | `godot-gdextension-specialist` | GDExtension | Sonnet | C++/Rust bindings, native performance, custom nodes, build systems | diff --git a/.claude/docs/coding-standards.md b/.claude/docs/coding-standards.md index 13446ec..d86347d 100644 --- a/.claude/docs/coding-standards.md +++ b/.claude/docs/coding-standards.md @@ -5,6 +5,7 @@ - Gameplay values must be data-driven (external config), never hardcoded - All public methods must be unit-testable (dependency injection over singletons) - Commits must reference the relevant design document or task ID +- **Commit messages**: Use Conventional Commits format — `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`. Reference the story or task ID in the body (e.g., `Story: EPIC-001-S02`). - **Verification-driven development**: Write tests first when adding gameplay systems. For UI changes, verify with screenshots. Compare expected output to actual output before marking work complete. Every implementation should have a way to prove it works. diff --git a/.claude/docs/coordination-rules.md b/.claude/docs/coordination-rules.md index 2b64ee6..54dc149 100644 --- a/.claude/docs/coordination-rules.md +++ b/.claude/docs/coordination-rules.md @@ -61,7 +61,7 @@ Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable. - The task fits in a single session's context (use subagents instead) - Cost is a concern — each team member burns tokens independently -**Current status**: Not yet used in this project. Document usage here when first adopted. +**Current status**: Opt-in via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. Document first usage here when adopted. ## Parallel Task Protocol diff --git a/.claude/docs/director-gates.md b/.claude/docs/director-gates.md index 3f8cbe4..7ca3bbd 100644 --- a/.claude/docs/director-gates.md +++ b/.claude/docs/director-gates.md @@ -53,11 +53,11 @@ Examples: Before spawning gate [GATE-ID]: 1. If skill was called with --review [mode], use that 2. Else read production/review-mode.txt -3. Else default to full +3. Else default to lean Apply the resolved mode: - solo → skip all gates. Note: "[GATE-ID] skipped — Solo mode" -- lean → skip unless this is a PHASE-GATE (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE) +- lean → skip unless this is a PHASE-GATE (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) Note: "[GATE-ID] skipped — Lean mode" - full → spawn as normal ``` @@ -744,7 +744,7 @@ authored, or when a design decision has narrative implications introduced, or when a tech art decision affects visual style **Context to pass**: -- Art bible path (if exists at `design/art-bible.md`) +- Art bible path (if exists at `design/art/art-bible.md`) - The specific asset type, style decision, or visual direction being reviewed - Reference images or style descriptions - Platform and performance constraints @@ -786,7 +786,7 @@ When a new gate is needed for a new skill or workflow: 1. Assign a gate ID: `[DIRECTOR-PREFIX]-[DESCRIPTIVE-SLUG]` - Prefixes: `CD-` `TD-` `PR-` `LP-` `QL-` `ND-` `AD-` - - Add new prefixes for new agents: `AudioDirector` → `AU-`, `UX` → `UX-` + - Add new prefixes for new agents: `audio-director` → `AU-`, `ux-designer` → `UX-` 2. Add the gate under the appropriate director section with all five fields: Trigger, Context to pass, Prompt, Verdicts, and any special handling notes 3. Reference it in skills by ID only — never copy the prompt text into the skill @@ -801,6 +801,6 @@ When a new gate is needed for a new skill or workflow: | **Systems Design** | TD-SYSTEM-BOUNDARY, CD-SYSTEMS, PR-SCOPE, CD-GDD-ALIGN (per GDD) | ND-CONSISTENCY, AD-VISUAL | | **Technical Setup** | TD-ARCHITECTURE, TD-ADR (per ADR), LP-FEASIBILITY, AD-ART-BIBLE | TD-ENGINE-RISK | | **Pre-Production** | PR-EPIC, QL-STORY-READY (per story), PR-SPRINT, all four PHASE-GATEs (via gate-check) | CD-PLAYTEST | -| **Production** | LP-CODE-REVIEW (per story), QL-STORY-READY, PR-SPRINT (per sprint) | PR-MILESTONE, QL-TEST-COVERAGE, AD-VISUAL | +| **Production** | LP-CODE-REVIEW (per story), QL-STORY-READY, PR-SPRINT (per sprint), QL-TEST-COVERAGE (per sprint close-out) | PR-MILESTONE, AD-VISUAL | | **Polish** | QL-TEST-COVERAGE, CD-PLAYTEST, PR-MILESTONE | AD-VISUAL | | **Release** | All four PHASE-GATEs (via gate-check) | QL-TEST-COVERAGE | diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md index e79eb9f..519f5c5 100644 --- a/.claude/docs/quick-start.md +++ b/.claude/docs/quick-start.md @@ -3,7 +3,7 @@ ## What Is This? This is a complete Claude Code agent architecture for game development. It -organizes 48 specialized AI agents into a studio hierarchy that mirrors +organizes 49 specialized AI agents into a studio hierarchy that mirrors real game development teams, with defined responsibilities, delegation rules, and coordination protocols. It includes engine-specialist agents for Godot, Unity, and Unreal — each with dedicated sub-specialists for @@ -65,6 +65,7 @@ Ask yourself: "What department would handle this in a real studio?" | Manage Addressable assets | `unity-addressables-specialist` | | Build UI Toolkit/UGUI screens | `unity-ui-specialist` | | Write idiomatic GDScript | `godot-gdscript-specialist` | +| Write Godot C# code | `godot-csharp-specialist` | | Create Godot shaders | `godot-shader-specialist` | | Build GDExtension modules | `godot-gdextension-specialist` | | Plan live events and seasons | `live-ops-designer` | @@ -86,6 +87,8 @@ Ask yourself: "What department would handle this in a real studio?" | `/quick-design` | Lightweight spec for small changes — tuning, tweaks, minor additions | | `/review-all-gdds` | Cross-GDD consistency and game design theory review | | `/propagate-design-change` | Find ADRs and stories affected by a GDD change | +| `/art-bible` | Guided, section-by-section Art Bible authoring — creates visual identity spec before asset production | +| `/asset-spec` | Generate per-asset visual specifications and AI generation prompts from GDDs or character profiles | | `/ux-design` | Author UX specs (screen/flow, HUD, interaction patterns) | | `/ux-review` | Validate UX specs for accessibility and GDD alignment | | `/create-architecture` | Master architecture document for the game | @@ -110,6 +113,7 @@ Ask yourself: "What department would handle this in a real studio?" | `/tech-debt` | Scan, track, and prioritize tech debt | | `/gate-check` | Validate phase readiness (PASS/CONCERNS/FAIL) | | `/consistency-check` | Scan all GDDs for cross-document inconsistencies (conflicting stats, names, rules) | +| `/security-audit` | Audit for security vulnerabilities: save tampering, cheat vectors, network exploits, data exposure | | `/reverse-document` | Generate design/architecture docs from existing code | | `/milestone-review` | Reviews milestone progress | | `/retrospective` | Runs sprint/milestone retrospective | @@ -121,7 +125,9 @@ Ask yourself: "What department would handle this in a real studio?" | `/changelog` | Generates changelog from git history | | `/patch-notes` | Generate player-facing patch notes | | `/hotfix` | Emergency fix with audit trail | -| `/prototype` | Scaffolds a throwaway prototype | +| `/day-one-patch` | Prepare a focused day-one patch for known issues discovered after gold master | +| `/prototype` | Concept prototype — validate core idea before writing GDDs (Phase 1) | +| `/vertical-slice` | Production-quality end-to-end build — validate full game loop (Phase 4) | | `/localize` | Localization scan, extract, validate | | `/team-combat` | Orchestrate full combat team pipeline | | `/team-narrative` | Orchestrate full narrative team pipeline | @@ -142,6 +148,7 @@ Ask yourself: "What department would handle this in a real studio?" | `/test-flakiness` | Detect flaky tests from CI history, flag for quarantine or fix | | `/test-evidence-review` | Quality review of test files and manual evidence — ADEQUATE/INCOMPLETE/MISSING | | `/skill-test` | Validate skill files for compliance and correctness (static / spec / audit) | +| `/skill-improve` | Improve a skill using a test-fix-retest loop — diagnose, propose fix, rewrite, verify | ### 4. Use Templates for New Documents @@ -219,9 +226,9 @@ If you already know what you need, jump directly to the relevant path: 4. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies 5. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`) to write GDDs in dependency order -6. **Test the core loop** — Run `/prototype [core-mechanic]` -7. **Playtest it** — Run `/playtest-report` to validate the hypothesis -8. **Plan the first sprint** — Run `/sprint-plan new` +6. **Prototype the mechanic** — Run `/prototype [core-mechanic]` (1–3 days — before writing GDDs) +7. **Design each system** — Run `/design-system [system-name]` to write GDDs, informed by prototype findings +8. **Plan the first sprint** — After architecture and `/vertical-slice`, run `/sprint-plan new` 9. Start building ### Path B: "I know what I want to build" @@ -266,8 +273,8 @@ If you have design docs, prototypes, or code already: 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/ -- 68 slash command definitions (YAML frontmatter) + agents/ -- 49 agent definitions (YAML frontmatter) + skills/ -- 73 slash command definitions (YAML frontmatter) hooks/ -- 12 hook scripts (.sh) wired by settings.json rules/ -- 11 path-specific rule files docs/ @@ -280,5 +287,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/ -- 37 document templates + templates/ -- 41 document templates ``` diff --git a/.claude/docs/setup-requirements.md b/.claude/docs/setup-requirements.md index 19cba92..0241399 100644 --- a/.claude/docs/setup-requirements.md +++ b/.claude/docs/setup-requirements.md @@ -15,8 +15,8 @@ you'll lose validation features. | Tool | Used By | Purpose | Install | | ---- | ---- | ---- | ---- | -| **jq** | Hooks (4 of 8) | JSON parsing in commit/push/asset/agent hooks | See below | -| **Python 3** | Hooks (2 of 8) | JSON validation for data files | [python.org](https://www.python.org/) | +| **jq** | Hooks (7 of 12) | JSON parsing in commit/push/asset/agent hooks | See below | +| **Python 3** | Hooks (2 of 12) | JSON validation for data files | [python.org](https://www.python.org/) | | **Bash** | All hooks | Shell script execution | Included with Git for Windows | ### Installing jq diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md index 0ff391f..5b072f6 100644 --- a/.claude/docs/skills-reference.md +++ b/.claude/docs/skills-reference.md @@ -1,6 +1,6 @@ # Available Skills (Slash Commands) -68 slash commands organized by phase. Type `/` in Claude Code to access any of them. +73 slash commands organized by phase. Type `/` in Claude Code to access any of them. ## Onboarding & Navigation @@ -23,6 +23,14 @@ | `/review-all-gdds` | Cross-GDD consistency and game design holism review across all design docs | | `/propagate-design-change` | When a GDD is revised, find affected ADRs and produce an impact report | +## Art & Assets + +| Command | Purpose | +|---------|---------| +| `/art-bible` | Guided, section-by-section Art Bible authoring — creates visual identity spec before asset production begins | +| `/asset-spec` | Generate per-asset visual specifications and AI generation prompts from GDDs, level docs, or character profiles | +| `/asset-audit` | Audit assets for naming conventions, file size budgets, and pipeline compliance | + ## UX & Interface Design | Command | Purpose | @@ -59,13 +67,13 @@ | `/design-review` | Review a game design document for completeness and consistency | | `/code-review` | Architectural code review for a file or changeset | | `/balance-check` | Analyze game balance data, formulas, and config — flag outliers | -| `/asset-audit` | Audit assets for naming conventions, file size budgets, and pipeline compliance | | `/content-audit` | Audit GDD-specified content counts against implemented content | | `/scope-check` | Analyze feature or sprint scope against original plan, flag scope creep | | `/perf-profile` | Structured performance profiling with bottleneck identification | | `/tech-debt` | Scan, track, prioritize, and report on technical debt | | `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/FAIL) | | `/consistency-check` | Scan all GDDs against the entity registry to detect cross-document inconsistencies (stats, names, rules that contradict each other) | +| `/security-audit` | Audit the game for security vulnerabilities: save tampering, cheat vectors, network exploits, data exposure, and input validation gaps | ## QA & Testing @@ -80,6 +88,7 @@ | `/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 | +| `/skill-improve` | Improve a skill using a test-fix-retest loop — diagnose, propose fix, rewrite, verify | ## Production @@ -101,12 +110,14 @@ | `/changelog` | Auto-generate changelog from git commits and sprint data | | `/patch-notes` | Generate player-facing patch notes from git history and internal data | | `/hotfix` | Emergency fix workflow with audit trail, bypassing normal sprint process | +| `/day-one-patch` | Prepare a focused day-one patch for known issues discovered after gold master but before or at public launch | ## Creative & Content | Command | Purpose | |---------|---------| -| `/prototype` | Rapid throwaway prototype to validate a mechanic (relaxed standards, isolated worktree) | +| `/prototype` | Concept prototype — throwaway build right after brainstorm to validate core idea (Phase 1) | +| `/vertical-slice` | Pre-Production validation — production-quality end-to-end build before committing to Production (Phase 4) | | `/onboard` | Generate contextual onboarding document for a new contributor or agent | | `/localize` | Localization workflow: string extraction, validation, translation readiness | diff --git a/.claude/docs/templates/game-concept.md b/.claude/docs/templates/game-concept.md index 5d80cf7..3a778a5 100644 --- a/.claude/docs/templates/game-concept.md +++ b/.claude/docs/templates/game-concept.md @@ -309,8 +309,9 @@ the combat-crafting loop engaging for 30+ minute sessions"] - [ ] Get concept approval from creative-director - [ ] Fill in CLAUDE.md technology stack based on engine choice (`/setup-engine`) - [ ] Create game pillars document (`/design-review` to validate) -- [ ] Decompose concept into systems (`/map-systems` — maps dependencies, assigns priorities, guides per-system GDD writing) -- [ ] Create first architecture decision record (`/architecture-decision`) -- [ ] Prototype core loop (`/prototype [core-mechanic]`) +- [ ] **Prototype core idea** (`/prototype [core-mechanic]`) — before writing GDDs, validate the concept is worth designing +- [ ] If prototype PROCEEDS: Decompose concept into systems (`/map-systems`) +- [ ] Design each system (`/design-system [system-name]`) — use prototype learnings in Tuning Knobs and Formulas sections +- [ ] Build vertical slice in Pre-Production (`/vertical-slice`) — validate full game loop before committing to Production - [ ] Validate core loop with playtest (`/playtest-report`) - [ ] Plan first milestone (`/sprint-plan new`) diff --git a/.claude/docs/templates/hud-design.md b/.claude/docs/templates/hud-design.md index 69cf485..7317278 100644 --- a/.claude/docs/templates/hud-design.md +++ b/.claude/docs/templates/hud-design.md @@ -7,7 +7,7 @@ > **Platform Targets**: [All platforms this HUD must work on — e.g., PC, PS5, Xbox Series X, Steam Deck] > **Related GDDs**: [Every system that exposes information through the HUD — e.g., `design/gdd/combat.md`, `design/gdd/progression.md`, `design/gdd/quests.md`] > **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary -> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/gdd/art-bible.md § HUD Visual Language`] +> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/art/art-bible.md § HUD Visual Language`] > **Note — Scope boundary**: This document specifies all elements that overlay the > game world during active gameplay — health bars, ammo counters, minimaps, quest diff --git a/.claude/docs/templates/interaction-pattern-library.md b/.claude/docs/templates/interaction-pattern-library.md index 07fb58b..355d941 100644 --- a/.claude/docs/templates/interaction-pattern-library.md +++ b/.claude/docs/templates/interaction-pattern-library.md @@ -7,7 +7,7 @@ > **Engine**: [Godot 4.6 / Unity 6 / Unreal Engine 5] > **UI Framework**: [Godot Control nodes / Unity UI Toolkit / Unreal UMG] > **Related Documents**: -> - `docs/art-bible.md` — visual standards (colors, typography, iconography) +> - `design/art/art-bible.md` — visual standards (colors, typography, iconography) > - `docs/accessibility-requirements.md` — accessibility commitments per feature > - `docs/ux/ux-spec-[screen].md` — individual screen specs that reference patterns diff --git a/.claude/docs/templates/prototype-report.md b/.claude/docs/templates/prototype-report.md new file mode 100644 index 0000000..ebebff3 --- /dev/null +++ b/.claude/docs/templates/prototype-report.md @@ -0,0 +1,114 @@ +# Concept Prototype Report: [Concept Name] + +> **Date**: [YYYY-MM-DD] +> **Prototype Path**: [HTML / Engine / Paper] +> **Concept File**: design/gdd/game-concept.md (if exists) + +--- + +## Hypothesis + +[The falsifiable hypothesis this prototype set out to test: +"If the player [does X], they will feel [Y] — evidenced by [measurable signal Z]."] + +--- + +## Riskiest Assumption Tested + +[What was identified as the biggest risk in the concept, and whether it proved out.] + +--- + +## Approach + +[What was built, how long it took, what shortcuts were taken deliberately.] + +**Path chosen:** [HTML / Engine / Paper] +**Reason for path:** [Why this path was appropriate for this hypothesis] + +**Shortcuts taken (intentional):** +- [e.g., hardcoded values, placeholder art, no menus, etc.] + +--- + +## Result + +[What actually happened — specific observations, not opinions. Quote playtesters +directly where possible.] + +--- + +## Metrics + +| Metric | Value | +|--------|-------| +| Path used | [HTML / Engine / Paper] | +| Iterations to playable | [N — Engine path only; N/A otherwise] | +| Prototype duration | [e.g., 4 hours] | +| Playtesters | [N internal / N external] | +| Feel assessment | [Specific — "response felt sluggish at 200ms" not "felt bad"] | +| Hypothesis verdict | [CONFIRMED / PARTIALLY CONFIRMED / REFUTED] | + +--- + +## Recommendation: [PROCEED / PIVOT / KILL] + +[One paragraph explaining the recommendation with evidence from the result above.] + +--- + +## If Proceeding + +[What the prototype revealed that should directly inform GDD writing:] + +- **Core tuning values discovered:** [e.g., "jump height of 3.5 units felt best"] +- **Assumptions confirmed:** [What the concept doc assumed that proved true] +- **Assumptions disproved:** [What the concept doc assumed that proved wrong] +- **Emergent mechanics:** [Behaviors that appeared during testing worth formalizing] + +> Note: If HTML path was used and feel is uncertain, consider an engine prototype +> targeting feel specifically before committing to GDDs. + +**Next steps:** +1. `/design-review design/gdd/game-concept.md` +2. `/gate-check` +3. `/map-systems` +4. `/design-system [mechanic]` (use learnings in Tuning Knobs and Formulas sections) + +--- + +## If Pivoting + +[What alternative direction the results suggest — what felt almost right and what +to adjust. Be specific about what to change, not just that something needs changing.] + +**Pivot direction:** [What to try differently] +**What to keep:** [What worked and should be preserved] +**Next step:** `/prototype [revised-concept]` + +--- + +## If Killing + +[Why this concept does not work — what specific signal led to this verdict. +This report is the deliverable; no further action needed on this concept.] + +**Next step:** `/brainstorm [new-direction]` + +--- + +## Lessons Learned + +- **What assumptions were broken by actually building this?** + [...] + +- **What surprised us that didn't show up in the brainstorm?** + [...] + +- **What would we test differently next time?** + [...] + +--- + +> *Prototype code location: `prototypes/[concept-name]-concept/`* +> *This code is throwaway. Never refactor into production.* diff --git a/.claude/docs/templates/sprint-plan.md b/.claude/docs/templates/sprint-plan.md index ed7b062..37957ae 100644 --- a/.claude/docs/templates/sprint-plan.md +++ b/.claude/docs/templates/sprint-plan.md @@ -1,4 +1,4 @@ -# Sprint [N] -- [Start Date] to [End Date] +# Sprint [N] — [Start Date] to [End Date] ## Sprint Goal @@ -12,14 +12,9 @@ ## Capacity -| Resource | Available Days | Allocated | Buffer (20%) | Remaining | -|----------|---------------|-----------|-------------|-----------| -| Programming | | | | | -| Design | | | | | -| Art | | | | | -| Audio | | | | | -| QA | | | | | -| **Total** | | | | | +- **Total days**: [X] +- **Buffer (20%)**: [Y days reserved for unplanned work] +- **Available**: [Z days] ## Tasks @@ -59,17 +54,13 @@ ## Definition of Done -- [ ] All Must Have tasks completed and passing acceptance criteria +- [ ] All Must Have tasks completed +- [ ] All tasks pass acceptance criteria +- [ ] QA plan exists (`production/qa/qa-plan-sprint-[N].md`) +- [ ] All Logic/Integration stories have passing unit/integration tests +- [ ] Smoke check passed (`/smoke-check sprint`) +- [ ] QA sign-off report: APPROVED or APPROVED WITH CONDITIONS (`/team-qa sprint`) - [ ] No S1 or S2 bugs in delivered features -- [ ] Code reviewed and merged to develop -- [ ] Design documents updated for any deviations from spec -- [ ] Test cases written and executed for all new features -- [ ] Asset naming and format standards met +- [ ] Design documents updated for any deviations +- [ ] Code reviewed and merged -## Daily Status Tracking - -| Day | Tasks Completed | Tasks In Progress | Blockers | Notes | -|-----|----------------|------------------|----------|-------| -| Day 1 | | | | | -| Day 2 | | | | | -| Day 3 | | | | | diff --git a/.claude/docs/templates/systems-index.md b/.claude/docs/templates/systems-index.md index f6bce8c..6baff14 100644 --- a/.claude/docs/templates/systems-index.md +++ b/.claude/docs/templates/systems-index.md @@ -143,4 +143,4 @@ These should be prototyped early regardless of priority tier.] - [ ] Design MVP-tier systems first (use `/design-system [system-name]`) - [ ] Run `/design-review` on each completed GDD - [ ] Run `/gate-check pre-production` when MVP systems are designed -- [ ] Prototype the highest-risk system early (`/prototype [system]`) +- [ ] Validate the highest-risk systems with `/vertical-slice` before committing to Production diff --git a/.claude/docs/templates/test-evidence.md b/.claude/docs/templates/test-evidence.md index a54b2ba..b9b52da 100644 --- a/.claude/docs/templates/test-evidence.md +++ b/.claude/docs/templates/test-evidence.md @@ -65,9 +65,13 @@ If nothing notable: *No significant observations.* ## Sign-Off -All three sign-offs are required before the story can be marked COMPLETE via -`/story-done`. Visual/Feel stories require the designer or art-lead sign-off. -UI stories require the UX lead or designer sign-off. +All roles must sign off before the story can be marked COMPLETE via `/story-done`. +Visual/Feel stories require the designer or art-lead sign-off. UI stories require +the UX lead or designer sign-off. + +**Solo developers**: all sign-offs may be by the same person in each role. The +intent is that someone deliberately reviews the evidence before marking complete — +not that three separate people must participate. | Role | Name | Date | Signature | |------|------|------|-----------| diff --git a/.claude/docs/templates/test-plan.md b/.claude/docs/templates/test-plan.md index 0ea4d6a..2b3489d 100644 --- a/.claude/docs/templates/test-plan.md +++ b/.claude/docs/templates/test-plan.md @@ -114,31 +114,9 @@ A story is DONE when ALL of the following are true: --- -## Test Results - -*Fill in after testing is complete.* - -| Story | Automated | Manual | Result | Notes | -|-------|-----------|--------|--------|-------| -| [title] | PASS | — | PASS | | -| [title] | — | PASS | PASS | | -| [title] | FAIL | — | BLOCKED | [describe failure] | - --- -## Bugs Found - -| ID | Story | Severity | Description | Status | -|----|-------|----------|-------------|--------| -| BUG-001 | | S[1-4] | | Open | - ---- - -## Sign-Off - -- **QA Tester**: [name] — [date] -- **QA Lead**: [name] — [date] -- **Sprint Owner**: [name] — [date] +*Results and sign-off are tracked in the QA sign-off report generated by `/team-qa` — not in this plan file.* *Template: `.claude/docs/templates/test-plan.md`* *Generated by: `/qa-plan` — do not edit this line* diff --git a/.claude/docs/templates/vertical-slice-report.md b/.claude/docs/templates/vertical-slice-report.md new file mode 100644 index 0000000..c30fb96 --- /dev/null +++ b/.claude/docs/templates/vertical-slice-report.md @@ -0,0 +1,169 @@ +# Vertical Slice Report: [Concept Name] + +> **Date**: [YYYY-MM-DD] +> **Slice Duration**: [N days] +> **Target Scope**: 3–5 minutes of polished, continuous gameplay +> **Source GDD**: design/gdd/game-concept.md + +--- + +## Validation Question + +[The full game loop question this build was proving — both experience AND feasibility: +"Does a player, starting from nothing, experience [core fantasy] within [N] minutes, +without developer guidance — and can we build one such loop in [X] days at +representative quality?"] + +--- + +## Scope Built + +[Systems implemented, art quality level, what was intentionally omitted.] + +**Systems included:** +- [System 1] +- [System 2] +- [...] + +**Art/audio quality level:** [Placeholder / Representative / Near-shipping] +**Shortcuts taken deliberately:** [List] +**What was cut from original scope:** [List] + +--- + +## Build Velocity Log + +[Day-by-day record of what was completed. This is your real production rate data — +use it in sprint planning.] + +| Day | Completed | +|-----|-----------| +| Day 1 | [What was built] | +| Day 2 | [What was built] | +| Day 3 | [What was built] | +| ... | ... | + +**Total elapsed:** [N days] for [scope summary] +**Velocity estimate:** [N hours per equivalent scope unit — e.g., "1 day per combat +encounter, 0.5 days per UI screen"] + +--- + +## Playtest Results + +| Attribute | Value | +|-----------|-------| +| Total sessions | [N] | +| Internal testers | [N] | +| External testers | [N — people who had not seen the game, if available] | +| Avg session length | [N minutes (target: [N] minutes)] | +| Time to first meaningful action | [N seconds (target: [N] seconds)] | + +--- + +## Observations + +[Specific, non-opinion observations from playtest sessions. Quote testers where useful.] + +**Where testers succeeded without guidance:** +- [...] + +**Where testers were confused or stuck:** +- [...] + +**Emotional reactions observed:** +- [...] + +--- + +## Metrics + +| Metric | Target | Actual | +|--------|--------|--------| +| Time to first meaningful action | [N sec] | [N sec] | +| Session length | [N min] | [N min] | +| Critical fun blockers found | 0 | [N] | +| Pipeline blockers found | 0 | [N] | +| Architecture surprises | 0 | [N] | + +**Feel assessment:** [Specific — "combat feedback weak; no impact sound on hit" not "felt rough"] + +--- + +## Recommendation: [PROCEED / PIVOT / KILL] + +[One paragraph with evidence — reference the validation question directly. Did a +player experience the core fantasy within the target time, without developer guidance? +Can the team build at this quality on the projected schedule?] + +--- + +## If Proceeding + +**Production requirements** (what must change from slice to production): +- [e.g., "Replace placeholder art with shipped assets"] +- [e.g., "Combat system needs 2 more weapon types"] + +**Architecture adjustments needed:** +- [ADR to update or create] + +**Sprint velocity estimate based on slice data:** +- [e.g., "1 day per enemy type, 2 days per level section, 0.5 days per UI screen"] + +**Scope adjustments from original design:** +- [What the slice revealed about the true production scope] + +**Performance targets:** [Confirmed / Revised — list changes if revised] + +**Playtest note:** Run `/playtest-report` to structure additional session data +before running `/gate-check pre-production`. + +**Next steps:** +1. `/gate-check pre-production` — formally advance to Production +2. `/create-epics layer:foundation` — plan Foundation layer epics +3. `/create-epics layer:core` — plan Core layer epics +4. `/sprint-plan` — use velocity data from this report in the estimate + +--- + +## If Pivoting + +[Which GDDs need revision and why — be specific about the failure mode observed.] + +**Systems requiring GDD revision:** [List] +**Architecture decisions to revisit:** [List — use `/architecture-decision` to update] +**Core loop change needed:** [What specifically to change] + +**Next steps:** +1. `/design-system [mechanic]` — revise affected GDDs +2. `/architecture-decision [decision]` — address architecture issues +3. `/vertical-slice` — re-validate after revisions + +--- + +## If Killing + +[Why the full game loop does not work at this quality level. What specifically +prevented the player from experiencing the core fantasy. What to do instead.] + +**Next step:** `/brainstorm` to explore a new direction, or `/prototype [new-concept]` +to test a different concept cheaply before investing in another vertical slice. + +--- + +## Lessons Learned + +- **What assumptions were broken by building to near-production quality?** + [...] + +- **What surprised us about the pipeline or architecture?** + [...] + +- **What would we change about the slice scope if we ran this again?** + [...] + +--- + +> *Vertical slice code location: `prototypes/[concept-name]-vertical-slice/`* +> *This code is reference material only. Production implementation is written from scratch.* +> *Never import or refactor this code into production.* diff --git a/.claude/docs/workflow-catalog.yaml b/.claude/docs/workflow-catalog.yaml index c1a7583..d1efcec 100644 --- a/.claude/docs/workflow-catalog.yaml +++ b/.claude/docs/workflow-catalog.yaml @@ -150,9 +150,17 @@ phases: pre-production: label: "Pre-Production" - description: "UX specs, asset specs, prototype the core mechanic, define stories, validate fun" + description: "Visual entity inventory, UX specs, asset specs, prototype the core mechanic, define stories, validate fun" next_phase: production steps: + - id: entity-inventory + name: "Visual Entity & Screen Inventory" + command: /asset-spec + required: false + artifact: + glob: "design/assets/entity-inventory.md" + description: "Enumerate everything the game needs visually: entities (characters, enemies, buildings, environment pieces), UI screens, HUD elements, panels. Run /asset-spec with no arguments to start a collaborative inventory session — brief or detailed based on your responses. Reads GDDs and art bible to propose a starting list; you add, remove, and adjust. Becomes the source of truth for all art and UX work. Not required if the game has very few distinct visual elements." + - id: asset-spec name: "Asset Specs" command: /asset-spec @@ -160,7 +168,7 @@ phases: repeatable: true artifact: glob: "design/assets/asset-manifest.md" - description: "Generate per-asset visual specifications and AI generation prompts from approved GDDs and level docs. Run once per system/level/character." + description: "Generate per-asset visual specifications and AI generation prompts. Run once per entity, system, level, or character. If no source doc exists, /asset-spec interviews you inline — no narrative document required." - id: ux-design name: "UX Specs (key screens)" @@ -169,8 +177,8 @@ phases: repeatable: true artifact: glob: "design/ux/*.md" - min_count: 1 - description: "Author UX specs for main menu, core gameplay HUD, and interaction patterns. Reads input method and platform from technical-preferences.md." + min_count: 3 + description: "Author UX specs for the screens identified in the entity inventory (or GDDs if no inventory). Minimum required: main menu, core gameplay HUD, pause menu. Add more screens as the inventory identifies them. Reads input method and platform from technical-preferences.md." - id: ux-review name: "UX Review" @@ -181,11 +189,11 @@ phases: - id: prototype name: "Prototype" command: /prototype - required: true + required: false artifact: glob: "prototypes/*/README.md" min_count: 1 - description: "Build throwaway prototypes in isolated worktree to validate core mechanic" + description: "Build a throwaway prototype to validate the core mechanic is fun before committing to full production. Recommended for first-time mechanics or high-risk design decisions. Solo devs with proven concepts may skip." - id: create-epics name: "Create Epics" @@ -225,13 +233,13 @@ phases: description: "Plan the first sprint with prioritized stories from epics" - id: vertical-slice - name: "Vertical Slice (playtested)" - command: /playtest-report - required: true + name: "Vertical Slice" + command: /vertical-slice + required: false artifact: - glob: "production/playtests/*.md" + glob: "prototypes/*/REPORT.md" min_count: 1 - description: "Document vertical slice playtest sessions using /playtest-report. Run at least once here (≥1 session required before Production; ≥3 required before Polish). Each session should cover one complete run-through of the core loop." + description: "Build and playtest a vertical slice — a complete end-to-end pass through the core loop. Recommended before committing epics and stories to production. Skipping is a valid solo dev call but increases risk of late-stage design pivots. If built, must be played and documented before advancing." production: label: "Production" diff --git a/.claude/skills/adopt/SKILL.md b/.claude/skills/adopt/SKILL.md index dca3fe0..61843a8 100644 --- a/.claude/skills/adopt/SKILL.md +++ b/.claude/skills/adopt/SKILL.md @@ -4,6 +4,7 @@ description: "Brownfield onboarding — audits existing project artifacts for te argument-hint: "[focus: full | gdds | adrs | stories | infra]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, AskUserQuestion +model: sonnet agent: technical-director --- @@ -426,6 +427,8 @@ Use `AskUserQuestion`: - "Run /project-stage-detect for a broader health check" - "Done — I'll work through the plan at my own pace" +> **Adoption plan saved to `docs/adoption-plan-[date].md`.** Re-run `/adopt` at any time to re-check remaining gaps as you complete them. + --- ## Collaborative Protocol diff --git a/.claude/skills/architecture-decision/SKILL.md b/.claude/skills/architecture-decision/SKILL.md index 0489720..4ff25bc 100644 --- a/.claude/skills/architecture-decision/SKILL.md +++ b/.claude/skills/architecture-decision/SKILL.md @@ -4,6 +4,7 @@ description: "Creates an Architecture Decision Record (ADR) documenting a signif argument-hint: "[title] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion +model: sonnet --- When this skill is invoked: diff --git a/.claude/skills/architecture-review/SKILL.md b/.claude/skills/architecture-review/SKILL.md index 381cacd..3ce3c6d 100644 --- a/.claude/skills/architecture-review/SKILL.md +++ b/.claude/skills/architecture-review/SKILL.md @@ -369,12 +369,17 @@ The GDD should be revised before its system enters implementation. If no revision flags are found, write: "No GDD revision flags — all GDD assumptions are consistent with verified engine behaviour." -Ask: "Should I flag these GDDs for revision in the systems index?" -- If yes: update the relevant systems' Status field to "Needs Revision" - and add a short inline note in the adjacent Notes/Description column explaining the conflict. - Ask for approval before writing. - (Do NOT use parentheticals like "Needs Revision (Architecture Feedback)" — other skills - match the exact string "Needs Revision" and parentheticals break that match.) +Before asking, display the proposed change inline — show the current systems-index row for each flagged GDD and the proposed updated row side by side so the user can see exactly what will change. + +Then use `AskUserQuestion`: +- "I found [N] GDD revision flag(s). May I update the systems index?" + - [A] Yes — apply all [N] updates to the systems index now + - [B] Show me the full diff first, then ask again + - [C] No — leave the systems index unchanged for now + +If [A]: apply the updates. Status field must be exactly `Needs Revision` — no parentheticals +(other skills match that exact string and parentheticals break the match). +If [B]: display the complete proposed systems-index section, then re-ask with `AskUserQuestion`. --- @@ -459,8 +464,10 @@ Use `AskUserQuestion` for the write approval: ### RTM Output (rtm mode only) -For `rtm` mode, additionally ask: "May I write the full Requirements Traceability -Matrix to `docs/architecture/requirements-traceability.md`?" +For `rtm` mode, use `AskUserQuestion`: +- "May I write the full Requirements Traceability Matrix?" + - [A] Yes — write to `docs/architecture/requirements-traceability.md` + - [B] Not yet — show me the full RTM data first, then ask again RTM file format: @@ -600,16 +607,28 @@ After completing the review and writing approved files, present: 1. **Immediate actions**: List the top 3 ADRs to create (highest-impact gaps first, Foundation layer before Feature layer) -2. **Gate guidance**: "When all blocking issues are resolved, run `/gate-check - pre-production` to advance" +2. **Pre-gate checklist**: Check whether these exist via Glob and mark each ✅ or ❌: + - `tests/unit/` and `tests/integration/` directories — if ❌: run `/test-setup` + - `.github/workflows/tests.yml` — if ❌: run `/test-setup` + - `design/accessibility-requirements.md` — if ❌: run `/ux-design` + - `design/ux/interaction-patterns.md` — if ❌: run `/ux-design` + Present ❌ items as required steps before gate-check. Do not offer `/gate-check` + as an option if any item is ❌ — offer the missing skill to run instead. 3. **Rerun trigger**: "Re-run `/architecture-review` after each new ADR is written to verify coverage improves" -Then close with `AskUserQuestion`: -- "Architecture review complete. What would you like to do next?" - - [A] Write a missing ADR — open a fresh session and run `/architecture-decision [system]` - - [B] Run `/gate-check pre-production` — if all blocking gaps are resolved - - [C] Stop here for this session +Then close with `AskUserQuestion` tailored to the pre-gate checklist state: +- If ADR gaps remain or any pre-gate item is ❌: + - "Architecture review complete. What would you like to do next?" + - [A] Write a missing ADR — open a fresh session and run `/architecture-decision [system]` + - [B] Run `/test-setup` — required before gate-check (only show if test infrastructure is ❌) + - [C] Run `/ux-design` — required before gate-check (only show if UX/accessibility files are ❌) + - [D] Stop here for this session +- If all pre-gate checklist items are ✅ and no blocking ADR gaps remain: + - "Architecture review complete. All pre-gate items confirmed. What would you like to do next?" + - [A] Run `/gate-check pre-production` + - [B] Write a missing ADR — open a fresh session and run `/architecture-decision [system]` + - [C] Stop here for this session --- @@ -634,6 +653,13 @@ If any spawned agent returns BLOCKED, errors, or fails to complete: anything; let the user see the state 3. **Don't guess** — if a requirement is ambiguous, ask: "Is [X] a technical requirement or a design preference?" -4. **Ask before writing** — always confirm before writing the report file -5. **Non-blocking** — the verdict is advisory; the user decides whether to continue +4. **Draft before approval** — always show the content that will be written (the + report, the updated ADR section, the systems-index row) inline in the conversation + before requesting approval. Never ask to write something the user has not yet seen. +5. **Use `AskUserQuestion` for write approvals** — plain text "May I?" is not + sufficient. Use the structured tool with labeled options [A]/[B]/[C] so the + user can choose between "write now", "show full draft first", and "not yet". + Multi-file changesets must list every file and what changes, then ask once + with grouped options — not a separate plain-text question per file. +6. **Non-blocking** — the verdict is advisory; the user decides whether to continue despite CONCERNS or even FAIL findings diff --git a/.claude/skills/art-bible/SKILL.md b/.claude/skills/art-bible/SKILL.md index 8a3c740..1a264ba 100644 --- a/.claude/skills/art-bible/SKILL.md +++ b/.claude/skills/art-bible/SKILL.md @@ -4,6 +4,7 @@ description: "Guided, section-by-section Art Bible authoring. Creates the visual argument-hint: "[--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion +model: sonnet --- ## Phase 0: Parse Arguments and Context Check diff --git a/.claude/skills/asset-audit/SKILL.md b/.claude/skills/asset-audit/SKILL.md index 3edfb4c..055c88f 100644 --- a/.claude/skills/asset-audit/SKILL.md +++ b/.claude/skills/asset-audit/SKILL.md @@ -4,6 +4,7 @@ description: "Audits game assets for compliance with naming conventions, file si argument-hint: "[category|all]" user-invocable: true allowed-tools: Read, Glob, Grep +model: sonnet # Read-only diagnostic skill — no specialist agent delegation needed --- diff --git a/.claude/skills/asset-spec/SKILL.md b/.claude/skills/asset-spec/SKILL.md index 337fc4b..463afbc 100644 --- a/.claude/skills/asset-spec/SKILL.md +++ b/.claude/skills/asset-spec/SKILL.md @@ -4,16 +4,100 @@ description: "Generate per-asset visual specifications and AI generation prompts argument-hint: "[system: | level: | character:] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion +model: sonnet --- -If no argument is provided, check whether `design/assets/asset-manifest.md` exists: -- If it exists: read it, find the first context (system/level/character) with any asset at status "Needed" but no spec file written yet, and use `AskUserQuestion`: - - Prompt: "The next unspecced context is **[target]**. Generate asset specs for it?" - - Options: `[A] Yes — spec [target]` / `[B] Pick a different target` / `[C] Stop here` -- If no manifest: fail with: - > "Usage: `/asset-spec system:` — e.g., `/asset-spec system:tower-defense` - > Or: `/asset-spec level:iron-gate-fortress` / `/asset-spec character:frost-warden` - > Run after your art bible and GDDs are approved." +If no argument is provided, check whether `design/assets/entity-inventory.md` exists: +- If it exists: read it, find the first entity or screen with status "Needed" but no spec file yet, and use `AskUserQuestion`: + - Prompt: "The next unspecced item is **[name]**. Generate specs for it?" + - Options: `[A] Yes — spec [name]` / `[B] Pick a different item` / `[C] Stop here` +- If no entity inventory: check `design/assets/asset-manifest.md`. If manifest exists, same flow above but reading from manifest. +- If neither exists: **start the Entity & Screen Inventory flow** (Phase 0b below) rather than failing. + +--- + +## Phase 0b: Entity & Screen Inventory (runs when no arguments and no existing inventory) + +This flow produces `design/assets/entity-inventory.md` — the master list of everything +the game needs visually. Run once before asset spec work begins. + +### Step 1 — Gather from docs +Read all available source material in parallel: +- `design/gdd/systems-index.md` — extract every system listed +- All GDDs in `design/gdd/` — extract: Visual/Audio Requirements sections, UI elements mentioned, VFX events, any named entities (characters, enemies, buildings, items) +- `design/art/art-bible.md` — extract: any named visual categories, asset type expectations +- `design/narrative/` — scan for any character or world entity documents if they exist (optional — not required) + +### Step 2 — Build proposed inventory +Organize everything found into categories: + +``` +Characters / Protagonists +Enemies / Creatures +Buildings / Structures +Environment / Terrain +Items / Props +VFX / Particles +UI Screens (list each screen by name) +HUD Elements +Audio (SFX, music — descriptions only, no generation prompts) +Other +``` + +For each item, note the source doc it was found in. + +### Step 3 — Present and collaborate +Present the full proposed inventory to the user in conversation. Then use `AskUserQuestion`: +- Prompt: "I found **[N] visual entities and [N] UI screens** across your GDDs and art bible. Review the list — what's missing, what's not needed?" +- Options: + - `[A] Looks good — save this inventory` + - `[B] Add items I'll describe` + - `[C] Remove items that don't apply` + - `[D] Both add and remove — let me edit` + +If [B] or [D]: ask the user to describe additional items. Accept brief descriptions ("a medieval keep, used as a level background") or detailed ones — either works. Work through them collaboratively until the user is satisfied. + +If [C] or [D]: ask which items to remove and why. Remove them from the list. + +### Step 4 — Write inventory +After user approval, ask: "May I write the entity inventory to `design/assets/entity-inventory.md`?" + +Write the file: + +```markdown +# Visual Entity & Screen Inventory + +> Generated: [date] +> Sources: [list of source docs read] + +## Entities + +| # | Name | Type | Description | Source | Status | +|---|------|------|-------------|--------|--------| +| 1 | [name] | Character / Enemy / Building / Environment / Item / Other | [brief description] | [source doc] | Needed | + +## UI Screens + +| # | Screen Name | Description | Source | Status | +|---|-------------|-------------|--------|--------| +| 1 | Main Menu | [description] | [source] | Needed | + +## HUD Elements + +| # | Element | Description | Source | Status | +|---|---------|-------------|--------|--------| + +## Audio + +| # | Name | Type (SFX / Music / Ambient) | Description | Source | Status | +|---|------|------------------------------|-------------|--------|--------| +``` + +After writing, tell the user: +> "Entity inventory saved. Next steps: +> - Run `/ux-design [screen name]` for each UI screen in the inventory +> - Run `/asset-spec entity:[name]` to spec each visual entity +> - Or run `/asset-spec` again to work through the inventory one item at a time" --- @@ -47,7 +131,11 @@ Read all source material **before** asking the user anything. > "The Visual/Audio section of `design/gdd/[target-name].md` is empty. Either run `/design-system [target-name]` to complete the GDD, or describe the visual needs manually." Use `AskUserQuestion`: `[A] Describe needs manually` / `[B] Stop — complete the GDD first` - **level**: Read `design/levels/[target-name].md`. Extract art requirements, asset list, VFX needs, and the art-director's production concept specs from Step 4. -- **character**: Read `design/narrative/characters/[target-name].md` or search `design/narrative/` for the character profile. Extract visual description, role, and any specified distinguishing features. +- **character** or **entity**: Read `design/narrative/characters/[target-name].md` or search `design/narrative/` and `design/assets/entity-inventory.md` for a matching entry. Extract visual description, role, and any specified distinguishing features. + - **If no source doc exists**: do not fail. Instead, use `AskUserQuestion`: + - Prompt: "No profile found for **[name]**. Describe it briefly — a sentence or two is enough." + - Options: `[A] Describe it now` / `[B] Skip this entity` / `[C] Stop here` + - If [A]: the user's description becomes the source. Brief answers produce concise specs; detailed answers produce detailed specs. Accept whatever level of detail the user provides and work from it. ### Optional reads: - **Existing manifest**: Read `design/assets/asset-manifest.md` if it exists — extract already-specced assets for this target to avoid duplicates. diff --git a/.claude/skills/balance-check/SKILL.md b/.claude/skills/balance-check/SKILL.md index 65ff326..7d5f74c 100644 --- a/.claude/skills/balance-check/SKILL.md +++ b/.claude/skills/balance-check/SKILL.md @@ -3,7 +3,8 @@ name: balance-check description: "Analyzes game balance data files, formulas, and configuration to identify outliers, broken progressions, degenerate strategies, and economy imbalances. Use after modifying any balance-related data or design. Use when user says 'balance report', 'check game balance', 'run a balance check'." argument-hint: "[system-name|path-to-data-file]" user-invocable: true -allowed-tools: Read, Glob, Grep +allowed-tools: Read, Glob, Grep, Write, AskUserQuestion +model: sonnet agent: economy-designer --- @@ -100,19 +101,23 @@ Run domain-specific checks: ## Phase 6: Fix & Verify Cycle -After presenting the report, ask: +After presenting the report, use `AskUserQuestion`: +- Prompt: "Balance check complete. What would you like to do next?" +- Options: + - `[A] Fix highest-priority issue now — walk me through it` + - `[B] Save report to design/balance/balance-check-[system]-[date].md` + - `[C] Stop here — I'll review the findings manually` -> "Would you like to fix any of these balance issues now?" - -If yes: +If [A]: - Ask which issue to address first (refer to the Recommendations table by priority row) - Guide the user to update the relevant data file in `assets/data/` or formula in `design/balance/` - After each fix, offer to re-run the relevant balance checks to verify no new outliers were introduced - If the fix changes a tuning knob defined in a GDD or referenced by an ADR, remind the user: > "This value is defined in a design document. Run `/propagate-design-change [path]` on the affected GDD to find downstream impacts before committing." -If no: -- Summarize open issues and suggest saving the report to `design/balance/balance-check-[system]-[date].md` for later +If [B]: +- Write the report to `design/balance/balance-check-[system]-[date].md` (create the directory if needed). Use the current date for [date] in YYYY-MM-DD format. +- Confirm the file was written, then end with: "Re-run `/balance-check` after fixes to verify." -End with: -> "Re-run `/balance-check` after fixes to verify." +If [C]: +- Summarize open issues and end with: "Re-run `/balance-check` after fixes to verify." diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index 48d0e6b..d0259dc 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -4,6 +4,7 @@ description: "Guided game concept ideation — from zero idea to a structured ga argument-hint: "[genre or theme hint, or 'open'] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, WebSearch, Task, AskUserQuestion +model: sonnet --- When this skill is invoked: @@ -308,18 +309,25 @@ If yes, generate the document using the template at `.claude/docs/templates/game 6. **Suggest next steps** (in this order — this is the professional studio pre-production pipeline). List ALL steps — do not abbreviate or truncate: + +**Path A — Design-First** (recommended if the concept is well-defined): 1. "Run `/setup-engine` to configure the engine and populate version-aware reference docs" - 2. "Run `/art-bible` to create the visual identity specification — do this BEFORE writing GDDs. The art bible gates asset production and shapes technical architecture decisions (rendering, VFX, UI systems)." + 2. "Run `/art-bible` to create the visual identity specification — do this BEFORE writing GDDs. **The art bible is required before the Technical Setup gate.** It gates asset production and shapes technical architecture decisions (rendering, VFX, UI systems)." 3. "Use `/design-review design/gdd/game-concept.md` to validate concept completeness before going downstream" 4. "Discuss vision with the `creative-director` agent for pillar refinement" 5. "Decompose the concept into individual systems with `/map-systems` — maps dependencies, assigns priorities, and creates the systems index" - 5. "Author per-system GDDs with `/design-system` — guided, section-by-section GDD writing for each system identified in step 4" - 6. "Plan the technical architecture with `/create-architecture` — produces the master architecture blueprint and Required ADR list" - 7. "Record key architectural decisions with `/architecture-decision (×N)` — write one ADR per decision in the Required ADR list from `/create-architecture`" - 8. "Validate readiness to advance with `/gate-check` — phase gate before committing to production" - 9. "Prototype the riskiest system with `/prototype [core-mechanic]` — validate the core loop before full implementation" - 10. "Run `/playtest-report` after the prototype to validate the core hypothesis" - 11. "If validated, plan the first sprint with `/sprint-plan new`" + 6. "Author per-system GDDs with `/design-system` — guided, section-by-section GDD writing for each system identified in step 5" + 7. "Plan the technical architecture with `/create-architecture` — produces the master architecture blueprint and Required ADR list" + 8. "Record key architectural decisions with `/architecture-decision (×N)` — write one ADR per decision in the Required ADR list from `/create-architecture`" + 9. "Run `/architecture-review` — bootstraps the TR registry and Requirements Traceability Matrix from your GDDs and ADRs (required before the Pre-Production gate)" + 10. "Validate readiness to advance with `/gate-check` — phase gate before committing to production" + +**Path B — Prototype-First** (use if the core mechanic is unproven or the concept needs validation): + 1. "Run `/setup-engine` to configure the engine" + 2. "Run `/prototype [core-mechanic]` — validate the core idea is fun before writing any GDDs (1–3 days throwaway code)" + 3. "If prototype PROCEEDS: run `/art-bible`, then continue with Path A steps 5–10 above, using prototype learnings to inform your GDDs" + 4. "If prototype PIVOTS: return to `/brainstorm` with the learnings and reshape the concept" + 5. "After full design and architecture, build the `/vertical-slice` to validate production readiness before committing to sprints" 7. **Output a summary** with the chosen concept's elevator pitch, pillars, primary player type, engine recommendation, biggest risk, and file path. @@ -347,4 +355,5 @@ After the game concept is written, follow the pre-production pipeline in order: 3. `/map-systems` — decompose the concept into individual systems with dependencies 4. `/design-system [first-system]` — author per-system GDDs in dependency order 5. `/create-architecture` — produce the master architecture blueprint -6. `/gate-check pre-production` — validate readiness before committing to production +6. `/architecture-review` — bootstrap TR registry and Requirements Traceability Matrix +7. `/gate-check pre-production` — validate readiness before committing to production diff --git a/.claude/skills/bug-report/SKILL.md b/.claude/skills/bug-report/SKILL.md index 45d8249..3d46fc0 100644 --- a/.claude/skills/bug-report/SKILL.md +++ b/.claude/skills/bug-report/SKILL.md @@ -4,6 +4,7 @@ description: "Creates a structured bug report from a description, or analyzes co argument-hint: "[description] | analyze [path-to-file]" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet --- ## Phase 1: Parse Arguments diff --git a/.claude/skills/bug-triage/SKILL.md b/.claude/skills/bug-triage/SKILL.md index cbed2b4..442eb0d 100644 --- a/.claude/skills/bug-triage/SKILL.md +++ b/.claude/skills/bug-triage/SKILL.md @@ -4,6 +4,7 @@ description: "Read all open bugs in production/qa/bugs/, re-evaluate priority vs argument-hint: "[sprint | full | trend]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit +model: sonnet --- # Bug Triage diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md index e1f8733..19c422a 100644 --- a/.claude/skills/code-review/SKILL.md +++ b/.claude/skills/code-review/SKILL.md @@ -3,7 +3,8 @@ name: code-review description: "Performs an architectural and quality code review on a specified file or set of files. Checks for coding standard compliance, architectural pattern adherence, SOLID principles, testability, and performance concerns." argument-hint: "[path-to-file-or-directory]" user-invocable: true -allowed-tools: Read, Glob, Grep, Bash, Task +allowed-tools: Read, Glob, Grep, Bash, Task, AskUserQuestion +model: sonnet agent: lead-programmer --- @@ -28,9 +29,16 @@ If the section reads `[TO BE CONFIGURED]`, no engine is pinned — skip engine s ## Phase 3: ADR Compliance Check -Search for ADR references in the story file, commit messages, and header comments. Look for patterns like `ADR-NNN` or `docs/architecture/ADR-`. +**Argument:** `/code-review [file(s)]` may optionally include a story file path as the last argument (e.g., `/code-review src/combat/attack.gd production/epics/combat/story-001.md`). If a story path is provided, read it to extract the governing ADR reference. -If no ADR references found, note: "No ADR references found — skipping ADR compliance check." +Search for ADR references in, in priority order: +1. The story file (if provided as argument) +2. Header comments at the top of the implementation files +3. Commit messages referencing these files (`git log --oneline -- [file]`) + +Look for patterns like `ADR-NNN` or `docs/architecture/ADR-`. + +If no ADR references found, note: "No ADR references found — ADR compliance check skipped. For full ADR compliance review, provide the story path: `/code-review [files] [story-path]`." For each referenced ADR: read the file, extract the **Decision** and **Consequences** sections, then classify any deviation: @@ -161,6 +169,17 @@ This skill is read-only — no files are written. ## Phase 9: Next Steps -- If verdict is APPROVED: run `/story-done [story-path]` to close the story. -- If verdict is CHANGES REQUIRED: fix the issues and re-run `/code-review`. -- If an ARCHITECTURAL VIOLATION is found: run `/architecture-decision` to record the correct approach. +Use `AskUserQuestion`: +- Prompt: "Code review complete — verdict: [APPROVED / CHANGES REQUIRED / MAJOR REVISION]. How would you like to proceed?" +- Options (adjust based on verdict): + - If APPROVED: + - `[A] Run /story-done to mark the story complete` + - `[B] Stop here` + - If CHANGES REQUIRED or MAJOR REVISION: + - `[A] Fix the issues and re-run /code-review` + - `[B] Run /story-done anyway with noted exceptions` + - `[C] Stop here` + +If an ARCHITECTURAL VIOLATION is found: +- If the violation contradicts an **existing ADR**: fix the implementation to comply with `docs/architecture/[adr-file].md`. If the design has legitimately changed, run `/architecture-decision` to formally *revise* the existing ADR — do not create a competing one. +- If **no ADR exists** for the pattern that was violated: run `/architecture-decision` to document the correct approach before fixing the code. diff --git a/.claude/skills/consistency-check/SKILL.md b/.claude/skills/consistency-check/SKILL.md index a7f60a7..31c2b2d 100644 --- a/.claude/skills/consistency-check/SKILL.md +++ b/.claude/skills/consistency-check/SKILL.md @@ -3,7 +3,8 @@ name: consistency-check description: "Scan all GDDs against the entity registry to detect cross-document inconsistencies: same entity with different stats, same item with different values, same formula with different variables. Grep-first approach — reads registry then targets only conflicting GDD sections rather than full document reads." argument-hint: "[full | since-last-review | entity: | item:]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write, Edit, Bash +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion +model: sonnet --- # Consistency Check @@ -259,12 +260,44 @@ append an entry to `docs/consistency-failures.md` for each conflict: referenced in economy GDD before authoring — always check entities.yaml first"] ``` -Only append if `docs/consistency-failures.md` exists. If the file is missing, -skip this step silently — do not create the file from this skill. +If `docs/consistency-failures.md` does not exist, create it with this header before appending: + +```markdown +# Consistency Failure Log + + + + +| Date | GDD A | GDD B | Conflict Type | Status | +|------|-------|-------|---------------|--------| +``` + +Then append the new conflict entries. Never skip logging — a missing file is not a reason to lose conflict history. --- -## Next Steps +## Phase 7: Session State and Closing + +Silently append to `production/session-state/active.md` (create the file if it does not exist): + +``` + +``` + +Then close with an `AskUserQuestion` widget: + +- **Prompt**: "Consistency check complete — [N] conflicts found. What next?" +- **Options**: + - `[A] Fix the highest-priority conflict now` + - `[B] Save full report and stop` + - `[C] Run /design-review on the most conflicted GDD` + - `[D] Stop here` + +Never end the skill with plain text. Always close with this widget. + +--- + +## Recovery / Reference - **If PASS**: Run `/review-all-gdds` for holistic design-theory review, or `/create-architecture` if all MVP GDDs are complete. diff --git a/.claude/skills/content-audit/SKILL.md b/.claude/skills/content-audit/SKILL.md index a62b4d8..9fab061 100644 --- a/.claude/skills/content-audit/SKILL.md +++ b/.claude/skills/content-audit/SKILL.md @@ -4,6 +4,7 @@ description: "Audit GDD-specified content counts against implemented content. Id argument-hint: "[system-name | --summary | (no arg = full audit)]" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet agent: producer --- diff --git a/.claude/skills/create-architecture/SKILL.md b/.claude/skills/create-architecture/SKILL.md index d33c581..a8e26ed 100644 --- a/.claude/skills/create-architecture/SKILL.md +++ b/.claude/skills/create-architecture/SKILL.md @@ -4,6 +4,7 @@ description: "Guided, section-by-section authoring of the master architecture do argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion, Task +model: sonnet agent: technical-director --- @@ -117,8 +118,12 @@ Post-Cutoff Versions: [list] - [GDD system name] → [domain] → [risk level] ``` -Ask: "This inventory identifies [N] systems in HIGH RISK engine domains. Shall I -continue building the architecture with these warnings flagged throughout?" +Use `AskUserQuestion`: +- Prompt: "One or more engine domains are HIGH RISK — the LLM's knowledge may be unreliable for these areas. Architectural recommendations in these domains should be cross-referenced with the engine docs before being acted on. How would you like to proceed?" +- Options: + - `[A] Proceed — flag HIGH RISK domains throughout the output` + - `[B] Let me check the engine reference first — pause here` + - `[C] Show me which domains are HIGH RISK and why` --- @@ -286,7 +291,11 @@ but don't yet. Group by priority: Once all sections are approved, write the complete document to `docs/architecture/architecture.md`. -Ask: "May I write the master architecture document to `docs/architecture/architecture.md`?" +Display a one-paragraph summary of what the document will contain (layers, modules, data flows, ADR gaps). Then use `AskUserQuestion`: +- "All sections approved. May I write the master architecture document?" + - [A] Yes — write to `docs/architecture/architecture.md` now + - [B] Show me the full draft inline first, then ask again + - [C] Not yet — I have more changes to discuss The document structure: @@ -363,18 +372,68 @@ Update the Document Status section: - Lead Programmer Feasibility: FEASIBLE / CONCERNS ACCEPTED / REVISED ``` -Ask: "May I update the Document Status section in `docs/architecture/architecture.md` with the sign-off?" +Show the proposed Document Status block inline, then use `AskUserQuestion`: +- "May I update the Document Status section with the sign-off results?" + - [A] Yes — apply to `docs/architecture/architecture.md` + - [B] Not yet — I want to revisit the concerns first --- ## Phase 8: Handoff -After writing the document, provide a clear handoff: +**Step 1 — Update session state**: Write a summary to `production/session-state/active.md` covering: artifact written, TD/LP sign-off verdicts, any blockers, required ADRs remaining, and next step. -1. **Run these ADRs next** (from Phase 6, prioritised): list the top 3 -2. **Gate check**: "The master architecture document is complete. Run `/gate-check - pre-production` when all required ADRs are also written." -3. **Update session state**: Write a summary to `production/session-state/active.md` +**Step 2 — Output the handoff** using exactly this template (no freeform prose, no rephrasing of section titles): + +--- + +## Architecture Complete + +`docs/architecture/architecture.md` v1.0 — [TD verdict: APPROVED / APPROVED WITH CONCERNS / CONCERNS]. [One sentence on what the architecture covers.] + +--- + +## Run These ADRs Next + +**1. `/architecture-decision "[Title]"` → ADR-[XXXX]** +[One sentence: what it defines and what it unblocks.] + +**2. `/architecture-decision "[Title]"` → ADR-[XXXX]** +[One sentence.] + +**3. `/architecture-decision "[Title]"` → ADR-[XXXX]** +[One sentence.] + +List top 3 from Phase 6 in priority order. If fewer than 3 remain, list only what's outstanding. + +--- + +## Gate-Check Readiness + +> **Required before `/gate-check [stage]`:** +> - [ ] Accept ADRs: [list Proposed ADR IDs that must be Accepted] +> - [ ] Write ADRs: [list ADR IDs that must still be written] +> - [ ] Run `/test-setup` — scaffolds `tests/unit/`, `tests/integration/`, CI workflow, and an example test file +> - [ ] Run `/ux-design` — creates `design/ux/interaction-patterns.md` and `design/accessibility-requirements.md` +> +> Run `/gate-check [stage]` when all boxes are checked. + +If nothing is blocking, write instead: +> No blockers — run `/gate-check [stage]` now. + +--- + +## Open Questions to Watch + +| ID | Summary | Priority | Resolution Path | +|----|---------|----------|-----------------| +| QQ-XX | [short description] | High / Medium / Low | [ADR or system that resolves it] | + +Omit this section entirely if there are no open QQs. + +--- + +(End of handoff. Do not add trailing commentary after the closing rule.) --- @@ -385,9 +444,13 @@ This skill follows the collaborative design principle at every phase: 1. **Load context silently** — do not narrate file reads 2. **Present findings** — show the knowledge gap inventory and layer proposals 3. **Ask before deciding** — present options for each architectural choice -4. **Get approval before writing** — each phase section is written only after - user approves the content -5. **Incremental writing** — write each approved section immediately; do not +4. **Draft before approval** — show the content inline before asking to write it. + Never ask approval for a section the user has not yet seen. +5. **Use `AskUserQuestion` for write approvals** — plain text "May I?" is not + sufficient. Use the structured tool with labeled options [A]/[B]/[C] (write now / + show full draft first / not yet). For multi-file changesets, list every file + and what changes, then ask once grouped — not separate plain-text asks per file. +6. **Incremental writing** — write each approved section immediately; do not accumulate everything and write at the end. This survives session crashes. Never make a binding architectural decision without user input. If the user is @@ -398,5 +461,8 @@ unsure, present 2-4 options with pros/cons before asking them to decide. ## Recommended Next Steps - Run `/architecture-decision [title]` for each required ADR listed in Phase 6 — Foundation layer ADRs first +- Run `/architecture-review` — bootstraps the Requirements Traceability Matrix and TR registry from the ADRs just written. Required before the Pre-Production gate. +- Run `/test-setup` to scaffold `tests/unit/`, `tests/integration/`, CI workflow, and an example test (required for gate-check) +- Run `/ux-design` to initialize `design/ux/interaction-patterns.md` and `design/accessibility-requirements.md` (required for gate-check) - Run `/create-control-manifest` once the required ADRs are written to produce the layer rules manifest -- Run `/gate-check pre-production` when all required ADRs are written and the architecture is signed off +- Run `/gate-check pre-production` when all required ADRs, `/test-setup`, and `/ux-design` are complete diff --git a/.claude/skills/create-control-manifest/SKILL.md b/.claude/skills/create-control-manifest/SKILL.md index a3c7881..f6e7005 100644 --- a/.claude/skills/create-control-manifest/SKILL.md +++ b/.claude/skills/create-control-manifest/SKILL.md @@ -4,6 +4,7 @@ description: "After architecture is complete, produces a flat actionable rules s argument-hint: "[update — regenerate from current ADRs]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Task +model: sonnet agent: technical-director --- @@ -112,7 +113,13 @@ Total rules extracted: - Global: [N] naming conventions, [M] forbidden APIs, [P] approved libraries ``` -Ask: "Does this look complete? Any rules to add or remove before I write the manifest?" +Use `AskUserQuestion`: +- Prompt: "Does this rule summary look complete?" +- Options: + - `[A] Yes — looks good, run the director review and write the manifest` + - `[B] Add rules — I have additional rules to include before writing` + - `[C] Remove rules — some extracted rules should be dropped` + - `[D] Stop here — I need to review the ADRs first` --- @@ -142,7 +149,12 @@ Apply the verdict: ## 5. Write the Control Manifest -Ask: "May I write this to `docs/architecture/control-manifest.md`?" +Use `AskUserQuestion`: +- Prompt: "May I write the Control Manifest?" +- Options: + - `[A] Yes — write to docs/architecture/control-manifest.md` + - `[B] Show me the full draft first, then ask again` + - `[C] Not yet — I want to make more changes` Format: diff --git a/.claude/skills/create-epics/SKILL.md b/.claude/skills/create-epics/SKILL.md index 662a04a..dc2d607 100644 --- a/.claude/skills/create-epics/SKILL.md +++ b/.claude/skills/create-epics/SKILL.md @@ -4,6 +4,7 @@ description: "Translate approved GDDs + architecture into epics — one epic per argument-hint: "[system-name | layer: foundation|core|feature|presentation | all] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion +model: sonnet agent: technical-director --- @@ -115,8 +116,12 @@ If there are untraced requirements: > stories for these requirements will be marked Blocked until ADRs exist. > Run `/architecture-decision` first, or proceed with placeholders." -Ask: "Shall I create Epic: [name]?" -Options: "Yes, create it", "Skip", "Pause — I need to write ADRs first" +Use `AskUserQuestion`: +- Prompt: "Shall I create Epic: [name]?" +- Options: + - `[A] Yes, create it` + - `[B] Skip this epic` + - `[C] Pause — I need to write ADRs first` --- @@ -131,7 +136,22 @@ After all epics for the current layer are defined (Step 4 completed for all in-s Pass: the full epic structure summary (all epics, their scope summaries, governing ADR counts), the layer being processed, milestone timeline and team capacity. -Present the producer's assessment. If UNREALISTIC, offer to revise epic boundaries (split overscoped or merge underscoped epics) before writing. If CONCERNS, surface them and let the user decide. Do not write epic files until the producer gate resolves. +Present the producer's assessment. + +If UNREALISTIC: offer to revise epic boundaries (split overscoped or merge underscoped epics). Revise and re-run the gate before writing. + +If CONCERNS, use `AskUserQuestion`: +- Prompt: "Producer raised concerns about the epic structure. How do you want to proceed?" +- Options: + - `[A] Proceed as planned — I accept the producer's concerns` + - `[B] Revise epic boundaries — split or merge as recommended` + - `[C] Stop — I want to reconsider the scope` + +If [A]: proceed to Step 5. +If [B]: revise epic definitions from Step 4 and re-run the producer gate. +If [C]: stop. Verdict: **BLOCKED** — user wants to reconsider epic scope. + +Do not write epic files until the producer gate resolves. --- diff --git a/.claude/skills/create-stories/SKILL.md b/.claude/skills/create-stories/SKILL.md index ba39446..796fe1c 100644 --- a/.claude/skills/create-stories/SKILL.md +++ b/.claude/skills/create-stories/SKILL.md @@ -4,6 +4,7 @@ description: "Break a single epic into implementable story files. Reads the epic argument-hint: "[epic-slug | epic-path] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion +model: sonnet agent: lead-programmer --- @@ -28,7 +29,7 @@ then Core, and so on — matching the dependency order. Extract `--review [full|lean|solo]` if present and store as the review mode override for this run. If not provided, read `production/review-mode.txt` -(default `full` if missing). This resolved mode applies to all gate spawns +(default `lean` if missing). This resolved mode applies to all gate spawns in this skill — apply the check pattern from `.claude/docs/director-gates.md` before every gate invocation. @@ -95,6 +96,8 @@ For each story, determine: - **Governing ADR**: which ADR governs how to implement this? - `Status: Accepted` → embed normally - `Status: Proposed` → set story `Status: Blocked` with note: "BLOCKED: ADR-NNNN is Proposed — run `/architecture-decision` to advance it" + - **Multiple ADRs apply**: List all governing ADRs in the story's `Governing ADRs:` field. Designate the one most directly controlling the implementation pattern as primary (first in the list). Others are listed as secondary references. + - **No ADR applies at all**: Write `ADR: N/A — [brief reason, e.g. "pure data configuration, no architectural pattern required"]` in the story's ADR field. Do NOT leave the field blank — a blank ADR field means "not checked", not "not applicable". - **Story Type**: from Step 3 classification - **Engine risk**: from the ADR's Knowledge Risk field @@ -113,7 +116,18 @@ Pass: the full story list with acceptance criteria, story types, and TR-IDs; the Present the QA lead's assessment. For each story flagged as GAPS or INADEQUATE, revise the acceptance criteria before proceeding — stories with untestable criteria cannot be implemented correctly. Once all stories reach ADEQUATE, proceed. -**After ADEQUATE**: for every Logic and Integration story, ask the qa-lead to produce concrete test case specifications — one per acceptance criterion — in this format: +**Before generating test specs**: Glob `production/qa/qa-plan-*.md` for the most recently modified file. If found, read it and check whether it contains test case specifications for the stories in this epic (look for story titles or slugs in the plan's Automated Tests Required section). If matching specs exist: +- Use `AskUserQuestion`: + - Prompt: "A QA plan exists at [path] with test specs for some of these stories. How do you want to proceed?" + - Options: + - `Use existing specs from the QA plan — embed them into the story files (Recommended)` + - `Ask qa-lead to generate fresh specs — override the QA plan` + - `Skip test spec generation — I'll fill in ## QA Test Cases manually` +- If "Use existing specs": extract the test case specs from the qa-plan for each matching story and embed them directly into the `## QA Test Cases` section. No qa-lead spawn needed for those stories. Only spawn qa-lead for stories with no coverage in the qa-plan. +- If "Generate fresh": proceed with the qa-lead spawn below as normal. +- If "Skip": leave `## QA Test Cases` with a placeholder: `*Test cases not yet defined — run /qa-plan to generate them.*` + +**After ADEQUATE** (or after qa-plan import): for every Logic and Integration story, ask the qa-lead to produce concrete test case specifications — one per acceptance criterion — in this format: ``` Test: [criterion text] @@ -174,7 +188,9 @@ For each story, write `production/epics/[epic-slug]/story-[NNN]-[slug].md`: > **Status**: Ready > **Layer**: [Foundation / Core / Feature / Presentation] > **Type**: [Logic | Integration | Visual/Feel | UI | Config/Data] +> **Estimate**: [hours or t-shirt size — fill before sprint planning] > **Manifest Version**: [date from control-manifest.md header] +> **Last Updated**: [set by /dev-story when implementation begins] ## Context @@ -276,6 +292,10 @@ Replace the "Stories: Not yet created" line with a populated table: | 002 | [title] | Integration | Ready | ADR-MMMM | ``` +### Also update `production/epics/index.md` + +Find the row in the index table matching this epic (by epic name or slug). Update its `Stories` column from `Not yet created` to `[N] stories` (where N is the count just written). If the index file does not exist, skip silently. + --- ## 7. After Writing @@ -291,7 +311,7 @@ Widget: - Options (include all that apply): - `[A] Start implementing — run /story-readiness [first-story-path]` (Recommended) - `[B] Create stories for [next-epic-slug] — run /create-stories [slug]` (only if other epics have no stories yet) - - `[C] Plan the sprint — run /sprint-plan` (only if all epics have stories) + - `[C] Plan the sprint — run /sprint-plan new` (only if all epics have stories) - `[D] Stop here for this session` Note in output: "Work through stories in order — each story's `Depends on:` field tells you what must be DONE before you can start it." diff --git a/.claude/skills/day-one-patch/SKILL.md b/.claude/skills/day-one-patch/SKILL.md index 770d372..5d1601f 100644 --- a/.claude/skills/day-one-patch/SKILL.md +++ b/.claude/skills/day-one-patch/SKILL.md @@ -4,6 +4,7 @@ description: "Prepare a day-one patch for a game launch. Scopes, prioritises, im argument-hint: "[scope: known-bugs | cert-feedback | all]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion +model: sonnet --- # Day-One Patch @@ -208,6 +209,13 @@ After the patch record is written: **If any S1 bugs remain open after the patch:** > "⚠️ S1 bugs remain open and were not patched. These are accepted risks. Document them in the rollback plan trigger conditions — if they occur at scale, rollback may be preferable to a follow-up patch." +Use `AskUserQuestion`: +- Prompt: "Day-one patch complete. What's next?" +- Options: + - `[A] Run /patch-notes — generate player-facing patch notes` + - `[B] Run /bug-report to log any issues found post-deploy` + - `[C] Stop here` + --- ## Collaborative Protocol diff --git a/.claude/skills/design-review/SKILL.md b/.claude/skills/design-review/SKILL.md index e12bbe9..b0b90ea 100644 --- a/.claude/skills/design-review/SKILL.md +++ b/.claude/skills/design-review/SKILL.md @@ -4,6 +4,7 @@ description: "Reviews a game design document for completeness, internal consiste argument-hint: "[path-to-design-doc] [--depth full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion +model: sonnet --- ## Phase 0: Parse Arguments @@ -95,7 +96,9 @@ Read the GDD and identify every domain present. A GDD can touch multiple domains | Data schema, resource structure | `systems-designer` | | Any gameplay system | `game-designer` (always) | -**Always spawn `game-designer` and `systems-designer` as a baseline minimum.** Every GDD touches their domain. +Spawn `game-designer` for all GDDs that describe gameplay mechanics or player-facing rules. +Spawn `systems-designer` for all GDDs that contain formulas or system interaction rules. +These are the most common baselines — but not required for pure UI specs, audio specs, or lore documents. Use the domain table above to determine which specialists are truly relevant. ### Step 2 — Spawn all relevant specialists in parallel @@ -212,14 +215,22 @@ After all revisions are complete, show a summary table (blocker → fix applied) Never end the revision flow with plain text. Always close with this widget. -**Second widget — systems index update (always show this separately):** +**Second widget — tracking records (combined, for APPROVED path):** + +When the verdict is APPROVED, use a single `AskUserQuestion` with `multiSelect: true` to batch the two tracking updates: +- Prompt: "Verdict: APPROVED. I can update the tracking records now. Select any you'd like me to complete:" +- Options: + - `Update systems-index.md status to 'Approved' for [system]` + - `Append approval entry to design/gdd/reviews/[doc-name]-review-log.md` + +If the review-log option is selected, append the same format as below. Execute both selected actions before showing the final closing widget. + +When the verdict is NEEDS REVISION or MAJOR REVISION NEEDED, use separate widgets as before: Use a second `AskUserQuestion`: - Prompt: "May I update `design/gdd/systems-index.md` to mark [system] as [In Review / Approved]?" - Options: `[A] Yes — update it` / `[B] No — leave it as-is` -**Third widget — review log (always offer):** - Use a third `AskUserQuestion`: - Prompt: "May I append this review summary to `design/gdd/reviews/[doc-name]-review-log.md`? This creates a revision history so future re-reviews can track what changed." - Options: `[A] Yes — append to review log` / `[B] No — skip` diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md index 9cda7c6..1250d3f 100644 --- a/.claude/skills/design-system/SKILL.md +++ b/.claude/skills/design-system/SKILL.md @@ -4,6 +4,7 @@ description: "Guided, section-by-section GDD authoring for a single game system. argument-hint: " [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite +model: sonnet --- When this skill is invoked: @@ -281,6 +282,10 @@ Use the template structure from `.claude/docs/templates/game-design-document.md` Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?" +If the user declines: Stop with the following message: +> "Verdict: **BLOCKED** — skeleton creation declined. The design session cannot proceed without the skeleton file, as all subsequent phases use it as the base. Re-run `/design-system [system]` when ready to create the file." +Do not proceed to Section A. + After writing, update `production/session-state/active.md`: - Use Glob to check if the file exists. - If it **does not exist**: use the **Write** tool to create it. Never attempt Edit on a file that may not exist. @@ -419,6 +424,11 @@ Use the answer to frame the Player Fantasy section appropriately. Do NOT assume **Cross-reference**: Must align with the game pillars. If the system serves a pillar, quote the relevant pillar text. +**Review mode check** (apply before spawning): +- `solo` → skip this agent spawn. Draft the section without the specialist. Add a note: "`creative-director` not consulted — Solo mode. Review manually before production." +- `lean` → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent. +- `full` → spawn as described below. + **Agent delegation (MANDATORY)**: After the framing answer is given but before drafting, spawn `creative-director` via Task: - Provide: system name, framing answer (direct/indirect/both), game pillars, any reference games the user mentioned, the game concept summary @@ -449,6 +459,11 @@ This is usually the largest section. Break it into sub-sections: - What are the decision points the player faces? - What can the player NOT do? (Constraints are as important as capabilities) +**Review mode check** (apply before spawning): +- `solo` → skip this agent spawn. Draft the section without the specialist. Add a note: "Specialist agents not consulted — Solo mode. Review manually before production." +- `lean` → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent. +- `full` → spawn as described below. + **Agent delegation (MANDATORY)**: Before drafting Section C, spawn specialist agents via Task in parallel: - Look up the system category in the routing table (Section 6 of this skill) - Spawn the Primary Agent AND Supporting Agent(s) listed for this category @@ -494,6 +509,11 @@ table. A formula without defined variables cannot be implemented without guesswo - Should scaling be linear, logarithmic, or stepped? - What should the output ranges be at early/mid/late game? +**Review mode check** (apply before spawning): +- `solo` → skip this agent spawn. Draft the section without the specialist. Add a note: "`systems-designer` not consulted — Solo mode. Review manually before production." +- `lean` → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent. +- `full` → spawn as described below. + **Agent delegation (MANDATORY)**: Before proposing any formulas or balance values, spawn specialist agents via Task in parallel: - **Always spawn `systems-designer`**: provide Core Rules from Section C, tuning goals from user, balance context from dependency GDDs. Ask them to propose formulas with variable tables and output ranges. - **For economy/cost systems, also spawn `economy-designer`**: provide placement costs, upgrade cost intent, and progression goals. Ask them to validate cost curves and ratios. @@ -526,6 +546,11 @@ design question, not a specification. - What happens when two rules apply at the same time? - What happens if a player finds an unintended interaction? (Identify degenerate strategies) +**Review mode check** (apply before spawning): +- `solo` → skip this agent spawn. Draft the section without the specialist. Add a note: "`systems-designer` not consulted — Solo mode. Review manually before production." +- `lean` → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent. +- `full` → spawn as described below. + **Agent delegation (MANDATORY)**: Spawn `systems-designer` via Task before finalising edge cases. Provide: the completed Sections C and D, and ask them to identify edge cases from the formula and rule space that the main session may have missed. For narrative systems, also spawn `narrative-director`. Present their findings and ask the user which to include. **Cross-reference**: Check edge cases against dependency GDDs. If a dependency @@ -582,6 +607,11 @@ Include at least: one criterion per core rule from Section C, and one per formul from Section D. Do NOT write "the system works as designed" — every criterion must be independently verifiable by a QA tester without reading the GDD. +**Review mode check** (apply before spawning): +- `solo` → skip this agent spawn. Draft the section without the specialist. Add a note: "`qa-lead` not consulted — Solo mode. Review manually before production." +- `lean` → skip unless this is a section with HIGH implementation risk (Sections D and H only). For other sections, draft without the agent. +- `full` → spawn as described below. + **Agent delegation (MANDATORY)**: Spawn `qa-lead` via Task before finalising acceptance criteria. Provide: the completed GDD sections C, D, E, and ask them to validate that the criteria are independently testable and cover all core rules and formulas. Surface any gaps or untestable criteria to the user. **Questions to ask**: @@ -731,7 +761,7 @@ After the GDD is complete (and optionally reviewed): Ask: "May I update the systems index at `design/gdd/systems-index.md`?" -### 5d: Update Session State +### 5e: Update Session State Update `production/session-state/active.md` with: - Task: [system-name] GDD @@ -740,7 +770,7 @@ Update `production/session-state/active.md` with: - Sections: All 8 written - Next: [suggest next system from design order] -### 5e: Suggest Next Steps +### 5f: Suggest Next Steps Use `AskUserQuestion`: - "What's next?" diff --git a/.claude/skills/dev-story/SKILL.md b/.claude/skills/dev-story/SKILL.md index cbf4fbe..13624ff 100644 --- a/.claude/skills/dev-story/SKILL.md +++ b/.claude/skills/dev-story/SKILL.md @@ -4,6 +4,7 @@ description: "Read a story file and implement it. Loads the full context (story, argument-hint: "[story-path]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Bash, Task, AskUserQuestion +model: sonnet --- # Dev Story @@ -44,7 +45,7 @@ If not found, ask: "Which story are we implementing?" Glob | File | Path | If missing | |------|------|------------| -| TR registry | `docs/architecture/tr-registry.yaml` | **STOP** — "TR registry not found. Run `/create-epics` to generate it." | +| TR registry | `docs/architecture/tr-registry.yaml` | **STOP** — "TR registry not found at `docs/architecture/tr-registry.yaml`. Run `/architecture-review` to bootstrap the registry from your GDDs and ADRs." | | Governing ADR | path from story's ADR field | **STOP** — "ADR file [path] not found. Run `/architecture-decision` to create it, or correct the filename in the story's ADR field." | | Control manifest | `docs/architecture/control-manifest.md` | **WARN and continue** — "Control manifest not found — layer rules cannot be checked. Run `/create-control-manifest`." | @@ -91,7 +92,7 @@ If they differ, use `AskUserQuestion` before proceeding: - `[C] Stop here — I want to review the manifest diff first` If [A]: edit the story file's `Manifest Version:` field to the current manifest date before spawning the programmer. Then read the manifest carefully for new rules. -If [B]: read the manifest carefully for new rules anyway, and note the version mismatch in the Phase 6 summary under "Deviations". +If [B]: edit the story file's `Manifest Version:` field to the current manifest date AND add a `Manifest-Note: Proceeded with old manifest rules on [date] — non-compliance risk accepted.` line to the story header. Read the manifest for new rules anyway. Note the decision in the Phase 6 summary under "Deviations". `/story-done` will include the Manifest-Note in its deviations section without re-checking staleness. If [C]: stop. Do not spawn any agent. Let the user review and re-run `/dev-story`. ### Dependency validation @@ -122,6 +123,14 @@ Read `.claude/docs/technical-preferences.md`: - Performance budgets (frame budget, memory ceiling) - Forbidden patterns +### Mark Story In Progress + +Silently update two things before spawning any agent: + +1. **`production/sprint-status.yaml`** (if it exists): find the entry matching this story's file path and set `status: in_progress`. Update the top-level `updated` field to today's date. If the file does not exist, skip silently. + +2. **The story file itself**: edit the `Last Updated:` field in the story header to today's date (format: `YYYY-MM-DD`). If the field does not exist in the story header, add it after the `Status:` line. This enables sprint-status staleness detection for this story. + --- ## Phase 3: Route to the Right Programmer @@ -167,15 +176,16 @@ assumptions about post-cutoff engine APIs that need expert verification. Spawn the chosen programmer agent(s) via Task with the full context package: -Provide the agent with: -1. The complete story file content -2. The current GDD requirement text (from TR registry) -3. The ADR Decision + Implementation Guidelines (verbatim — do not summarise) -4. The control manifest rules for this layer -5. The engine naming conventions and performance budgets -6. Any engine-specific notes from the ADR Engine Compatibility section -7. The test file path that must be created -8. Explicit instruction: **implement this story and write the test** +Brief the agent with file paths and targeted reading instructions — do not serialize document content into the Task prompt. The agent reads what it needs directly: + +1. **Story file**: `[story-path]` — read in full +2. **GDD requirement**: look up TR-ID `[TR-XXX-NNN]` in `docs/architecture/tr-registry.yaml` — use the `requirement` field as source of truth +3. **ADR**: `docs/architecture/[adr-file].md` — read the **Decision** and **Implementation Guidelines** sections only +4. **Control manifest**: `docs/architecture/control-manifest.md` — read rules for the **[layer]** layer only +5. **Engine preferences**: `.claude/docs/technical-preferences.md` — read naming conventions and performance budgets +6. **Test file path**: `[path from story's Test Evidence section]` — this file must be created as part of implementation +7. **Test requirement** (Logic and Integration stories only): The test file MUST be created at `[path from the story's Test Evidence section]`. Write the test alongside the implementation — do not defer it. The story cannot be closed via `/story-done` without this file present. Each acceptance criterion must have at least one test function covering it. Test file naming: `[system]_[feature]_test.[ext]`. Function naming: `test_[scenario]_[expected_outcome]`. No random seeds, no time-dependent assertions, no external I/O. +8. **Explicit instruction**: implement this story following the ADR guidelines, respect the manifest rules, stay within the story's Out of Scope boundaries. Write clean, doc-commented public APIs. The agent should: - Create or modify files in `src/` following the ADR guidelines @@ -198,29 +208,19 @@ check happens in `/story-done` via manual confirmation. --- -## Phase 5: Write the Test +## Phase 5: Test Evidence Requirements -For **Logic** and **Integration** stories, the test must be written as part of -this implementation — not deferred to later. +The test requirement was included in the Phase 4 programmer agent brief (item 7). This phase summarizes what evidence each story type requires — used when collecting the Phase 6 summary. -Remind the programmer agent: +| Story Type | Required Evidence | Notes | +|---|---|---| +| **Logic** | Automated unit test at path from story's Test Evidence section | BLOCKING — included in Phase 4 agent brief | +| **Integration** | Integration test OR documented playtest record | BLOCKING — included in Phase 4 agent brief | +| **Visual/Feel** | Evidence doc at `production/qa/evidence/[slug]-evidence.md` | ADVISORY — note in Phase 6 summary | +| **UI** | Manual walkthrough doc or interaction test | ADVISORY — note in Phase 6 summary | +| **Config/Data** | None — smoke check serves as evidence | N/A | -> "The test file for this story is required at: `[path from Test Evidence section]`. -> The story cannot be closed via `/story-done` without it. Write the test -> alongside the implementation, not after." - -Test requirements (from coding-standards.md): -- File name: `[system]_[feature]_test.[ext]` -- Function names: `test_[scenario]_[expected_outcome]` -- Each acceptance criterion must have at least one test function covering it -- No random seeds, no time-dependent assertions, no external I/O -- Test the formula bounds from the GDD Formulas section - -For **Visual/Feel** and **UI** stories: no automated test. Remind the agent to -note in the implementation summary what manual evidence will be needed: -"Evidence doc required at `production/qa/evidence/[slug]-evidence.md`." - -For **Config/Data** stories: no test file. A smoke check will serve as evidence. +For Visual/Feel and UI stories, include in the Phase 6 summary: "Manual evidence required at `production/qa/evidence/[slug]-evidence.md` before this story can be fully closed." --- @@ -252,6 +252,8 @@ Present a concise implementation summary: **Engine risks flagged**: [None] or [specialist finding] **Blockers**: [None] or [describe] +**Before running `/story-done`:** run your test suite locally and confirm the tests you wrote pass. `/story-done` will re-run them automatically, but a failing test discovered there means returning to implementation context. + Ready for: `/code-review [file1] [file2]` then `/story-done [story-path]` ``` diff --git a/.claude/skills/estimate/SKILL.md b/.claude/skills/estimate/SKILL.md index f1a6068..042a2d7 100644 --- a/.claude/skills/estimate/SKILL.md +++ b/.claude/skills/estimate/SKILL.md @@ -4,6 +4,7 @@ description: "Estimates task effort by analyzing complexity, dependencies, histo argument-hint: "[task-description]" user-invocable: true allowed-tools: Read, Glob, Grep +model: sonnet --- ## Phase 1: Understand the Task diff --git a/.claude/skills/gate-check/SKILL.md b/.claude/skills/gate-check/SKILL.md index 9625dbb..8feb8f6 100644 --- a/.claude/skills/gate-check/SKILL.md +++ b/.claude/skills/gate-check/SKILL.md @@ -66,6 +66,11 @@ Note: in `solo` mode, director spawns (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GA - [ ] Game pillars defined (in concept doc or `design/gdd/game-pillars.md`) - [ ] Visual Identity Anchor section exists in `design/gdd/game-concept.md` (from brainstorm Phase 4 art-director output) +**Recommended (not blocking):** +- [ ] Concept prototype exists in `prototypes/` with a REPORT.md showing PROCEED verdict + (`/prototype [core-mechanic]`) — skipping this means GDDs may be written for an + idea that hasn't been played. Acceptable if the concept is proven by other means. + **Quality Checks:** - [ ] Game concept has been reviewed (`/design-review` verdict not MAJOR REVISION NEEDED) - [ ] Core loop is described and understood @@ -104,7 +109,7 @@ Note: in `solo` mode, director spawns (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GA - [ ] CI/CD test workflow exists at `.github/workflows/tests.yml` (or equivalent) - [ ] At least one example test file exists to confirm the framework is functional - [ ] Master architecture document exists at `docs/architecture/architecture.md` -- [ ] Architecture traceability index exists at `docs/architecture/architecture-traceability.md` +- [ ] Architecture traceability index exists at `docs/architecture/requirements-traceability.md` - [ ] `/architecture-review` has been run (a review report file exists in `docs/architecture/`) - [ ] `design/accessibility-requirements.md` exists with accessibility tier committed - [ ] `design/ux/interaction-patterns.md` exists (pattern library initialized, even if minimal) @@ -139,22 +144,23 @@ A depends on B). If any cycle is detected (e.g. A→B→A, or A→B→C→A): ### Gate: Pre-Production → Production **Required Artifacts:** -- [ ] At least 1 prototype in `prototypes/` with a README +- [ ] Vertical slice exists in `prototypes/` with a REPORT.md (run `/vertical-slice`) — **recommended, not blocking**; if absent, surface as CONCERNS - [ ] First sprint plan exists in `production/sprints/` - [ ] Art bible is complete (all 9 sections) and AD-ART-BIBLE sign-off verdict is recorded in `design/art/art-bible.md` -- [ ] Character visual profiles exist for key characters referenced in narrative docs +- [ ] Entity inventory exists at `design/assets/entity-inventory.md` (recommended — run `/asset-spec` with no arguments to generate collaboratively from GDDs + art bible) - [ ] All MVP-tier GDDs from systems index are complete - [ ] Master architecture document exists at `docs/architecture/architecture.md` - [ ] At least 3 ADRs covering Foundation-layer decisions exist in `docs/architecture/` +- [ ] All Foundation and Core layer ADRs have status `Accepted` (not `Proposed`) — stories cannot be unblocked until their governing ADR is accepted - [ ] Control manifest exists at `docs/architecture/control-manifest.md` (generated by `/create-control-manifest` from Accepted ADRs) - [ ] Epics defined in `production/epics/` with at least Foundation and Core layer epics present (use `/create-epics layer: foundation` and `/create-epics layer: core` to create them, then `/create-stories [epic-slug]` for each epic) -- [ ] Vertical Slice build exists and is playable (not just scope-defined) -- [ ] Vertical Slice has been playtested with at least 3 sessions (internal OK) -- [ ] Vertical Slice playtest report exists at `production/playtests/` or equivalent +- [ ] Vertical Slice build exists and is playable (not just scope-defined) — **recommended, not blocking**; if absent, surface as CONCERNS +- [ ] Vertical Slice has been playtested with at least 1 documented session — **recommended, not blocking**; if absent, surface as CONCERNS +- [ ] Vertical Slice playtest report exists at `production/playtests/` or equivalent — **recommended, not blocking**; if absent, surface as CONCERNS - [ ] UX specs exist for key screens: main menu, core gameplay HUD (at `design/ux/`), pause menu - [ ] HUD design document exists at `design/ux/hud.md` (if game has in-game HUD) - [ ] All key screen UX specs have passed `/ux-review` (verdict APPROVED or NEEDS REVISION accepted) @@ -174,15 +180,19 @@ A depends on B). If any cycle is detected (e.g. A→B→A, or A→B→C→A): (run `/review-all-gdds` and `/architecture-review` if not done recently) - [ ] **Core fantasy is delivered** — at least one playtester independently described an experience that matches the Player Fantasy section of the core system GDDs (without being prompted). -**Vertical Slice Validation** (FAIL if any item is NO): +**Vertical Slice Validation** (only run these checks if a Vertical Slice was built): - [ ] A human has played through the core loop without developer guidance - [ ] The game communicates what to do within the first 2 minutes of play - [ ] No critical "fun blocker" bugs exist in the Vertical Slice build - [ ] The core mechanic feels good to interact with (this is a subjective check — ask the user) -> **Note**: If any Vertical Slice Validation item is FAIL, the verdict is automatically FAIL -> regardless of other checks. Advancing without a validated Vertical Slice is the #1 cause of -> production failure in game development (per GDC postmortem data from 155 projects). +> **Verdict rules for Vertical Slice:** +> - **Slice was built AND any validation item is NO** → verdict is automatically FAIL. A broken +> or unfun vertical slice should not advance to Production. +> - **Slice was not built (skipped)** → downgrade to CONCERNS only, not FAIL. Surface the risk +> clearly: "Advancing without a validated Vertical Slice increases the risk of late-stage design +> pivots. Recommended before committing full production scope." The user decides. +> - Skipping is a valid solo dev or time-constrained call. Shipping a broken one is not. --- @@ -196,6 +206,7 @@ A depends on B). If any cycle is detected (e.g. A→B→A, or A→B→C→A): - [ ] All Logic stories from this sprint have corresponding unit test files in `tests/unit/` - [ ] Smoke check has been run with a PASS or PASS WITH WARNINGS verdict — report exists in `production/qa/` - [ ] QA plan exists in `production/qa/` (generated by `/qa-plan`) covering this sprint or final production sprint +- [ ] At least one QA plan exists in `production/qa/` covering this production phase — run `/qa-plan` if missing (CONCERNS — advisory, not blocking) - [ ] QA sign-off report exists in `production/qa/` (generated by `/team-qa`) with verdict APPROVED or APPROVED WITH CONDITIONS - [ ] At least 3 distinct playtest sessions documented in `production/playtests/` - [ ] Playtest reports cover: new player experience, mid-game systems, and difficulty curve @@ -295,6 +306,13 @@ For items that can't be automatically verified, **ask the user**: ## 4b. Director Panel Assessment +**Apply review mode before spawning any director:** +- `solo` → skip all four directors. Note in output: "Director Panel skipped — Solo mode. Gate verdict based on artifact and quality checks only." Proceed to Phase 5. +- `lean` → spawn all four directors (phase gates always run in lean mode — this is their purpose). +- `full` → spawn all four directors as normal. + +(Review mode was resolved in Phase 1. Use that stored value here.) + Before generating the final verdict, spawn all four directors as **parallel subagents** via Task using the parallel gate protocol from `.claude/docs/director-gates.md`. Issue all four Task calls simultaneously — do not wait for one before starting the next. **Spawn in parallel:** @@ -372,10 +390,12 @@ After drafting the verdict in Phase 5, challenge it before finalising. **Step 1 — Generate 5 challenge questions** designed to disprove the verdict: +> **Tool-action requirement**: At least 2 of the 5 challenge questions below must be answered by re-reading a specific file (Read tool) or re-running a specific check (Grep tool) — not by reflection alone. Mark these with [TOOL ACTION] to indicate a tool was used. + For a **PASS** draft: - "Which quality checks did I verify by actually reading a file, vs. inferring they passed?" -- "Are there MANUAL CHECK NEEDED items I marked PASS without user confirmation?" -- "Did I confirm all listed artifacts have real content, not just empty headers?" +- "Are there MANUAL CHECK NEEDED items I marked PASS without user confirmation? [TOOL ACTION] Re-scan the checklist for any [?] or MANUAL CHECK items." +- "Did I confirm all listed artifacts have real content, not just empty headers? [TOOL ACTION] Re-read the file and check it has non-placeholder content." - "Could any blocker I dismissed as minor actually prevent the phase from succeeding?" - "Which single check am I least confident in, and why?" @@ -441,11 +461,27 @@ Gate passed. What would you like to do next? For **technical-setup PASS**: ``` Gate passed. What would you like to do next? -[A] Start Pre-Production — begin prototyping the Vertical Slice -[B] Write more ADRs first — run /architecture-decision [next-system] -[C] Stop here for this session +[A] Run /create-control-manifest — generate the layer rules manifest from your Accepted ADRs (do this first) +[B] Run /vertical-slice — build the Vertical Slice (do this before writing epics — validate fun first) +[C] Write more ADRs first — run /architecture-decision [next-system] +[D] Stop here for this session ``` +> **Note for technical-setup PASS**: The Pre-Production sequence is deliberately ordered +> to validate fun before committing to detailed planning: +> +> 1. `/create-control-manifest` — extract technical rules from Accepted ADRs (required before epics) +> 2. `/vertical-slice` — build the Vertical Slice **FIRST**, before writing epics or stories +> 3. Playtest → `/playtest-report` — at least 1 session required to pass the Pre-Production gate; 3+ recommended before committing the full team +> 4. `/ux-design [screen]` — UX specs for main menu, core HUD, pause menu (if not done) +> 5. `/create-epics layer:foundation` then `/create-epics layer:core` — plan after fun is validated +> 6. `/create-stories [epic-slug]` for each epic +> 7. `/sprint-plan new` +> +> **Why prototype before epics?** If the prototype reveals the core loop needs to change, +> epics written before that discovery will be partially wrong. Validate fun cheaply first, +> then plan in detail. This is the #1 lesson from GDC postmortem data. + For all other gates, offer the two most logical next steps for that phase plus "Stop here". --- @@ -462,13 +498,7 @@ Based on the verdict, suggest specific next steps: - **Small design change needed?** → `/quick-design` for changes under ~4 hours (bypasses full GDD pipeline) - **No UX specs?** → `/ux-design [screen name]` to author specs, or `/team-ui [feature]` for full pipeline - **UX specs not reviewed?** → `/ux-review [file]` or `/ux-review all` to validate -- **No accessibility requirements doc?** → Use `AskUserQuestion` to offer to create it now: - - Prompt: "The gate requires `design/accessibility-requirements.md`. Shall I create it from the template?" - - Options: `Create it now — I'll choose an accessibility tier`, `I'll create it myself`, `Skip for now` - - If "Create it now": use a second `AskUserQuestion` to ask for the tier: - - Prompt: "Which accessibility tier fits this project?" - - Options: `Basic — remapping + subtitles only (lowest effort)`, `Standard — Basic + colorblind modes + scalable UI`, `Comprehensive — Standard + motor accessibility + full settings menu`, `Exemplary — Comprehensive + external audit + full customization` - - Then write `design/accessibility-requirements.md` using the template at `.claude/docs/templates/accessibility-requirements.md`, filling in the chosen tier. Confirm: "May I write `design/accessibility-requirements.md`?" +- **No accessibility requirements doc?** → run `/ux-design` which creates both `design/accessibility-requirements.md` and `design/ux/interaction-patterns.md` in one step - **No interaction pattern library?** → `/ux-design patterns` to initialize it - **GDDs not cross-reviewed?** → `/review-all-gdds` (run after all MVP GDDs are individually approved) - **Cross-GDD consistency issues?** → fix flagged GDDs, then re-run `/review-all-gdds` @@ -484,9 +514,9 @@ Based on the verdict, suggest specific next steps: - **Stories not implementation-ready?** → `/story-readiness` to validate stories before developers pick them up - **Tests failing?** → delegate to `lead-programmer` or `qa-tester` - **No playtest data?** → `/playtest-report` -- **Less than 3 playtest sessions?** → Run more playtests before advancing. Use `/playtest-report` to structure findings. -- **No Difficulty Curve doc?** → Consider creating one at `design/difficulty-curve.md` before polish -- **No player journey document?** → create `design/player-journey.md` using the player journey template +- **No playtest sessions beyond the minimum?** → Additional sessions give more reliable signal. 3+ total is recommended before committing the full team. Use `/playtest-report` to structure findings. +- **No Difficulty Curve doc?** → Create `design/difficulty-curve.md` from the template at `.claude/docs/templates/difficulty-curve.md` — or use `/quick-design "difficulty curve"` for a guided session. +- **No player journey map?** → Create `design/player-journey.md` from the template at `.claude/docs/templates/player-journey.md` — or author it collaboratively using `/ux-design` Phase 2b. - **Need a quick sprint check?** → `/sprint-status` for current sprint progress snapshot - **Performance unknown?** → `/perf-profile` - **Not localized?** → `/localize` @@ -503,6 +533,10 @@ This skill follows the collaborative design principle: 3. **Present findings**: Show the full checklist with status 4. **User decides**: The verdict is a recommendation — the user makes the final call 5. **Get approval**: "May I write this gate check report to production/gate-checks/?" +6. **Never auto-fix**: If required artifacts are missing, report the FAIL verdict and + name the skill to run (e.g. "run `/test-setup`"). Do NOT create missing files or + re-run the gate automatically. Creating files to manufacture a PASS defeats the + gate's purpose. **Never** block a user from advancing — the verdict is advisory. Document the risks and let the user decide whether to proceed despite concerns. diff --git a/.claude/skills/hotfix/SKILL.md b/.claude/skills/hotfix/SKILL.md index 2efd09d..73243ad 100644 --- a/.claude/skills/hotfix/SKILL.md +++ b/.claude/skills/hotfix/SKILL.md @@ -3,18 +3,28 @@ name: hotfix description: "Emergency fix workflow that bypasses normal sprint processes with a full audit trail. Creates hotfix branch, tracks approvals, and ensures the fix is backported correctly." argument-hint: "[bug-id or description]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion +model: sonnet --- > **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/hotfix`. Do not auto-invoke based on context matching. ## Phase 1: Assess Severity -Read the bug description or ID. Determine severity: +Read the bug description or ID. Assess severity using these criteria: -- **S1 (Critical)**: Game unplayable, data loss, security vulnerability — hotfix immediately -- **S2 (Major)**: Significant feature broken, workaround exists — hotfix within 24 hours -- If severity is S3 or lower, recommend using the normal bug fix workflow instead and stop. +- **S1 (Critical)**: Game unplayable, data loss, security vulnerability +- **S2 (Major)**: Significant feature broken, workaround exists +- **S3 or lower**: Minor issue — normal bug fix workflow applies + +Confirm with `AskUserQuestion`: +- Prompt: "I've assessed this as **[assessed severity]** — [brief rationale]. Confirm severity to proceed:" +- Options: + - `[A] S1 (Critical) — game unplayable, data loss, or security issue` + - `[B] S2 (Major) — significant feature broken, workaround exists` + - `[C] S3 or lower — redirect to normal bug fix workflow` + +If [C]: stop. Verdict: **REDIRECTED** — use the normal bug fix workflow for S3 and below. --- @@ -58,11 +68,20 @@ If yes, write the file, creating the directory if needed. ## Phase 3: Create Hotfix Branch -If git is initialized, create the hotfix branch: +Check whether this is a git repository: -``` -git checkout -b hotfix/[short-name] [release-tag-or-main] -``` +`Bash: git rev-parse --is-inside-work-tree 2>/dev/null` + +If this command fails or returns empty: note "Not a git repository — create the branch manually." and skip branch creation. + +If the check passes, use `AskUserQuestion` before creating the branch: +- Prompt: "Ready to create hotfix branch 'hotfix/[short-name]' from [base-ref]?" +- Options: + - `[A] Yes — create branch` + - `[B] Use a different base ref — I'll specify it` + - `[C] Skip — I'll create the branch myself` + +Only run `git checkout -b hotfix/[short-name] [base-ref]` if user selects [A]. If [B]: ask the user for the base ref, then run the command with that ref. If [C]: skip branch creation and proceed to Phase 4. --- @@ -152,3 +171,10 @@ If VERIFIED FIXED: run `/bug-report close [BUG-ID]` to formally close it. If STILL PRESENT: the hotfix failed — immediately re-open, assess rollback, and escalate. Schedule a post-incident review within 48 hours using `/retrospective hotfix`. + +Use `AskUserQuestion`: +- Prompt: "Hotfix complete. What's the next step?" +- Options: + - `[A] Run /smoke-check to verify the fix` + - `[B] Run /patch-notes to document this hotfix` + - `[C] Stop here` diff --git a/.claude/skills/launch-checklist/SKILL.md b/.claude/skills/launch-checklist/SKILL.md index 46dc237..1dd6442 100644 --- a/.claude/skills/launch-checklist/SKILL.md +++ b/.claude/skills/launch-checklist/SKILL.md @@ -4,6 +4,7 @@ description: "Complete launch readiness validation covering every department: co argument-hint: "[launch-date or 'dry-run']" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet --- > **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/launch-checklist`. Do not auto-invoke based on context matching. diff --git a/.claude/skills/localize/SKILL.md b/.claude/skills/localize/SKILL.md index 8b241bf..505286a 100644 --- a/.claude/skills/localize/SKILL.md +++ b/.claude/skills/localize/SKILL.md @@ -5,6 +5,7 @@ argument-hint: "[scan|extract|validate|status|brief|cultural-review|vo-pipeline| user-invocable: true agent: localization-lead allowed-tools: Read, Glob, Grep, Write, Bash, Task, AskUserQuestion +model: sonnet --- # Localization Pipeline diff --git a/.claude/skills/map-systems/SKILL.md b/.claude/skills/map-systems/SKILL.md index bcbefc1..f69ae1b 100644 --- a/.claude/skills/map-systems/SKILL.md +++ b/.claude/skills/map-systems/SKILL.md @@ -4,6 +4,7 @@ description: "Decompose a game concept into individual systems, map dependencies argument-hint: "[next | system-name] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite, Task +model: sonnet --- When this skill is invoked: @@ -312,10 +313,10 @@ After the systems index is created (or after designing some systems), present ne - "Systems index is written. What would you like to do next?" - [A] Start designing GDDs — run `/design-system [first-system-in-order]` - - [B] Ask a director to review the index first — ask `creative-director` or `technical-director` to validate the system set before committing to 10+ GDD sessions + - [B] Run `/gate-check systems-design` — triggers the CD-SYSTEMS and TD-SYSTEM-BOUNDARY gates automatically for a formal director sign-off on the system set - [C] Stop here for this session -**The director review option ([B]) is worth highlighting**: having a Creative Director or Technical Director review the completed systems index before starting GDD authoring catches scope issues, missing systems, and boundary problems before they're locked in across many documents. It is optional but recommended for new projects. +**The gate-check option ([B]) is worth highlighting**: running `/gate-check systems-design` triggers both the CD-SYSTEMS and TD-SYSTEM-BOUNDARY gates, catching scope issues, missing systems, and boundary problems before they're locked in across many documents. It is optional but recommended for new projects. After any individual GDD is completed: - "Run `/design-review design/gdd/[system].md` in a fresh session to validate quality" diff --git a/.claude/skills/milestone-review/SKILL.md b/.claude/skills/milestone-review/SKILL.md index 06a9191..cf60b95 100644 --- a/.claude/skills/milestone-review/SKILL.md +++ b/.claude/skills/milestone-review/SKILL.md @@ -4,6 +4,7 @@ description: "Generates a comprehensive milestone progress review including feat argument-hint: "[milestone-name|current] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion +model: sonnet --- ## Phase 0: Parse Arguments @@ -117,7 +118,23 @@ Before generating the Go/No-Go recommendation, spawn `producer` via Task using g Pass: milestone name and target date, current completion percentage, blocked story count, velocity data from sprint reports (if available), list of cut candidates. -Present the producer's assessment inline within the Go/No-Go section. The producer's verdict (ON TRACK / AT RISK / OFF TRACK) informs the overall recommendation — do not issue a GO against an OFF TRACK producer verdict without explicit user acknowledgement. +Present the producer's assessment inline within the Go/No-Go section. The producer's verdict (ON TRACK / AT RISK / OFF TRACK) informs the overall recommendation. + +If OFF TRACK, use `AskUserQuestion` before generating the recommendation: +- Prompt: "Producer verdict: OFF TRACK. The milestone is in jeopardy. This review will recommend NO-GO. How do you want to proceed?" +- Options: + - `[A] Accept NO-GO — generate the full review with that recommendation` + - `[B] Override to CONDITIONAL GO — I'll document the accepted risks myself` + - `[C] Stop — I want to address blockers before generating the review` + +If AT RISK, use `AskUserQuestion`: +- Prompt: "Producer verdict: AT RISK. Milestone may slip. How should the Go/No-Go section be framed?" +- Options: + - `[A] CONDITIONAL GO — include producer's conditions in the review` + - `[B] NO-GO — conditions cannot be met in time` + - `[C] GO — I accept the risk and want to proceed` + +Do not issue a GO against an OFF TRACK verdict unless the user explicitly selects [B] above. --- diff --git a/.claude/skills/perf-profile/SKILL.md b/.claude/skills/perf-profile/SKILL.md index 813ca25..68f2166 100644 --- a/.claude/skills/perf-profile/SKILL.md +++ b/.claude/skills/perf-profile/SKILL.md @@ -5,6 +5,7 @@ argument-hint: "[system-name or 'full']" user-invocable: true agent: performance-analyst allowed-tools: Read, Glob, Grep, Bash +model: sonnet --- ## Phase 1: Determine Scope diff --git a/.claude/skills/playtest-report/SKILL.md b/.claude/skills/playtest-report/SKILL.md index 33f981a..cc4c3af 100644 --- a/.claude/skills/playtest-report/SKILL.md +++ b/.claude/skills/playtest-report/SKILL.md @@ -4,6 +4,7 @@ description: "Generates a structured playtest report template or analyzes existi argument-hint: "[new|analyze path-to-notes] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion +model: sonnet --- ## Phase 1: Parse Arguments diff --git a/.claude/skills/propagate-design-change/SKILL.md b/.claude/skills/propagate-design-change/SKILL.md index 801e931..86d50eb 100644 --- a/.claude/skills/propagate-design-change/SKILL.md +++ b/.claude/skills/propagate-design-change/SKILL.md @@ -4,6 +4,7 @@ description: "When a GDD is revised, scans all ADRs and the traceability index t argument-hint: "[path/to/changed-gdd.md]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Bash, Task +model: sonnet agent: technical-director --- diff --git a/.claude/skills/prototype/SKILL.md b/.claude/skills/prototype/SKILL.md index 12f8c8e..c25e3d9 100644 --- a/.claude/skills/prototype/SKILL.md +++ b/.claude/skills/prototype/SKILL.md @@ -1,13 +1,32 @@ --- name: prototype -description: "Rapid prototyping workflow. Skips normal standards to quickly validate a game concept or mechanic. Produces throwaway code and a structured prototype report." -argument-hint: "[concept-description] [--review full|lean|solo]" +description: "Concept prototype — validate the core idea is worth designing before writing GDDs. Run right after /brainstorm and /setup-engine. Routes to HTML, Engine, or Paper path based on game type. Produces a throwaway build and a PROCEED/PIVOT/KILL verdict." +argument-hint: "[concept-description] [--path html|engine|paper] [--review full|lean|solo] [--spike]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion +model: sonnet agent: prototyper isolation: worktree --- +## Purpose + +This is the **concept prototype** — a fast, throwaway build that answers one question: +*"Is this core idea actually fun to interact with?"* + +**Default use** — run right after `/brainstorm` and `/setup-engine`, before writing +GDDs or architecture docs. Its verdict determines whether the concept is worth the +investment of full design documentation. + +**Mid-production?** You can also run this at any stage to test a specific mechanic, +design change, or technical question. Pass `--spike` to activate spike mode: a +lightweight ~4-hour build with no GDD prerequisites and no phase gate implications. + +**Already have GDDs and architecture complete?** To validate the full game loop +before committing to Production, run `/vertical-slice` instead. + +--- + ## Phase 1: Define the Question Resolve the review mode (once, store for all gate spawns this run): @@ -15,33 +34,234 @@ Resolve the review mode (once, store for all gate spawns this run): 2. Else read `production/review-mode.txt` → use that value 3. Else → default to `lean` -See `.claude/docs/director-gates.md` for the full check pattern. +**Check for spike mode:** If `--spike` was passed, skip to the **Spike Mode** section +at the bottom of this skill. -Read the concept description from the argument. Identify the core question this prototype must answer. If the concept is vague, state the question explicitly before proceeding — a prototype without a clear question wastes time. +Otherwise, use `AskUserQuestion` to confirm intent before proceeding: + +- **Prompt**: "How would you like to use this prototype session?" +- **Options**: + - `Prototype this concept` — build a throwaway build to validate the core idea is fun before writing GDDs (1–3 days) + - `Skip — concept already proven` — I have enough evidence this works; log it and proceed directly to design + - `Mid-production spike` — I'm already in Production and want to test a specific mechanic or technical question quickly (~4 hours, no phase gate implications) + +**If "Skip — concept already proven":** +Ask (plain text, not a widget): "What evidence do you have that the concept works?" +Record the one-line answer, then stop. Note: "Concept prototype skipped — evidence: +[answer]." Suggest next step: `/map-systems` or `/design-system [mechanic]`. + +**If "Mid-production spike"**: skip to the **Spike Mode** section below. + +**If "Prototype this concept"**: continue with Phase 1 below. --- -## Phase 2: Load Project Context +**A note on prototype strategy:** The research on successful indie development +is consistent — building 2-3 concept variants and letting the best one win is +far more likely to succeed than iterating one concept until it works. This is +your first prototype, not necessarily your only one. If this prototype produces +a PIVOT verdict, consider whether to refine this concept OR start fresh with a +different angle on the same game idea and prototype that instead. -Read `CLAUDE.md` for project context and the current tech stack. Understand what engine, language, and frameworks are in use so the prototype is built with compatible tooling. +**Game jam as a prototype vehicle:** If you're planning a concept prototype anyway, +consider timing it to a game jam (Ludum Dare, GMTK Game Jam, Global Game Jam). Jams +provide a forced timebox (48-72 hours), instant distribution to thousands of players +who rate and review early builds, and a deadline that prevents scope creep by design. +Many shipped games (Celeste, VVVVVV) began as jam prototypes. Not required — but +worth considering if the timing is right. + +Read the concept description from the argument. Before building anything, define +the **falsifiable hypothesis** this prototype must answer: + +> *"If the player [does X], they will feel [Y] — we will know this is true if [measurable signal Z]."* + +Good: "If the player swings on grapple hooks, traversal will feel fluid — we'll know if +players chain 3+ swings without stopping within 2 minutes of picking it up." + +Bad: "Does this feel fun?" ← not testable, not falsifiable. + +**If the concept is too vague to form a hypothesis, stop here.** Ask the user to +narrow the question before proceeding. A prototype without a clear question wastes time. + +Also ask: **"What is the riskiest assumption in this concept?"** That is the first +thing the prototype should test — not the easiest part, the riskiest. --- -## Phase 3: Plan the Prototype +## Phase 2: Load Concept Context -Define in 3-5 bullet points what the minimum viable prototype looks like: +Read `design/gdd/game-concept.md` if it exists. Extract: +- Core fantasy (what the player is supposed to feel) +- Core loop (the moment-to-moment action being tested) -- What is the core question? -- What is the absolute minimum code needed to answer it? -- What can be skipped (error handling, polish, architecture)? - -Present this plan to the user before building. Ask for confirmation if scope seems unclear. +Read `CLAUDE.md` and `.claude/docs/technical-preferences.md` for the engine and +language in use. --- -## Phase 4: Implement +## Phase 3: Choose the Prototype Path -Ask: "May I create the prototype directory at `prototypes/[concept-name]/` and begin implementation?" +Select the prototype path. If `--path [html|engine|paper]` was passed, use that. +Otherwise, use this quick-reference first, then read the full path details below: + +| Genre | Recommended path | Key reason | +|-------|-----------------|------------| +| Platformer / action / fighter | **Engine** | Feel IS the hypothesis; browser latency produces false results | +| Racing / sports | **Engine** | Same — timing and physics feedback are the point | +| Top-down shooter / twin-stick | **Engine** | Aim feel is timing-sensitive | +| Puzzle (logic) | **HTML** or **Paper** | Timing is not the point; logic and clarity are | +| Card game | **Paper** first | Fastest iteration by hand before touching code | +| Narrative / visual novel | **Paper** (Twine / Ink / Yarn Spinner) | Story is the mechanic — test it without code overhead | +| Strategy / 4X / city builder | **Paper** (spreadsheet sim) | Validate economy and progression rules before building | +| Roguelike (systems-heavy) | **Paper** → Engine | Validate that the ruleset is interesting before building | +| Idle / clicker / incremental | **HTML** | Turn-based logic, no feel sensitivity required | +| Rhythm game | **Paper** first (design levels in audio) | Design levels before the engine exists | +| RPG / open world | **Paper** → Engine | Systems complexity: validate rules, then validate feel | +| Horror / atmospheric | **Engine** | Atmosphere requires real rendering | + +**Rule of thumb:** "Does this feel right?" → Engine. "Are these rules interesting?" → Paper. "Is this logic correct?" → HTML or Paper. + +### Path: HTML (browser-playable) + +**Best for:** Puzzle games, card games, turn-based strategy, word games, idle games, +top-down logic games. Anything where timing precision doesn't matter. + +**Reliability:** ~85–90% one-shot. The agent writes a single self-contained HTML +file the user opens in a browser — no install required. + +**Limitation — browser latency lies about game feel.** Browsers introduce +50–133ms of rendering variance. This makes HTML prototypes fundamentally unreliable +for action games, platformers, fighting games, or anything where input timing, +jump arcs, or collision feel are what you're testing. If feel is the hypothesis, +use the Engine path instead. + +**Alternative tools for this path:** PICO-8 (extreme constraints, great for retro +arcade concepts, web-export in one command), Phaser.js (more capable browser game +framework, still no install needed), or Twine (narrative/choice-based games). +These are faster than raw HTML for their respective genres — suggest them if appropriate. + +**Output:** A single `prototype.html` (or PICO-8/Phaser equivalent) the user opens in any browser. + +**Distribution — the HTML path's biggest advantage:** Unlike Engine prototypes, this +build can reach real players globally in minutes. Use this actively: +- **itch.io** — upload the file, share the link, get play counts and written feedback + within hours. Free. The indie community plays rough builds here without expecting + polish. This is genuine external validation at zero cost. +- **Loom + file share** — share via Google Drive/Dropbox, ask someone to record their + screen + audio with Loom while playing. You get a video of real first-impression + reactions and confusion without synchronous scheduling. +- **r/playmygame or r/WebGames** (Reddit) — active communities that specifically + test early builds and give unsolicited honest feedback. +- **Game dev Discord servers** (GMTK, Brackeys, GameDev.tv) — members test each + other's prototypes routinely; an HTML file is the easiest possible ask. + +--- + +### Path: Engine (engine project) + +**Best for:** Action games, platformers, physics-heavy games, anything where +moment-to-moment feel IS the hypothesis. Use this when HTML latency would lie about +the result. + +**Reliability:** ~50–60% one-shot. Expect 2–4 rounds of iteration — this is +normal, not a failure. + +**Limitation — requires engine installed and running.** This path is a +multi-turn collaborative loop: +1. Agent writes the code +2. User runs it in the engine +3. User reports errors or observations +4. Agent fixes and iterates + +**Sunk cost rule:** If the user has been iterating for more than 2 hours without +reaching a playable state, stop. The scope is too large or the question is wrong. +Reframe the hypothesis and simplify aggressively, or switch to Paper path. + +**Output:** A minimal runnable engine project in `prototypes/[name]-concept/`. + +**Lighter alternative — Love2D (Lua):** If the project engine (Godot, Unity, Unreal) +feels too heavy to stand up for a throwaway build, consider Love2D — a minimal 2D +framework that installs in minutes, requires no project scaffolding, and renders +natively with no browser latency. Used by many indie devs for rapid 2D action and +platformer prototypes (Balatro prototyped in Love2D; Nuclear Throne's early builds +used it). It sits between HTML overhead and full engine overhead: heavier than +opening a browser, lighter than setting up a full engine project. Best for 2D +action/platformer feel validation when the project engine is 3D-first or takes +significant time to configure. + +--- + +### Path: Paper (rules document + play log) + +**Best for:** Strategy games, card games, board game-style mechanics, economy +systems, progression loops, any game where the logic can be simulated by hand. +Works for any genre when you need to validate rules, not feel. + +**Reliability:** 100%. No code, no engine, no install. + +**Limitation — cannot validate moment-to-moment feel.** Paper prototypes prove +that the rules are internally consistent and the decisions are interesting. They +cannot tell you whether jumping feels right or whether explosions feel satisfying. + +**Paper playtest observation protocol (run this with 5+ people):** +1. Brief the rules once. Hand them the rule summary sheet. Then step back. +2. Do NOT explain further. Do NOT help. Do NOT clarify. Confusion is data. +3. Watch silently. Note every moment they slow down, re-read, or ask a question. +4. After the session, ask one question only: "What was confusing?" — not "Did you like it?" +5. Use fresh testers for each iteration. The same person cannot give new first-impression data. +6. If 3+ testers hit the same confusion point, that rule is broken — redesign it before re-testing. + +**Output:** A printable rules document + a completed play log showing one simulated session. + +**Narrative tools for this path:** For dialogue-heavy and story-driven games, skip the +generic rules doc — use a dedicated narrative scripting tool instead: +- **Twine** — zero-code hypertext fiction; ideal for branching structure experiments and choice-impact testing +- **Ink** (Inkle) — plain-text scripting language used in *80 Days*, *Heaven's Vault*, and *Overboard*; exports directly to Unity and Godot +- **Yarn Spinner** — dialogue scripting used in *A Short Hike*, *DREDGE*, and *Night in the Woods*; integrates natively with Unity and Godot + +All three let you write and playtest branching dialogue in minutes. Key metric for +narrative prototypes: **time to first emotional beat** — how many exchanges before +the player feels something? If it takes more than 3-4 exchanges, the opening is too slow. + +--- + +Assess which path best fits the hypothesis, then use `AskUserQuestion` with your +recommendation pre-stated: + +- **Prompt**: "Which prototype path would you like to use? (Based on your concept, I'd recommend [path] — [one sentence reason].)" +- **Options**: + - `HTML — browser prototype` — puzzle, card, turn-based, strategy, idle. Opens by double-clicking, no install. 85–90% reliable. **Not suitable for action games** — browser latency lies about feel. + - `Engine — native prototype` — action, platformer, physics, or anything where feel IS the hypothesis. 50–60% one-shot; 2–4 iteration rounds are normal. Requires engine installed. + - `Paper — rules document + play log` — strategy, economy, logic, board-game-style mechanics. 100% reliable. Cannot validate feel. + +--- + +## Phase 4: Plan the Prototype + +Define in 3–5 bullet points the minimum viable prototype: + +- What is the falsifiable hypothesis? +- What is the riskiest assumption — and how does this prototype test it first? +- What is the absolute minimum needed to answer the question? +- What is explicitly cut? (menus, save systems, error handling, polish, architecture — all of it) + +**Scope constraint:** A concept prototype tests ONE mechanic — not the whole game. +If scope covers more than one mechanic, cut it down. When in doubt, cut more. + +Present this plan to the user before building. Get confirmation before proceeding. + +Once confirmed, write a session checkpoint to `production/session-state/active.md` +(create `production/session-state/` if it does not exist). Include: concept name, +hypothesis, path chosen, scope bullet points, and current phase ("Phase 5 — +Implement"). This lets the next session resume without starting over if the session +ends mid-build — especially important for multi-day Engine path work. + +--- + +## Phase 5: Implement + +Ask: "May I create the prototype directory at `prototypes/[concept-name]-concept/` +and begin implementation?" If yes, create the directory. Every file must begin with: @@ -54,104 +274,306 @@ If yes, create the directory. Every file must begin with: Standards are intentionally relaxed: - Hardcode values freely -- Use placeholder assets -- Skip error handling +- Use placeholder assets (colored rectangles, debug shapes) +- Skip error handling entirely - Use the simplest approach that works - Copy code rather than importing from production +- No architecture, no patterns, no abstractions -Run the prototype. Observe behavior. Collect any measurable data (frame times, interaction counts, feel assessments). +**Do not add polish.** No menus, no game over screens, no music, no tutorial text +unless the tutorial IS the mechanic being tested. Every addition beyond the +hypothesis is waste. + +**Playtesting tip:** If you have access to anyone who hasn't seen the game — +friends, family, strangers online — watching them play without explanation gives +far better signal than testing it yourself. Watch silently; don't guide them. +Confusion is data. Ask one question after: "What was confusing?" Not "Did you +like it?" + +**No external testers available?** Use rotation: if you built system A, you're a +naive tester for system B. In a two-person team this works well. Solo developer? +Step away for 2-3 days before playing fresh — you won't have perfect first-impression +signal, but you'll surface the worst blockers. Another option: play your own +prototype as a speedrun (force yourself through it in 5 minutes without stopping +to fix things) — the friction you feel is what strangers will hit. + +**Want more granular UX data?** Ask the tester to **think aloud** as they play — +narrate their thoughts in real time: "I'm pressing space... nothing happened... is +that the jump key?" This surfaces confusion the moment it happens rather than +waiting for a post-play debrief. Best for UI/UX and onboarding clarity. Silent +observation is still better for testing raw feel; think-aloud changes how people +play slightly but gives much richer data about why they're confused. + +**HTML prototype?** itch.io, Reddit (r/playmygame), and Discord (GMTK, Brackeys) +let you reach strangers today at zero cost — see the distribution options in the +HTML path section above. + +**Testing AI, NPC, or complex system behavior before writing the code?** Use the +**Wizard of Oz** technique: one person plays normally while a second person secretly +controls the NPC, enemy, or system behavior in real time — making the decisions a +human would make, not an algorithm. The player believes it's automated. This lets +you validate whether your AI design *feels right* before writing a single line of +pathfinding or decision tree code. When you observe what responses the human +controller naturally produces, you learn exactly what the AI needs to do. + +### Engine path: multi-turn loop + +After writing the initial code: + +> "The prototype files are written. Run the project in your engine now. +> If there are errors, paste them here and I'll fix them. If it runs, +> describe what you see and whether it feels like it's answering the question." + +Iterate until the prototype is playable. Each loop: +1. User runs → reports errors or observations +2. Agent fixes errors or adjusts the mechanic +3. Repeat until playable or sunk cost rule triggers + +### HTML path: single output + +Write a single `prototype.html` to `prototypes/[concept-name]-concept/`. Include +all styles, logic, and assets inline. The file must be openable by double-clicking +with no server required. + +### Paper path: document + log + +Write `prototypes/[concept-name]-concept/rules.md` (the game rules) and +`prototypes/[concept-name]-concept/play-log.md` (a simulated session walking +through one complete play cycle step by step with dice rolls, decisions, and +outcomes narrated). --- -## Phase 5: Generate Prototype Report +## Phase 6: Playtest Debrief -Draft the report: +The prototype is built. Now hand it to the user and capture what they actually +experienced. Do NOT skip to report generation — the report is only as good as the +observations you collect here. -```markdown -## Prototype Report: [Concept Name] +**For HTML path:** Say exactly this: +> "The prototype is ready. Open `prototypes/[name]-concept/prototype.html` in your +> browser and play it. Take as long as you need. Don't rush through it — try to +> approach it the way a new player would. Come back here when you're done." -### Hypothesis -[What we expected to be true -- the question we set out to answer] +**For Engine path:** The multi-turn iteration loop already captured errors and +behavior. Now ask for the overall assessment: +> "Now that it's running — play through it a few times as if you're the player, +> not the developer. Come back when you have a feel for it." -### Approach -[What we built, how long it took, what shortcuts we took] +**For Paper path:** Say exactly this: +> "Read through `prototypes/[name]-concept/rules.md` and walk through the +> `play-log.md` as if you're playing it for the first time. If you have someone +> nearby, try running the rules with them. Come back when you've seen at least one +> full play cycle." -### Result -[What actually happened -- specific observations, not opinions] +Once the user returns, ask these questions **one at a time** — wait for each answer +before asking the next: -### Metrics -[Any measurable data collected during testing] -- Frame time: [if relevant] -- Feel assessment: [subjective but specific -- "response felt sluggish at - 200ms delay" not "felt bad"] -- Player action counts: [if relevant] -- Iteration count: [how many attempts to get it working] +1. **Hypothesis check:** + > "The hypothesis was: [restate the hypothesis from Phase 1]. Did it hold up — + > CONFIRMED, PARTIALLY CONFIRMED, or REFUTED? Tell me what you saw." -### Recommendation: [PROCEED / PIVOT / KILL] +2. **Best moment:** + > "What was the moment — if any — where it felt like it was working? Be specific." -[One paragraph explaining the recommendation with evidence] +3. **Worst moment:** + > "What was the most frustrating, confusing, or broken moment? Be specific — + > not 'it felt slow' but 'the jump took about half a second to respond and it + > felt like I was fighting the controls'." -### If Proceeding -[What needs to change for a production-quality implementation] -- Architecture requirements -- Performance targets -- Scope adjustments from the original design -- Estimated production effort +4. **Surprise:** + > "Did anything happen that you didn't expect — good or bad?" -### If Pivoting -[What alternative direction the results suggest] +5. **Verdict:** + > "PROCEED, PIVOT, or KILL — and one sentence why." -### If Killing -[Why this concept does not work and what we should do instead] +Collect all answers before moving to report generation. If any answer is vague +("it felt fine", "pretty good"), ask a follow-up: "Can you be more specific? +What exactly felt fine about it?" Precise observations make the report useful. +Vague ones make it useless. -### Lessons Learned -[Discoveries that affect other systems or future work] +--- + +## Phase 7: Generate Prototype Report + +Read `.claude/docs/templates/prototype-report.md` to get the report structure. +Fill in every section based on what was observed during this session. Replace all +placeholder text with real observations — no generic filler. + +Ask: "May I write this report to `prototypes/[concept-name]-concept/REPORT.md`?" + +If yes, write the file. Then update `prototypes/index.md` (create if it does not +exist) — append one row to the concept prototype table: concept name, date, path +used, verdict (PROCEED/PIVOT/KILL), and a link to the REPORT.md. If a PIVOT chain +exists (prior PIVOT-NOTE.md in a related concept folder), note the chain. This file +is the project's complete history of what was tried and what was learned. + +--- + +## Phase 8: Creative Director Review + +**Review mode check:** +- `solo` → skip. Note: "CD-PLAYTEST skipped — Solo mode." +- `lean` → skip. Note: "CD-PLAYTEST skipped — Lean mode." +- `full` → spawn `creative-director` via Task using gate **CD-PLAYTEST** if + `design/gdd/game-concept.md` exists with game pillars defined. If pillars are + not yet defined, note: "CD-PLAYTEST skipped — game pillars not yet defined at + concept prototype stage." + +Pass: the full REPORT.md content, the original hypothesis, and game pillars / +core fantasy from `design/gdd/game-concept.md`. + +The creative director evaluates the result against the game's creative vision and +confirms, modifies, or overrides the recommendation. Their verdict is final. Update +REPORT.md if the verdict differs. + +--- + +## Phase 9: Summary and Next Steps + +Output a summary: the hypothesis, the result, and the final recommendation. +Link to `prototypes/[concept-name]-concept/REPORT.md`. + +**If PROCEED:** +Your concept prototype validated the core idea. Now design it properly, informed by +what you just learned. + +Recommended path (in order): +1. `/design-review design/gdd/game-concept.md` — validate the concept doc against what the prototype revealed +2. `/gate-check` — confirm readiness to advance to Systems Design +3. `/art-bible` — define visual identity (optional but worth doing before GDDs) +4. `/map-systems` — decompose the concept into all game systems +5. `/design-system [mechanic]` — GDD for each MVP system; use prototype learnings + in the Tuning Knobs and Formulas sections +6. `/review-all-gdds` — cross-system consistency check + +**Note:** If you used the HTML path and feel is still uncertain, consider running +a quick engine path prototype targeting feel before writing GDDs. + +**If PIVOT:** + +Before routing to the next prototype, capture the carry-forward note. Ask these +two questions (plain text, one at a time): + +1. "What specifically worked in this prototype that we should preserve in the next version?" +2. "What is the single most important thing to change?" + +Ask: "May I write this to `prototypes/[concept-name]-concept/PIVOT-NOTE.md`?" + +If yes, write the file with: original hypothesis, what to keep, what to change, and +the revised hypothesis for the next prototype. When `/prototype` is next run, check +`prototypes/` for any `PIVOT-NOTE.md` files — if found, read them and use the +revised hypothesis as the starting point rather than forming one from scratch. + +- Run `/prototype [revised-concept]` to test the adjusted direction +- Or `/brainstorm [hint]` if the concept needs more fundamental rethinking + +**If KILL:** + +Before moving on, run this check to confirm the verdict is sound and not temporary frustration: + +- [ ] Core mechanic still unclear to testers after 2+ playtests? +- [ ] No "fun moment" (smile, laugh, or retry by choice) observed in any session? +- [ ] 3+ PIVOT iterations on the same concept with no clear improvement? +- [ ] Concept only works when heavily explained or when the dev guides the player? +- [ ] Building this feels like obligation, not excitement? + +If 2+ boxes apply → KILL verdict is sound. If 0–1 apply → consider one more focused PIVOT before killing. + +**Document the kill in `prototypes/GRAVEYARD.md`** (create if it doesn't exist). +Ask: "May I append this concept to `prototypes/GRAVEYARD.md`?" If yes, add one entry: + +``` +## [Concept Name] — YYYY-MM-DD +- **Kill reason:** [specific blocker — not "it was boring" but "players never understood the core action"] +- **What worked:** [2-3 things worth carrying forward to future concepts] +- **What failed:** [the specific mechanic, design decision, or scope issue] +- **Next time:** [one explicit action to try differently on a similar concept] ``` -Ask: "May I write this report to `prototypes/[concept-name]/REPORT.md`?" +This file exists so the same mistake doesn't get made twice on the next concept. -If yes, write the file. +- Run `/brainstorm open` or `/brainstorm [new-hint]` to explore a different concept +- The prototype report is the deliverable — no further action needed --- -## Phase 6: Creative Director Review - -**Review mode check** — apply before spawning CD-PLAYTEST: -- `solo` → skip. Note: "CD-PLAYTEST skipped — Solo mode." Proceed to Phase 7 summary with the prototyper's recommendation as the final verdict. -- `lean` → skip (not a PHASE-GATE). Note: "CD-PLAYTEST skipped — Lean mode." Proceed to Phase 7 summary with the prototyper's recommendation as the final verdict. -- `full` → spawn as normal. - -Spawn `creative-director` via Task using gate **CD-PLAYTEST** (`.claude/docs/director-gates.md`). - -Pass: the full REPORT.md content, the original design question, game pillars and core fantasy from `design/gdd/game-concept.md` (if it exists). - -The creative director evaluates the prototype result against the game's creative vision and pillars, then confirms, modifies, or overrides the prototyper's PROCEED / PIVOT / KILL recommendation. Their verdict is final. Update the REPORT.md `Recommendation` section if the creative director's verdict differs from the prototyper's. - --- -## Phase 7: Summary and Next Steps +## Spike Mode -Output a summary to the user: the core question, the result, the prototyper's initial recommendation, and the creative-director's final decision. Link to the full report at `prototypes/[concept-name]/REPORT.md`. +**Triggered by:** `--spike` flag OR "Mid-production spike" entry choice in Phase 1. -If **PROCEED**: run `/design-system` to begin the production GDD for this mechanic, or `/architecture-decision` to record key technical decisions before implementation. +**Purpose:** Test a specific technical or design question mid-production, without +the overhead of a full concept prototype workflow. No GDD prerequisites. No phase +gate implications. Hard cap: ~4 hours. -If **PIVOT** or **KILL**: no further action needed — the prototype report is the deliverable. +**When to use:** +- You're in Production and want to test whether a new mechanic should be added +- You're unsure if a technical approach will work before building it properly +- A design change is being considered and you want a quick before/after comparison +- A GDD system is proving harder than expected and you want to prototype the hard part +- You need to confirm target hardware can sustain the required framerate before writing gameplay code (**performance spike** — see below) -Verdict: **COMPLETE** — prototype finished. Recommendation is PROCEED, PIVOT, or KILL based on findings above. +**Spike Mode workflow (replaces Phases 1–9):** + +1. **Define the spike question** (plain text, not a widget): "What specific question does this spike answer? Give me one sentence: 'Can we [do X] using [approach Y]?'" + +2. **Choose path** — same AskUserQuestion widget as Phase 3 (HTML / Engine / Paper). + +3. **Scope** — maximum 2-3 bullet points. One mechanic, one technical question, nothing else. + +4. **Build** — same relaxed standards as concept prototype. Hard cap: 4 hours. If not demonstrable in 4 hours, the question is too large. Split it. + +5. **Observe and decide** — no formal playtest debrief. Ask: "Did the spike answer the question? YES or NO, and why in one sentence." + +6. **Write a spike note** (not a full report) to `prototypes/[concept-name]-spike-[date]/SPIKE-NOTE.md`: + - Question tested + - Result (YES it works / NO it doesn't / PARTIAL — needs more investigation) + - What to do next (add to current sprint / investigate further / abandon the idea) + +7. **Update `production/session-state/active.md`** to clear the spike and return to the current sprint state. + +**No CD gate. No phase gate. No PROCEED/PIVOT/KILL.** Spike results inform decisions; they don't make them. The developer decides whether to add the mechanic/approach to the sprint backlog based on what the spike revealed. + +**Performance spike (special case):** If the game involves demanding rendering — +large open worlds, hundreds of simultaneous physics bodies, heavy particle systems, +complex shaders — run a performance spike before writing gameplay code to confirm +the target hardware can sustain the required framerate. This is distinct from other +spikes in two ways: +- The question is "can the engine render [scene X] at 60fps on [minimum spec hardware]?" + not "does this mechanic feel good?" +- The output is a benchmark number, not a feel verdict +- No gameplay logic is needed — just the maximum intended scene load (terrain, draw + calls, physics objects, particles) running at once +- Build time stays within the ~4-hour cap; the spike is setting up the rendering + load, not the game +- If the answer is NO at this scope, this is an architecture or scope constraint + that affects everything downstream — better to surface it now than during Sprint 8 + +--- ### Important Constraints - Prototype code must NEVER import from production source files - Production code must NEVER import from prototype directories -- If the recommendation is PROCEED, the production implementation must be written from scratch — prototype code is not refactored into production -- Total prototype effort should be timeboxed to 1-3 days equivalent of work -- If the prototype scope starts growing, stop and reassess whether the question can be simplified - ---- - -## Recommended Next Steps - -- **If PROCEED**: Run `/design-system [mechanic]` to author the production GDD, or `/architecture-decision` to record key technical decisions before implementation -- **If PIVOT**: Run `/prototype [revised-concept]` to test the adjusted direction -- **If KILL**: No further action required — the prototype report is the deliverable -- Run `/playtest-report` to formally document any playtest sessions conducted during prototyping +- If the recommendation is PROCEED, production implementation is written from + scratch — prototype code is never refactored into production +- Total effort is hard-capped at 1 day (concept prototypes test one mechanic) +- Test ONE mechanic — if scope grows, stop and simplify the question +- No polish. No menus, no game over, no music, no UI unless it IS the mechanic +- If stuck after 2 hours of engine iteration, reframe the question or switch paths +- **3 PIVOT iterations → force a KILL decision.** If this is the third time the + same concept has produced a PIVOT verdict, the concept likely doesn't work. + Ask: "Is this the right idea, or am I in the sunk cost trap?" A new concept + prototyped fresh will almost always beat a fourth iteration of a struggling one. +- Building 2-3 different concept variants and picking the best one is a healthier + strategy than iterating one concept to death. Natural selection between prototypes + beats willpower. +- **Networked/multiplayer games:** A local prototype cannot validate the feel of a + networked mechanic. Latency fundamentally changes how combat, movement, and + prediction feel — a prototype running at 0ms local will feel entirely different at + 80ms network delay. Use a local prototype to validate that the mechanic is + *interesting*. Do not use it as evidence that it *feels good* under real network + conditions. Network feel requires real peers or simulated latency (e.g., throttle + tools, network condition simulators). diff --git a/.claude/skills/qa-plan/SKILL.md b/.claude/skills/qa-plan/SKILL.md index 054edf3..0e6c52b 100644 --- a/.claude/skills/qa-plan/SKILL.md +++ b/.claude/skills/qa-plan/SKILL.md @@ -4,6 +4,7 @@ description: "Generate a QA test plan for a sprint or feature. Reads GDDs and st argument-hint: "[sprint | feature: system-name | story: path]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, AskUserQuestion +model: sonnet agent: qa-lead --- @@ -68,9 +69,12 @@ After reading stories, load supporting context once (not per story): - `design/gdd/systems-index.md` — to understand system priorities and which GDDs are approved -- For each unique GDD referenced across all stories: read only the - **Acceptance Criteria** and **Formulas** sections. Do not load full GDD text — - these two sections contain the testable requirements and the math to verify. +- For each unique GDD referenced across all stories: read the + **Acceptance Criteria**, **Formulas**, and **Edge Cases** sections. Do not load + the full GDD text. These three sections contain the testable requirements, the math + to verify, and the boundary conditions that tests must cover. If an Edge Cases + section is absent from the GDD, note it per GDD: "No Edge Cases section found — edge + case coverage will be inferred from acceptance criteria only." - `docs/architecture/control-manifest.md` — scan for forbidden patterns that automated tests should guard against (if the file exists) @@ -81,9 +85,10 @@ The story will be classified using acceptance criteria alone. ## Phase 3: Classify Each Story -For each story, assign a Story Type. If the story already has a `Type:` field -in its header, use that value and validate it against the criteria below. If the -field is missing or ambiguous, infer the type from the acceptance criteria. +For each story, assign a Story Type: + +- **If the story already has a `Type:` field in its header**: accept it as-is. Do NOT re-classify or validate against the criteria below — the Type was set by lead-programmer at story creation and is authoritative. Record it as-is. +- **If the `Type:` field is missing**: infer the type from the acceptance criteria using the table below, and note in the report that the type was inferred (not declared). Flag this as a gap — the story should have its Type declared explicitly before implementation begins. | Story Type | Classification Indicators | |---|---| @@ -226,11 +231,19 @@ test entry should reflect the real requirements of these specific stories. ## Phase 5: Write Output Show the complete plan in conversation (or a summary if the plan is very long), -then ask: +then ask two questions together using `AskUserQuestion`: -"May I write this QA plan to `production/qa/qa-plan-[sprint-slug]-[date].md`?" +``` +question: "Ready to write the QA plan. Choose output options:" +multiSelect: true +options: + - "Write QA plan to production/qa/qa-plan-[sprint-slug]-[date].md" + - "Also back-fill test case specs into each story file's ## QA Test Cases section (Recommended — enables /dev-story and /code-review traceability)" +``` -Write the plan exactly as generated — do not truncate. +If "Write QA plan" is selected: write the plan file exactly as generated — do not truncate. + +If "Also back-fill story files" is selected: for each Logic and Integration story in scope, edit the story file at its path. Find the `## QA Test Cases` section and replace its content with the test case specs generated in Phase 4 for that story. If a story has no `## QA Test Cases` section, append it before `## Test Evidence`. For Visual/Feel and UI stories, write the manual verification steps instead of test specs. After writing: @@ -238,10 +251,16 @@ After writing: Next steps: - Share this plan with the team before sprint implementation begins -- Run `/smoke-check sprint` after all stories are implemented to gate QA hand-off +- Once all sprint stories are implemented, run `/smoke-check sprint` to gate QA hand-off — not yet, only after implementation is complete - For Logic/Integration stories, create the test files at the listed paths before marking stories done — `/story-done` checks for them" +Silently append to `production/session-state/active.md` (create the file if it does not exist): + +``` + +``` + --- ## Collaborative Protocol diff --git a/.claude/skills/quick-design/SKILL.md b/.claude/skills/quick-design/SKILL.md index 55d28eb..bdb3392 100644 --- a/.claude/skills/quick-design/SKILL.md +++ b/.claude/skills/quick-design/SKILL.md @@ -3,7 +3,8 @@ name: quick-design description: "Lightweight design spec for small changes — tuning adjustments, minor mechanics, balance tweaks. Skips full GDD authoring when a system GDD already exists or the change is too small to warrant one. Produces a Quick Design Spec that embeds directly into story files." argument-hint: "[brief description of the change]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write, Edit +allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion +model: sonnet --- # Quick Design @@ -43,8 +44,20 @@ significant cross-system dependencies, requires more than one week of implementation, or fundamentally alters an existing system's core rules — stop and redirect to `/design-system` instead. -Present the classification to the user and confirm it is correct before -proceeding. If there is no argument, ask the user to describe the change. +If there is no argument, ask the user to describe the change (plain text prompt), then classify it using the criteria above. + +Present the inferred classification using `AskUserQuestion`: +- Prompt: "I've classified this as **[inferred type]** — [brief reason]. Is that correct?" +- Options: + - `[A] Yes — [inferred type] is correct` + - `[B] Tuning — changing numbers or balance values only` + - `[C] Tweak — small behavioral change to an existing system` + - `[D] Addition — adding a small mechanic to an existing system` + - `[E] New Small System — standalone feature, under one week of work` + - `[F] This is too large — redirect me to /design-system` + +If [F]: stop. Verdict: **REDIRECTED** — use `/design-system` for this change. +Otherwise: proceed with the selected type. --- @@ -209,9 +222,17 @@ tracking threshold — quick spec is sufficient."] ## 4. Approval and Filing -Present the draft to the user in full. Then ask: +Present the draft to the user in full. Then use `AskUserQuestion`: +- Prompt: "Here's the Quick Design Spec draft. How do you want to proceed?" +- Options: + - `[A] Approve — write it as shown` + - `[B] Revise — I'll describe what to change` + - `[C] This grew too large — redirect to /design-system instead` -"May I write this Quick Design Spec to +If [B]: collect the requested changes, revise the draft, and re-present this widget. +If [C]: stop. Verdict: **REDIRECTED** — use `/design-system` for this change. + +If [A]: ask "May I write this Quick Design Spec to `design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md`?" Use today's date in the filename. The title should be a kebab-case description diff --git a/.claude/skills/regression-suite/SKILL.md b/.claude/skills/regression-suite/SKILL.md index 376d2d0..e0f7655 100644 --- a/.claude/skills/regression-suite/SKILL.md +++ b/.claude/skills/regression-suite/SKILL.md @@ -3,7 +3,8 @@ name: regression-suite description: "Map test coverage to GDD critical paths, identify fixed bugs without regression tests, flag coverage drift from new features, and maintain tests/regression-suite.md. Run after implementing a bug fix or before a release gate." argument-hint: "[update | audit | report]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write, Edit +allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion +model: sonnet --- # Regression Suite @@ -35,7 +36,12 @@ and known failure points. This skill maintains that list. existing test coverage; flag paths with no regression test - `/regression-suite report` — read-only status report (no writes); suitable for sprint reviews -- No argument — run `update` if a sprint is active, else `audit` +- No argument — if a sprint is clearly active (sprint plan exists with in-progress stories), run `update`. If ambiguous or no active sprint is detected, use `AskUserQuestion`: + - Prompt: "No subcommand specified. Which mode do you want to run?" + - Options: + - `[A] update — scan new bug fixes this sprint and add missing regression tests` + - `[B] audit — full audit of all GDD critical paths vs. existing test coverage` + - `[C] report — read-only status report (no writes)` --- diff --git a/.claude/skills/release-checklist/SKILL.md b/.claude/skills/release-checklist/SKILL.md index 8415a28..57d2eff 100644 --- a/.claude/skills/release-checklist/SKILL.md +++ b/.claude/skills/release-checklist/SKILL.md @@ -4,6 +4,7 @@ description: "Generates a comprehensive pre-release validation checklist coverin argument-hint: "[platform: pc|console|mobile|all]" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet --- > **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/release-checklist`. Do not auto-invoke based on context matching. diff --git a/.claude/skills/retrospective/SKILL.md b/.claude/skills/retrospective/SKILL.md index f404331..c2a8d1e 100644 --- a/.claude/skills/retrospective/SKILL.md +++ b/.claude/skills/retrospective/SKILL.md @@ -3,9 +3,8 @@ name: retrospective description: "Generates a sprint or milestone retrospective by analyzing completed work, velocity, blockers, and patterns. Produces actionable insights for the next iteration." argument-hint: "[sprint-N|milestone-name]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write -context: | - !git log --oneline --since="2 weeks ago" 2>/dev/null +allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion +model: sonnet --- ## Phase 1: Parse Arguments @@ -22,17 +21,14 @@ Before loading any data, glob for an existing retrospective file: (also check `production/sprints/sprint-[N]-retrospective.md` as an alternate location) - For milestone retrospectives: `production/retrospectives/retro-[milestone-name]-*.md` -If a matching file is found, present the user with: +If a matching file is found, use `AskUserQuestion`: +- Prompt: "An existing retrospective was found: [filename]. How do you want to proceed?" +- Options: + - `[A] Update existing — load it and add/revise sections with new data` + - `[B] Start fresh — generate a new retrospective (archive the old one)` -``` -An existing retrospective was found: [filename] - -[A] Update existing retrospective — load it and add/revise sections -[B] Start fresh — generate a new retrospective, archiving the old one -``` - -Wait for user selection before continuing. If updating, read the existing file and -carry its content forward into the generation phase, revising sections with new data. +If [A]: read the existing file and carry its content forward, revising sections with new data. +If [B]: continue to Phase 2 with a blank slate. Before writing the new file, rename the existing one with a `-archived-[date]` suffix. --- @@ -43,6 +39,8 @@ Read the sprint or milestone plan from the appropriate location: - Sprint plans: `production/sprints/` - Milestone definitions: `production/milestones/` +**Also check for `production/sprint-status.yaml`**: if it exists, read it alongside the sprint plan. It is the authoritative source for actual story completion status (status: done, completed dates, blockers). Use it as the primary source for completion metrics in Phase 3. Fall back to markdown scanning only if the yaml does not exist. Note discrepancies between the yaml and the sprint plan (e.g., stories in yaml not in plan, or vice versa). + **If the file does not exist or is empty**, output: > "No sprint data found for [sprint/milestone]. Run `/sprint-status` to generate @@ -59,7 +57,13 @@ If the user chooses [B], stop here. Extract: planned tasks, estimated effort, owners, and goals. -Read the git log for the period covered by the sprint or milestone to understand what was actually committed and when. +Run git log for the sprint period to understand what was actually committed and when. Use the Bash tool (which uses Git Bash on Windows — the `2>/dev/null` is bash syntax, not PowerShell): + +``` +Bash: git log --oneline --since="4 weeks ago" 2>/dev/null || git log --oneline -20 +``` + +Adjust the `--since` date to match the sprint duration if known from the sprint plan. --- @@ -79,7 +83,7 @@ Scan the codebase for TODO/FIXME trends: - Compare to previous sprint counts if available (check previous retrospectives) - Note whether technical debt is growing or shrinking -Read previous retrospectives (if any) from `production/sprints/` or `production/milestones/` to check: +Read previous retrospectives (if any) from `production/retrospectives/` to check: - Were previous action items addressed? - Are the same problems recurring? @@ -187,9 +191,9 @@ the single most important thing to change going forward?] Present the retrospective and top findings to the user (completion rate, velocity trend, top blocker, most important action item). -Ask: "May I write this to `production/sprints/sprint-[N]-retrospective.md`?" (or the milestone path if applicable) +Ask: "May I write this to `production/retrospectives/retro-sprint-[N]-[date].md`?" (or `production/retrospectives/retro-[milestone-name]-[date].md` for milestone retrospectives) -If yes, write the file, creating the directory if needed. Verdict: **COMPLETE** — retrospective saved. +If yes, write the file, creating the `production/retrospectives/` directory if needed. Verdict: **COMPLETE** — retrospective saved. If no, stop here. Verdict: **BLOCKED** — user declined write. @@ -197,7 +201,14 @@ If no, stop here. Verdict: **BLOCKED** — user declined write. ## Phase 6: Next Steps -- Run `/sprint-plan` to incorporate the action items and velocity data into the next sprint. +Use `AskUserQuestion`: +- Prompt: "Retrospective complete. The action items and velocity data are ready. Would you like to start sprint planning now with this data pre-loaded?" +- Options: + - `[A] Yes — open sprint planning with retro action items and velocity delta pre-populated` + - `[B] No — I'll reference the retrospective file manually when I'm ready` + +If the user selects [A]: Proceed to invoke `/sprint-plan new`, passing the retrospective file path and a summary of the action items and velocity change so the sprint planner can reference them. + - If this was a milestone retrospective, run `/gate-check` to formally assess readiness for the next phase. ### Guidelines diff --git a/.claude/skills/reverse-document/SKILL.md b/.claude/skills/reverse-document/SKILL.md index d73cc58..04d4f31 100644 --- a/.claude/skills/reverse-document/SKILL.md +++ b/.claude/skills/reverse-document/SKILL.md @@ -4,6 +4,7 @@ description: "Generate design or architecture documents from existing implementa argument-hint: " (e.g., 'design src/gameplay/combat' or 'architecture src/core')" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash +model: sonnet # Read-only diagnostic skill — no specialist agent delegation needed --- diff --git a/.claude/skills/review-all-gdds/SKILL.md b/.claude/skills/review-all-gdds/SKILL.md index dd09d62..67b604f 100644 --- a/.claude/skills/review-all-gdds/SKILL.md +++ b/.claude/skills/review-all-gdds/SKILL.md @@ -105,6 +105,14 @@ the same GDD inputs but produce separate reports. Spawn both as parallel Task agents simultaneously rather than waiting for Phase 2 to complete before starting Phase 3. Collect both results before writing the combined report. +**When spawning parallel Task agents for Phase 2 and Phase 3, always pass:** +- The complete list of GDD file paths loaded in Phase 1 (explicit paths, not just counts) +- The full TR registry contents if loaded in Phase 1b (paste the registry text, not just a file path) +- The specific checklist items assigned to that agent's phase (Phase 2 gets 2a–2f; Phase 3 gets 3a–3g) +- The engine name and version from `.claude/docs/technical-preferences.md` and `docs/engine-reference/[engine]/VERSION.md` + +Do not rely on the subagent to re-read these files — it has its own context window and cannot access Phase 1 results unless they are explicitly passed in the Task prompt. + --- ## Phase 2: Cross-GDD Consistency @@ -566,7 +574,10 @@ append to `production/session-state/active.md`: - Flagged for revision: [comma-separated list, or "None"] - Blocking issues: [N — brief one-line descriptions, or "None"] - Recommended next: [the Phase 7 handoff action, condensed to one line] - - Report: design/gdd/gdd-cross-review-[date].md + - Report: design/gdd/gdd-cross-review-[date].md ← only if user approved the write + - Report: (not written — user declined at [date]) ← only if user declined the write + +Use the appropriate line based on the user's response to the write-permission widget in Phase 6. If `active.md` does not exist, create it with this block as the initial content. Confirm in conversation: "Session state updated." diff --git a/.claude/skills/security-audit/SKILL.md b/.claude/skills/security-audit/SKILL.md index 9e363fe..d77b678 100644 --- a/.claude/skills/security-audit/SKILL.md +++ b/.claude/skills/security-audit/SKILL.md @@ -4,6 +4,7 @@ description: "Audit the game for security vulnerabilities: save tampering, cheat argument-hint: "[full | network | save | input | quick]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write, Task +model: sonnet agent: security-engineer --- diff --git a/.claude/skills/setup-engine/SKILL.md b/.claude/skills/setup-engine/SKILL.md index d39b81e..5dcf61b 100644 --- a/.claude/skills/setup-engine/SKILL.md +++ b/.claude/skills/setup-engine/SKILL.md @@ -4,6 +4,7 @@ description: "Configure the project's game engine and version. Pins the engine i argument-hint: "[engine] | [engine version] | refresh | upgrade [old-version] [new-version] | no args for guided selection" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, WebSearch, WebFetch, Task, AskUserQuestion +model: sonnet --- When this skill is invoked: @@ -560,7 +561,7 @@ Next Steps: 1. Review docs/engine-reference//VERSION.md 2. [If from /brainstorm] Run /map-systems to decompose your concept into individual systems 3. [If from /brainstorm] Run /design-system to author per-system GDDs (guided, section-by-section) -4. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop +4. [If from /brainstorm] Run /prototype [core-mechanic] to validate the core idea before writing GDDs 5. [If fresh start] Run /brainstorm to discover your game concept 6. Create your first milestone: /sprint-plan new ``` diff --git a/.claude/skills/skill-improve/SKILL.md b/.claude/skills/skill-improve/SKILL.md index 340aee4..c9a0f2b 100644 --- a/.claude/skills/skill-improve/SKILL.md +++ b/.claude/skills/skill-improve/SKILL.md @@ -4,6 +4,7 @@ description: "Improve a skill using a test-fix-retest loop. Runs static checks, argument-hint: "[skill-name]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Bash +model: sonnet --- # Skill Improve diff --git a/.claude/skills/skill-test/SKILL.md b/.claude/skills/skill-test/SKILL.md index 07ba49d..e6748d8 100644 --- a/.claude/skills/skill-test/SKILL.md +++ b/.claude/skills/skill-test/SKILL.md @@ -4,6 +4,7 @@ description: "Validate skill files for structural compliance and behavioral corr argument-hint: "static [skill-name | all] | spec [skill-name] | category [skill-name | all] | audit" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet --- # Skill Test diff --git a/.claude/skills/smoke-check/SKILL.md b/.claude/skills/smoke-check/SKILL.md index 6cb1932..2f5d073 100644 --- a/.claude/skills/smoke-check/SKILL.md +++ b/.claude/skills/smoke-check/SKILL.md @@ -4,6 +4,7 @@ description: "Run the critical path smoke test gate before QA hand-off. Executes argument-hint: "[sprint | quick | --platform pc|console|mobile|all]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write, AskUserQuestion +model: sonnet --- # Smoke Check @@ -92,7 +93,9 @@ path for your test framework." Unity tests require the editor and cannot be run headlessly via shell in most environments. Check for recent test result artifacts: ```bash -ls -t test-results/ 2>/dev/null | head -5 +# List most recent test results (bash) — on Windows PowerShell use the fallback below +ls -t test-results/ 2>/dev/null | head -5 \ + || powershell -Command "Get-ChildItem test-results/ -ErrorAction SilentlyContinue | Sort-Object LastWriteTime -Descending | Select-Object -First 5 -ExpandProperty Name" ``` If test result files exist (XML or JSON), read the most recent one and parse PASS/FAIL counts. If no artifacts exist: "Unity tests must be run from the @@ -100,7 +103,9 @@ editor or CI pipeline. Please confirm test status manually before proceeding." **Unreal Engine:** ```bash -ls -t Saved/Logs/ 2>/dev/null | grep -i "test\|automation" | head -5 +# List most recent Unreal automation logs (bash) — on Windows PowerShell use the fallback below +ls -t Saved/Logs/ 2>/dev/null | grep -i "test\|automation" | head -5 \ + || powershell -Command "Get-ChildItem Saved/Logs/ -ErrorAction SilentlyContinue | Where-Object { $_.Name -match 'test|automation' } | Sort-Object LastWriteTime -Descending | Select-Object -First 5 -ExpandProperty Name" ``` If no matching log found: "UE automation tests must be run via the Session Frontend or CI pipeline. Please confirm test status manually." @@ -181,86 +186,86 @@ Use `AskUserQuestion` to batch-verify. Keep to at most 3 calls. **Batch 1 — Core stability (always run):** ``` -question: "Smoke check — Batch 1: Core stability. Please verify each:" +question: "Core stability — select any items that FAILED (leave all unselected if everything passed):" +multiSelect: true options: - - "Game launches to main menu without crash — PASS" - - "Game launches to main menu without crash — FAIL" - - "New game / session starts successfully — PASS" - - "New game / session starts successfully — FAIL" - - "Main menu responds to all inputs — PASS" - - "Main menu responds to all inputs — FAIL" + - "Game does not launch or crashes before reaching the main menu" + - "New game / session fails to start" + - "Main menu does not respond to inputs" + - "Crash or hang observed during basic navigation" ``` -**Batch 2 — Sprint mechanic and regression (always run):** +For any selected item, ask the user to briefly describe what failed before generating the report. + +**Batch 2 — Sprint changes and regression (always run):** ``` -question: "Smoke check — Batch 2: This sprint's changes and regression check:" +question: "Sprint changes and regression — select any items that FAILED (leave all unselected if everything passed):" +multiSelect: true options: - - "[Primary mechanic this sprint] — PASS" - - "[Primary mechanic this sprint] — FAIL: [describe what broke]" - - "[Second notable change this sprint, if any] — PASS" - - "[Second notable change this sprint] — FAIL" - - "Previous sprint's features still work (no regressions) — PASS" - - "Previous sprint's features — regression found: [brief description]" + - "[Primary mechanic this sprint] — FAILED" + - "[Second notable change this sprint, if any] — FAILED" + - "Regression in a previous sprint's feature — FAILED" + - "Other unexpected breakage observed — FAILED" ``` +For any selected item, ask the user to briefly describe what broke before generating the report. + **Batch 3 — Data integrity and performance (run unless `quick` argument):** ``` -question: "Smoke check — Batch 3: Data integrity and performance:" +question: "Data integrity and performance — select any items that FAILED or were skipped (leave all unselected if everything passed):" +multiSelect: true options: - - "Save / load completes without data loss — PASS" - - "Save / load — FAIL: [describe what broke]" + - "Save / load — FAILED (data loss or corruption observed)" - "Save / load — N/A (save system not yet implemented)" - - "No new frame rate drops or hitches observed — PASS" - - "Frame rate drops or hitches found — FAIL: [where]" - - "Performance — not checked in this session" + - "Frame rate drops or hitches observed — FAILED" + - "Performance not checked this session" ``` +For any FAILED item selected, ask the user to describe what broke before generating the report. + Record each response verbatim for the Phase 5 report. **Platform Batches** *(run only if `--platform` argument was provided)*: **PC platform** (`--platform pc` or `--platform all`): ``` -question: "Smoke check — PC Platform: Verify platform-specific behaviour:" +question: "PC Platform — select any items that FAILED (leave all unselected if everything passed):" +multiSelect: true options: - - "Keyboard controls work correctly across all menus and gameplay — PASS" - - "Keyboard controls — FAIL: [describe issue]" - - "Mouse input and cursor visibility correct in all states — PASS" - - "Mouse input — FAIL: [describe issue]" - - "Windowed and fullscreen modes function without graphical issues — PASS" - - "Windowed/fullscreen — FAIL: [describe issue]" - - "Resolution changes apply correctly — PASS" - - "Resolution changes — FAIL: [describe issue]" + - "Keyboard controls — FAILED (describe issue after)" + - "Mouse input or cursor visibility — FAILED (describe issue after)" + - "Windowed / fullscreen mode — FAILED (describe issue after)" + - "Resolution change — FAILED (describe issue after)" ``` +For any selected item, ask the user to briefly describe what failed before generating the report. + **Console platform** (`--platform console` or `--platform all`): ``` -question: "Smoke check — Console Platform: Verify platform-specific behaviour:" +question: "Console Platform — select any items that FAILED (leave all unselected if everything passed):" +multiSelect: true options: - - "Gamepad input works correctly for all actions — PASS" - - "Gamepad input — FAIL: [describe issue]" - - "UI fits within TV safe zone margins (no text clipped) — PASS" - - "TV safe zone — FAIL: [describe what is clipped]" - - "No keyboard/mouse-only fallbacks shown to gamepad user — PASS" - - "Input prompt inconsistency — FAIL: [describe]" - - "Game boots correctly from cold start (no prior save) — PASS" - - "Cold start — FAIL: [describe issue]" + - "Gamepad input — FAILED (describe issue after)" + - "UI outside TV safe zone / text clipped — FAILED (describe what is clipped after)" + - "Keyboard/mouse fallback shown to gamepad user — FAILED (describe after)" + - "Cold start (no prior save) — FAILED (describe issue after)" ``` +For any selected item, ask the user to briefly describe what failed before generating the report. + **Mobile platform** (`--platform mobile` or `--platform all`): ``` -question: "Smoke check — Mobile Platform: Verify platform-specific behaviour:" +question: "Mobile Platform — select any items that FAILED (leave all unselected if everything passed):" +multiSelect: true options: - - "Touch controls work correctly for all primary actions — PASS" - - "Touch controls — FAIL: [describe issue]" - - "Game handles orientation change (portrait ↔ landscape) correctly — PASS" - - "Orientation change — FAIL: [describe what breaks]" - - "Background / foreground transitions (home button) handled gracefully — PASS" - - "Background/foreground — FAIL: [describe issue]" - - "No visible performance issues on target device (no thermal throttling signs) — PASS" - - "Mobile performance — FAIL: [describe issue]" + - "Touch controls — FAILED (describe issue after)" + - "Orientation change (portrait ↔ landscape) — FAILED (describe what breaks after)" + - "Background / foreground transition (home button) — FAILED (describe issue after)" + - "Performance / thermal throttling on target device — FAILED (describe after)" ``` +For any selected item, ask the user to briefly describe what failed before generating the report. + --- ## Phase 5: Generate Report diff --git a/.claude/skills/soak-test/SKILL.md b/.claude/skills/soak-test/SKILL.md index 389f402..e09c519 100644 --- a/.claude/skills/soak-test/SKILL.md +++ b/.claude/skills/soak-test/SKILL.md @@ -4,6 +4,7 @@ description: "Generate a soak test protocol for extended play sessions. Defines argument-hint: "[duration: 30m | 1h | 2h | 4h] [focus: memory | stability | balance | all]" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet --- # Soak Test diff --git a/.claude/skills/sprint-plan/SKILL.md b/.claude/skills/sprint-plan/SKILL.md index 4cdff74..65254a9 100644 --- a/.claude/skills/sprint-plan/SKILL.md +++ b/.claude/skills/sprint-plan/SKILL.md @@ -4,6 +4,7 @@ description: "Generates a new sprint plan or updates an existing one based on th argument-hint: "[new|update|status] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion +model: sonnet context: | !ls production/sprints/ 2>/dev/null --- @@ -17,6 +18,17 @@ Extract the mode argument (`new`, `update`, or `status`) and resolve the review See `.claude/docs/director-gates.md` for the full check pattern. +**Review mode check** (before gates run): +- Read `production/review-mode.txt` if it exists. Use that mode. +- If the file doesn't exist and this is a `new` sprint: use `AskUserQuestion`: + - Prompt: "No review mode is set. Which review depth would you like for this sprint?" + - Options: + - `[A] full — spawn all director and lead gates` + - `[B] lean — skip non-phase-gate director reviews (recommended for most sprints)` + - `[C] solo — skip all gate spawning` + - After selection: write `production/review-mode.txt` with the chosen mode. Say: "Review mode set to [mode] and saved to production/review-mode.txt." +- If the file doesn't exist and this is NOT a `new` sprint (e.g., updating an existing sprint): default to `lean` silently. + --- ## Phase 1: Gather Context @@ -40,7 +52,7 @@ For `new`: **Generate a sprint plan** following this format and present it to the user. Do NOT ask to write yet — the producer feasibility gate (Phase 4) runs first and may require revisions before the file is written. ```markdown -# Sprint [N] -- [Start Date] to [End Date] +# Sprint [N] — [Start Date] to [End Date] ## Sprint Goal [One sentence describing what this sprint achieves toward the milestone] @@ -87,6 +99,19 @@ For `new`: - [ ] Code reviewed and merged ``` +For `update`: + +**Update an existing sprint plan**: + +1. Read the most recent sprint plan from `production/sprints/`. +2. Present the current story list with their current statuses from `production/sprint-status.yaml`. +3. Ask the user what to change: stories to add, remove, reprioritize, or re-estimate. Use `AskUserQuestion` to gather changes. +4. Apply the changes and re-present the full revised plan for review. +5. Re-run the producer feasibility gate (Phase 4) on the revised plan. +6. Write the updated markdown plan and yaml together (same approval as `new` mode). + +Note: `update` mode does not reset story statuses. Stories already marked `in-progress` or `done` keep their status. Only `backlog` and `ready-for-dev` stories can be removed or reprioritized freely. + For `status`: **Generate a status report**: @@ -122,19 +147,27 @@ For `status`: --- -## Phase 3: Write Sprint Status File +## Phase 3: Prepare Sprint Status File -After generating a new sprint plan, also write `production/sprint-status.yaml`. +After generating a new sprint plan, also prepare the `production/sprint-status.yaml` content. This is the machine-readable source of truth for story status — read by `/sprint-status`, `/story-done`, and `/help` without markdown parsing. -Ask: "May I also write `production/sprint-status.yaml` to track story status?" +**Do not write the yaml yet** — hold it in context. The producer feasibility gate (Phase 4) may revise the story list. Both files will be written together after Phase 4 in a single write approval. Format: ```yaml -# Auto-generated by /sprint-plan. Updated by /story-done. +# Auto-generated by /sprint-plan. Updated by /story-done and /dev-story. # DO NOT edit manually — use /story-done to update story status. +# +# Status value mapping (yaml ↔ story file Status field): +# backlog ↔ Not Started +# ready-for-dev ↔ Ready +# in-progress ↔ In Progress +# review ↔ In Review +# done ↔ Complete +# blocked ↔ Blocked sprint: [N] goal: "[sprint goal]" @@ -176,9 +209,22 @@ Before finalising the sprint plan, spawn `producer` via Task using gate **PR-SPR Pass: proposed story list (titles, estimates, dependencies), total team capacity in hours/days, any carryover from the previous sprint, milestone constraints and deadline. -Present the producer's assessment. If UNREALISTIC, revise the story selection (defer stories to Should Have or Nice to Have) before asking for write approval. If CONCERNS, surface them and let the user decide whether to adjust. +Present the producer's assessment. -After handling the producer's verdict, ask: "May I write this sprint plan to `production/sprints/sprint-[N].md`?" If yes, write the file, creating the directory if needed. Verdict: **COMPLETE** — sprint plan created. If no: Verdict: **BLOCKED** — user declined write. +If UNREALISTIC: revise the story selection (defer stories to Should Have or Nice to Have) and re-present the updated plan before asking for write approval. + +If CONCERNS, use `AskUserQuestion`: +- Prompt: "Producer flagged concerns with this sprint plan. How do you want to proceed?" +- Options: + - `[A] Proceed as planned — I accept the risk` + - `[B] Adjust scope — defer some Should Have stories` + - `[C] Extend the sprint timeline` + +If [A]: proceed to write approval. +If [B]: revise the story list, re-present the updated plan, then proceed to write approval. +If [C]: adjust sprint dates and capacity, re-present the updated plan, then proceed to write approval. + +After handling the producer's verdict, ask: "May I write the sprint plan to `production/sprints/sprint-[N].md` and `production/sprint-status.yaml`?" If yes, write both files (creating directories as needed). Verdict: **COMPLETE** — sprint plan and status file created. If no: Verdict: **BLOCKED** — user declined write. After writing, add: @@ -226,3 +272,10 @@ After the sprint plan is written and QA plan status is resolved: - `/dev-story [story-file]` — begin implementing the first story - `/sprint-status` — check progress mid-sprint - `/scope-check [epic]` — verify no scope creep before implementation begins + +**Review mode configuration:** All director gates (producer feasibility, QA review, code review) respect the project review mode. The review mode is set in Phase 0 when the file does not exist (for `new` sprints), or can be overridden per-run with `--review full|lean|solo` as an argument. The file `production/review-mode.txt` contains one of: +- `lean` — skip automated director gates (default if file is absent — fastest for solo dev) +- `full` — run all director gates as spawned sub-agents +- `solo` — skip all gates unconditionally (single-developer, no review) + +This file is read by `/sprint-plan`, `/story-readiness`, `/story-done`, and other skills at startup. diff --git a/.claude/skills/sprint-status/SKILL.md b/.claude/skills/sprint-status/SKILL.md index ccd4b2c..0f82f4d 100644 --- a/.claude/skills/sprint-status/SKILL.md +++ b/.claude/skills/sprint-status/SKILL.md @@ -87,14 +87,14 @@ After collecting status for all stories, check each IN PROGRESS story for stalen or `updated: 2026-04-01`). Accept any reasonable date field name: `Last Updated`, `Updated`, `last-updated`, `updated_at`. - Calculate days since that date using today's date. -- If the date is more than 2 days ago, flag the story as **STALE**. +- If the date is more than 4 days ago, flag the story as **STALE**. (4-day threshold accounts for weekends — a story last touched on Friday won't appear stale until Wednesday.) - If no date field is found in the story file, note "no timestamp — cannot check staleness." - If the story has no referenced file (inline task), note "inline task — cannot check staleness." STALE stories are included in the output table and collected into an "Attention Needed" section (see Phase 5 output format). -**Stale story escalation**: If any IN PROGRESS story is flagged STALE, the burndown verdict +**Stale story escalation**: If any IN PROGRESS story is flagged STALE (no progress in 4+ days), the burndown verdict is upgraded to at least **At Risk** — even if the completion percentage is within the normal On Track window. Record this escalation reason: "At Risk — [N] story(ies) with no progress in [N] days." @@ -123,7 +123,7 @@ At Risk / Behind: unknown — sprint dates not found." ## 5. Output -Keep the total output to 30 lines or fewer. Use this format: +Keep the output concise. The story status table is mandatory — do not truncate it. Aim for under 50 lines total; omit the Emerging Risks section if nothing notable was found. Use this format: ```markdown ## Sprint [N] Status — [Today's Date] @@ -205,4 +205,4 @@ For more detail on a specific story, the user can read the story file directly or run `/story-readiness [path]`. For sprint replanning, use `/sprint-plan update`. -For end-of-sprint retrospective, use `/milestone-review`. +For end-of-sprint retrospective, use `/retrospective`. diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md index 9e4ce7e..0cb102d 100644 --- a/.claude/skills/start/SKILL.md +++ b/.claude/skills/start/SKILL.md @@ -4,6 +4,7 @@ description: "First-time onboarding — asks where you are, then guides you to t argument-hint: "[no arguments]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, AskUserQuestion +model: sonnet --- # Guided Onboarding @@ -58,6 +59,7 @@ The user needs creative exploration before anything else. **Concept phase:** - `/brainstorm open` — discover your game concept - `/setup-engine` — configure the engine (brainstorm will recommend one) + - `/prototype` — throwaway concept build: validate the core idea is fun before designing (1–3 days) - `/art-bible` — define visual identity (uses the Visual Identity Anchor brainstorm produces) - `/map-systems` — decompose the concept into systems - `/design-system` — author a GDD for each MVP system @@ -70,7 +72,7 @@ The user needs creative exploration before anything else. - `/architecture-review` — validate architecture coverage **Pre-Production phase:** - `/ux-design` — author UX specs for key screens (main menu, HUD, core interactions) - - `/prototype` — build a throwaway prototype to validate the core mechanic + - `/vertical-slice` — production-quality end-to-end build to validate the full game loop - `/playtest-report (×1+)` — document each vertical slice playtest session - `/create-epics` — map systems to epics - `/create-stories` — break epics into implementable stories @@ -86,6 +88,7 @@ The user needs creative exploration before anything else. **Concept phase:** - `/brainstorm [hint]` — develop the idea into a full concept - `/setup-engine` — configure the engine + - `/prototype` — throwaway concept build: validate the core idea is fun before designing (1–3 days) - `/art-bible` — define visual identity (uses the Visual Identity Anchor brainstorm produces) - `/map-systems` — decompose the concept into systems - `/design-system` — author a GDD for each MVP system @@ -98,7 +101,7 @@ The user needs creative exploration before anything else. - `/architecture-review` — validate architecture coverage **Pre-Production phase:** - `/ux-design` — author UX specs for key screens (main menu, HUD, core interactions) - - `/prototype` — build a throwaway prototype to validate the core mechanic + - `/vertical-slice` — production-quality end-to-end build to validate the full game loop - `/playtest-report (×1+)` — document each vertical slice playtest session - `/create-epics` — map systems to epics - `/create-stories` — break epics into implementable stories @@ -116,6 +119,7 @@ The user needs creative exploration before anything else. 3. Show the recommended path: **Concept phase:** - `/brainstorm` or `/setup-engine` — (their pick from step 2) + - `/prototype` — throwaway concept build: validate the core idea is fun before designing (1–3 days) - `/art-bible` — define visual identity (after brainstorm if run, or after concept doc exists) - `/design-review` — validate the concept doc - `/map-systems` — decompose the concept into individual systems @@ -129,7 +133,7 @@ The user needs creative exploration before anything else. - `/architecture-review` — validate architecture coverage **Pre-Production phase:** - `/ux-design` — author UX specs for key screens (main menu, HUD, core interactions) - - `/prototype` — build a throwaway prototype to validate the core mechanic + - `/vertical-slice` — production-quality end-to-end build to validate the full game loop - `/playtest-report (×1+)` — document each vertical slice playtest session - `/create-epics` — map systems to epics - `/create-stories` — break epics into implementable stories @@ -163,6 +167,22 @@ The user needs creative exploration before anything else. --- +## Phase 3c: Write Initial Stage File + +After confirming the starting path (and before asking about review mode), write the initial stage to `production/stage.txt`. Create the `production/` directory if it does not exist. + +Stage mapping: +- **Path A, B, or C (starting from scratch)**: write `Concept` +- **Path D, existing project, engine not configured or only a game concept exists**: write `Concept` +- **Path D, existing project with GDDs but no architecture documents**: write `Systems Design` +- **Path D, existing project with full architecture (ADRs, architecture doc)**: write `Technical Setup` + +Do this silently — no "May I write?" needed for this single-line file. + +Say: "I've set `production/stage.txt` to `[stage]` — this anchors your status line and stage detection." + +--- + ## Phase 3b: Set Review Mode Check if `production/review-mode.txt` already exists. diff --git a/.claude/skills/story-done/SKILL.md b/.claude/skills/story-done/SKILL.md index b067f1d..851a496 100644 --- a/.claude/skills/story-done/SKILL.md +++ b/.claude/skills/story-done/SKILL.md @@ -4,6 +4,7 @@ description: "End-of-story completion review. Reads the story file, verifies eac argument-hint: "[story-file-path] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion, Task +model: sonnet --- # Story Done @@ -168,9 +169,10 @@ playtest record referencing this story. If none found: flag as **BLOCKING** (same rule as Logic). **For Visual/Feel and UI stories**: glob `production/qa/evidence/` for a file -referencing this story. If none: flag as **ADVISORY** — -"No manual test evidence found. Create `production/qa/evidence/[story-slug]-evidence.md` -using the test-evidence template and obtain sign-off before final closure." +referencing this story. +- If none: flag as **ADVISORY** — "No manual test evidence found. Create `production/qa/evidence/[story-slug]-evidence.md` using the test-evidence template and obtain sign-off before final closure." +- If found: read the file and check the sign-off table for unchecked boxes. Grep for lines matching `| .* | .* | .* | \[ \] Approved` (a sign-off row with an unchecked checkbox). If any unchecked sign-off rows are found: flag as **ADVISORY** — "Evidence file found at `[path]` but [N] sign-off(s) are still pending (shown as `[ ] Approved` in the sign-off table). Obtain required sign-offs before final closure. Note: for solo developers, all roles may be signed off by the same person." +- If all sign-off rows show `[x] Approved` or equivalent: note "Evidence file found and all sign-offs complete — ADVISORY passed." **For Config/Data stories**: check for any `production/qa/smoke-*.md` file. If none: flag as **ADVISORY** — "No smoke check report found. Run `/smoke-check`." @@ -255,7 +257,13 @@ Skip this phase for Config/Data stories (no code tests required). **Review mode check** — apply before spawning LP-CODE-REVIEW: - `solo` → skip. Note: "LP-CODE-REVIEW skipped — Solo mode." Proceed to Phase 6 (completion report). -- `lean` → skip (not a PHASE-GATE). Note: "LP-CODE-REVIEW skipped — Lean mode." Proceed to Phase 6 (completion report). +- `lean` → use `AskUserQuestion` before proceeding: + - Prompt: "Code review is skipped in lean mode. Did you run `/code-review` on the implemented files?" + - Options: + - `Yes — /code-review passed or was approved with suggestions` + - `No — skipping code review for this story` + - `No — I'll run /code-review before the sprint close-out` + - Record the answer in the completion notes (Phase 7). All three options proceed to Phase 6. - `full` → spawn as normal. Spawn `lead-programmer` via Task using gate **LP-CODE-REVIEW** (`.claude/docs/director-gates.md`). @@ -321,13 +329,21 @@ fixed. Offer to help fix the blocking items. ## Phase 7: Update Story Status -Ask before writing: "May I update the story file to mark it Complete and log -the completion notes?" +Use `AskUserQuestion` before writing anything: +- Prompt: "Verification complete. How do you want to proceed?" +- Options: + - `Close the story — update file, mark Complete, log notes (Recommended)` + - `Close and log advisory deviations as tech debt in docs/tech-debt-register.md` + - `There are issues I want to fix first — don't close yet` + - `Accept deviations as-is and close anyway` -If yes, edit the story file: +If "Close", "Close and log tech debt", or "Accept deviations": edit the story file. +If "Close and log tech debt": after updating the story file, also append the advisory deviations to `docs/tech-debt-register.md` (create the file if it does not exist). +If "Fix first": stop here and list what the user flagged. Do not write any files. 1. Update the status field: `Status: Complete` -2. Add a `## Completion Notes` section at the bottom: +2. Update the `Last Updated:` field in the story header to today's date (format: `YYYY-MM-DD`). If the field does not exist, add it after the `Status:` line. +3. Add a `## Completion Notes` section at the bottom: ```markdown ## Completion Notes @@ -338,15 +354,28 @@ If yes, edit the story file: **Code Review**: [Pending / Complete / Skipped] ``` -3. If advisory deviations exist, ask: "Should I log these as tech debt in - `docs/tech-debt-register.md`?" +4. If the user chose "Close and log tech debt": append each advisory deviation to `docs/tech-debt-register.md` in this format: + ``` + - **[date]** ([story title]): [deviation description] — tracked from [story file path] + ``` + Create the file with a `# Tech Debt Register` heading if it does not exist. -4. **Update `production/sprint-status.yaml`** (if it exists): +5. **Update `production/sprint-status.yaml`** (if it exists): - Find the entry matching this story's file path or ID - Set `status: done` and `completed: [today's date]` - Update the top-level `updated` field - This is a silent update — no extra approval needed (already approved in step above) +6. **Suggest a git commit**: Output a ready-to-use commit command covering the implementation files from the dev-story summary and the updated story file: + +``` +Suggested commit: +git add [src/ and tests/ files changed during implementation] [story-file-path] +git commit -m "feat: [story title] ([TR-ID])" +``` + +The `validate-commit.sh` hook will verify design doc references and check for hardcoded values automatically. + ### Session State Update After updating the story file, silently append to @@ -395,7 +424,9 @@ Run these in order: 1. `/smoke-check sprint` — verify the critical path still works end-to-end 2. `/team-qa sprint` — full QA cycle: test case execution, bug triage, sign-off report -3. `/gate-check` — advance to the next phase once QA approves +3. `/retrospective` — capture what went well, what didn't, and action items for the next sprint +4. `/gate-check` — advance to the next phase once QA approves (only if advancing a phase) +5. `/sprint-plan new` — plan the next sprint, incorporating velocity data and retrospective action items Do not run `/gate-check` until `/team-qa` returns APPROVED or APPROVED WITH CONDITIONS. ``` diff --git a/.claude/skills/story-readiness/SKILL.md b/.claude/skills/story-readiness/SKILL.md index 5390f68..8ddabcf 100644 --- a/.claude/skills/story-readiness/SKILL.md +++ b/.claude/skills/story-readiness/SKILL.md @@ -4,7 +4,7 @@ description: "Validate that a story file is implementation-ready. Checks for emb argument-hint: "[story-file-path or 'all' or 'sprint']" user-invocable: true allowed-tools: Read, Glob, Grep, AskUserQuestion, Task -model: haiku +model: sonnet --- # Story Readiness @@ -92,10 +92,14 @@ items pass or are explicitly marked N/A with a stated reason. observable condition — not "implement X" or "the system works correctly". Bad example: "Implement the jump mechanic." Good example: "Jump reaches max height of 5 units within 0.3 seconds when jump is held." -- [ ] **No acceptance criteria require judgment calls**: Criteria like +- [ ] **No acceptance criteria require judgment calls** *(auto-pass for `Type: Visual/Feel`)*: Criteria like "feels responsive" or "looks good" are not testable without a defined - benchmark. These must be replaced with specific observable conditions or - playtest protocols. + benchmark. For Logic, Integration, UI, and Config/Data stories, these must be + replaced with specific observable conditions. For Visual/Feel stories, subjective + criteria are expected and this check auto-passes — instead verify that each + subjective criterion has a paired playtest protocol or evidence requirement + (e.g., "evidence doc required at `production/qa/evidence/[slug]-evidence.md`"). + PASS if the acceptance criterion ends with or is accompanied by an explicit reference to a file path such as `production/qa/evidence/[slug]-evidence.md`. NEEDS WORK if the criterion is purely subjective with no evidence file path specified. ### Architecture Completeness @@ -176,8 +180,11 @@ items pass or are explicitly marked N/A with a stated reason. ### Definition of Done -- [ ] **At least 3 testable acceptance criteria**: Fewer than 3 suggests - the story is either trivially small (should it be a story?) or under-specified. +- [ ] **Minimum testable acceptance criteria by story type**: + - Logic / Integration stories: at least 3 + - Visual/Feel and UI stories: at least 2 + - Config/Data stories: at least 1 + Apply the threshold matching the story's `Type:` field. If the story has fewer than the minimum, mark as NEEDS WORK. - [ ] **Performance budget noted if applicable**: If this story touches any part of the gameplay loop, rendering, or physics, a performance budget or a "no performance impact expected — [reason]" note is present. diff --git a/.claude/skills/team-audio/SKILL.md b/.claude/skills/team-audio/SKILL.md index f719864..c93e708 100644 --- a/.claude/skills/team-audio/SKILL.md +++ b/.claude/skills/team-audio/SKILL.md @@ -1,9 +1,10 @@ --- name: team-audio description: "Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer for full audio pipeline from direction to implementation." -argument-hint: "[feature or area to design audio for]" +argument-hint: "[feature or area to design audio for] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite +model: sonnet --- If no argument is provided, output usage guidance and exit without spawning any agents: @@ -16,6 +17,19 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next step. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + 1. **Read the argument** for the target feature or area (e.g., `combat`, `main menu`, `forest biome`, `boss encounter`). @@ -87,7 +101,9 @@ Spawn the `gameplay-programmer` agent to: 4. **Compile the audio design document** combining all team outputs. -5. **Save to** `design/gdd/audio-[feature].md`. +5. **Save to** `design/audio/audio-[feature].md`. + + Note: If `design/audio/` does not exist, the sub-agent writing the document should create it (the directory will be created automatically when the file is written). 6. **Output a summary** with: audio event count, estimated asset count, implementation tasks, and any open questions between team members. diff --git a/.claude/skills/team-combat/SKILL.md b/.claude/skills/team-combat/SKILL.md index f08bcb6..201014b 100644 --- a/.claude/skills/team-combat/SKILL.md +++ b/.claude/skills/team-combat/SKILL.md @@ -1,9 +1,10 @@ --- name: team-combat description: "Orchestrate the combat team: coordinates game-designer, gameplay-programmer, ai-programmer, technical-artist, sound-designer, and qa-tester to design, implement, and validate a combat feature end-to-end." -argument-hint: "[combat feature description]" +argument-hint: "[combat feature description] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite +model: sonnet --- **Argument check:** If no combat feature description is provided, output: > "Usage: `/team-combat [combat feature description]` — Provide a description of the combat feature to design and implement (e.g., `melee parry system`, `ranged weapon spread`)." @@ -16,6 +17,19 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next phase. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + ## Team Composition - **game-designer** — Design the mechanic, define formulas and edge cases - **gameplay-programmer** — Implement the core gameplay code @@ -58,6 +72,15 @@ Then spawn the **primary engine specialist** to validate the proposed architectu - Any proposed APIs that are deprecated or changed in the pinned engine version? - Output: engine architecture notes — incorporate into the architecture before Phase 3 begins +Use `AskUserQuestion`: +- Prompt: "Architecture sketch complete. Approve to proceed with parallel implementation." +- Options: + - `[A] Proceed — spawn implementation agents (gameplay-programmer, ai-programmer, technical-artist, sound-designer)` + - `[B] Revise the architecture first — I'll describe what needs to change` + - `[C] Stop here — I'll continue later` + +Only spawn implementation agents if user selects [A]. + ### Phase 3: Implementation (parallel where possible) Delegate in parallel: - **gameplay-programmer**: Implement core combat mechanic code diff --git a/.claude/skills/team-level/SKILL.md b/.claude/skills/team-level/SKILL.md index b5dc161..3e53c93 100644 --- a/.claude/skills/team-level/SKILL.md +++ b/.claude/skills/team-level/SKILL.md @@ -1,9 +1,10 @@ --- name: team-level description: "Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation." -argument-hint: "[level name or area to design]" +argument-hint: "[level name or area to design] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite +model: sonnet --- When this skill is invoked: @@ -13,6 +14,19 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next step. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + 1. **Read the argument** for the target level or area (e.g., `tutorial`, `forest dungeon`, `hub town`, `final boss arena`). @@ -134,7 +148,12 @@ Spawn the `qa-tester` agent to: 4. **Compile the level design document** combining all team outputs into the level design template format. -5. **Save to** `design/levels/[level-name].md`. +After all subagent outputs are collected, spawn `level-designer` via Task to compile and write the final document: +- Pass: all subagent outputs (verbatim), the level brief, game pillars, relevant GDD sections +- Ask level-designer to: compile into the level design document format, then request user approval before writing ("May I write the compiled level design to design/levels/[level-name].md?") +- The orchestrator does NOT call Write directly for the final document. + +5. **Save to** `design/levels/[level-name].md` (handled by the level-designer subagent after user approval — see above). 6. **Output a summary** with: area overview, encounter count, estimated asset list, narrative beats, any cross-team dependencies or open questions, open diff --git a/.claude/skills/team-live-ops/SKILL.md b/.claude/skills/team-live-ops/SKILL.md index c4f6e7f..553e09d 100644 --- a/.claude/skills/team-live-ops/SKILL.md +++ b/.claude/skills/team-live-ops/SKILL.md @@ -1,9 +1,10 @@ --- name: team-live-ops description: "Orchestrate the live-ops team for post-launch content planning: coordinates live-ops-designer, economy-designer, analytics-engineer, community-manager, writer, and narrative-director to design and plan a season, event, or live content update." -argument-hint: "[season name or event description]" +argument-hint: "[season name or event description] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite +model: sonnet --- **Argument check:** If no season name or event description is provided, output: > "Usage: `/team-live-ops [season name or event description]` — Provide the name or description of the season or live event to plan." @@ -16,6 +17,19 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next phase. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + ## Team Composition - **live-ops-designer** — Season structure, event cadence, retention mechanics, battle pass - **economy-designer** — Live economy balance, store rotation, currency pricing, pity timers @@ -100,7 +114,7 @@ Present a summary to the user with: - **Analytics readiness**: are success criteria defined and instrumented? - **Ethics review**: check the Phase 3 economy design against `design/live-ops/ethics-policy.md` - If the file does not exist: flag "ETHICS REVIEW SKIPPED: `design/live-ops/ethics-policy.md` not found. Economy design was not reviewed against an ethics policy. Recommend creating one before production begins." Include this flag in the season design output document. Add to next steps: create `design/live-ops/ethics-policy.md`. - - If the file exists and a violation is found: flag "ETHICS FLAG: [element] in Phase 3 economy design violates [policy rule]. Approval is blocked until this is resolved." Do NOT issue a COMPLETE verdict or write output documents. Use `AskUserQuestion` with options: revise economy design / override with documented rationale / cancel. If user chooses to revise: re-spawn economy-designer to produce a corrected design, then return to Phase 7 review. + - If the file exists and a violation is found: flag "ETHICS FLAG: [element] in Phase 3 economy design violates [policy rule]. Approval is blocked until this is resolved." Do NOT issue a COMPLETE verdict or write output documents. Use `AskUserQuestion` with options: revise economy design / override with documented rationale / cancel. If user chooses to revise: re-spawn economy-designer to produce a corrected design, then return to Phase 7 review. If user selects Cancel: end with Verdict: BLOCKED — "Live ops design cancelled due to unresolved ethics violation. Resolve the flagged issues and re-run /team-live-ops." - **Open questions**: decisions still needed before production begins Ask the user to approve the season plan before delegating to production teams. Issue the COMPLETE verdict only after the user approves and no unresolved ethics violations remain. If an ethics violation is unresolved, end with Verdict: **BLOCKED**. diff --git a/.claude/skills/team-narrative/SKILL.md b/.claude/skills/team-narrative/SKILL.md index 373ad22..45f2833 100644 --- a/.claude/skills/team-narrative/SKILL.md +++ b/.claude/skills/team-narrative/SKILL.md @@ -1,9 +1,10 @@ --- name: team-narrative description: "Orchestrate the narrative team: coordinates narrative-director, writer, world-builder, and level-designer to create cohesive story content, world lore, and narrative-driven level design." -argument-hint: "[narrative content description]" +argument-hint: "[narrative content description] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite +model: sonnet --- If no argument is provided, output usage guidance and exit without spawning any agents: > Usage: `/team-narrative [narrative content description]` — describe the story content, scene, or narrative area to work on (e.g., `boss encounter cutscene`, `faction intro dialogue`, `tutorial narrative`). Do not use `AskUserQuestion` here; output the guidance directly. @@ -15,12 +16,26 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next phase. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + ## Team Composition - **narrative-director** — Story arcs, character design, dialogue strategy, narrative vision - **writer** — Dialogue writing, lore entries, item descriptions, in-game text - **world-builder** — World rules, faction design, history, geography, environmental storytelling - **art-director** — Character visual design, environmental visual storytelling, cutscene/cinematic tone - **level-designer** — Level layouts that serve the narrative, pacing, environmental storytelling beats +- **localization-lead** — Localization readiness — flags non-localizable strings, cultural assumptions, and i18n gaps ## How to Delegate @@ -30,7 +45,7 @@ Use the Task tool to spawn each team member as a subagent: - `subagent_type: world-builder` — World rules, faction design, history, geography - `subagent_type: art-director` — Character visual profiles, environmental visual storytelling, cinematic tone - `subagent_type: level-designer` — Level layouts that serve the narrative, pacing -- `subagent_type: localization-lead` — i18n validation, string key compliance, translation headroom +- `subagent_type: localization-lead` — Localization readiness — flags non-localizable strings, cultural assumptions, and i18n gaps Always provide full context in each agent's prompt (narrative brief, lore dependencies, character profiles). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 2 agents can run simultaneously). diff --git a/.claude/skills/team-polish/SKILL.md b/.claude/skills/team-polish/SKILL.md index 5cdd6ca..41fe1e2 100644 --- a/.claude/skills/team-polish/SKILL.md +++ b/.claude/skills/team-polish/SKILL.md @@ -1,9 +1,10 @@ --- name: team-polish description: "Orchestrate the polish team: coordinates performance-analyst, technical-artist, sound-designer, and qa-tester to optimize, polish, and harden a feature or area for release quality." -argument-hint: "[feature or area to polish]" +argument-hint: "[feature or area to polish] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite +model: sonnet --- If no argument is provided, output usage guidance and exit without spawning any agents: > Usage: `/team-polish [feature or area]` — specify the feature or area to polish (e.g., `combat`, `main menu`, `inventory system`, `level-1`). Do not use `AskUserQuestion` here; output the guidance directly. @@ -15,6 +16,21 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next phase. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + +**Director gate skip rule**: Before spawning any Tier 1 director or lead for review (outside of PHASE-GATE triggers), apply the resolved mode: skip if solo mode; skip if lean mode and this is not a PHASE-GATE. + ## Team Composition - **performance-analyst** — Profiling, optimization, memory analysis, frame budget - **engine-programmer** — Engine-level bottlenecks: rendering pipeline, memory, resource loading (invoke when performance-analyst identifies low-level root causes) diff --git a/.claude/skills/team-qa/SKILL.md b/.claude/skills/team-qa/SKILL.md index f8ba570..55e0c73 100644 --- a/.claude/skills/team-qa/SKILL.md +++ b/.claude/skills/team-qa/SKILL.md @@ -1,9 +1,10 @@ --- name: team-qa description: "Orchestrate the QA team through a full testing cycle. Coordinates qa-lead (strategy + test plan) and qa-tester (test case writing + bug reporting) to produce a complete QA package for a sprint or feature. Covers: test plan generation, test case writing, smoke check gate, manual QA execution, and sign-off report." -argument-hint: "[sprint | feature: system-name]" +argument-hint: "[sprint | feature: system-name] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion +model: sonnet agent: qa-lead --- @@ -14,6 +15,19 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next phase. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + ## Team Composition - **qa-lead** — QA strategy, test plan generation, story classification, sign-off report @@ -34,7 +48,7 @@ Always provide full context in each agent's prompt (story file paths, QA plan pa Before doing anything else, gather the full scope: 1. Detect the current sprint or feature scope from the argument: - - If argument is a sprint identifier (e.g., `sprint-03`): read all story files in `production/sprints/[sprint]/` + - If argument is a sprint identifier (e.g., `sprint-03`): Glob `production/sprints/` for files matching `*[sprint-identifier]*.md`. Read the matched file. If multiple match, use the most recently modified. - If argument is `feature: [system-name]`: glob story files tagged for that system - If no argument: read `production/session-state/active.md` and `production/sprint-status.yaml` (if present) to infer the active sprint @@ -53,13 +67,13 @@ Prompt the qa-lead to: - Identify which stories require automated test evidence vs. manual QA - Flag any stories with missing acceptance criteria or missing test evidence that would block QA - Estimate manual QA effort (number of test sessions needed) -- Check `tests/smoke/` for smoke test scenarios; for each, assess whether it can be verified given the current build. Produce a smoke check verdict: **PASS** / **PASS WITH WARNINGS [list]** / **FAIL [list of failures]** +- **Before assessing smoke status, check for an existing smoke check report**: Glob `production/qa/smoke-*.md` and read the most recently modified file (if found). If a report exists, use its verdict and findings directly — do not re-interview the user. If no report exists, note: "No prior smoke check report found — run `/smoke-check sprint` before proceeding." and set smoke check status to UNKNOWN (treat as PASS WITH WARNINGS for the purpose of continuing). Produce a smoke check verdict: **PASS** / **PASS WITH WARNINGS [list]** / **FAIL [list of failures]** / **UNKNOWN (no report found)** - Produce a strategy summary table and smoke check result: | Story | Type | Automated Required | Manual Required | Blocker? | |-------|------|--------------------|-----------------|----------| - **Smoke Check**: [PASS / PASS WITH WARNINGS / FAIL] — [details if not PASS] + **Smoke Check**: [PASS / PASS WITH WARNINGS / FAIL / UNKNOWN] — [source: `production/qa/smoke-[date].md` or "no report found"] — [details if not PASS] If the smoke check result is **FAIL**, the qa-lead must list the failures prominently. QA cannot proceed past the strategy phase with a failed smoke check. @@ -75,7 +89,8 @@ options: - "Cancel — resolve blockers first" ``` -If smoke check **FAIL**: do not proceed to Phase 3. Surface the failures and stop. The user must fix them and re-run `/team-qa`. +If smoke check **FAIL**: do not proceed to Phase 3. Surface the failures from the smoke check report and stop. The user must fix them, re-run `/smoke-check sprint`, and then re-run `/team-qa`. +If smoke check **UNKNOWN**: surface a warning — "No smoke check report found. Recommend running `/smoke-check sprint` before QA. Proceeding with caution." If smoke check **PASS WITH WARNINGS**: note the warnings for the sign-off report and continue. If blockers are present: list them explicitly. The user may choose to skip blocked stories or cancel the cycle. @@ -89,7 +104,7 @@ The test plan should cover: - **Automated Test Requirements**: which stories need test files, expected paths in `tests/` - **Manual QA Scope**: which stories need manual walkthrough and what to validate - **Out of Scope**: what is explicitly not being tested this cycle and why -- **Entry Criteria**: what must be true before QA can begin (smoke check pass, build stable) +- **Entry Criteria**: what must be true before QA can begin. Always include: (1) Smoke check PASS or PASS WITH WARNINGS report exists at `production/qa/smoke-*.md`, (2) build is stable (no crashes on launch), (3) all Must Have stories have Status: in-progress or done in `production/sprint-status.yaml`. Add any sprint-specific criteria beyond these. - **Exit Criteria**: what constitutes a completed QA cycle (all stories PASS or FAIL with bugs filed) Ask: "May I write the QA plan to `production/qa/qa-plan-[sprint]-[date].md`?" @@ -98,7 +113,7 @@ Write only after receiving approval. ### Phase 4: Test Case Writing (qa-tester) -> **Smoke check** is performed as part of Phase 2 (QA Strategy). If the smoke check returned FAIL in Phase 2, the cycle was stopped there. This phase only runs when the Phase 2 smoke check was PASS or PASS WITH WARNINGS. +> **Smoke check** is performed as part of Phase 2 (QA Strategy). If the smoke check returned FAIL in Phase 2, the cycle was stopped there. This phase only runs when the Phase 2 smoke check was PASS, PASS WITH WARNINGS, or UNKNOWN. For each story requiring manual QA (Visual/Feel, UI, Integration without automated tests): @@ -127,7 +142,7 @@ options: - "Skip manual QA for [story name] — not ready" ``` -### Phase 6: Manual QA Execution +### Phase 5: Manual QA Execution Walk through each story in the approved manual QA list. @@ -152,7 +167,7 @@ After collecting all results, summarize: - Stories FAIL: [count] — bugs filed: [IDs] - Stories BLOCKED: [count] -### Phase 7: QA Sign-Off Report +### Phase 6: QA Sign-Off Report Spawn `qa-lead` via Task to produce the sign-off report using all results from Phases 4–6. @@ -161,7 +176,6 @@ The sign-off report format: ```markdown ## QA Sign-Off Report: [Sprint/Feature] **Date**: [date] -**QA Lead sign-off**: [pending] ### Test Coverage Summary | Story | Type | Auto Test | Manual QA | Result | @@ -220,3 +234,11 @@ A summary covering: stories in scope, smoke check result, manual QA results, bug Verdict: **COMPLETE** — QA cycle finished. Verdict: **BLOCKED** — smoke check failed or critical blocker prevented cycle completion; partial report produced. + +## Session State Update + +After the final phase completes (sign-off report written or BLOCKED verdict reached), silently append to `production/session-state/active.md`: + +``` + +``` diff --git a/.claude/skills/team-release/SKILL.md b/.claude/skills/team-release/SKILL.md index 845199f..b002091 100644 --- a/.claude/skills/team-release/SKILL.md +++ b/.claude/skills/team-release/SKILL.md @@ -1,9 +1,10 @@ --- name: team-release description: "Orchestrate the release team: coordinates release-manager, qa-lead, devops-engineer, and producer to execute a release from candidate to deployment." -argument-hint: "[version number or 'next']" +argument-hint: "[version number or 'next'] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite +model: sonnet --- **Argument check:** If no version number is provided: 1. Read `production/session-state/active.md` and the most recent file in `production/milestones/` (if they exist) to infer the target version. @@ -17,6 +18,19 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next phase. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + ## Team Composition - **release-manager** — Release branch, versioning, changelog, deployment - **qa-lead** — Test sign-off, regression suite, release quality gate @@ -88,13 +102,19 @@ Delegate to **producer**: - Produce a partial report summarizing Phases 1–5 and what was skipped (Phase 6) and why. - Verdict: **BLOCKED** — release not deployed. +After the user selects "Override NO-GO with documented rationale": +- Ask (plain text, not widget): "Please describe the justification for overriding the NO-GO verdict. This will be embedded in the release record." +- Wait for the user's written justification. +- Embed the justification text in the partial approval record before Phase 6: append a "⚠️ Override Justification: [user's text]" field. +- Only then proceed to Phase 6. + ### Phase 6: Deployment (if GO) Delegate to **release-manager** + **devops-engineer**: - Tag the release in version control - Generate changelog using `/changelog` - Deploy to staging for final smoke test - Deploy to production -- Monitor for 48 hours post-release +- Human team action: Monitor dashboards and error rates for 48 hours post-release. Schedule a follow-up retrospective using `/retrospective` at the 48-hour mark. Delegate to **community-manager** (in parallel with deployment): - Finalize patch notes using `/patch-notes [version]` diff --git a/.claude/skills/team-ui/SKILL.md b/.claude/skills/team-ui/SKILL.md index 7f68b0f..50707bd 100644 --- a/.claude/skills/team-ui/SKILL.md +++ b/.claude/skills/team-ui/SKILL.md @@ -1,9 +1,10 @@ --- name: team-ui description: "Orchestrate the UI team through the full UX pipeline: from UX spec authoring through visual design, implementation, review, and polish. Integrates with /ux-design, /ux-review, and studio UX templates." -argument-hint: "[UI feature description]" +argument-hint: "[UI feature description] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite +model: sonnet --- When this skill is invoked, orchestrate the UI team through a structured pipeline. @@ -12,6 +13,21 @@ the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. The user must approve before moving to the next phase. +## Phase 0: Resolve Review Mode + +1. If `--review [mode]` was passed as an argument, use that mode. +2. Else read `production/review-mode.txt` — use whatever is written there. +3. Else default to `lean`. + +Modes: +- `full` — spawn all director and lead gates as described +- `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE) +- `solo` — skip all director gate spawning entirely; run the skill without any agent gates + +Store the resolved mode for use in all subsequent phases. + +**Director gate skip rule**: Before spawning creative-director, art-director, or any other Tier 1/2 director for review (outside of PHASE-GATE triggers), apply the resolved mode: skip if solo mode; skip if lean mode and this is not a PHASE-GATE. + ## Team Composition - **ux-designer** — User flows, wireframes, accessibility, input handling - **ui-programmer** — UI framework, screens, widgets, data binding, implementation diff --git a/.claude/skills/tech-debt/SKILL.md b/.claude/skills/tech-debt/SKILL.md index 1195626..5d624dc 100644 --- a/.claude/skills/tech-debt/SKILL.md +++ b/.claude/skills/tech-debt/SKILL.md @@ -3,7 +3,8 @@ name: tech-debt description: "Track, categorize, and prioritize technical debt across the codebase. Scans for debt indicators, maintains a debt register, and recommends repayment scheduling." argument-hint: "[scan|add|prioritize|report]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write +allowed-tools: Read, Glob, Grep, Write, AskUserQuestion +model: sonnet --- ## Phase 1: Parse Subcommand @@ -52,9 +53,27 @@ If no, stop here. Verdict: **BLOCKED** — user declined write. ## Phase 2B: Add Mode -Prompt for: description, category, affected files, estimated fix effort, impact if left unfixed. +Ask the user for the description, affected files, and impact if left unfixed (plain text prompts). -Present the new entry to the user. +Then use `AskUserQuestion` to collect the **category**: +- Prompt: "What category does this tech debt belong to?" +- Options: + - `[A] Architecture Debt — wrong abstractions, missing patterns, coupling issues` + - `[B] Code Quality Debt — duplication, complexity, naming, missing types` + - `[C] Test Debt — missing tests, flaky tests, untested edge cases` + - `[D] Documentation Debt — missing/outdated docs, undocumented APIs` + - `[E] Dependency Debt — outdated packages, deprecated APIs, version conflicts` + - `[F] Performance Debt — known slow paths, memory issues, unoptimized queries` + +Then use `AskUserQuestion` to collect the **estimated fix effort**: +- Prompt: "What is the estimated effort to fix this item?" +- Options: + - `[A] S — Small (under 1 day)` + - `[B] M — Medium (1–3 days)` + - `[C] L — Large (3–7 days)` + - `[D] XL — Extra Large (over 1 week)` + +Present the complete new entry to the user. Ask: "May I append this entry to `docs/tech-debt-register.md`?" diff --git a/.claude/skills/test-evidence-review/SKILL.md b/.claude/skills/test-evidence-review/SKILL.md index afa7dff..279cd38 100644 --- a/.claude/skills/test-evidence-review/SKILL.md +++ b/.claude/skills/test-evidence-review/SKILL.md @@ -4,6 +4,7 @@ description: "Quality review of test files and manual evidence documents. Goes b argument-hint: "[story-path | sprint | system-name]" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet --- # Test Evidence Review diff --git a/.claude/skills/test-flakiness/SKILL.md b/.claude/skills/test-flakiness/SKILL.md index c2427af..099a193 100644 --- a/.claude/skills/test-flakiness/SKILL.md +++ b/.claude/skills/test-flakiness/SKILL.md @@ -4,6 +4,7 @@ description: "Detect non-deterministic (flaky) tests by reading CI run logs or t argument-hint: "[ci-log-path | scan | registry]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash +model: sonnet --- # Test Flakiness Detection diff --git a/.claude/skills/test-helpers/SKILL.md b/.claude/skills/test-helpers/SKILL.md index a7e10b1..0592ac9 100644 --- a/.claude/skills/test-helpers/SKILL.md +++ b/.claude/skills/test-helpers/SKILL.md @@ -4,6 +4,7 @@ description: "Generate engine-specific test helper libraries for the project's t argument-hint: "[system-name | all | scaffold]" user-invocable: true allowed-tools: Read, Glob, Grep, Write +model: sonnet --- # Test Helpers diff --git a/.claude/skills/test-setup/SKILL.md b/.claude/skills/test-setup/SKILL.md index a1b193d..634128b 100644 --- a/.claude/skills/test-setup/SKILL.md +++ b/.claude/skills/test-setup/SKILL.md @@ -4,6 +4,7 @@ description: "Scaffold the test framework and CI/CD pipeline for the project's e argument-hint: "[force]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write +model: sonnet --- # Test Setup diff --git a/.claude/skills/ux-design/SKILL.md b/.claude/skills/ux-design/SKILL.md index 31ab8e2..ce3389a 100644 --- a/.claude/skills/ux-design/SKILL.md +++ b/.claude/skills/ux-design/SKILL.md @@ -4,6 +4,7 @@ description: "Guided, section-by-section UX spec authoring for a screen, flow, o argument-hint: "[screen/flow name] or 'hud' or 'patterns'" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Task +model: sonnet agent: ux-designer --- @@ -54,6 +55,9 @@ If the player journey file does not exist, note the gap and proceed: > means we'll be making assumptions about player context. Consider running a player > journey session after this spec is drafted." +Also add to the UX spec's Open Questions section: +> "Player journey map not yet created. Template available at `.claude/docs/templates/player-journey.md`. Run `/ux-design` Phase 2b or create it manually to establish player context for this screen." + ### 2c: GDD UI Requirements Glob `design/gdd/*.md` and grep for `UI Requirements` sections. Read any GDD whose @@ -416,9 +420,13 @@ Context -> Questions -> Options -> Decision -> Draft -> Approval -> 4. **Decision**: User picks an approach or provides custom direction. 5. **Draft**: Write the section content in conversation for review. Flag provisional assumptions explicitly. -6. **Approval**: "Does this capture it? Any changes before I write it to the file?" -7. **Write**: Use `Edit` to replace the `[To be designed]` placeholder with approved - content. Confirm the write. +6. **Approval**: Use `AskUserQuestion`: + - "Does this capture the [section name] correctly?" + - Options: "Yes — write it to the file", "Small changes needed (describe below)", "Major rethink needed" + Do not proceed to step 7 until the user selects "Yes". +7. **Write**: Use `AskUserQuestion`: "May I write the [section name] section to `[filepath]`?" + - Options: "Yes, write it", "Wait — one more change" + Once confirmed, use `Edit` to replace the `[To be designed]` placeholder with approved content. After writing each section, update `production/session-state/active.md`. @@ -501,7 +509,9 @@ This is the largest and most interactive section. Work through it in sub-section area, action bar, sidebar, etc.). - Offer 2-3 zone arrangements with rationale for each. Reference platform and input context gathered from game concept. -- Ask: "Do any of these match your mental image, or shall we build a custom arrangement?" +- Use `AskUserQuestion` to capture the choice: + - "Which zone arrangement fits best?" + - Options: [the 2-3 named arrangements you just presented] + "None — build a custom arrangement" **Sub-section 3 — Component Inventory**: - For each zone, list the UI components it contains. For each component, note: @@ -631,9 +641,9 @@ Walk through the ux-designer agent's standard checklist for this screen: - Screen reader considerations for any non-text elements - Any motion or animation that needs a reduced-motion alternative -Use `AskUserQuestion` to surface any open questions on accessibility tier: -- "Has the accessibility tier been committed to for this project?" - - Options: "Yes, read from requirements doc", "Not yet — let's flag it as a question", "Skip accessibility section for now" +If no accessibility tier has been defined for this project, note the gap in the UX spec's Open Questions section: +> "Accessibility tier not yet defined — consider WCAG-AA as a baseline. Run `/gate-check` to see whether this blocks any phase gates." +Then continue to the next section without stopping. --- @@ -672,7 +682,9 @@ Write at least 5 specific, testable criteria that a QA tester can verify without - 1 accessibility criterion (per committed tier) - 1 criterion specific to this screen's core purpose -Ask the user to confirm: "Do these criteria cover what would actually make this screen 'done' for your QA process?" +Use `AskUserQuestion` to confirm: +- "Do these acceptance criteria cover what would make this screen 'done' for your QA process?" +- Options: "Yes — these are solid", "Add one more criterion", "Remove or rephrase one" --- @@ -812,8 +824,9 @@ For each pattern (existing or new), document: **Reference**: [Screenshot path or ASCII example, if available] ``` -Work through patterns in groups. Offer: "Shall I draft the first batch based on what -I've found in the existing specs, or do you want to define them one by one?" +Work through patterns in groups. Use `AskUserQuestion`: +- "How do you want to work through these patterns?" +- Options: "Draft the first batch from existing specs (faster)", "Define them one by one (more control)", "Start with the most-used pattern first" --- @@ -839,8 +852,9 @@ this screen have a corresponding element in this spec? Present any gaps. **2. Pattern library alignment**: Are all interaction patterns used in this spec referenced by name? If a new pattern was invented during this spec session, flag it for addition to the pattern library: -> "This spec uses [pattern name], which isn't in the pattern library yet. -> Want to add it now, or flag it as a gap?" +Use `AskUserQuestion`: +- "This spec uses [pattern name], which isn't in the pattern library yet. What should we do?" +- Options: "Add it to the pattern library now", "Flag it as a gap and continue", "Skip — this pattern is one-off" **3. Navigation consistency**: Do the entry/exit points in this spec match the navigation map in any related specs? Flag mismatches. diff --git a/.claude/skills/ux-review/SKILL.md b/.claude/skills/ux-review/SKILL.md index 609bf69..c65bc8e 100644 --- a/.claude/skills/ux-review/SKILL.md +++ b/.claude/skills/ux-review/SKILL.md @@ -4,6 +4,7 @@ description: "Validates a UX spec, HUD design, or interaction pattern library fo argument-hint: "[file-path or 'all' or 'hud' or 'patterns']" user-invocable: true allowed-tools: Read, Glob, Grep +model: sonnet agent: ux-designer --- diff --git a/.claude/skills/vertical-slice/SKILL.md b/.claude/skills/vertical-slice/SKILL.md new file mode 100644 index 0000000..03083a7 --- /dev/null +++ b/.claude/skills/vertical-slice/SKILL.md @@ -0,0 +1,359 @@ +--- +name: vertical-slice +description: "Pre-Production validation — build a production-quality end-to-end build to confirm the full game loop is achievable before committing to Production. Run after GDDs, architecture, and UX specs are complete. Produces a PROCEED/PIVOT/KILL verdict that gates the Pre-Production → Production transition." +argument-hint: "[--review full|lean|solo]" +user-invocable: true +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion +model: sonnet +agent: prototyper +isolation: worktree +--- + +## Purpose + +The **vertical slice** answers a different question from the concept prototype: +*"Can we build this full game loop at production quality, on schedule?"* + +**Default use** — run late in Pre-Production, after GDDs, architecture, and UX +specs are complete. It is a near-production-quality build demonstrating one complete +[start → challenge → resolution] cycle. + +**Post-pivot?** If a PIVOT verdict from an earlier vertical slice sent you back to +revise GDDs and architecture, run this again after revisions to re-validate. It can +be run as many times as needed until a PROCEED or KILL verdict is reached. + +It validates: + +1. The pipeline (can the team actually produce this quality of content?) +2. Execution feasibility (are the architecture decisions correct for this game?) +3. Fun survival (does the fun from the concept prototype survive full design?) +4. **Velocity** (how long did this take? That's your real production rate estimate.) + +**Earlier in the project?** If you haven't written GDDs yet and want to validate +whether the core idea is worth designing, run `/prototype` (concept prototype) instead. + +--- + +## Phase 1: Resolve Review Mode and Load Context + +Resolve the review mode: +1. If `--review [full|lean|solo]` was passed → use that +2. Else read `production/review-mode.txt` → use that value +3. Else → default to `lean` + +See `.claude/docs/director-gates.md` for the full check pattern. + +Read the following files to understand the full design intent: +- `CLAUDE.md` — tech stack and engine +- `design/gdd/game-concept.md` — core fantasy and game pillars +- `design/gdd/systems-index.md` — MVP systems and their priorities +- `docs/architecture/architecture.md` — layer structure +- `docs/architecture/control-manifest.md` — technical rules for implementation +- Key GDDs for the systems being sliced + +--- + +## Phase 2: Define the Slice Scope and Validation Question + +Before building, define the **falsifiable validation question**: + +> *"Does a player, starting from nothing, experience [core fantasy from game-concept.md] +> within [N] minutes, without developer guidance — and can we build one such loop +> in [X] days at representative quality?"* + +Both parts matter: player experience AND build feasibility. + +**Scope discipline:** +- Include ALL core loop systems (minimum). If a system is required to complete one + [start → challenge → resolution] cycle, it must be in the slice. +- **Target scope: 3–5 minutes of polished, continuous gameplay.** This is the + industry-standard vertical slice length — long enough to demonstrate mechanics + and tone, short enough to build at representative quality. If your slice would + take longer than 5 minutes to play through, cut content, not quality. +- **Cut scope before cutting quality.** A low-quality slice that looks nothing like + the intended game cannot validate production feasibility. +- If the scope feels too large to build in 1–3 weeks, the slice scope is wrong — + not too big to build, but the slice is trying to prove too much at once. + +**Scope creep warning:** The vertical slice is the highest-risk moment for scope +creep in the pre-production phase. Features feel "almost there" and it's tempting +to add "just one more system." Resist this. Cut, do not extend. + +Present scope to the user before building and get confirmation. + +--- + +## Phase 3: Plan the Build + +Define in bullet points: +- Systems implemented (which GDD sections are being exercised) +- The complete game loop cycle ([start] → [challenge] → [resolution] exactly) +- Art and audio quality level (placeholder acceptable, representative preferred) +- Specific, measurable success criteria for the validation question +- Hard time limit: [X] days. If exceeded, scope was wrong — stop and reassess. + +Ask the user to confirm scope before building. + +Once confirmed, write a session checkpoint to `production/session-state/active.md` +(create `production/session-state/` if it does not exist). Include: concept name, +validation question, systems in scope, art quality level, and current phase ("Phase +4 — Implement"). Update this file at the end of each build day with what was +completed. This is the primary recovery mechanism if the session ends mid-slice — +multi-week Engine builds will span many sessions. + +--- + +## Phase 4: Implement + +Ask: "May I create the vertical slice directory at +`prototypes/[concept-name]-vertical-slice/` and begin implementation?" + +If yes, create the directory. Every file must begin with: + +``` +// VERTICAL SLICE - NOT FOR PRODUCTION +// Validation Question: [What this build is proving] +// Date: [Current date] +``` + +**Quality standards** — higher than concept prototype, not full production: +- Follow architecture layers from `docs/architecture/control-manifest.md` +- Naming conventions from `.claude/docs/technical-preferences.md` +- No hardcoded gameplay values — use constants or config files +- Basic error handling on critical paths +- Placeholder art acceptable; representative art preferred + +**Multi-turn loop:** After writing the initial files, ask the user to run the +build and report what they observe. Iterate until the complete game loop cycle +is demonstrable. Each round: +1. User runs → reports errors or observations +2. Agent fixes errors or adjusts systems +3. Repeat until the full [start → challenge → resolution] cycle is playable + +**Sunk cost checkpoint (day 3 of planned timeline):** If the full game loop cycle +is not yet demonstrable, stop and reassess. Either the scope is too large or an +architectural assumption is wrong. Surface the blocker explicitly rather than +continuing to iterate. + +Conduct at least 1 playtest session once the loop is demonstrable. + +**Playtesting tip:** If you can get anyone who hasn't seen the game to play it — +a friend, family member, online community — watch them silently without explaining +anything. Don't guide them. Their confusion reveals what the game isn't +communicating on its own. This gives much better signal than self-testing. + +**No external testers available?** Use rotation within the team: Dev A built +system X, so Dev A is a naive tester for system Y. Even a two-person team can +rotate effectively. Solo? Step away for 2-3 days then play through as a new +player — you won't have perfect first-impression signal but you'll catch the +critical blockers. Also try a "silent walkthrough": play your own slice in one +sitting without stopping to fix anything and log every moment you hesitate. + +**Want richer observation data?** Ask the tester to **think aloud** as they play — +narrate what they're doing and why in real time. "I'm trying to figure out how to +attack... I pressed E... nothing... is it click?" This surfaces confusion the +instant it occurs rather than in retrospect. Best for onboarding and UI clarity +validation. Silent observation is still better for feel testing; think-aloud +changes the experience slightly but produces far more granular UX data. + +**Async remote option:** Record a Loom or OBS session — give someone the build, +ask them to record their screen + audio, and send you the video. You get genuine +first-impression data without synchronous scheduling. Works across timezones. + +**Testing AI, NPC, or complex system behavior before it's fully implemented?** Use the +**Wizard of Oz** technique: one person plays normally while a second person secretly +controls the NPC or system behavior in real time. The player believes it's automated. +This validates the *design intent* of an AI or economy system before the implementation +is complete — and reveals exactly what behaviors the system must produce to feel correct. +Particularly useful for vertical slices where an AI system is in scope but not yet +polished enough for unguided testing. + +--- + +## Phase 5: Playtest Debrief + +The loop is demonstrable. Before writing the report, collect structured observations +from actually playing it. Do NOT skip to report generation — the report is only as +good as the observations you capture here. + +Say exactly this: +> "Play through the complete [start → challenge → resolution] cycle from scratch, +> as if you're a new player with no knowledge of how it was built. Don't skip ahead +> or use developer shortcuts. Come back when you've completed the full loop — +> or when you've hit something that stopped you." + +Once the user returns, ask these questions **one at a time**: + +1. **Loop completion:** + > "Did you complete the full [start → challenge → resolution] cycle on your own, + > without needing any guidance from me or prior knowledge of the build?" + +2. **Time check:** + > "How long did it take to reach the first meaningful action — the first moment + > where you felt like you were actually playing the game?" + +3. **Core fantasy:** + > "The game is supposed to make you feel [core fantasy from game-concept.md]. + > Did it? Be honest — not 'kind of' but specifically what you felt and when." + +4. **Blockers:** + > "What stopped you, confused you, or pulled you out of the experience? Any + > moment where you weren't sure what to do, or where something broke?" + +5. **Pipeline check:** + > "As the developer — not the player — does this feel achievable at this quality + > for the full game? What surprised you about how long things took to build?" + +6. **Verdict:** + > "PROCEED, PIVOT, or KILL — and the specific reason." + +If any answer is vague, ask: "Can you give me the specific moment where that happened?" +Precise observations populate the report. Vague ones produce a useless report. + +--- + +## Phase 6: Generate Vertical Slice Report + + +Track velocity throughout the build. Log: +- Day 1: what was built +- Day 2: what was built +- etc. + +This is the most honest data you will ever have about your production rate. Do not +skip it. It feeds directly into sprint planning. + +Read `.claude/docs/templates/vertical-slice-report.md` to get the report structure. +If the template file is not found, use this fallback structure: +- `## Vertical Slice Report — [Game Title] — [Date]` +- `### Executive Summary` (PROCEED / PIVOT / STOP verdict + 2-sentence rationale) +- `### Core Loop Validation` (what was tested, what passed, what failed) +- `### Feel Assessment` (animation, controls, feedback — subjective notes) +- `### Technical Findings` (performance, engine issues, architectural risks) +- `### Velocity Log` (day-by-day actual progress — do not skip) +- `### Recommended Next Steps` + +Fill in every section based on what was observed and built during this session. +The velocity log must reflect actual day-by-day progress, not estimates — this is +the most honest production rate data you will ever have. Replace all placeholder +text with real observations. + +### Lessons Learned +- What assumptions were broken by actually building to near-production quality? +- What surprised us about the pipeline or architecture? +- What would we change about the slice scope if we ran this again? +``` + +Ask: "May I write this report to +`prototypes/[concept-name]-vertical-slice/REPORT.md`?" + +If yes, write the file. Then update `prototypes/index.md` (create if it does not +exist) — append one row to the vertical slice table: concept name, date, verdict, +and a link to the REPORT.md. Note whether this was a first-run slice or a re-run +after a PIVOT. The velocity log in this report is some of the most valuable data in +the project — cross-reference it with sprint estimates. + +--- + +## Phase 7: Creative Director Review + +**Review mode check:** +- `solo` → skip. Note: "CD-PLAYTEST skipped — Solo mode." +- `lean` → skip (not a PHASE-GATE). Note: "CD-PLAYTEST skipped — Lean mode." +- `full` → spawn `creative-director` via Task using gate **CD-PLAYTEST** + (`.claude/docs/director-gates.md`). + +Pass: the full REPORT.md content, the validation question, game pillars and core +fantasy from `design/gdd/game-concept.md`. + +The creative director evaluates the vertical slice result against the game's +creative vision and pillars, then confirms, modifies, or overrides the +recommendation. Their verdict is final. Update REPORT.md if the verdict differs. + +--- + +## Phase 8: Summary and Next Steps + +Output a summary: the validation question, velocity data, and final recommendation. +Link to `prototypes/[concept-name]-vertical-slice/REPORT.md`. + +**If PROCEED:** +Your vertical slice validated the full game loop. The project is ready for +Production. + +Recommended next steps: +- `/create-epics layer:foundation` — plan Foundation layer epics +- `/create-epics layer:core` — plan Core layer epics +- `/create-stories [epic-slug]` — break each epic into implementable stories +- `/sprint-plan` — plan the first sprint using velocity data from the slice +- `/gate-check pre-production` — formally advance the stage to Production + +**Playtest note:** `/gate-check` will look for documented playtest evidence. +At minimum, 1 documented session with a REPORT.md showing PROCEED is required +to pass the gate. More sessions give more reliable signal — 3+ is recommended +before committing the full team to Production, but is not a hard gate. + +**If PIVOT:** + +Before routing back to GDD revision, capture the carry-forward note. Ask these +two questions (plain text, one at a time): + +1. "What systems or mechanics worked at this quality level and should be preserved in the revised design?" +2. "What specifically failed — the core loop, the architecture, the pipeline, or the fun?" + +Ask: "May I write this to `prototypes/[concept-name]-vertical-slice/PIVOT-NOTE.md`?" + +If yes, write the file with: what worked, what failed, the specific systems or +architecture decisions that need revision, and what the next slice should prove +differently. When `/vertical-slice` is next run after a PIVOT, check the +`prototypes/` directory for a `PIVOT-NOTE.md` — use it to frame the new validation +question and inform scope decisions. + +- Revise affected GDDs with `/design-system [mechanic]` +- Address architecture issues via `/architecture-decision` +- Then re-run `/vertical-slice` to validate the revised direction + +**If KILL:** + +Before abandoning the concept, confirm the verdict is sound: + +- [ ] Full game loop takes >5 minutes even for an experienced player? +- [ ] No emotional high point (delight, surprise, satisfaction) observed in any playtest session? +- [ ] 50%+ of testers confused or stuck at the same point after 2+ slice attempts? +- [ ] Architecture issues would require rebuilding more than 50% of what was built? +- [ ] This is the 3rd vertical slice attempt on the same concept? + +If 2+ boxes apply → KILL verdict is sound. If 0–1 apply → one targeted PIVOT may recover the concept. + +**Document the kill in `prototypes/GRAVEYARD.md`** (create if it doesn't exist). +Ask: "May I append this to `prototypes/GRAVEYARD.md`?" If yes, add one entry: + +``` +## [Concept Name] Vertical Slice — YYYY-MM-DD +- **Kill reason:** [what specifically prevented the player from experiencing the core fantasy] +- **What worked at slice quality:** [systems or mechanics that held up] +- **What failed:** [core loop issue, architecture decision, or pipeline blocker] +- **Next time:** [one specific change for the next time a similar concept is attempted] +``` + +- Return to `/brainstorm` with what you learned +- Or run `/prototype [new-concept]` to test a new direction cheaply first + +--- + +### Important Constraints + +- Vertical slice code must NEVER be refactored into production — it is reference only +- Production code must NEVER import from `prototypes/` +- If recommendation is PROCEED, production implementation is written from scratch + using the slice as a design reference only +- Scope cuts are acceptable; quality cuts are not — a low-quality slice proves nothing +- Total effort: 1–3 weeks. If longer, scope is too large — cut the slice, not the quality. +- Day 3 sunk cost rule: if the full game loop cycle is not demonstrable by then, + stop and surface the blocker +- **Networked/multiplayer games:** A local vertical slice cannot validate the feel + of a networked mechanic. Latency fundamentally changes how combat, movement, and + prediction feel — testing locally at 0ms will feel entirely different at 80ms + network delay. The slice can validate that the game loop is interesting and + complete; it cannot validate that networked mechanics feel good under real + conditions. Network feel requires real peers or simulated latency. diff --git a/.gitignore b/.gitignore index 23d22bb..5830aab 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,9 @@ production/session-logs/ expansions/ +# === Marrow (eval tooling — never commit) === +marrow/ + # === Runtime Artifacts (auto-generated, start empty on fresh clone) === # Created on first use by /consistency-check and /architecture-review docs/consistency-failures.md diff --git a/CCGS Skill Testing Framework/CLAUDE.md b/CCGS Skill Testing Framework/CLAUDE.md index f3fe49b..ef1334b 100644 --- a/CCGS Skill Testing Framework/CLAUDE.md +++ b/CCGS Skill Testing Framework/CLAUDE.md @@ -7,7 +7,7 @@ framework. It is self-contained and separate from any game project. | File | Purpose | |------|---------| -| `catalog.yaml` | Master registry for all 72 skills and 49 agents. Contains category, spec path, and last-test tracking fields. Always read this first when running any test command. | +| `catalog.yaml` | Master registry for all 73 skills and 49 agents. Contains category, spec path, and last-test tracking fields. Always read this first when running any test command. | | `quality-rubric.md` | Category-specific pass/fail metrics. Read the matching `###` section for the skill's category when running `/skill-test category`. | | `skills/[category]/[name].md` | Behavioral spec for a skill — 5 test cases + protocol compliance assertions. | | `agents/[tier]/[name].md` | Behavioral spec for an agent — 5 test cases + protocol compliance assertions. | diff --git a/CCGS Skill Testing Framework/README.md b/CCGS Skill Testing Framework/README.md index 82c4476..f674a6a 100644 --- a/CCGS Skill Testing Framework/README.md +++ b/CCGS Skill Testing Framework/README.md @@ -15,7 +15,7 @@ Tests the skills and agents themselves — not any game built with them. CCGS Skill Testing Framework/ ├── README.md ← you are here ├── CLAUDE.md ← tells Claude how to use this framework -├── catalog.yaml ← master registry: all 72 skills + 49 agents, coverage tracking +├── catalog.yaml ← master registry: all 73 skills + 49 agents, coverage tracking ├── quality-rubric.md ← category-specific pass/fail metrics for /skill-test category │ ├── skills/ ← behavioral spec files for skills (one per skill) @@ -56,7 +56,7 @@ All testing is driven by two skills already in the framework: ``` /skill-test static [skill-name] # Check one skill (7 checks) -/skill-test static all # Check all 72 skills +/skill-test static all # Check all 73 skills ``` ### Run a behavioral spec test diff --git a/CLAUDE.md b/CLAUDE.md index 789b883..d365d5e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # Claude Code Game Studios -- Game Studio Agent Architecture -Indie game development managed through 48 coordinated Claude Code subagents. +Indie game development managed through 49 coordinated Claude Code subagents. Each agent owns a specific domain, enforcing separation of concerns and quality. ## Technology Stack diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..90c9fc9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +# Contributing to Claude Code Game Studios + +CCGS is a coordination framework for indie game development using Claude Code. +Contributions are welcome — bug fixes, new skills that fill a real gap, agent +improvements, and hook fixes. PRs that don't fit the framework's direction will +be closed without lengthy explanation. + +## What Makes a Good PR + +- **Bug fixes** — something is broken, here's the fix +- **New skills** that address a workflow gap not already covered +- **Improvements** to existing agents, skills, or hooks +- **Documentation corrections** — wrong info, broken references, outdated steps + +Feature requests submitted as PRs will be closed. Open an issue instead. + +**What this repo isn't:** +CCGS is the system that helps you build games, not a place to store the games +you build with it. GDDs, ADRs, PRDs, game concepts, level designs, narrative +docs, or any other output generated by CCGS for your own project won't be +merged here — keep those in your own repo. + +## The Non-Negotiable Technical Rules + +These are the things that will get your PR rejected if you miss them. + +**Skill files** +- Skills live in `.claude/skills//SKILL.md` — the subdirectory format is + required. Flat `.md` files are silently ignored by Claude Code. +- SKILL.md must include YAML frontmatter: `name`, `description`, + `argument-hint`, `allowed-tools`, and `model` +- Model tier: `haiku` for read-only status checks, `opus` for multi-document + synthesis and phase gates, `sonnet` for everything else + +**Hooks** +- Use `grep -E` — never `grep -P` (Perl regex breaks on Windows Git Bash) +- Include fallbacks for systems without `jq` or `python` installed +- Hooks run on every session start — they must exit quickly and gracefully + (`exit 0`) when not applicable + +**Agents** +- New agents must include a **Collaboration Protocol** section that describes + how the agent asks questions and defers decisions to the user +- Agents must not modify files outside their documented domain without explicit + user delegation + +**Reference docs** +- If your PR adds or changes a skill, agent, or hook, update the matching + reference doc (agent-roster, skills-reference, hooks-reference, or + rules-reference). PRs that add things without updating the index will be + sent back. + +## The Collaborative Principle + +CCGS is not an autonomous system. Every workflow follows: +**Question → Options → Decision → Draft → Approval → Write** + +Skills and agents must ask before acting. Nothing writes to files without +explicit user confirmation. If your contribution has an agent making decisions +or writing files unilaterally, it won't be merged. + +## Testing Your Changes + +Run it in a Claude Code session and confirm it works end-to-end. For skills, +invoke the skill and verify the output matches what the skill claims to do. +For hooks, trigger the relevant event and confirm the hook fires correctly +and exits cleanly. + +Include a brief note in your PR description describing what you tested and +what the output looked like. + +## Commit Format + +Use [Conventional Commits](https://www.conventionalcommits.org/): + +``` +feat: add /retrospective skill for end-of-sprint reviews +fix: correct grep -P usage in session-start hook +docs: update skills-reference with new /qa-plan entry +``` + +Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test` + +## PR Process + +- Your PR will be auto-assigned to the maintainer via CODEOWNERS +- Reviews happen when they happen — this is a solo-maintained project +- If your PR sits open without feedback for a few weeks, a nudge comment is fine +- Merged contributors are credited in release notes + +## Platform Compatibility + +CCGS must work on Windows (Git Bash), macOS, and Linux. If your hook or +script uses anything platform-specific, it will be rejected. When in doubt, +test on Windows. diff --git a/README.md b/README.md index 88b5c1b..c08cec9 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@

Turn a single Claude Code session into a full game development studio.
- 49 agents. 72 skills. One coordinated AI team. + 49 agents. 73 skills. One coordinated AI team.

MIT License 49 Agents - 72 Skills + 73 Skills 12 Hooks 11 Rules Built for Claude Code @@ -53,10 +53,10 @@ The result: you still make every decision, but now you have a team that asks the | Category | Count | Description | |----------|-------|-------------| | **Agents** | 49 | Specialized subagents across design, programming, art, audio, narrative, QA, and production | -| **Skills** | 72 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) | +| **Skills** | 73 | 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** | 39 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more | +| **Templates** | 41 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more | ## Studio Hierarchy @@ -94,7 +94,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 72 skills: +Type `/` in Claude Code to access all 73 skills: **Onboarding & Navigation** `/start` `/help` `/project-stage-detect` `/setup-engine` `/adopt` @@ -115,7 +115,7 @@ Type `/` in Claude Code to access all 72 skills: `/create-epics` `/create-stories` `/dev-story` `/sprint-plan` `/sprint-status` `/story-readiness` `/story-done` `/estimate` **Reviews & Analysis** -`/design-review` `/code-review` `/balance-check` `/content-audit` `/scope-check` `/perf-profile` `/tech-debt` `/gate-check` `/consistency-check` +`/design-review` `/code-review` `/balance-check` `/content-audit` `/scope-check` `/perf-profile` `/tech-debt` `/gate-check` `/consistency-check` `/security-audit` **QA & Testing** `/qa-plan` `/smoke-check` `/soak-test` `/regression-suite` `/test-setup` `/test-helpers` `/test-evidence-review` `/test-flakiness` `/skill-test` `/skill-improve` @@ -124,7 +124,7 @@ Type `/` in Claude Code to access all 72 skills: `/milestone-review` `/retrospective` `/bug-report` `/bug-triage` `/reverse-document` `/playtest-report` **Release** -`/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix` +`/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix` `/day-one-patch` **Creative & Content** `/prototype` `/onboard` `/localize` @@ -176,13 +176,13 @@ CLAUDE.md # Master configuration .claude/ settings.json # Hooks, permissions, safety rules agents/ # 49 agent definitions (markdown + YAML frontmatter) - skills/ # 72 slash commands (subdirectory per skill) + skills/ # 73 slash commands (subdirectory per skill) hooks/ # 12 hook scripts (bash, cross-platform) rules/ # 11 path-scoped coding standards statusline.sh # Status line script (context%, model, stage, epic breadcrumb) docs/ workflow-catalog.yaml # 7-phase pipeline definition (read by /help) - templates/ # 39 document templates + templates/ # 41 document templates src/ # Game source code assets/ # Art, audio, VFX, shaders, data files design/ # GDDs, narrative docs, level designs @@ -279,7 +279,7 @@ This is a **template**, not a locked framework. Everything is meant to be custom ## Platform Support -Tested on **Windows 10** with Git Bash. All hooks use POSIX-compatible patterns (`grep -E`, not `grep -P`) and include fallbacks for missing tools. Works on macOS and Linux without modification. +Primary development and testing on **Windows 10** with Git Bash. All hooks use POSIX-compatible patterns (`grep -E`, not `grep -P`) and include fallbacks for missing tools, so they should run on macOS and Linux. The `notify.sh` hook uses PowerShell for Windows toast notifications and is a no-op elsewhere — desktop notifications on macOS/Linux are not yet wired. Cross-platform testing is ongoing; please file issues for any platform-specific breakage. ## Community diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f16603e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,80 @@ +# Security Policy + +## Supported Versions + +Only the `main` branch receives security fixes. Forks and older releases are +not supported. + +## Reporting a Vulnerability + +**Do not report security vulnerabilities through public GitHub issues.** + +Use GitHub's private vulnerability reporting instead: + +**[Report a vulnerability →](https://github.com/Donchitos/Claude-Code-Game-Studios/security/advisories/new)** + +Include as much detail as possible: +- Description of the vulnerability and what it affects +- Steps to reproduce +- Potential impact and attack scenarios +- Any suggested mitigations + +**What to expect:** +- Acknowledgment within **48 hours** +- Status update within **7 days** +- Resolution within **90 days** for confirmed vulnerabilities + +## What Is In Scope + +CCGS is a **local development tool** — it installs shell hooks and coordinates +AI agents that run directly on your machine. Security issues are primarily about +contributed code that executes in users' environments without their awareness. + +### High Severity +- Hooks (`.claude/hooks/*.sh`) that execute malicious or undisclosed shell + commands on user machines +- Skills or agents that exfiltrate environment variables, API keys, or secrets +- Prompt injection via skill or agent definitions that causes Claude to bypass + safety measures or take unauthorized destructive actions +- Contributions that silently alter behavior in ways users cannot audit + +### Medium Severity +- Skills that make undisclosed outbound network requests +- Agent definitions that escalate permissions or bypass user confirmation prompts +- Hook patterns that behave differently across platforms to conceal behavior +- Skills that write outside their documented scope without an explicit user + approval step + +### Out of Scope +- The behavior of Claude or the Claude Code CLI itself + (report to [Anthropic](https://www.anthropic.com/security)) +- Bugs in the user's Claude Code installation or editor extension +- Theoretical vulnerabilities with no realistic attack path +- Issues requiring physical access to the user's machine + +## Security Guidelines for Contributors + +When contributing hooks, skills, or agents: + +- **Hooks must be POSIX-compatible** — use `grep -E`, not `grep -P`; avoid + platform-specific syntax that behaves differently across operating systems +- **No silent network calls** from hooks or skills unless explicitly documented + and opt-in by the user +- **No reading secrets or environment variables** beyond what is minimally + required and clearly documented in the skill's header +- **Skills must not write outside their documented scope** without an explicit + user confirmation step + +## Disclosure Policy + +We follow a **90-day coordinated disclosure** timeline: + +1. You submit the vulnerability privately +2. We acknowledge within 48 hours +3. We confirm and assess severity within 7 days +4. We develop and test a fix +5. We notify you before any public disclosure +6. Public disclosure happens after the fix ships, or at 90 days — whichever + comes first + +We credit reporters in release notes unless you prefer to remain anonymous. diff --git a/UPGRADING.md b/UPGRADING.md index 406d624..9cd6f1d 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -14,6 +14,7 @@ Or check `README.md` for the version badge. ## Table of Contents - [Upgrade Strategies](#upgrade-strategies) +- [v1.0.0-beta → v1.0](#v100-beta--v10) - [v0.4.x → v1.0](#v04x--v10) - [v0.4.0 → v0.4.1](#v040--v041) - [v0.3.0 → v0.4.0](#v030--v040) @@ -126,6 +127,48 @@ None — all changes are to infrastructure files with no user content. --- +## v1.0.0-beta → v1.0 + +**Released:** 2026-05-13 +**Commit range:** `49d1e45..HEAD` +**Key themes:** New `/vertical-slice` gate, skill polish & bug fixes, contributor docs + +### What Changed + +| Category | Changes | +|----------|---------| +| **New skill** | `/vertical-slice` — Pre-Production gate that validates the full game loop with a production-quality end-to-end build before Production. Pairs with the overhauled `/prototype` (concept validation right after `/brainstorm`). | +| **New flow** | Entity inventory step in `/map-systems` — surfaces all named entities up front for cleaner downstream GDD authoring. | +| **UX polish** | Added missing `AskUserQuestion` widgets to 7 skills; comprehensive skill audit for consistency, prompts, and flow gaps; exposed `--review` flag in `argument-hints` for all `team-*` skills. | +| **Bug fixes** | `#21` log-agent hooks logged "unknown" `agent_type`; `#36` missing `allowed-tools` in `/architecture-decision` and `/story-done`; `#42` `rg --type gdscript` is invalid (now uses `--glob *.gd`); `#43` session-start preview showed oldest state instead of newest; `#45` duplicate `## 0.` heading and broken step numbering in `/architecture-decision`. | +| **Project docs** | Added `CONTRIBUTING.md` (framework contribution guidelines) and `SECURITY.md` (coordinated disclosure policy). | +| **Counts/refs** | Synced agent/skill/hook counts across `WORKFLOW-GUIDE.md`, `README.md`, and agent rosters; fixed stale agent names and skill model-tier fields. | + +--- + +### Files: Safe to Overwrite + +**New files to add:** +``` +.claude/skills/vertical-slice/SKILL.md +CONTRIBUTING.md +SECURITY.md +``` + +**Existing files to overwrite (no user content):** +- All files under `.claude/skills/` modified in the commit range (skill audit + AskUserQuestion widgets + `--review` argument-hints) +- `.claude/hooks/log-agent.sh` (fix #21) +- `README.md`, `docs/WORKFLOW-GUIDE.md`, `docs/examples/skill-flow-diagrams.md` +- `UPGRADING.md` + +--- + +### Files: Merge Carefully + +None — all changes are to infrastructure files with no user content. + +--- + ## v0.4.x → v1.0 **Released:** 2026-03-29 diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index bc2f629..30a11c9 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, 68 slash commands, and 12 automated hooks. It assumes you +> 49-agent system, 73 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`) @@ -159,6 +159,11 @@ with defined pillars and a player journey. This is where you figure out Player motiv. core loop, USP document | v + /prototype + (concept prototype — 1-3 days) + PROCEED ↓ PIVOT → /brainstorm + | + v (PROCEED) /map-systems | v @@ -558,28 +563,23 @@ Vertical Slice that proves the core loop is fun. ### Phase 4 Pipeline ``` -/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 - (playable build, - 3 unguided sessions) +/ux-design --> /vertical-slice --> /create-epics --> /create-stories --> /sprint-plan + | | | | | + v v v v v + UX specs Production-quality Epic files in Story files in First sprint with + design/ux/ end-to-end build production/ production/ prioritized stories + in prototypes/ epics/*/EPIC.md epics/*/story-*.md production/sprints/ + PROCEED/PIVOT/KILL (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) ``` ### Step 4.1: UX Specs for Key Screens @@ -624,25 +624,34 @@ etc.) with animation and sound standards. Validates UX specs for GDD alignment and accessibility tier compliance. Produces APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED verdict. -### Step 4.2: Prototype Risky Mechanics +### Step 4.2: Build the Vertical Slice -Not everything needs a prototype. Prototype when: -- A mechanic is novel and you are not sure it is fun -- A technical approach is risky and you are not sure it is feasible -- Two design options both seem viable and you need to feel the difference +The vertical slice is the production-quality proof that you can build the full +game loop end-to-end before committing to full Production. ``` -/prototype "grappling hook movement with momentum" +/vertical-slice ``` -**What happens:** The skill collaborates with you to define a hypothesis, -success criteria, and minimal scope. The `prototyper` agent works in an -isolated git worktree (`isolation: worktree`) so throwaway code never -pollutes `src/`. +**What it proves:** Does a player, starting from nothing, experience the core +fantasy within a few minutes, without developer guidance? -**Key rule:** The `prototype-code` rule intentionally relaxes coding standards -- -hardcoded values OK, no tests required -- but a README with hypothesis and -findings is mandatory. +**What it builds:** A near-production-quality playable build covering at least +one complete [start → challenge → resolution] cycle. Uses real architecture +layers, real naming conventions, no hardcoded values — but not final art or +audio. This is not a throwaway like the concept prototype; it demonstrates +production pipeline feasibility. + +**Note on concept prototyping:** If you ran `/prototype` in Phase 1 (Concept), +you already validated the core idea is fun. The vertical slice now validates +you can build it properly. They answer different questions. If you skipped the +concept prototype, now is a reasonable time to run one first before investing +in the full slice. + +**Verdict:** The vertical slice produces a PROCEED / PIVOT / KILL verdict. +- **PROCEED** → move to Step 4.3 (epics and stories) +- **PIVOT** → revise affected GDDs with `/design-system [mechanic]`, then re-run `/vertical-slice` +- **KILL** → return to `/brainstorm` with what you learned ### Step 4.3: Create Epics and Stories From Design Artifacts @@ -668,7 +677,7 @@ automatically to the correct programmer agent. ### Step 4.4: Validate Stories Before Pickup ``` -/story-readiness production/stories/combat-damage-calc.md +/story-readiness production/epics/combat/story-combat-damage-calc.md ``` Checks: Design completeness, Architecture coverage, Scope clarity, Definition @@ -677,7 +686,7 @@ of Done. Verdict: READY / NEEDS WORK / BLOCKED. ### Step 4.5: Effort Estimation ``` -/estimate production/stories/combat-damage-calc.md +/estimate production/epics/combat/story-combat-damage-calc.md ``` Provides effort estimates with risk assessment. @@ -718,7 +727,7 @@ played the build unguided. - 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/` +- Story files exist in `production/epics/[epic-slug]/` - At least 1 sprint plan exists - At least 1 playtest report exists (Vertical Slice played in 3+ sessions) @@ -762,7 +771,7 @@ The production phase centers on the **story lifecycle**: **1. Story Readiness:** Before picking up a story, validate it: ``` -/story-readiness production/stories/combat-damage-calc.md +/story-readiness production/epics/combat/story-combat-damage-calc.md ``` This checks design completeness, architecture coverage, ADR status (blocks @@ -785,7 +794,7 @@ implement. **3. Story Completion:** When a story is done: ``` -/story-done production/stories/combat-damage-calc.md +/story-done production/epics/combat/story-combat-damage-calc.md ``` This runs an 8-phase completion review: @@ -1213,9 +1222,12 @@ Tier 3 (Specialists): gameplay-programmer, engine-programmer, live-ops-designer, prototyper, security-engineer, community-manager, godot-specialist, godot-gdscript-specialist, godot-shader-specialist, - unity-specialist, unity-csharp-specialist, - unreal-specialist, unreal-blueprint-specialist, - unreal-cpp-specialist + godot-csharp-specialist, godot-gdextension-specialist, + unity-specialist, unity-dots-specialist, + unity-shader-specialist, unity-addressables-specialist, + unity-ui-specialist, unreal-specialist, + ue-blueprint-specialist, ue-gas-specialist, + ue-replication-specialist, ue-umg-specialist ``` **Coordination rules:** @@ -1410,9 +1422,9 @@ conflicts go to `producer`. ## Appendix B: Slash Command Quick-Reference -### All 66 Commands by Category +### All 73 Commands by Category -#### Onboarding and Navigation (5) +#### Onboarding and Navigation (6) | Command | Purpose | Phase | |---------|---------|-------| @@ -1421,6 +1433,7 @@ conflicts go to `producer`. | `/project-stage-detect` | Full project audit to determine current phase | Any | | `/setup-engine` | Configure engine, pin version, set preferences | 1 | | `/adopt` | Brownfield audit and migration plan | Any (existing projects) | +| `/skill-improve` | Improve a skill via test-fix-retest loop | Any | #### Game Design (6) @@ -1462,7 +1475,7 @@ conflicts go to `producer`. | `/story-done` | 8-phase story completion review | 5 | | `/estimate` | Effort estimation with risk assessment | 4-5 | -#### Reviews and Analysis (10) +#### Reviews and Analysis (13) | Command | Purpose | Phase | |---------|---------|-------| @@ -1470,12 +1483,15 @@ conflicts go to `producer`. | `/code-review` | Architectural code review | 5+ | | `/balance-check` | Game balance formula analysis | 5-6 | | `/asset-audit` | Asset naming, format, size verification | 6 | +| `/asset-spec` | Per-asset visual specs and AI generation prompts | 5-6 | | `/content-audit` | GDD-specified content vs. implemented | 5 | +| `/consistency-check` | Cross-GDD entity and formula inconsistency scan | 2+ | | `/scope-check` | Scope creep detection | 5 | | `/perf-profile` | Performance profiling workflow | 6 | | `/tech-debt` | Tech debt scanning and prioritization | 6 | | `/gate-check` | Formal phase gate with PASS/CONCERNS/FAIL | All transitions | | `/reverse-document` | Generate design docs from existing code | Any | +| `/security-audit` | Security vulnerability audit (save, network, input) | 6-7 | #### QA and Testing (9) @@ -1502,7 +1518,7 @@ conflicts go to `producer`. | `/playtest-report` | Structured playtest session report | 4-6 | | `/onboard` | Onboard a new team member | Any | -#### Release (5) +#### Release (6) | Command | Purpose | Phase | |---------|---------|-------| @@ -1511,12 +1527,15 @@ conflicts go to `producer`. | `/changelog` | Auto-generate internal changelog | 7 | | `/patch-notes` | Player-facing patch notes | 7 | | `/hotfix` | Emergency fix workflow | 7+ | +| `/day-one-patch` | Scoped patch for issues found after gold master | 7+ | -#### Creative (2) +#### Creative (4) | Command | Purpose | Phase | |---------|---------|-------| -| `/prototype` | Throwaway prototype in isolated worktree | 4 | +| `/prototype` | Concept prototype — validate core idea before GDDs | 1 | +| `/art-bible` | Guided Art Bible authoring — visual identity spec | 1-2 | +| `/vertical-slice` | Production-quality end-to-end build before Production | 4 | | `/localize` | String extraction and validation | 6-7 | #### Team Orchestration (9) diff --git a/docs/examples/skill-flow-diagrams.md b/docs/examples/skill-flow-diagrams.md index 0d1ded2..c5a7062 100644 --- a/docs/examples/skill-flow-diagrams.md +++ b/docs/examples/skill-flow-diagrams.md @@ -12,6 +12,9 @@ PHASE 1: CONCEPT /start ──────────────────────────────────────────────────────► routes to A/B/C/D /brainstorm ──────────────────────────────────────────────────► design/gdd/game-concept.md /setup-engine ────────────────────────────────────────────────► CLAUDE.md + technical-preferences.md + /prototype [core-mechanic] ───────────────────────────────────► prototypes/[name]-concept/REPORT.md + │ PROCEED (validate idea BEFORE writing GDDs) + ▼ /design-review [game-concept.md] ────────────────────────────► concept validated /gate-check ─────────────────────────────────────────────────► PASS → advance to systems-design │ @@ -45,11 +48,13 @@ PHASE 4: PRE-PRODUCTION /test-setup ─────────────────────────────────────────────────► test framework + CI/CD pipeline /test-helpers ───────────────────────────────────────────────► tests/helpers/[engine-specific].gd - [Stories + prototype] + [Vertical slice — before epics, validate full game loop] + /vertical-slice ─────────────────────────────────────────────► prototypes/[name]-vertical-slice/REPORT.md + /playtest-report ────────────────────────────────────────────► production/playtests/ + + [Stories + sprint plan — only after vertical slice PROCEEDS] /create-epics [layer] ───────────────────────────────────────► production/epics/*/EPIC.md /create-stories [epic-slug] ─────────────────────────────────► production/epics/*/story-*.md - /prototype [core-mechanic] ──────────────────────────────────► prototypes/[name]/ - /playtest-report ────────────────────────────────────────────► tests/playtest/vertical-slice.md /sprint-plan new ────────────────────────────────────────────► production/sprints/sprint-01.md /gate-check ─────────────────────────────────────────────────► PASS → advance to production │ @@ -297,36 +302,6 @@ How a story gets from backlog to closed (summary view): --- -## Skill Chain: UX Pipeline in Detail (Legacy Reference) - -``` -design/gdd/*.md (UX requirements extracted) -design/player-journey.md (emotional arc) - │ - ▼ -/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 → all specs ready for /team-ui - ├── NEEDS REVISION → blocking issues listed → fix → re-run review - └── MAJOR REVISION → fundamental UX problems → significant redesign - │ - ▼ (after APPROVED) - /team-ui - │ - ├── Phase 1: context load + /ux-design (if specs missing) - ├── Phase 2: visual design (art-director) - ├── Phase 3: layout implementation (ui-programmer) - ├── Phase 4: accessibility audit (accessibility-specialist) - └── Phase 5: final review -``` - ---- - ## Brownfield Onboarding Flow For projects with existing work (use `/start` option D or run directly):