From b36eb2728d0acdef569baace6e5c3ec097e532f4 Mon Sep 17 00:00:00 2001 From: Donchitos <150119193+Donchitos@users.noreply.github.com> Date: Thu, 12 Mar 2026 12:50:51 +1100 Subject: [PATCH] Docs sync: update all references to v0.4.0 state (52 skills, 9 hooks, 36 templates) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: badges and skills section updated (37→52 skills, 8→9 hooks, 29→36 templates); all 52 commands listed in 10 categories; log-agent-stop.sh added to hooks table - UPGRADING: added complete v0.3.0→v0.4.0 section with file lists, feature highlights, and after-upgrade steps - WORKFLOW-GUIDE: full rewrite from 10-phase to 7-phase structure; all 52 skills documented across phases and Appendix B - skills-reference: added 15 missing skills; reorganized into categorized sections - hooks-reference: added log-agent-stop.sh entry - quick-start: corrected counts; removed stale orphan doc references - COLLABORATIVE-DESIGN-PRINCIPLE: AskUserQuestion integration count 10→16 Co-Authored-By: Claude Sonnet 4.6 --- .claude/docs/hooks-reference.md | 3 +- .claude/docs/quick-start.md | 14 +- .claude/docs/skills-reference.md | 130 +- README.md | 54 +- UPGRADING.md | 157 ++ docs/COLLABORATIVE-DESIGN-PRINCIPLE.md | 2 +- docs/WORKFLOW-GUIDE.md | 2320 +++++++++++------------- 7 files changed, 1324 insertions(+), 1356 deletions(-) diff --git a/.claude/docs/hooks-reference.md b/.claude/docs/hooks-reference.md index 4f53c5d..9c8f483 100644 --- a/.claude/docs/hooks-reference.md +++ b/.claude/docs/hooks-reference.md @@ -11,7 +11,8 @@ Hooks are configured in `.claude/settings.json` and fire automatically: | `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect | | `pre-compact.sh` | PreCompact | Context compression | Dumps session state (active.md, modified files, WIP design docs) into conversation before compaction so it survives summarization | | `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log | -| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail of all subagent invocations with timestamps | +| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail start — logs subagent invocation with timestamp | +| `log-agent-stop.sh` | SubagentStop | Agent stops | Audit trail stop — completes subagent record | Hook reference documentation: `.claude/docs/hooks-reference/` Hook input schema documentation: `.claude/docs/hooks-reference/hook-input-schemas.md` diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md index 0069f14..a95e6e6 100644 --- a/.claude/docs/quick-start.md +++ b/.claude/docs/quick-start.md @@ -219,8 +219,8 @@ CLAUDE.md -- Master config (read this first, ~60 lines) .claude/ settings.json -- Claude Code hooks and project settings agents/ -- 48 agent definitions (YAML frontmatter) - skills/ -- 37 slash command definitions (YAML frontmatter) - hooks/ -- 8 hook scripts (.sh) wired by settings.json + skills/ -- 52 slash command definitions (YAML frontmatter) + hooks/ -- 9 hook scripts (.sh) wired by settings.json rules/ -- 11 path-specific rule files docs/ quick-start.md -- This file @@ -228,15 +228,9 @@ CLAUDE.md -- Master config (read this first, ~60 lines) coding-standards.md -- Coding and design doc standards coordination-rules.md -- Agent coordination rules context-management.md -- Context budgets and compaction instructions - review-workflow.md -- Review and sign-off process directory-structure.md -- Project directory layout - agent-roster.md -- Full agent list with tiers - skills-reference.md -- All slash commands - rules-reference.md -- Path-specific rules - hooks-reference.md -- Active hooks - agent-coordination-map.md -- Full delegation and workflow map + 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 - hooks-reference/ -- Hook documentation and git hook examples - templates/ -- 28 document templates + templates/ -- 36 document templates ``` diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md index 89ac704..a82cf46 100644 --- a/.claude/docs/skills-reference.md +++ b/.claude/docs/skills-reference.md @@ -1,41 +1,107 @@ # Available Skills (Slash Commands) +52 slash commands organized by phase. Type `/` in Claude Code to access any of them. + +## Onboarding & Navigation + | Command | Purpose | |---------|---------| | `/start` | First-time onboarding — asks where you are, then guides you to the right workflow | +| `/help` | Context-aware "what do I do next?" — reads current stage and surfaces the required next step | +| `/project-stage-detect` | Full project audit — detect phase, identify existence gaps, recommend next steps | +| `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs | +| `/adopt` | Brownfield format audit — checks internal structure of existing GDDs/ADRs/stories, produces migration plan | + +## Game Design + +| Command | Purpose | +|---------|---------| +| `/brainstorm` | Guided ideation using professional studio methods (MDA, SDT, Bartle, verb-first) | +| `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order | +| `/design-system` | Guided, section-by-section GDD authoring for a single game system | +| `/quick-design` | Lightweight design spec for small changes — tuning, tweaks, minor additions | +| `/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 | + +## UX & Interface Design + +| Command | Purpose | +|---------|---------| +| `/ux-design` | Guided section-by-section UX spec authoring (screen/flow, HUD, or pattern library) | +| `/ux-review` | Validate UX specs for GDD alignment, accessibility, and pattern compliance | + +## Architecture + +| Command | Purpose | +|---------|---------| +| `/create-architecture` | Guided authoring of the master architecture document | +| `/architecture-decision` | Create an Architecture Decision Record (ADR) | +| `/architecture-review` | Validate all ADRs for completeness, dependency ordering, and GDD coverage | +| `/create-control-manifest` | Generate flat programmer rules sheet from accepted ADRs | + +## Stories & Sprints + +| Command | Purpose | +|---------|---------| +| `/create-epics-stories` | Translate GDDs + ADRs + manifest into implementable story files | +| `/sprint-plan` | Generate or update a sprint plan; initializes sprint-status.yaml | +| `/sprint-status` | Fast 30-line sprint snapshot (reads sprint-status.yaml) | +| `/story-readiness` | Validate a story is implementation-ready before pickup (READY/NEEDS WORK/BLOCKED) | +| `/story-done` | 8-phase completion review after implementation; updates story file, surfaces next story | +| `/estimate` | Structured effort estimate with complexity, dependencies, and risk breakdown | + +## Reviews & Analysis + +| Command | Purpose | +|---------|---------| | `/design-review` | Review a game design document for completeness and consistency | | `/code-review` | Architectural code review for a file or changeset | -| `/playtest-report` | Generate a structured playtest report template | -| `/balance-check` | Analyze game balance data and flag outliers | -| `/sprint-plan` | Generate or update a sprint plan | -| `/bug-report` | Create a structured bug report | -| `/architecture-decision` | Create an Architecture Decision Record (ADR) | -| `/asset-audit` | Audit assets for naming, sizing, and pipeline compliance | -| `/milestone-review` | Review milestone progress and generate status report | -| `/onboard` | Generate onboarding context for a new contributor or agent | -| `/prototype` | Scaffold a throwaway prototype to test a mechanic or technical approach | -| `/release-checklist` | Generate and validate a pre-release checklist for the current build | -| `/changelog` | Auto-generate changelog from git commits and sprint data | -| `/retrospective` | Run a structured sprint or milestone retrospective | -| `/estimate` | Produce a structured effort estimate with complexity and risk breakdown | -| `/hotfix` | Emergency fix workflow with audit trail, bypassing normal sprint process | -| `/tech-debt` | Scan, track, prioritize, and report on technical debt across the codebase | +| `/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 | -| `/localize` | Localization workflow: scan for hardcoded strings, extract, validate translations | -| `/perf-profile` | Structured performance profiling with bottleneck identification and recommendations | -| `/project-stage-detect` | Automatically analyze project state, detect stage, identify gaps, and recommend next steps | -| `/reverse-document` | Generate design or architecture documents from existing implementation (works backwards from code) | -| `/team-combat` | Orchestrate combat team: game-designer + gameplay-programmer + ai-programmer + technical-artist + sound-designer + qa-tester | -| `/team-narrative` | Orchestrate narrative team: narrative-director + writer + world-builder + level-designer | -| `/team-ui` | Orchestrate UI team: ux-designer + ui-programmer + art-director | -| `/team-release` | Orchestrate release team: release-manager + qa-lead + devops-engineer + producer | -| `/team-polish` | Orchestrate polish team: performance-analyst + technical-artist + sound-designer + qa-tester | -| `/team-audio` | Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer | -| `/team-level` | Orchestrate level team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester | -| `/launch-checklist` | Complete launch readiness validation across all departments | -| `/patch-notes` | Generate player-facing patch notes from git history and internal data | -| `/brainstorm` | Guided ideation using professional studio methods (MDA, SDT, Bartle, verb-first) | +| `/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) | -| `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order, guide per-system GDDs | -| `/design-system` | Guided, section-by-section GDD authoring for a single game system with cross-referencing and incremental writing | -| `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs | + +## Production + +| Command | Purpose | +|---------|---------| +| `/milestone-review` | Review milestone progress and generate status report | +| `/retrospective` | Run a structured sprint or milestone retrospective | +| `/bug-report` | Create a structured bug report | +| `/reverse-document` | Generate design or architecture docs from existing implementation | +| `/playtest-report` | Generate a structured playtest report or analyze existing playtest notes | + +## Release + +| Command | Purpose | +|---------|---------| +| `/release-checklist` | Generate and validate a pre-release checklist for the current build | +| `/launch-checklist` | Complete launch readiness validation across all departments | +| `/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 | + +## Creative & Content + +| Command | Purpose | +|---------|---------| +| `/prototype` | Rapid throwaway prototype to validate a mechanic (relaxed standards, isolated worktree) | +| `/onboard` | Generate contextual onboarding document for a new contributor or agent | +| `/localize` | Localization workflow: string extraction, validation, translation readiness | + +## Team Orchestration + +Coordinate multiple agents on a single feature area: + +| Command | Coordinates | +|---------|-------------| +| `/team-combat` | game-designer + gameplay-programmer + ai-programmer + technical-artist + sound-designer + qa-tester | +| `/team-narrative` | narrative-director + writer + world-builder + level-designer | +| `/team-ui` | ux-designer + ui-programmer + art-director + accessibility-specialist | +| `/team-release` | release-manager + qa-lead + devops-engineer + producer | +| `/team-polish` | performance-analyst + technical-artist + sound-designer + qa-tester | +| `/team-audio` | audio-director + sound-designer + technical-artist + gameplay-programmer | +| `/team-level` | level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester | diff --git a/README.md b/README.md index a78c7f4..53bf812 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,15 @@

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

MIT License 48 Agents - 37 Skills - 8 Hooks + 52 Skills + 9 Hooks 11 Rules Built for Claude Code Ko-fi @@ -51,10 +51,10 @@ The result: you still make every decision, but now you have a team that asks the | Category | Count | Description | |----------|-------|-------------| | **Agents** | 48 | Specialized subagents across design, programming, art, audio, narrative, QA, and production | -| **Skills** | 37 | Slash commands for common workflows (`/start`, `/sprint-plan`, `/code-review`, `/brainstorm`, etc.) | -| **Hooks** | 8 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit, and gap detection | +| **Skills** | 52 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics-stories`, `/story-done`, etc.) | +| **Hooks** | 9 | 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** | 29 | Document templates for GDDs, ADRs, sprint plans, economy models, faction design, and more | +| **Templates** | 36 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more | ## Studio Hierarchy @@ -92,22 +92,34 @@ The template includes agent sets for all three major engines. Use the set that m ## Slash Commands -Type `/` in Claude Code to access all 37 skills: +Type `/` in Claude Code to access all 52 skills: + +**Onboarding & Navigation** +`/start` `/help` `/project-stage-detect` `/setup-engine` `/adopt` + +**Game Design** +`/brainstorm` `/map-systems` `/design-system` `/quick-design` `/review-all-gdds` `/propagate-design-change` + +**UX & Interface Design** +`/ux-design` `/ux-review` + +**Architecture** +`/create-architecture` `/architecture-decision` `/architecture-review` `/create-control-manifest` + +**Stories & Sprints** +`/create-epics-stories` `/sprint-plan` `/sprint-status` `/story-readiness` `/story-done` `/estimate` **Reviews & Analysis** -`/design-review` `/code-review` `/balance-check` `/asset-audit` `/scope-check` `/perf-profile` `/tech-debt` +`/design-review` `/code-review` `/balance-check` `/asset-audit` `/content-audit` `/scope-check` `/perf-profile` `/tech-debt` `/gate-check` **Production** -`/sprint-plan` `/milestone-review` `/estimate` `/retrospective` `/bug-report` - -**Project Management** -`/start` `/project-stage-detect` `/reverse-document` `/gate-check` `/map-systems` `/design-system` +`/milestone-review` `/retrospective` `/bug-report` `/reverse-document` `/playtest-report` **Release** `/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix` -**Creative** -`/brainstorm` `/playtest-report` `/prototype` `/onboard` `/localize` +**Creative & Content** +`/prototype` `/onboard` `/localize` **Team Orchestration** (coordinate multiple agents on a single feature) `/team-combat` `/team-narrative` `/team-ui` `/team-release` `/team-polish` `/team-audio` `/team-level` @@ -156,15 +168,12 @@ CLAUDE.md # Master configuration .claude/ settings.json # Hooks, permissions, safety rules agents/ # 48 agent definitions (markdown + YAML frontmatter) - skills/ # 37 slash commands (subdirectory per skill) - hooks/ # 8 hook scripts (bash, cross-platform) + skills/ # 52 slash commands (subdirectory per skill) + hooks/ # 9 hook scripts (bash, cross-platform) rules/ # 11 path-scoped coding standards docs/ - quick-start.md # Detailed usage guide - agent-roster.md # Full agent table with domains - agent-coordination-map.md # Delegation and escalation paths - setup-requirements.md # Prerequisites and platform notes - templates/ # 28 document templates + workflow-catalog.yaml # 7-phase pipeline definition (read by /help) + templates/ # 36 document templates src/ # Game source code assets/ # Art, audio, VFX, shaders, data files design/ # GDDs, narrative docs, level designs @@ -212,7 +221,8 @@ You stay in control. The agents provide structure and expertise, not autonomy. | `detect-gaps.sh` | Session open | Detects fresh projects (suggests `/start`) and missing documentation when code/prototypes exist | | `pre-compact.sh` | Context compression | Preserves session progress notes | | `session-stop.sh` | Session close | Logs accomplishments | -| `log-agent.sh` | Agent spawned | Audit trail of all subagent invocations | +| `log-agent.sh` | Agent spawned | Audit trail start — logs subagent invocation | +| `log-agent-stop.sh` | Agent stops | Audit trail stop — completes subagent record | **Permission rules** in `settings.json` auto-allow safe operations (git status, test runs) and block dangerous ones (force push, `rm -rf`, reading `.env` files). diff --git a/UPGRADING.md b/UPGRADING.md index a2f1261..ad82006 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) +- [v0.3.0 → v0.4.0](#v030--v040) - [v0.2.0 → v0.3.0](#v020--v030) - [v0.1.0 → v0.2.0](#v010--v020) @@ -77,6 +78,162 @@ Best when: you didn't use git to set up the template (just downloaded a zip). --- +## v0.3.0 → v0.4.0 + +**Released:** 2026-03-09 +**Commit range:** `b1cad29..HEAD` +**Key themes:** Full UX/UI pipeline, complete story lifecycle, brownfield adoption, pipeline integrity, 15 new skills + +### What Changed + +| Category | Changes | +|----------|---------| +| **New skills (15)** | `/ux-design`, `/ux-review`, `/help`, `/quick-design`, `/review-all-gdds`, `/story-readiness`, `/story-done`, `/sprint-status`, `/adopt`, `/create-architecture`, `/create-control-manifest`, `/create-epics-stories`, `/propagate-design-change`, `/content-audit`, `/architecture-review` | +| **New hook** | `log-agent-stop.sh` — completes agent audit trail (stop event to match start) | +| **New templates (8)** | `ux-spec.md`, `hud-design.md`, `accessibility-requirements.md`, `interaction-pattern-library.md`, `player-journey.md`, `difficulty-curve.md`, and 2 adoption plan templates | +| **New infrastructure** | `workflow-catalog.yaml` (7-phase pipeline, read by `/help`), `docs/architecture/tr-registry.yaml` (stable TR-IDs), `production/sprint-status.yaml` schema | +| **Skill updates** | `/gate-check` — 3 gates now require UX artifacts; Pre-Production gate requires vertical slice (HARD gate) | +| **Skill updates** | `/sprint-plan` — writes `sprint-status.yaml`; `/sprint-status` reads it | +| **Skill updates** | `/story-done` — 8-phase completion review, updates story file, surfaces next ready story | +| **Skill updates** | `/design-review` — removed architecture gap check (wrong stage) | +| **Skill updates** | `/team-ui` — full UX pipeline (ux-design → ux-review → team phases) | +| **Agent updates** | 14 specialist agents — `memory: project` added | +| **Agent updates** | `prototyper` — `isolation: worktree` (throwaway work in isolated git branch) | +| **Pipeline integrity** | TR-ID stability, manifest versioning, ADR status gates, TR-ID reference not quote | +| **GDD template** | `## Game Feel` section added (input responsiveness, animation targets, impact moments) | + +--- + +### Files: Safe to Overwrite + +**New files to add:** +``` +.claude/skills/ux-design/SKILL.md +.claude/skills/ux-review/SKILL.md +.claude/skills/help/SKILL.md +.claude/skills/quick-design/SKILL.md +.claude/skills/review-all-gdds/SKILL.md +.claude/skills/story-readiness/SKILL.md +.claude/skills/story-done/SKILL.md +.claude/skills/sprint-status/SKILL.md +.claude/skills/adopt/SKILL.md +.claude/skills/create-architecture/SKILL.md +.claude/skills/create-control-manifest/SKILL.md +.claude/skills/create-epics-stories/SKILL.md +.claude/skills/propagate-design-change/SKILL.md +.claude/skills/content-audit/SKILL.md +.claude/skills/architecture-review/SKILL.md +.claude/hooks/log-agent-stop.sh +.claude/docs/workflow-catalog.yaml +.claude/docs/templates/ux-spec.md +.claude/docs/templates/hud-design.md +.claude/docs/templates/accessibility-requirements.md +.claude/docs/templates/interaction-pattern-library.md +.claude/docs/templates/player-journey.md +.claude/docs/templates/difficulty-curve.md +``` + +**Existing files to overwrite (no user content):** +``` +.claude/skills/gate-check/SKILL.md +.claude/skills/sprint-plan/SKILL.md +.claude/skills/sprint-status/SKILL.md +.claude/skills/design-review/SKILL.md +.claude/skills/team-ui/SKILL.md +.claude/skills/story-readiness/SKILL.md +.claude/skills/story-done/SKILL.md +.claude/docs/templates/game-design-document.md ← adds Game Feel section +README.md +docs/WORKFLOW-GUIDE.md +UPGRADING.md +``` + +**Agent files to overwrite** (if you haven't written custom prompts into them): +``` +.claude/agents/prototyper.md ← adds isolation: worktree +.claude/agents/art-director.md ← adds memory: project +.claude/agents/audio-director.md ← adds memory: project +.claude/agents/economy-designer.md ← adds memory: project +.claude/agents/game-designer.md ← adds memory: project +.claude/agents/gameplay-programmer.md ← adds memory: project +.claude/agents/lead-programmer.md ← adds memory: project +.claude/agents/level-designer.md ← adds memory: project +.claude/agents/narrative-director.md ← adds memory: project +.claude/agents/systems-designer.md ← adds memory: project +.claude/agents/technical-artist.md ← adds memory: project +.claude/agents/ui-programmer.md ← adds memory: project +.claude/agents/ux-designer.md ← adds memory: project +.claude/agents/world-builder.md ← adds memory: project +``` + +--- + +### Files: Merge Carefully + +#### `.claude/settings.json` + +The new version registers `log-agent-stop.sh` as a hook for the `PostToolUse` (agent stop) event. If you haven't customized `settings.json`, overwriting is safe. Otherwise, add the new hook entry for `SubagentStop` manually. + +#### Customized agent files + +If you've added project-specific knowledge to agent `.md` files, do a diff and manually add the `memory: project` line to the YAML frontmatter where appropriate. Creative and technical director agents intentionally keep `memory: user` — only specialist agents get `memory: project`. + +--- + +### New Features + +#### Complete Story Lifecycle + +Stories now have a formal lifecycle enforced by two skills: + +- **`/story-readiness`** — validates a story is implementation-ready before a developer picks it up. Checks Design (GDD req linked), Architecture (ADR accepted), Scope (criteria testable), and DoD (manifest version current). Verdict: READY / NEEDS WORK / BLOCKED. +- **`/story-done`** — 8-phase completion review after implementation. Verifies each acceptance criterion, checks for GDD/ADR deviations, prompts code review, updates the story file to `Status: Complete`, and surfaces the next ready story. + +Flow: `/story-readiness` → implement → `/story-done` → next story + +#### Full UX/UI Pipeline + +- **`/ux-design`** — guided section-by-section UX spec authoring. Three modes: screen/flow, HUD, or interaction pattern library. Reads GDD UI requirements and player journey. Output to `design/ux/`. +- **`/ux-review`** — validates UX specs against GDD alignment, accessibility tier, and pattern library. Verdict: APPROVED / NEEDS REVISION / MAJOR REVISION. +- **`/team-ui`** updated: Phase 1 now runs `/ux-design` + `/ux-review` as a hard gate before visual design begins. + +#### Brownfield Adoption + +**`/adopt`** onboards existing projects to the template format. Audits internal structure of GDDs, ADRs, stories, systems-index, and infra. Classifies gaps (BLOCKING/HIGH/MEDIUM/LOW). Builds an ordered migration plan. Never regenerates existing artifacts — only fills gaps. + +Argument modes: `full | gdds | adrs | stories | infra` + +Also: `/design-system retrofit [path]` and `/architecture-decision retrofit [path]` detect existing files and add only missing sections. + +#### Sprint Tracking YAML + +`production/sprint-status.yaml` is now the authoritative story tracking format: +- Written by `/sprint-plan` (initializes all stories) and `/story-done` (sets status to `done`) +- Read by `/sprint-status` (fast snapshot) and `/help` (per-story status in production phase) +- Status values: `backlog | ready-for-dev | in-progress | review | done | blocked` +- Falls back gracefully to markdown scanning if file doesn't exist + +#### `/help` — Context-Aware Next Step + +`/help` reads your current stage and in-progress work, checks which artifacts are complete, and tells you exactly what to do next — one primary required step, plus optional opportunities. Distinct from `/start` (first-time only) and `/project-stage-detect` (full audit). + +--- + +### After Upgrading + +1. **Verify new hooks** are registered in `.claude/settings.json` — check for `log-agent-stop.sh`. + +2. **Test the audit trail** by spawning any subagent — both start and stop events should appear in `production/session-logs/`. + +3. **Generate sprint-status.yaml** if you're in active production: + ``` + /sprint-plan status + ``` + +4. **Run `/adopt`** if you have existing GDDs or ADRs that predate this template version — it will identify which sections need to be added without overwriting your content. + +--- + ## v0.2.0 → v0.3.0 **Released:** 2026-03-09 diff --git a/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md b/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md index 08be1f7..c81f38c 100644 --- a/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md +++ b/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md @@ -685,4 +685,4 @@ This principle has been fully embedded across the project: - **All skills** — Updated to require approval before writing - **WORKFLOW-GUIDE.md** — Rewritten with collaborative examples - **README.md** — Clarifies collaborative (not autonomous) design -- **AskUserQuestion tool** — Integrated into 10 skills for structured option UI +- **AskUserQuestion tool** — Integrated into 16 skills for structured option UI diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index 85ca2ee..38d1a9f 100644 --- a/docs/WORKFLOW-GUIDE.md +++ b/docs/WORKFLOW-GUIDE.md @@ -3,31 +3,33 @@ > **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, 37 slash commands, and automated hooks. It assumes you +> 48-agent system, 52 slash commands, and 9 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`) +> that must pass before you advance. The authoritative phase sequence is +> defined in `.claude/docs/workflow-catalog.yaml` and read by `/help`. --- ## Table of Contents -1. [Phase 0: Setup & Configuration](#phase-0-setup--configuration) -2. [Phase 1: Ideation & Concept](#phase-1-ideation--concept) -3. [Phase 2: Pre-Production & Design](#phase-2-pre-production--design) -4. [Phase 3: Prototyping & Validation](#phase-3-prototyping--validation) -5. [Phase 4: Production Sprint Workflow](#phase-4-production-sprint-workflow) -6. [Phase 5: Implementation Deep-Dive](#phase-5-implementation-deep-dive) -7. [Phase 6: Testing & Quality Assurance](#phase-6-testing--quality-assurance) -8. [Phase 7: Polish & Optimization](#phase-7-polish--optimization) -9. [Phase 8: Localization & Accessibility](#phase-8-localization--accessibility) -10. [Phase 9: Release & Launch](#phase-9-release--launch) -11. [Phase 10: Post-Launch & Live Ops](#phase-10-post-launch--live-ops) -12. [Appendix A: Agent Quick-Reference](#appendix-a-agent-quick-reference) -13. [Appendix B: Slash Command Quick-Reference](#appendix-b-slash-command-quick-reference) -14. [Appendix C: Common Workflows](#appendix-c-common-workflows) +1. [Quick Start](#quick-start) +2. [Phase 1: Concept](#phase-1-concept) +3. [Phase 2: Systems Design](#phase-2-systems-design) +4. [Phase 3: Technical Setup](#phase-3-technical-setup) +5. [Phase 4: Pre-Production](#phase-4-pre-production) +6. [Phase 5: Production](#phase-5-production) +7. [Phase 6: Polish](#phase-6-polish) +8. [Phase 7: Release](#phase-7-release) +9. [Cross-Cutting Concerns](#cross-cutting-concerns) +10. [Appendix A: Agent Quick-Reference](#appendix-a-agent-quick-reference) +11. [Appendix B: Slash Command Quick-Reference](#appendix-b-slash-command-quick-reference) +12. [Appendix C: Common Workflows](#appendix-c-common-workflows) --- -## Phase 0: Setup & Configuration +## Quick Start ### What You Need @@ -38,59 +40,31 @@ Before you start, make sure you have: - **jq** (optional but recommended -- hooks fall back to `grep` if missing) - **Python 3** (optional -- some hooks use it for JSON validation) -### Step 0.1: Clone and Configure - -Clone the repository and open it in your editor: +### Step 1: Clone and Open ```bash git clone my-game cd my-game ``` -### Step 0.2: Run /start (Recommended for New Users) +### Step 2: Run /start -If you're new to the project or don't yet know what game you're building: +If this is your first session: ``` /start ``` -This guided onboarding asks where you are (no idea, vague idea, clear concept, -existing work) and routes you to the right phase. Skip this if you already have -a game concept and engine decision. +This guided onboarding asks where you are and routes you to the right phase: -### Step 0.3: Choose Your Engine +- **Path A** -- No idea yet: routes to `/brainstorm` +- **Path B** -- Vague idea: routes to `/brainstorm` with seed +- **Path C** -- Clear concept: routes to `/setup-engine` and `/map-systems` +- **Path D1** -- Existing project, few artifacts: normal flow +- **Path D2** -- Existing project, GDDs/ADRs exist: runs `/project-stage-detect` + then `/adopt` for brownfield migration -Run `/setup-engine` in Claude Code. This is the single most important -configuration step -- it tells every agent what engine, language, and toolchain -you're using: - -```bash -/setup-engine godot 4.6 -``` - -Or run `/setup-engine` with no arguments to get an interactive recommendation -based on your game's needs (2D/3D, platforms, team size, language preferences). - -**What `/setup-engine` does:** - -- Pins the engine and version in `CLAUDE.md` -- Populates `.claude/docs/technical-preferences.md` with naming conventions, - performance budgets, and engine-specific defaults -- Detects knowledge gaps (engine version newer than LLM training data) and - fetches current docs from the web so agents suggest correct APIs -- Creates version-pinned reference docs in `docs/engine-reference/` - -**Why this matters:** Once you set the engine, the system knows which -engine-specialist agents to use. If you pick Godot, agents like -`godot-specialist`, `godot-gdscript-specialist`, and `godot-shader-specialist` -become your go-to experts. The Unity and Unreal specialists remain available -but won't be primary. - -> **Manual alternative:** You can also edit the Technology Stack section in -> `CLAUDE.md` directly if you prefer. - -### Step 0.3: Verify Hooks Are Working +### Step 3: Verify Hooks Are Working Start a new Claude Code session. You should see output from the `session-start.sh` hook: @@ -106,10 +80,21 @@ Recent commits: If you see this, hooks are working. If not, check `.claude/settings.json` to make sure the hook paths are correct for your OS. -### Step 0.4: Create Your Directory Structure +### Step 4: Ask for Help Anytime -The directories listed in `CLAUDE.md` don't all exist yet. Create them as -needed -- the system expects this layout: +At any point, run: + +``` +/help +``` + +This reads your current phase from `production/stage.txt`, checks which +artifacts exist, and tells you exactly what to do next. It distinguishes +between REQUIRED next steps and OPTIONAL opportunities. + +### Step 5: Create Your Directory Structure + +Directories are created as needed. The system expects this layout: ``` src/ # Game source code @@ -130,6 +115,7 @@ design/ # Design documents narrative/ # Story, lore, dialogue levels/ # Level design documents balance/ # Balance spreadsheets and data + ux/ # UX specifications docs/ # Technical documentation architecture/ # Architecture Decision Records api/ # API documentation @@ -140,9 +126,13 @@ production/ # Sprint plans, milestones, releases sprints/ milestones/ releases/ + stories/ # Story files (from /create-epics-stories) + playtests/ # Playtest reports + session-state/ # Ephemeral session state (gitignored) + session-logs/ # Session audit trail (gitignored) ``` -> **Tip:** You don't need all of these on day one. Create directories as you +> **Tip:** You do not need all of these on day one. Create directories as you > reach the phase that needs them. The important thing is to follow this > structure when you do create them, because the **rules system** enforces > standards based on file paths. Code in `src/gameplay/` gets gameplay rules, @@ -150,19 +140,36 @@ production/ # Sprint plans, milestones, releases --- -## Phase 1: Ideation & Concept +## Phase 1: Concept ### What Happens in This Phase -You go from "no idea" or "vague idea" to a structured game concept document. -This is where you figure out **what** you're making. +You go from "no idea" or "vague idea" to a structured game concept document +with defined pillars and a player journey. This is where you figure out +**what** you are making and **why**. -> **Tip:** If you ran `/start` in Phase 0 and chose Path A or B, you're already -> here. `/start` routes you to `/brainstorm` automatically. +### Phase 1 Pipeline -### Step 1.1: Brainstorm With `/brainstorm` +``` +/brainstorm --> game-concept.md --> /design-review --> /setup-engine + | | | + v v v + 10 concepts Concept doc with Validation Engine pinned in + MDA analysis pillars, MDA, of concept technical-preferences.md + Player motiv. core loop, USP document + | + v + /map-systems + | + v + systems-index.md + (all systems, deps, + priority tiers) +``` -This is your starting point if you skipped `/start`. Run the brainstorm skill: +### Step 1.1: Brainstorm With /brainstorm + +This is your starting point. Run the brainstorm skill: ``` /brainstorm @@ -177,43 +184,15 @@ Or with a genre hint: **What happens:** The brainstorm skill guides you through a collaborative 6-phase ideation process using professional studio techniques: -Agent: "Let's explore game concepts. What genre or theme interests you? (Optional, - or leave blank for open exploration)" +1. Asks about your interests, themes, and constraints +2. Generates 10 concept seeds with MDA (Mechanics, Dynamics, Aesthetics) analysis +3. You pick 2-3 favorites for deep analysis +4. Performs player motivation mapping and audience targeting +5. You choose the winning concept +6. Formalizes it into `design/gdd/game-concept.md` -User: "Roguelike deckbuilder" +The concept document includes: -Agent: "I've generated 10 concept seeds combining roguelike and deckbuilder mechanics. - Here are the top 3: - - **Concept A: Spell Compiler** - Code-themed deckbuilder where cards are functions - **Concept B: Memory Palace** - Psychological thriller where cards are memories - **Concept C: Ecosystem Builder** - Nature theme where cards are species - - Which concept(s) would you like me to develop with MDA analysis?" - -User: "Concept B sounds unique" - -Agent: [Performs MDA Analysis, Player Motivation mapping, Audience Targeting, Verb-First - Design for Concept B, showing work at each stage and asking for feedback] - - "Here's the complete analysis. Should I formalize this into a structured - concept document?" - -User: "Yes" - -Agent: [Creates structured concept document with top ideas, target audience, - core mechanics, and emotional goals] - -### Step 1.2: Document the Winning Concept - -Take the brainstorm output and formalize it. Use the **game concept template**: - -``` -Ask Claude to create a game concept document using the template at -.claude/docs/templates/game-concept.md -``` - -This template includes: - Elevator pitch (one sentence) - Core fantasy (what the player imagines themselves doing) - MDA breakdown @@ -221,38 +200,43 @@ This template includes: - Core loop diagram - Unique selling proposition - Comparable titles and differentiation +- Game pillars (3-5 non-negotiable design values) +- Anti-pillars (things the game intentionally avoids) -### Step 1.3: Define Your Game Pillars - -Before you go further, lock in your **game pillars** -- the 3-5 non-negotiable -design values that guide every decision. Use the template: +### Step 1.2: Review the Concept (Optional but Recommended) ``` -Ask Claude to create a game pillars document using the template at -.claude/docs/templates/game-pillars.md +/design-review design/gdd/game-concept.md ``` -Example pillars: -- **Meaningful Choices**: Every decision changes something permanently -- **Emergent Storytelling**: Systems create unique narratives, not scripts -- **Accessible Depth**: Easy to start, deep to master +Validates structure and completeness before you proceed. -Also define **anti-pillars** -- things your game intentionally avoids: -- We do NOT pursue: photorealism, competitive balance, linear narrative +### Step 1.3: Choose Your Engine -> **When you're happy with your concept and pillars, you're ready for -> Pre-Production.** +``` +/setup-engine +``` ---- +Or with a specific engine: -## Phase 2: Pre-Production & Design +``` +/setup-engine godot 4.6 +``` -### What Happens in This Phase +**What /setup-engine does:** -You create all the design documents that define how your game works. Nothing -gets coded yet -- this is pure design and architecture. +- Populates `.claude/docs/technical-preferences.md` with naming conventions, + performance budgets, and engine-specific defaults +- Detects knowledge gaps (engine version newer than LLM training data) and + advises cross-referencing `docs/engine-reference/` +- Creates version-pinned reference docs in `docs/engine-reference/` -### Step 2.1: Decompose Your Concept Into Systems +**Why this matters:** Once you set the engine, the system knows which +engine-specialist agents to use. If you pick Godot, agents like +`godot-specialist`, `godot-gdscript-specialist`, and `godot-shader-specialist` +become your go-to experts. + +### Step 1.4: Decompose Your Concept Into Systems Before writing individual GDDs, enumerate all the systems your game needs: @@ -260,136 +244,161 @@ Before writing individual GDDs, enumerate all the systems your game needs: /map-systems ``` -This creates `design/gdd/systems-index.md` — a master tracking document that: +This creates `design/gdd/systems-index.md` -- a master tracking document that: - Lists every system your game needs (combat, movement, UI, etc.) - Maps dependencies between systems - Assigns priority tiers (MVP, Vertical Slice, Alpha, Full Vision) -- Determines design order (Foundation → Core → Feature → Presentation → Polish) +- Determines design order (Foundation > Core > Feature > Presentation > Polish) -Then design each system in dependency order: +This step is **required** before proceeding to Phase 2. Research from 155 game +postmortems confirms that skipping systems enumeration costs 5-10x more in +production. + +### Phase 1 Gate + +``` +/gate-check concept +``` + +**Requirements to pass:** + +- Engine configured in `technical-preferences.md` +- `design/gdd/game-concept.md` exists with pillars +- `design/gdd/systems-index.md` exists with dependency ordering + +**Verdict:** PASS / CONCERNS / FAIL. CONCERNS is passable with acknowledged +risks. FAIL blocks advancement. + +--- + +## Phase 2: Systems Design + +### What Happens in This Phase + +You create all the design documents that define how your game works. Nothing +gets coded yet -- this is pure design. Each system identified in the systems +index gets its own GDD, authored section by section, reviewed individually, +and then all GDDs are cross-checked for consistency. + +### Phase 2 Pipeline + +``` +/map-systems next --> /design-system --> /design-review + | | | + v v v + Picks next system Section-by-section Validates 8 + from systems-index GDD authoring required sections + (incremental writes) APPROVED/NEEDS REVISION + | + | (repeat for each MVP system) + v +/review-all-gdds + | + v + Cross-GDD consistency + design theory review + PASS / CONCERNS / FAIL +``` + +### Step 2.1: Author System GDDs + +Design each system in dependency order using the guided workflow: ``` /map-systems next ``` -This picks the highest-priority undesigned system and hands off to `/design-system`, -which guides you through creating its GDD section by section. Each completed GDD -goes through `/design-review` before the next starts. +This picks the highest-priority undesigned system and hands off to +`/design-system`, which guides you through creating its GDD section by section. -You can also write a specific system's GDD directly: +You can also design a specific system directly: ``` /design-system combat-system ``` -### Step 2.2: Create the Game Design Document (GDD) +**What /design-system does:** -For each major system in your game, create a design document in `design/gdd/`. -Use the template: +1. Reads your game concept, systems index, and any upstream/downstream GDDs +2. Runs a Technical Feasibility Pre-Check (domain mapping + feasibility brief) +3. Walks you through each of the 8 required GDD sections one at a time +4. Each section follows: Context > Questions > Options > Decision > Draft > Approval > Write +5. Each section is written to file immediately after approval (survives crashes) +6. Flags conflicts with existing approved GDDs +7. Routes to specialist agents per category (systems-designer for math, + economy-designer for economy, narrative-director for story systems) -``` -Ask Claude to create a GDD using the template at -.claude/docs/templates/game-design-document.md -``` - -**The `design-docs` rule** (`.claude/rules/design-docs.md`) requires every GDD -to have these 8 sections: +**The 8 required GDD sections:** | # | Section | What Goes Here | |---|---------|---------------| | 1 | **Overview** | One-paragraph summary of the system | | 2 | **Player Fantasy** | What the player imagines/feels when using this system | -| 3 | **Detailed Rules** | Unambiguous mechanical rules -- if two designers read this, they'd build the same thing | +| 3 | **Detailed Rules** | Unambiguous mechanical rules | | 4 | **Formulas** | Every calculation, with variable definitions and ranges | | 5 | **Edge Cases** | What happens in weird situations? Explicitly resolved. | | 6 | **Dependencies** | What other systems this connects to (bidirectional) | | 7 | **Tuning Knobs** | Which values designers can safely change, with safe ranges | | 8 | **Acceptance Criteria** | How do you test that this works? Specific, measurable. | -**Example GDD files you might create:** -- `design/gdd/core-loop.md` -- The fundamental play loop -- `design/gdd/combat-system.md` -- How combat works -- `design/gdd/progression-system.md` -- How the player advances -- `design/gdd/inventory-system.md` -- Item management -- `design/gdd/ability-system.md` -- Player abilities and skills +Plus a **Game Feel** section: feel reference, input responsiveness (ms/frames), +animation feel targets (startup/active/recovery), impact moments, weight profile. -### Step 2.2: Use the Game Designer Agent for Complex Mechanics +### Step 2.2: Review Each GDD -For systems that need deep mechanical thinking, delegate to `game-designer`: +Before the next system starts, validate the current one: ``` -Ask the game-designer agent to design a crafting system that supports -emergent recipes (players discover combinations) with a skill progression -tied to experimentation. The system should feel rewarding without being -grindy. Target audience is Explorers and Achievers. +/design-review design/gdd/combat-system.md ``` -**What happens:** The `game-designer` agent collaborates with you to create the design: +Checks all 8 sections for completeness, formula clarity, edge case resolution, +bidirectional dependencies, and testable acceptance criteria. -Agent: "I'll help design the crafting system. First, some questions: - - Should recipes be discovered through experimentation or taught explicitly? - - How punishing should failed crafting attempts be? - - Target audience - primarily Explorers or Achievers?" +**Verdict:** APPROVED / NEEDS REVISION / MAJOR REVISION. Only APPROVED GDDs +should proceed. -User: "Discovered through experimentation. Moderate punishment - waste ingredients - but gain partial skill XP. Target Explorers primarily." +### Step 2.3: Small Changes Without Full GDDs -Agent: "Based on that, here are three mechanical approaches: - - **Option A: Pure Discovery** - No hints, full freedom - Pros: Maximum exploration reward - Cons: High frustration risk, may need wiki - - **Option B: Hint System** - Visual cues when ingredients are compatible - Pros: Guided exploration, less frustration - Cons: Less satisfying 'eureka' moments - - **Option C: Hybrid** - Free experimentation + optional journal hints unlocked by skill - Pros: Supports both playstyles, progressive scaffolding - Cons: More complex to implement - - I recommend Option C because it respects Explorers while providing safety nets, - and the journal hints can be gated behind skill progression for Achievers. - Which approach fits your vision?" - -User: "Option C sounds perfect" - -Agent: [Drafts GDD sections iteratively - Overview, Player Fantasy, Detailed Rules, - Formulas, Edge Cases - showing each and incorporating feedback] - - "I need detailed formula work for success rates and skill progression curves. - Let me consult the systems-designer for the math." - -Agent: [After consultation] "Complete draft ready with formulas validated by - systems-designer. The economy-designer flagged that ingredient costs - need balancing - I've incorporated their recommendations. - - May I write this to design/gdd/crafting-system.md?" - -User: "Yes" - -Agent: [Writes file] - -### Step 2.3: Design Review - -Before any design doc goes to programmers, run a review: +For tuning changes, small additions, or tweaks that do not warrant a full GDD: ``` -/design-review design/gdd/crafting-system.md +/quick-design "add 10% damage bonus for flanking attacks" ``` -**What happens:** The skill checks the document against the 8-section -standard, verifying: -- Are all sections present and complete? -- Are formulas unambiguous with defined variables? -- Are edge cases explicitly resolved (not "TBD")? -- Do dependencies list both directions? -- Are acceptance criteria testable? +This creates a lightweight spec in `design/quick-specs/` instead of a full +8-section GDD. Use it for tuning, number changes, and small additions. -Fix any issues flagged before proceeding. +### Step 2.4: Cross-GDD Consistency Review -### Step 2.4: Create Narrative Design (if applicable) +After all MVP system GDDs are approved individually: + +``` +/review-all-gdds +``` + +This reads ALL GDDs simultaneously and runs two analysis phases: + +**Phase 1 -- Cross-GDD Consistency:** +- Dependency bidirectionality (A references B, does B reference A?) +- Rule contradictions between systems +- Stale references to renamed or removed systems +- Ownership conflicts (two systems claiming the same responsibility) +- Formula range compatibility (does System A's output fit System B's input?) +- Acceptance criteria cross-check + +**Phase 2 -- Design Theory (Game Design Holism):** +- Competing progression loops (do two systems fight for the same reward space?) +- Cognitive load (more than 4 active systems at once?) +- Dominant strategies (one approach that makes all others irrelevant) +- Economic loop analysis (sources and sinks balanced?) +- Difficulty curve consistency across systems +- Pillar alignment and anti-pillar violations +- Player fantasy coherence + +**Output:** `design/gdd/gdd-cross-review-[date].md` with a verdict. + +### Step 2.5: Narrative Design (If Applicable) If your game has story, lore, or dialogue, this is when you build it: @@ -398,302 +407,433 @@ If your game has story, lore, or dialogue, this is when you build it: 2. **Story structure** -- Use `narrative-director` to design story arcs, character arcs, and narrative beats 3. **Character sheets** -- Use the `narrative-character-sheet.md` template - for each major character -The `narrative` rule (`.claude/rules/narrative.md`) enforces: -- Lore consistency across documents -- Canon levels (Core Canon vs Flavor vs Apocrypha) -- Character voice profiles -- World rule documentation +### Phase 2 Gate -### Step 2.5: Technical Architecture +``` +/gate-check systems-design +``` -Before coding starts, make key technical decisions: +**Requirements to pass:** + +- All MVP systems in `systems-index.md` have `Status: Approved` +- Each MVP system has a reviewed GDD +- Cross-GDD review report exists (`design/gdd/gdd-cross-review-*.md`) + with verdict of PASS or CONCERNS (not FAIL) + +--- + +## Phase 3: Technical Setup + +### What Happens in This Phase + +You make key technical decisions, document them as Architecture Decision Records +(ADRs), validate them through review, and produce a control manifest that +gives programmers flat, actionable rules. You also establish UX foundations. + +### Phase 3 Pipeline + +``` +/create-architecture --> /architecture-decision (x N) --> /architecture-review + | | | + v v v + Master architecture Per-decision ADRs Validates completeness, + document covering in docs/architecture/ dependency ordering, + all systems adr-*.md engine compatibility + | + v + /create-control-manifest + | + v + Flat programmer rules + docs/architecture/ + control-manifest.md + Also in this phase: + ------------------- + /ux-design --> /ux-review + Accessibility requirements doc + Interaction pattern library +``` + +### Step 3.1: Master Architecture Document + +``` +/create-architecture +``` + +Creates the overarching architecture document in `docs/architecture/architecture.md` +covering system boundaries, data flow, and integration points. + +### Step 3.2: Architecture Decision Records (ADRs) + +For each significant technical decision: ``` /architecture-decision "State Machine vs Behavior Tree for NPC AI" ``` -**What happens:** The skill guides you through creating an Architecture Decision Record: +**What happens:** The skill guides you through creating an ADR with: +- Context and decision drivers +- All options with pros/cons and engine compatibility +- Chosen option with rationale +- Consequences (positive, negative, risks) +- Dependencies (Depends On, Enables, Blocks, Ordering Note) +- GDD Requirements Addressed (linked by TR-ID) -Agent: "I'll help document this architectural decision. First, let me understand - the context. What's driving this decision right now?" +ADRs go through a lifecycle: Proposed > Accepted > Superseded/Deprecated. -User: "We need to choose between state machine and behavior tree for NPC AI. - We have 50+ enemy types planned." +**Minimum 3 Foundation-layer ADRs are required** before the gate check. -Agent: "Given 50+ enemy types, here's my analysis: - - **Option A: Finite State Machine** - Pros: Simple, debuggable, less overhead - Cons: Becomes unwieldy with complex behaviors, hard to reuse logic - - **Option B: Behavior Tree** - Pros: Highly reusable, scales well, visual debugging - Cons: Steeper learning curve, slightly more overhead - - **Option C: Utility AI** - Pros: Emergent behaviors, dynamic decision-making - Cons: Harder to debug, needs careful tuning - - For 50+ types, I recommend Behavior Trees - the reusability and - scalability outweigh the learning curve. - - Should I create an ADR documenting this decision?" - -User: "Yes, go with Behavior Trees" - -Agent: [Creates ADR in docs/architecture/ with context, decision drivers, - all options with pros/cons, chosen option with rationale, and consequences] - -**For complex architectural decisions, use the `technical-director` agent:** +**Retrofitting existing ADRs:** If you already have ADRs from a brownfield +project: ``` -Ask the technical-director agent to evaluate whether we should use an -ECS architecture or a traditional component system for our gameplay -entities, considering our team size (solo) and engine choice (Godot 4). +/architecture-decision retrofit docs/architecture/adr-005.md ``` -Agent: "Let me analyze the ECS vs traditional component decision for your context: +This detects which template sections are missing and adds only those, never +overwriting existing content. - [Performs detailed analysis considering Godot 4's scene system, solo dev - workflow, learning curve, debugging tools, performance needs] - - **Recommendation: Traditional Godot node-based components** - - Reasoning: [Detailed rationale] - - Shall I create an ADR documenting this decision with full analysis?" - -User: "Yes" - -Agent: [Creates comprehensive ADR] - -### Step 2.6: Milestone Planning - -Define your project milestones using the template: +### Step 3.3: Architecture Review ``` -Ask Claude to create a milestone definition using the template at -.claude/docs/templates/milestone-definition.md +/architecture-review ``` -Typical indie milestones: -1. **Vertical Slice** -- One level, fully playable, representative quality -2. **Alpha** -- All core systems functional, placeholder art OK -3. **Beta** -- Content complete, all features in, polishing begins -4. **Release Candidate** -- Bug fixes only, ready for launch -5. **Gold** -- Ship it +Validates all ADRs together: +- Topological sort of ADR dependencies (detects cycles) +- Engine compatibility verification +- GDD Revision Flags (flags GDD sections that need updates based on ADR choices) +- TR-ID registry maintenance (`docs/architecture/tr-registry.yaml`) -> **When all your design documents are reviewed and your architecture is -> decided, you're ready to start building.** +### Step 3.4: Control Manifest + +``` +/create-control-manifest +``` + +Takes all Accepted ADRs and produces a flat programmer rules sheet: + +``` +docs/architecture/control-manifest.md +``` + +This contains Required patterns, Forbidden patterns, and Guardrails organized +by code layer. Stories created later embed the manifest version date so +staleness can be detected. + +### Step 3.5: UX Foundations + +Three UX artifacts are required before leaving this phase: + +**Accessibility Requirements:** + +Create `design/accessibility-requirements.md` using the template. Commit to a +tier (Basic / Standard / Comprehensive / Exemplary) and fill the 4-axis feature +matrix (visual, motor, cognitive, auditory). + +**UX Specs for Key Screens:** + +``` +/ux-design main-menu +/ux-design core-gameplay-hud +``` + +Three modes: screen/flow, HUD, and interaction patterns. Output goes to +`design/ux/`. Each spec includes: player need, layout zones, states, +interaction map, data requirements, events fired, accessibility, localization. + +**UX Review:** + +``` +/ux-review +``` + +Validates UX specs for GDD alignment and accessibility tier compliance. + +**Interaction Pattern Library:** + +Create `design/ux/interaction-patterns.md` -- 16 standard controls plus +game-specific patterns (inventory slot, ability icon, HUD bar, dialogue box, +etc.) with animation and sound standards. + +### Phase 3 Gate + +``` +/gate-check technical-setup +``` + +**Requirements to pass:** + +- `docs/architecture/architecture.md` exists +- At least 3 ADRs exist and are Accepted +- Architecture review report exists +- `docs/architecture/control-manifest.md` exists +- `design/accessibility-requirements.md` exists +- At least 1 UX spec reviewed in `design/ux/` +- UX review completed --- -## Phase 3: Prototyping & Validation +## Phase 4: Pre-Production ### What Happens in This Phase -Before committing to full production, you validate risky or uncertain -mechanics with throwaway prototypes. This saves weeks of wasted production -effort. +You turn design documents into implementable stories, create prototypes to +validate risky mechanics, plan your first sprint, and build a Vertical Slice +that proves the core loop is fun. -### Step 3.1: Identify What Needs Prototyping +### Phase 4 Pipeline + +``` +/prototype --> /create-epics-stories --> /sprint-plan + | | | + v v v + Throwaway Story files in First sprint with + prototypes production/stories/ prioritized stories + in prototypes/ from GDDs + ADRs + production/sprints/ + control manifest sprint-*.md + | + v + /story-readiness + (validates each story + before pickup) + | + v + Vertical Slice + (playable build, + 3 unguided sessions) +``` + +### Step 4.1: Prototype Risky Mechanics Not everything needs a prototype. Prototype when: -- A mechanic is novel and you're not sure it's fun -- A technical approach is risky and you're not sure it's feasible +- 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 -### Step 3.2: Run the Prototype Skill - ``` /prototype "grappling hook movement with momentum" ``` -**What happens:** The skill collaborates with you to set up the prototype: +**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/`. -Agent: "Let's prototype the grappling hook movement. First, let me clarify the - hypothesis we're testing: +**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. - - Are we testing if momentum-based grappling feels good? - - Or testing technical feasibility of the physics? - - Or comparing different control schemes? - - What's the core question this prototype needs to answer?" - -User: "Testing if momentum transfer feels satisfying and creates skill expression" - -Agent: "Got it. Here's my proposed setup: - - **Hypothesis**: Grappling hook with momentum transfer will feel satisfying - and create emergent movement options through skill-based physics manipulation - - **Success Criteria**: - - Player can chain 3+ grapple points fluidly without losing momentum - - Momentum feels predictable enough to plan, expressive enough to surprise - - Players discover unintended movement tricks within 5 minutes - - **Prototype Scope** (1-2 hours max): - - Basic grapple point attachment - - Momentum calculation and transfer - - Simple test level with various grapple configurations - - No art, UI, or sounds - pure mechanics - - Does this match what you want to validate?" - -User: "Perfect, but add one more criteria: can we swing around corners" - -Agent: "Updated success criteria to include corner swinging. Should I create - prototypes/grappling-hook/ and implement this?" - -User: "Yes" - -Agent: [Creates directory structure, README with hypothesis/criteria/status, - delegates to prototyper agent for minimal implementation] - -**Key rule:** The `prototype-code` rule (`.claude/rules/prototype-code.md`) -intentionally relaxes coding standards for prototypes - hardcoded values OK, -no tests required, but README with hypothesis and findings is mandatory. - -### Step 3.3: Evaluate the Prototype - -Play/test the prototype and answer: -- Does the hypothesis hold? Is it fun / feasible / better? -- What surprised you? -- What would change for production? - -Update the prototype README with findings and a **verdict**: Ship It, Rework, -or Kill It. - -### Step 3.4: Run a Playtest Report - -If you had others test the prototype: +### Step 4.2: Create Stories From Design Artifacts ``` -/playtest-report +/create-epics-stories ``` -This generates a structured report template covering: -- Tester demographics and context -- Task completion rates -- Confusion points and friction -- Moments of delight -- Quantitative ratings -- Prioritized takeaways +This reads your GDDs, ADRs, and control manifest to generate implementable +story files in `production/stories/`. Each story embeds: +- GDD requirement references (TR-IDs, not quoted text -- stays fresh) +- ADR references (only from Accepted ADRs; Proposed ADRs cause `Status: Blocked`) +- Control manifest version date (for staleness detection) +- Engine-specific implementation notes +- Acceptance criteria from the GDD -> **When your prototypes have validated (or invalidated) your riskiest -> assumptions, you're ready for production.** +### Step 4.3: Validate Stories Before Pickup ---- +``` +/story-readiness production/stories/combat-damage-calc.md +``` -## Phase 4: Production Sprint Workflow +Checks: Design completeness, Architecture coverage, Scope clarity, Definition +of Done. Verdict: READY / NEEDS WORK / BLOCKED. -### What Happens in This Phase +### Step 4.4: Effort Estimation -This is the core production loop. You work in sprints (typically 1-2 weeks), -implementing features, fixing bugs, and tracking progress. This phase repeats -until your game is content-complete. +``` +/estimate production/stories/combat-damage-calc.md +``` -### Step 4.1: Create Your First Sprint +Provides effort estimates with risk assessment. + +### Step 4.5: Plan Your First Sprint ``` /sprint-plan new ``` -**What happens:** The skill delegates to `producer` to collaborate on sprint planning: +**What happens:** The `producer` agent collaborates on sprint planning: +- Asks for sprint goal and available time +- Breaks the goal into Must Have / Should Have / Nice to Have tasks +- Identifies risks and blockers +- Creates `production/sprints/sprint-01.md` +- Populates `production/sprint-status.yaml` (machine-readable story tracking) -Agent: "Let's plan your sprint. First, what's your primary goal for this sprint? - (One sentence that defines success)" +### Step 4.6: Vertical Slice (Hard Gate) -User: "Implement core combat system with basic attacks and health" +Before advancing to Production, you must build and playtest a Vertical Slice: -Agent: "How much time do you have available this sprint? (hours or days)" +- One complete end-to-end core loop, playable from start to finish +- Representative quality (not placeholder everything) +- Played unguided in at least 3 sessions +- Playtest report written (`/playtest-report`) -User: "20 hours over 2 weeks" +This is a **hard gate** -- `/gate-check` will auto-FAIL if a human has not +played the build unguided. -Agent: "Based on 'core combat system' I'm breaking this into tasks. Here's my - proposed structure: - - **Must Have** (sprint fails without these): - - Damage calculation system (design/gdd/combat-system.md formulas) - - Health component with damage handling - - Basic attack input and execution - - Unit tests for damage calculation - - **Should Have** (important but can slip): - - Hit reactions and feedback VFX - - Death state handling - - Combat stat data files - - **Nice to Have** (if time permits): - - Attack combo system - - Damage numbers UI - - **Risks I see**: - - No combat design doc exists yet (blocker - need to create first) - - VFX requires technical-artist involvement - - Does this task breakdown match your vision? Any tasks to add/remove/reprioritize?" - -User: "Move combo system to Should Have - it's important for feel" - -Agent: "Updated. Should I create production/sprints/sprint-01.md with this plan?" - -User: "Yes" - -Agent: [Creates sprint plan with goal, categorized tasks, 20hr capacity estimate, - risk register, and dependencies] - -### Step 4.2: The Daily Work Loop - -Each session follows this pattern: +### Phase 4 Gate ``` -1. Start a Claude Code session - (session-start hook shows branch, sprint status, recent commits) - -2. Pick a task from the sprint plan - ("I'm working on the combat damage calculation system") - -3. Claude identifies the right agent(s) to help - - game-designer if the design needs work - - gameplay-programmer for implementation - - systems-designer for formula details - -4. Implement the feature (see Phase 5 for details) - -5. Write tests (verification-driven development) - -6. Commit your work - (validate-commit hook checks for design doc references, - valid JSON data, no hardcoded values) - -7. Repeat until the session's context is getting full (~65-70%) - -8. /clear to start fresh, or compact to continue +/gate-check pre-production ``` -### Step 4.3: Sprint Tracking +**Requirements to pass:** -Check on sprint progress anytime: +- At least 1 prototype with README +- Story files exist in `production/stories/` +- At least 1 sprint plan exists +- At least 1 playtest report exists (Vertical Slice played in 3+ sessions) + +--- + +## Phase 5: Production + +### What Happens in This Phase + +This is the core production loop. You work in sprints (typically 1-2 weeks), +implementing features story by story, tracking progress, and closing stories +through a structured completion review. This phase repeats until your game +is content-complete. + +### Phase 5 Pipeline (Per Sprint) ``` -/sprint-plan status +/sprint-plan new --> /story-readiness --> implement --> /story-done + | | | | + v v v v + Sprint created Story validated Code written 8-phase review: + sprint-status.yaml READY verdict Tests pass verify criteria, + populated check deviations, + update story status + | + | (repeat per story until sprint complete) + v + /sprint-status (quick 30-line snapshot anytime) + /scope-check (if scope is growing) + /retrospective (at sprint end) ``` +### Step 5.1: The Story Lifecycle + +The production phase centers on the **story lifecycle**: + +``` +/story-readiness --> implement --> /story-done --> next story +``` + +**1. Story Readiness:** Before picking up a story, validate it: + +``` +/story-readiness production/stories/combat-damage-calc.md +``` + +This checks design completeness, architecture coverage, ADR status (blocks +if ADR is still Proposed), control manifest version (warns if stale), and +scope clarity. Verdict: READY / NEEDS WORK / BLOCKED. + +**2. Implementation:** Work with the appropriate agents: + +- `gameplay-programmer` for gameplay systems +- `engine-programmer` for core engine work +- `ai-programmer` for AI behavior +- `network-programmer` for multiplayer +- `ui-programmer` for UI code +- `tools-programmer` for dev tools + +All agents follow the collaborative protocol: they read the design doc, ask +clarifying questions, present architectural options, get your approval, then +implement. + +**3. Story Completion:** When a story is done: + +``` +/story-done production/stories/combat-damage-calc.md +``` + +This runs an 8-phase completion review: +1. Find and read the story file +2. Load referenced GDD, ADRs, and control manifest +3. Verify acceptance criteria (auto-checkable, manual, deferred) +4. Check for GDD/ADR deviations (BLOCKING / ADVISORY / OUT OF SCOPE) +5. Prompt for code review +6. Generate completion report (COMPLETE / COMPLETE WITH NOTES / BLOCKED) +7. Update story `Status: Complete` with completion notes +8. Surface the next ready story + +Tech debt discovered during review is logged to `docs/tech-debt-register.md`. + +### Step 5.2: Sprint Tracking + +Check progress anytime: + +``` +/sprint-status +``` + +Quick 30-line snapshot reading from `production/sprint-status.yaml`. + If scope is growing: ``` /scope-check production/sprints/sprint-03.md ``` -This compares current scope against the original plan and flags: -- Tasks added since sprint start -- Scope increase percentage -- Recommendations for what to cut +This compares current scope against the original plan and flags scope increase, +recommends cuts. -### Step 4.4: Sprint Review & Retrospective +### Step 5.3: Content Tracking + +``` +/content-audit +``` + +Compares GDD-specified content against what has been implemented. Catches +content gaps early. + +### Step 5.4: Design Change Propagation + +When a GDD changes after stories have been created: + +``` +/propagate-design-change design/gdd/combat-system.md +``` + +Git-diffs the GDD, finds affected ADRs, generates an impact report, and +walks you through Superseded/update/keep decisions. + +### Step 5.5: Multi-System Features (Team Orchestration) + +For features spanning multiple domains, use team skills: + +``` +/team-combat "healing ability with HoT and cleanse" +/team-narrative "Act 2 story content" +/team-ui "inventory screen redesign" +/team-level "forest dungeon level" +/team-audio "combat audio pass" +``` + +Each team skill coordinates a 6-phase collaborative workflow: +1. **Design** -- game-designer asks questions, presents options +2. **Architecture** -- lead-programmer proposes code structure +3. **Parallel Implementation** -- specialists work simultaneously +4. **Integration** -- gameplay-programmer wires everything together +5. **Validation** -- qa-tester runs against acceptance criteria +6. **Report** -- coordinator summarizes status + +The orchestration is automated, but **decision points stay with you**. + +### Step 5.6: Sprint Review and Next Sprint At the end of a sprint: @@ -701,13 +841,7 @@ At the end of a sprint: /retrospective ``` -This analyzes: -- What was planned vs. what was completed -- Velocity (tasks/points completed) -- What went well -- What went poorly -- Blockers encountered -- Actionable improvements for next sprint +Analyzes planned vs. completed, velocity, blockers, and actionable improvements. Then plan the next sprint: @@ -715,10 +849,7 @@ Then plan the next sprint: /sprint-plan new ``` -The new sprint incorporates carry-over tasks, retrospective learnings, and -updated priorities. - -### Step 4.5: Milestone Reviews +### Step 5.7: Milestone Reviews At milestone checkpoints: @@ -726,747 +857,181 @@ At milestone checkpoints: /milestone-review "alpha" ``` -This produces a comprehensive report: -- Feature completeness percentage -- Quality metrics (bug counts, test coverage) -- Risk assessment -- Go/no-go recommendation -- Action items to reach the milestone +Produces feature completeness, quality metrics, risk assessment, and go/no-go +recommendation. + +### Phase 5 Gate + +``` +/gate-check production +``` + +**Requirements to pass:** + +- All MVP stories complete +- Playtesting: 3 sessions covering new player, mid-game, and difficulty curve +- Fun hypothesis validated +- No confusion loops in playtest data --- -## Phase 5: Implementation Deep-Dive +## Phase 6: Polish ### What Happens in This Phase -This is where code gets written. The agent system ensures code quality through -path-specific rules, automated hooks, and structured delegation. +Your game is feature-complete. Now you make it good. This phase focuses on +performance, balance, accessibility, audio, visual polish, and playtesting. -### Step 5.1: Single-System Implementation - -For a single gameplay system (e.g., "implement the damage calculation"): +### Phase 6 Pipeline ``` -Ask the gameplay-programmer agent to implement the damage calculation -system as specified in design/gdd/combat-system.md. The formulas are in -section 4. Use the project's data-driven approach with config files in -assets/data/. +/perf-profile --> /balance-check --> /asset-audit --> /playtest-report (x3) + | | | | + v v v v + Profile CPU/GPU Analyze formulas Verify naming, Cover: new player, + memory, optimize and data for formats, sizes mid-game, difficulty + bottlenecks broken progressions curve + + /tech-debt --> /team-polish + | | + v v + Track and Coordinated pass: + prioritize performance + art + + debt items audio + UX + QA ``` -**What happens:** The `gameplay-programmer` agent collaborates on implementation: - -Agent: "I've read design/gdd/combat-system.md. Before implementing, I need to - clarify a few details: - - Section 4 shows the damage formula: `base_damage * (1 + attack_stat * 0.1) * type_modifier` - - Questions: - - Should attack_stat be clamped to a max value? - - Where should type_modifiers live - per weapon or per damage type? - - Do you want damage rounding (floor/ceil/round)? - - Also, I don't see a design doc for the health component yet. Should I - create a minimal one or do you want to design that separately?" - -User: "Clamp attack_stat to 0-100. Type modifiers per damage type. Round down. - Create minimal health doc - just current/max HP and damage handling." - -Agent: "Got it. Here's my implementation approach: - - **Files to create**: - - src/gameplay/combat/damage_calculator.gd (core formula logic) - - src/gameplay/combat/health_component.gd (HP tracking) - - assets/data/combat_damage.json (base damage values, type modifiers) - - design/gdd/health-system.md (minimal doc) - - **Architecture**: - - DamageCalculator as stateless utility (testable) - - HealthComponent as node component (signals for damage/death) - - All values from config file (gameplay-code rule) - - May I proceed with implementation?" - -User: "Yes" - -Agent: [Implements with automatic rule enforcement - data-driven values, delta time - independence, signal-based communication, dependency injection for testing] - - "Implementation complete. Files created: - - src/gameplay/combat/damage_calculator.gd - - src/gameplay/combat/health_component.gd - - assets/data/combat_damage.json (validated JSON structure) - - design/gdd/health-system.md - - Ready for testing. Should I draft unit tests?" - -User: "Yes" - -Agent: [Writes tests] - -### Step 5.2: Multi-System Feature (Team Orchestration) - -For features that span multiple domains, use a team skill: - -``` -/team-combat "healing ability with HoT (heal-over-time) and cleanse" -``` - -**What happens:** The team skill orchestrates collaborative 6-phase development: - -**Phase 1 - Design**: -Agent (game-designer): "I'll design the healing ability. Questions: - - Should HoT stack or refresh duration? - - What debuffs should cleanse remove - all, or specific categories? - - Mana cost scaling with heal amount?" - -User: [Answers questions] - -Agent: [Creates design doc, shows draft] "Design ready. Approve to proceed to architecture?" - -User: "Approved" - -**Phase 2 - Architecture**: -Agent (gameplay-programmer): "Here's my proposed code structure: - - HealAbility class extending BaseAbility - - HoT as separate buff component (reusable) - - Cleanse as utility function (may be used elsewhere) - - This work or want changes?" - -User: "Approved" - -**Phase 3 - Parallel Implementation**: -Agent (coordinator): "Starting parallel implementation: - - gameplay-programmer: HealAbility + HoT buff code - - ai-programmer: AI logic for when NPCs should use heal - - technical-artist: HoT VFX particle spec - - sound-designer: Heal cast and HoT tick SFX spec - - I'll check back when all are complete." - -[Each specialist asks clarifying questions and shows their work before finalizing] - -**Phase 4 - Integration**: -Agent (gameplay-programmer): "All components ready. Integrating now..." - [Shows integrated result] "Working in test scene. Ready for validation?" - -**Phase 5 - Validation**: -Agent (qa-tester): "Testing against acceptance criteria from design doc..." - [Reports results] "2 edge cases found: [details]. Should we fix or defer?" - -User: "Fix the critical one, defer the other" - -**Phase 6 - Report**: -Agent (coordinator): "Feature complete. Status: - ✓ Design, architecture, implementation, integration done - ✓ Critical bugs fixed - - 1 minor edge case deferred to backlog - Ready to merge." - -Other team skills work similarly: -- `/team-narrative` -- Story content from structure to written dialogue -- `/team-ui` -- UI feature from wireframe to polished implementation -- `/team-level` -- Level from layout to fully dressed with encounters -- `/team-audio` -- Audio from direction to implemented events - -### Step 5.3: AI Systems - -For NPC behavior, pathfinding, or decision-making: - -``` -Ask the ai-programmer agent to implement a patrol/investigate/chase -behavior tree for enemy NPCs as specified in design/gdd/enemy-ai.md. -``` - -**What happens:** The `ai-programmer` agent asks clarifying questions before implementing: - -Agent: "I've read design/gdd/enemy-ai.md. Before building the behavior tree, I need - to clarify some behaviors: - - - During patrol, should NPCs stop at waypoints or continuous loop? - - For investigate state: how long should they search before returning to patrol? - - Chase transition: should they chase immediately on sight or require 'confirmation time'? - - What happens if player breaks line-of-sight during chase? - - Also, I see performance budget is 2ms/frame for all AI. How many NPCs will - be active simultaneously (worst case)?" - -User: "Stop at waypoints for 2 seconds. Search for 8 seconds. Immediate chase on sight. - Break LOS = return to last known position, search there, then investigate. - Max 15 NPCs active." - -Agent: "Got it. That gives me ~0.13ms per NPC. I'll use a hierarchical behavior tree - with shared pathfinding queries to stay under budget. - - My approach: - - Root selector: Chase > Investigate > Patrol - - All timing/ranges from assets/data/enemy_ai.json (data-driven per ai-code rule) - - Debug visualization showing current state + detection radius - - Telegraph attacks with 0.5s windup (visible to player) - - Approve this approach?" - -User: "Yes" - -Agent: [Implements with rule enforcement: 2ms budget, data-driven params, debug viz, - telegraphed intentions] - - "Implementation complete. Tested with 20 NPCs - running at 1.8ms/frame. - Debug visualization shows state colors (green=patrol, yellow=investigate, - red=chase). Ready for review?" - -The `ai-code` rule automatically enforces performance budgets, data-driven parameters, -debug visualization, and player-fair behavior. - -### Step 5.4: Engine-Specific Work - -When you need engine-specific expertise: - -``` -# For Godot: -Ask the godot-specialist agent to review our scene tree architecture -and suggest improvements for performance and maintainability. - -# For a specific subsystem: -Ask the godot-gdscript-specialist to refactor our signal architecture -to reduce coupling between the combat and UI systems. -``` - -Engine specialists know: -- Engine-specific patterns and anti-patterns -- Performance optimization techniques for that engine -- Proper use of engine subsystems (Godot signals, Unity Addressables, UE GAS) -- When to use native extensions vs scripting - -### Step 5.5: Architecture Decision Records - -When you face a significant technical choice during implementation: - -``` -/architecture-decision "Event Bus vs Direct Signals for System Communication" -``` - -This documents the decision so future-you (or future contributors) understand -*why* things were built this way. - -### Step 5.6: Code Review - -After implementing a feature: - -``` -/code-review src/gameplay/combat/damage_calculator.gd -``` - -**What happens:** The skill performs collaborative architectural review: - -Agent: "Reviewing src/gameplay/combat/damage_calculator.gd... - - **Architectural Compliance**: - ✓ Matches ADR-003 (stateless utility pattern) - ✓ Data-driven values (gameplay-code rule) - ✗ Issue: Direct reference to HealthComponent - breaks dependency injection - - **SOLID Principles**: - ✓ Single Responsibility - only calculates damage - ✗ Dependency Inversion - tightly coupled to HealthComponent type - - **Testability**: - ✗ Hard to mock HealthComponent dependency - - **Performance**: - ✓ No allocations in hot path - ⚠ Warning: Type lookup in dictionary every call - consider caching - - **Recommendations**: - 1. HIGH: Add interface for HealthComponent to enable mocking - 2. MEDIUM: Cache type modifier lookups - 3. LOW: Add null checks for edge cases - - Should I show you how to fix issue #1 (dependency injection)?" - -User: "Yes, show me" - -Agent: [Shows refactored code with interface] - - "This change lets you pass any object with take_damage(), making it testable. - Approve this refactor?" - -User: "Approved" - -Agent: [Applies changes] "Code review complete. All high-priority issues resolved." - ---- - -## Phase 6: Testing & Quality Assurance - -### What Happens in This Phase - -Testing runs throughout production, not just at the end. The system supports -test-driven development with automated enforcement. - -### Step 6.1: Write Tests First (Verification-Driven Development) - -The project enforces **verification-driven development**: write tests before -or alongside implementation, not after. - -The `test-standards` rule (`.claude/rules/test-standards.md`) enforces: -- Test naming: `test_[system]_[scenario]_[expected_result]` -- Structure: Arrange / Act / Assert -- No external state dependencies -- Tests clean up after themselves -- Each test file mirrors the source file it tests - -``` -Ask the qa-tester agent to write test cases for the damage calculation -system based on the acceptance criteria in design/gdd/combat-system.md. -``` - -**What happens:** The `qa-tester` agent collaborates on test case creation: - -Agent: "I've read the acceptance criteria from design/gdd/combat-system.md. Before - writing tests, let me confirm the test scope: - - From the acceptance criteria, I see: - - Base damage formula must produce expected values - - Type modifiers apply correctly - - Edge case: attack_stat clamped at 0-100 - - Edge case: negative damage becomes 0 - - Questions: - - Should I include integration tests with HealthComponent or just unit tests? - - Do you want performance tests (e.g., 1000 calculations < Xms)? - - Any specific edge cases beyond those in the doc?" - -User: "Unit tests only for now. Add performance test - target 10,000 calcs < 1ms. - Also test what happens with invalid damage types." - -Agent: "Got it. Here's my test plan: - - **Unit Tests**: - - test_damage_basic_calculation (base formula, known values) - - test_damage_type_modifiers (each modifier from config) - - test_damage_attack_stat_clamping (below 0, above 100) - - test_damage_negative_becomes_zero - - test_damage_invalid_type (undefined type in config) - - test_damage_rounding (verify floor behavior) - - **Performance Test**: - - test_damage_performance_10k_calculations - - Approve this test suite?" - -User: "Yes" - -Agent: [Writes tests following test-standards rule: proper naming, Arrange/Act/Assert - structure, no external dependencies, cleanup] - - "Test suite complete. All 7 tests written. Ready to run?" - -### Step 6.2: Bug Reporting - -When you find a bug: - -``` -/bug-report "Healing spell applies damage instead of healing when -target has a shield buff active" -``` - -This creates a structured bug report with: -- Severity (Critical / Major / Minor / Cosmetic) -- Priority (P0-P4) -- Steps to reproduce -- Expected vs actual behavior -- System/component affected -- Related design doc - -### Step 6.3: Test Planning - -For milestone validation: - -``` -Ask the qa-lead agent to create a test plan for the Alpha milestone, -covering combat, progression, and UI systems. -``` - -**What happens:** The `qa-lead` agent collaborates on comprehensive test planning: - -Agent: "I'll create a test plan for the Alpha milestone. First, let me understand - the scope: - - From the milestone definition, I see these systems are in scope: - - Combat system - - Progression system - - UI systems - - Questions: - - What platforms are we testing? (Windows, Linux, Mac, mobile?) - - What's our target performance? (60fps? 30fps?) - - Any known risky areas that need extra test coverage? - - Timeline - when does testing need to complete?" - -User: "Windows and Linux. Target 60fps. Combat AI is risky - lots of edge cases. - Testing deadline is end of next week." - -Agent: "Got it. Here's my proposed test plan structure: - - **Functional Tests** (3 days): - - Combat: Damage calculation, status effects, death states, AI behavior - - Progression: XP gain, level-up, skill unlocks, stat increases - - UI: Menus, HUD, inventory, settings - - **Edge Case Tests** (1 day): - - Combat AI: Line-of-sight breaks, pathfinding failures, stuck states - - Boundary conditions: Max level, inventory full, negative damage - - **Regression Suite** (1 day): - - Re-run all previous milestone tests - - **Performance Benchmarks** (1 day): - - 60fps with 15 enemies, complex VFX - - Memory under 2GB - - Load times under 5s - - **Platform Tests** (1 day): - - Windows 10/11 - - Ubuntu 22.04 LTS - - This fits the timeline. Approve or adjust?" - -User: "Approved" - -Agent: [Creates detailed test plan using test-plan.md template] - -### Step 6.4: Balance Testing - -After implementing economy or progression systems: - -``` -/balance-check assets/data/combat_damage.json -``` - -This analyzes your balance data for: -- Statistical outliers -- Broken progression curves -- Degenerate strategies (one option dominates all others) -- Economy imbalances (inflation, deflation, exploits) - ---- - -## Phase 7: Polish & Optimization - -### What Happens in This Phase - -Your game is feature-complete. Now you make it *good*. This phase focuses on -performance, visual polish, audio, and feel. - -### Step 7.1: Performance Profiling +### Step 6.1: Performance Profiling ``` /perf-profile ``` -**What happens:** The skill guides you through structured performance profiling: +Guides you through structured performance profiling: +- Establish targets (FPS, memory, platform) +- Identify bottlenecks ranked by impact +- Generate actionable optimization tasks with code locations and expected gains -Agent: "Starting performance profiling. First, let's establish your targets: - - Target FPS? - - Target memory limit? - - Target platform(s)?" - -User: "60fps on mid-range PC. Under 2GB RAM. Windows/Linux." - -Agent: "Running profiler on current build... - - **Current Performance**: - - Average FPS: 48 - - Frame time: 20.8ms (target: 16.6ms for 60fps) - - Memory: 2.4GB (400MB over target) - - **Bottlenecks Identified** (ranked by impact): - 1. Combat AI: 8.2ms/frame (49% of frame time) - HIGH PRIORITY - 2. Particle VFX: 3.1ms/frame (18% of frame time) - MEDIUM - 3. UI rendering: 2.8ms/frame (17% of frame time) - MEDIUM - 4. Physics: 1.9ms/frame (11% of frame time) - LOW - - **Memory Issues**: - 1. Texture atlas not compressed: +280MB - HIGH PRIORITY - 2. Audio buffers not streaming: +120MB - HIGH PRIORITY - - **Recommendations**: - 1. Combat AI: Implement hierarchical behavior tree, reduce per-frame checks - 2. Textures: Enable GPU compression - 3. Audio: Stream longer sounds instead of loading all - - Should I generate detailed optimization tasks for the top 3 issues?" - -User: "Yes" - -Agent: [Generates actionable optimization tasks with code locations and expected gains] - -**For deeper analysis, use the `performance-analyst` agent:** +### Step 6.2: Balance Analysis ``` -Ask the performance-analyst agent to analyze our combat system for -frame time spikes. We're seeing hitches when 10+ enemies are active. +/balance-check assets/data/combat_damage.json ``` -Agent: "I'll analyze the combat system performance. Let me profile with varying - enemy counts... +Analyzes balance data for statistical outliers, broken progression curves, +degenerate strategies, and economy imbalances. - **Analysis Results**: - - 5 enemies: 58fps stable - - 10 enemies: 52fps with occasional drops to 45fps - - 15 enemies: 38fps with spikes down to 22fps - - **Root Cause**: Behavior tree re-evaluates entire tree every frame for - every NPC. With 15 NPCs, that's 15 full tree traversals = 8.2ms. - - **Solution Options**: - 1. Stagger updates: Only update 5 NPCs per frame (rotation) - 2. Cache tree results: Re-evaluate only on state change - 3. Simplify tree: Reduce node count from 12 to 6 - - I recommend Option 2 + 3: Cache results AND simplify the tree. - Expected gain: 8.2ms -> 1.5ms (6.7ms saved = +40fps) - - Should I show you the refactored behavior tree?" - -User: "Yes" - -Agent: [Shows optimized implementation] - -### Step 7.2: Visual Polish - -Use the team polish skill for comprehensive polishing: +### Step 6.3: Asset Audit ``` -/team-polish "combat system" +/asset-audit ``` -**What happens:** The team polish skill coordinates collaborative polish passes: +Verifies naming conventions, file format standards, and size budgets across +all assets. -Agent (coordinator): "Starting polish pass for combat system. Let me assess - current state and identify polish priorities... - - **Current State Analysis**: - - Performance: 48fps (needs optimization) - - Visual feedback: Hit effects present but underwhelming - - Audio: SFX in place but mixing needs work - - Feel: Input response good, but impacts lack weight - - I'll coordinate 4 specialists in parallel. First, let me get your polish - priorities - rank these: - - Performance (hitting 60fps) - - Visual impact (VFX, shaders, feedback) - - Audio polish (mixing, spatial, punch) - - Feel/juice (screen shake, hitstop, particles)" - -User: "Performance #1, then visual impact, then feel, then audio" - -**Phase 1 - Performance** (performance-analyst): -Agent: "Running combat performance optimization..." - [Implements optimizations from previous profiling] - "Now at 62fps stable. Performance target met." - -**Phase 2 - Visual Impact** (technical-artist): -Agent: "Analyzing visual feedback. I see hit VFX but they're generic. Questions: - - Should different damage types have distinct visual feedback? - - Do you want critical hits to be visually distinct? - - Screen shake on hits - subtle or pronounced?" - -User: "Distinct per damage type. Crits should pop. Subtle screen shake." - -Agent: [Creates polished VFX specifications and shader improvements] - "VFX polish complete. Want to see a comparison video?" - -**Phase 3 - Feel** (technical-artist + gameplay-programmer): -Agent: "Adding hitstop (frame freeze) on impacts, particle bursts on crits, - subtle camera shake. Testing feel..." - "Hitstop feels good at 100ms for normal hits, 200ms for crits. Approve?" - -User: "Approved" - -**Phase 4 - Validation** (qa-tester): -Agent: "Running regression tests on all combat polish changes..." - "All tests pass. No bugs introduced." - -Agent (coordinator): "Polish pass complete: - ✓ Performance: 48fps -> 62fps - ✓ Visual: Enhanced VFX, type-specific effects, crit feedback - ✓ Feel: Hitstop, particles, camera shake - ✓ Tests: All passing - Ready to merge." - -### Step 7.3: Audio Implementation +### Step 6.4: Playtesting (Required: 3 Sessions) ``` -/team-audio "combat audio" +/playtest-report ``` -**What happens:** The team audio skill coordinates the full collaborative audio pipeline: +Generates structured playtest reports. Three sessions are required, covering: +- New player experience +- Mid-game systems +- Difficulty curve -**Phase 1 - Audio Direction** (audio-director): -Agent: "Let's define the audio direction for combat. What's the emotional goal? - - Brutal and visceral? - - Tactical and precise? - - Magical and fantastical? - - Fast and arcade-like?" - -User: "Tactical and precise with some weight to impacts" - -Agent: "Got it. Here's my audio direction for combat: - - **Audio Pillars**: - - Clarity: Every action has distinct, recognizable sound - - Spatial awareness: Enemy positions clear from audio alone - - Feedback: Successful actions feel satisfying - - Atmosphere: Tension maintained without fatigue - - **Priorities**: - 1. Weapon sounds must be punchy but not fatiguing - 2. Footsteps critical for spatial awareness - 3. Enemy attack telegraphs via audio cues - 4. Hit confirmation with satisfying impact sounds - - Approve this direction?" - -User: "Approved" - -**Phase 2 - SFX Specification** (sound-designer): -Agent: "Based on the audio direction, here's my SFX event list: - - **Player Actions**: - - weapon_swing_light, weapon_swing_heavy (distinct whoosh) - - footstep_walk, footstep_run (material-aware) - - ability_cast_start, ability_cast_release - - **Impacts**: - - hit_flesh_light, hit_flesh_heavy (with pitch variation) - - hit_armor_deflect (metallic ping) - - critical_hit (special layered impact) - - **Enemy Audio**: - - enemy_attack_windup (0.5s telegraph) - - enemy_footstep (louder than player for spatial awareness) - - Each sound has variation pool (3-5 variants) to avoid repetition. - Missing anything critical?" - -User: "Add dodge/roll sound" - -Agent: "Added dodge_roll event. Complete SFX spec ready." - -**Phase 3 - Audio Implementation** (technical-artist): -Agent: "Implementing audio system with: - - Event-based triggers (no hardcoded audio calls) - - 3D spatial audio with distance attenuation - - Priority system (critical sounds never cut off) - - Dynamic mixing (combat music layer + SFX balance) - - Questions: - - Max simultaneous sounds limit? (recommend 32) - - Distance attenuation curve - linear or logarithmic?" - -User: "32 sounds max. Logarithmic attenuation." - -Agent: [Implements audio middleware integration] - -**Phase 4 - Integration** (gameplay-programmer): -Agent: "Wiring audio events to gameplay code... - - Weapon swings: Connected to animation events - - Footsteps: Tied to movement speed and surface type - - Impacts: Hooked to damage events - - Enemy telegraphs: 0.5s before attack execution - - Ready for audio playtest." - -Agent (coordinator): "Combat audio pipeline complete. Test in-game and provide feedback - on balance, clarity, and feel." - -### Step 7.4: Technical Debt - -Before release, assess your tech debt: +### Step 6.5: Technical Debt Assessment ``` /tech-debt ``` -This scans the codebase for: -- TODO/FIXME/HACK comments -- Code duplication -- Overly complex functions -- Missing tests -- Outdated dependencies +Scans for TODO/FIXME/HACK comments, code duplication, overly complex functions, +missing tests, and outdated dependencies. Each item categorized and prioritized. -Each debt item gets categorized and prioritized. You decide what to fix -before release vs. what to defer. +### Step 6.6: Coordinated Polish Pass ---- +``` +/team-polish "combat system" +``` -## Phase 8: Localization & Accessibility +Coordinates 4 specialists in parallel: +1. Performance optimization (performance-analyst) +2. Visual polish (technical-artist) +3. Audio polish (sound-designer) +4. Feel/juice (gameplay-programmer + technical-artist) -### Step 8.1: Localization Scan +You set priorities; the team executes with your approval at each step. + +### Step 6.7: Localization and Accessibility ``` /localize src/ ``` -This scans for: -- Hardcoded strings that should be externalized -- String concatenation that breaks translation -- Text that doesn't account for expansion (German text is ~30% longer) -- Missing locale files +Scans for hardcoded strings, concatenation that breaks translation, text that +does not account for expansion, and missing locale files. -### Step 8.2: Accessibility Review +Accessibility is audited against the tier committed in Phase 3's accessibility +requirements document. + +### Phase 6 Gate ``` -Ask the accessibility-specialist agent to audit our UI system for -WCAG compliance, colorblind support, and input remapping. +/gate-check polish ``` -The `ui-code` rule already enforces some accessibility: -- Localization-ready strings (no hardcoded text) -- Keyboard and gamepad input support -- Text scaling support -- Colorblind-friendly design +**Requirements to pass:** -The `accessibility-specialist` goes deeper: -- Screen reader compatibility -- Key remapping completeness -- Subtitle and caption support -- Motion sensitivity options -- Difficulty/assist options +- At least 3 playtest reports exist +- Coordinated polish pass completed (`/team-polish`) +- No blocking performance issues +- Accessibility tier requirements met --- -## Phase 9: Release & Launch +## Phase 7: Release ### What Happens in This Phase Your game is polished, tested, and ready. Now you ship it. -### Step 9.1: Release Checklist +### Phase 7 Pipeline + +``` +/release-checklist --> /launch-checklist --> /team-release + | | | + v v v + Pre-release Full cross-department Coordinate: + validation across validation (Go/No-Go build, QA sign-off, + code, content, per department) deployment, launch + store, legal + Also: /changelog, /patch-notes, /hotfix +``` + +### Step 7.1: Release Checklist ``` /release-checklist v1.0.0 ``` -This generates a comprehensive pre-release checklist covering: +Generates a comprehensive pre-release checklist covering: - Build verification (all platforms compile and run) - Certification requirements (platform-specific) - Store metadata (descriptions, screenshots, trailers) - Legal compliance (EULA, privacy policy, ratings) - Save game compatibility -- Analytics and telemetry verification +- Analytics verification -### Step 9.2: Launch Readiness (Full Validation) +### Step 7.2: Launch Readiness (Full Validation) ``` /launch-checklist ``` -This is the nuclear option -- a complete cross-department validation: +Complete cross-department validation: -| Department | What's Checked | +| Department | What Is Checked | |-----------|---------------| | **Engineering** | Build stability, crash rates, memory leaks, load times | | **Design** | Feature completeness, tutorial flow, difficulty curve | @@ -1484,15 +1049,14 @@ This is the nuclear option -- a complete cross-department validation: Each item gets a **Go / No-Go** status. All must be Go to ship. -### Step 9.3: Generate Player-Facing Content +### Step 7.3: Generate Player-Facing Content ``` /patch-notes v1.0.0 ``` -Generates player-friendly patch notes from git history and internal data. -Translates developer language ("refactored state machine") into player -language ("improved enemy behavior responsiveness"). +Generates player-friendly patch notes from git history and sprint data. +Translates developer language into player language. ``` /changelog v1.0.0 @@ -1500,154 +1064,212 @@ language ("improved enemy behavior responsiveness"). Generates an internal changelog (more technical, for the team). -### Step 9.4: Coordinate the Release +### Step 7.4: Coordinate the Release ``` /team-release ``` -**What happens:** The team release skill coordinates all departments for launch: +Coordinates release-manager, QA, and DevOps through: +1. Pre-release validation +2. Build management +3. Final QA sign-off +4. Deployment preparation +5. Go/No-Go decision -**Phase 1 - Pre-Release Validation** (release-manager): -Agent: "Starting release coordination for v1.0.0. First, status check across - all departments... - - Reviewing launch checklist results: - ✓ Engineering: All green - ✓ QA: 2 minor bugs open (non-blocking) - ✓ Art/Audio: Complete - ✓ Localization: Complete - ⚠ Store: Screenshots pending approval - ✗ Marketing: Launch trailer not finalized - - Two blockers identified. Timeline impact?" - -User: "Screenshots approved this morning. Trailer done by end of day." - -Agent: "Got it. Updated timeline: Release tomorrow pending trailer completion. - Should I proceed with build preparation?" - -User: "Yes" - -**Phase 2 - Build Management** (release-manager): -Agent: "Creating release build v1.0.0... - - Windows build: ✓ Complete, tested, 2.1GB - - Linux build: ✓ Complete, tested, 2.3GB - - Checksums generated - - Version manifest created - - Update server configured - - All builds ready for deployment." - -**Phase 3 - Final QA Sign-Off** (qa-lead): -Agent: "Running final regression suite on release builds... - - All critical tests: ✓ Pass - - All high-priority tests: ✓ Pass - - Platform-specific tests: ✓ Pass - - QA signs off for release. No blocking issues." - -**Phase 4 - Deployment Preparation** (devops-engineer): -Agent: "CI/CD pipeline ready. Deployment plan: - 1. Upload builds to CDN (12:00 UTC) - 2. Update store listings (12:30 UTC) - 3. Enable download access (13:00 UTC - launch time) - 4. Monitor server load and error rates - - Rollback plan ready if critical issues detected. - Approve deployment schedule?" - -User: "Approved" - -**Phase 5 - Go/No-Go Decision** (producer): -Agent: "Final go/no-go check: - ✓ All builds validated - ✓ QA sign-off complete - ✓ Store metadata approved - ✓ Launch trailer complete (confirmed) - ✓ Marketing materials ready - ✓ Support team briefed - ✓ Deployment plan approved - - All systems GO. Recommend proceeding with launch at 13:00 UTC tomorrow. - Final approval?" - -User: "GO for launch" - -Agent: "Launch approved. Deployment begins 12:00 UTC tomorrow. I'll monitor and - report status updates." - -### Step 9.5: Ship +### Step 7.5: Ship The `validate-push` hook will warn you when pushing to `main` or `develop`. This is intentional -- release pushes should be deliberate: -``` +```bash git tag v1.0.0 git push origin main --tags ``` ---- +### Step 7.6: Post-Launch -## Phase 10: Post-Launch & Live Ops - -### Step 10.1: Hotfix Workflow - -When a critical bug appears in production: +**Hotfix workflow** for critical production bugs: ``` /hotfix "Players losing save data when inventory exceeds 99 items" ``` -This bypasses normal sprint processes with a full audit trail: +Bypasses normal sprint processes with a full audit trail: 1. Creates a hotfix branch -2. Tracks approvals -3. Implements the fix -4. Ensures the fix is backported to the development branch -5. Documents the incident +2. Implements the fix +3. Ensures backport to development branch +4. Documents the incident -### Step 10.2: Post-Mortem - -After launch dust settles: +**Post-mortem** after launch stabilizes: ``` Ask Claude to create a post-mortem using the template at .claude/docs/templates/post-mortem.md ``` -This covers: -- What went well -- What went poorly -- What was surprising -- Key metrics (sales, reviews, crash rates) -- Lessons for the next project +--- -### Step 10.3: Live Operations (if applicable) +## Cross-Cutting Concerns -For games with ongoing content: +These topics apply across all phases. + +### The Collaboration Protocol + +This system is **user-driven collaborative**, not autonomous. + +**Pattern:** Question > Options > Decision > Draft > Approval + +Every agent interaction follows this pattern: +1. Agent asks clarifying questions +2. Agent presents 2-4 options with trade-offs and reasoning +3. You decide +4. Agent drafts based on your decision +5. You review and refine +6. Agent asks "May I write this to [filepath]?" before writing + +See `docs/COLLABORATIVE-DESIGN-PRINCIPLE.md` for the full protocol with +examples. + +### The AskUserQuestion Tool + +Agents use the `AskUserQuestion` tool for structured option presentation. +The pattern is Explain then Capture: full analysis in conversation text first, +then a clean UI picker for the decision. Use it for design choices, +architecture decisions, and strategic questions. Do not use it for open-ended +discovery questions or simple yes/no confirmations. + +### Agent Coordination (3-Tier Hierarchy) ``` -Ask the live-ops-designer agent to design a seasonal content cadence -with battle pass, weekly events, and monthly content drops. Target -retention for the 30-60-90 day cohorts. +Tier 1 (Directors): creative-director, technical-director, producer + | +Tier 2 (Leads): game-designer, lead-programmer, art-director, + audio-director, narrative-director, qa-lead, + release-manager, localization-lead + | +Tier 3 (Specialists): gameplay-programmer, engine-programmer, + ai-programmer, network-programmer, ui-programmer, + tools-programmer, systems-designer, level-designer, + economy-designer, world-builder, writer, + technical-artist, sound-designer, ux-designer, + qa-tester, performance-analyst, devops-engineer, + analytics-engineer, accessibility-specialist, + 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 ``` -The `live-ops-designer` handles: -- Season/event calendar -- Battle pass design -- Content cadence planning -- Retention mechanics -- Live economy tuning -- Engagement analytics +**Coordination rules:** +- Vertical delegation: Directors > Leads > Specialists. Never skip tiers for + complex decisions. +- Horizontal consultation: Agents at the same tier may consult each other but + must not make binding decisions outside their domain. +- Conflict resolution: Design conflicts go to `creative-director`. Technical + conflicts go to `technical-director`. Scope conflicts go to `producer`. +- No unilateral cross-domain changes. -### Step 10.4: Community Management +### Automated Hooks (Safety Net) + +The system has 9 hooks that run automatically: + +| Hook | Trigger | What It Does | +|------|---------|-------------| +| `session-start.sh` | Session start | Shows branch, recent commits, detects active.md for recovery | +| `detect-gaps.sh` | Session start | Detects fresh projects (no engine, no concept) and suggests `/start` | +| `pre-compact.sh` | Before compaction | Dumps session state into conversation for auto-recovery | +| `validate-commit.sh` | Before commit | Checks for design doc references, valid JSON, no hardcoded values | +| `validate-push.sh` | Before push | Warns on pushes to main/develop | +| `validate-assets.sh` | Before commit | Checks asset naming and size | +| `log-agent.sh` | Agent start | Logs agent invocations for audit trail | +| `log-agent-stop.sh` | Agent stop | Completes agent audit trail (start + stop) | +| `session-stop.sh` | Session end | Final session logging | + +### Context Resilience + +**Session state file:** `production/session-state/active.md` is a living +checkpoint. Update it after each significant milestone. After any disruption +(compaction, crash, `/clear`), read this file first. + +**Incremental writing:** When creating multi-section documents, write each +section to file immediately after approval. This means completed sections +survive crashes and context compactions. Previous discussion about written +sections can be safely compacted. + +**Automatic recovery:** The `session-start.sh` hook detects and previews +`active.md` automatically. The `pre-compact.sh` hook dumps state into the +conversation before compaction. + +**Sprint status tracking:** `production/sprint-status.yaml` is the +machine-readable story tracker. Written by `/sprint-plan` (init) and +`/story-done` (status updates). Read by `/sprint-status`, `/help`, and +`/story-done` (next story). Eliminates fragile markdown scanning. + +### Brownfield Adoption + +For existing projects that already have some artifacts: ``` -Ask the community-manager agent to draft patch notes for v1.0.1, -respond to the top 5 community complaints from the feedback channel, -and prepare a "known issues" post. +/adopt ``` +Or targeted: + +``` +/adopt gdds +/adopt adrs +/adopt stories +/adopt infra +``` + +This audits existing artifacts for **format** (not existence), classifies gaps +as BLOCKING/HIGH/MEDIUM/LOW, builds an ordered migration plan, and writes +`docs/adoption-plan-[date].md`. Core principle: MIGRATION not REPLACEMENT -- +it never regenerates existing work, only fills gaps. + +Individual skills also support retrofit mode: + +``` +/design-system retrofit design/gdd/combat-system.md +/architecture-decision retrofit docs/architecture/adr-005.md +``` + +These detect which sections are present vs. missing and fill only the gaps. + +### Gate System + +Phase gates are formal checkpoints. Run `/gate-check` with the transition name: + +``` +/gate-check concept # Concept -> Systems Design +/gate-check systems-design # Systems Design -> Technical Setup +/gate-check technical-setup # Technical Setup -> Pre-Production +/gate-check pre-production # Pre-Production -> Production +/gate-check production # Production -> Polish +/gate-check polish # Polish -> Release +``` + +**Verdicts:** +- **PASS** -- all requirements met, advance to next phase +- **CONCERNS** -- requirements met with acknowledged risks, passable +- **FAIL** -- requirements not met, blocks advancement with specific remediation + +When a gate passes, `production/stage.txt` is updated (only then), which +controls the status line and `/help` behavior. + +### Reverse Documentation + +For code that exists without design docs (common after brownfield adoption): + +``` +/reverse-document src/gameplay/combat/ +``` + +Reads existing code and generates GDD-format design documentation from it. + --- ## Appendix A: Agent Quick-Reference @@ -1692,8 +1314,13 @@ and prepare a "known issues" post. | Audit security | `security-engineer` | 3 | | Communicate with players | `community-manager` | 3 | | Godot-specific help | `godot-specialist` | 3 | +| GDScript-specific help | `godot-gdscript-specialist` | 3 | +| Godot shader help | `godot-shader-specialist` | 3 | | Unity-specific help | `unity-specialist` | 3 | +| Unity C# help | `unity-csharp-specialist` | 3 | | Unreal-specific help | `unreal-specialist` | 3 | +| Unreal Blueprint help | `unreal-blueprint-specialist` | 3 | +| Unreal C++ help | `unreal-cpp-specialist` | 3 | ### Agent Hierarchy @@ -1701,10 +1328,14 @@ and prepare a "known issues" post. creative-director / technical-director / producer | --------------------------------------------------------------- - | | | | | | + | | | | | | | game-designer lead-prog art-dir audio-dir narr-dir qa-lead release-mgr - | | | | | | + | | | | | | | specialists programmers tech-art snd-design writer qa-tester devops + (systems, (gameplay, (sound) (world- (perf, (analytics, + economy, engine, builder) access.) security) + level) ai, net, + ui, tools) ``` **Escalation rule:** If two agents disagree, go up. Design conflicts go to @@ -1715,20 +1346,110 @@ conflicts go to `producer`. ## Appendix B: Slash Command Quick-Reference -### By Workflow Stage +### All 52 Commands by Category -| Stage | Commands | -|-------|----------| -| **Onboarding** | `/start` | -| **Ideation** | `/brainstorm` | -| **Design** | `/map-systems`, `/design-system`, `/design-review`, `/architecture-decision` | -| **Sprint** | `/sprint-plan`, `/estimate`, `/scope-check`, `/retrospective` | -| **Implementation** | `/code-review`, `/prototype`, `/tech-debt` | -| **Testing** | `/balance-check`, `/playtest-report`, `/perf-profile` | -| **Assets** | `/asset-audit`, `/localize` | -| **Release** | `/release-checklist`, `/launch-checklist`, `/changelog`, `/patch-notes`, `/hotfix` | -| **Production** | `/milestone-review`, `/onboard` | -| **Teams** | `/team-combat`, `/team-narrative`, `/team-ui`, `/team-release`, `/team-polish`, `/team-audio`, `/team-level` | +#### Onboarding and Navigation (5) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/start` | Guided onboarding, routes to right workflow | Any (first session) | +| `/help` | Context-aware "what do I do next?" | Any | +| `/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) | + +#### Game Design (6) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/brainstorm` | Collaborative ideation with MDA analysis | 1 | +| `/map-systems` | Decompose concept into systems index | 1-2 | +| `/design-system` | Guided section-by-section GDD authoring | 2 | +| `/quick-design` | Lightweight spec for small changes | 2+ | +| `/review-all-gdds` | Cross-GDD consistency and design theory review | 2 | +| `/propagate-design-change` | Find ADRs/stories affected by GDD changes | 5 | + +#### UX and Interface (2) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/ux-design` | Author UX specs (screen/flow, HUD, patterns) | 3 | +| `/ux-review` | Validate UX specs for accessibility and GDD alignment | 3 | + +#### Architecture (4) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/create-architecture` | Master architecture document | 3 | +| `/architecture-decision` | Create or retrofit an ADR | 3 | +| `/architecture-review` | Validate all ADRs, dependency ordering | 3 | +| `/create-control-manifest` | Flat programmer rules from Accepted ADRs | 3 | + +#### Stories and Sprints (6) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/create-epics-stories` | Break GDDs + ADRs into story files | 4 | +| `/sprint-plan` | Create or manage sprint plans | 4-5 | +| `/sprint-status` | Quick 30-line sprint snapshot | 5 | +| `/story-readiness` | Validate story is implementation-ready | 4-5 | +| `/story-done` | 8-phase story completion review | 5 | +| `/estimate` | Effort estimation with risk assessment | 4-5 | + +#### Reviews and Analysis (10) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/design-review` | Validate GDD against 8-section standard | 1-2 | +| `/code-review` | Architectural code review | 5+ | +| `/balance-check` | Game balance formula analysis | 5-6 | +| `/asset-audit` | Asset naming, format, size verification | 6 | +| `/content-audit` | GDD-specified content vs. implemented | 5 | +| `/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 | + +#### Production Management (5) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/milestone-review` | Milestone progress and go/no-go | 5 | +| `/retrospective` | Sprint retrospective analysis | 5 | +| `/bug-report` | Structured bug report creation | 5+ | +| `/playtest-report` | Structured playtest session report | 4-6 | +| `/onboard` | Onboard a new team member | Any | + +#### Release (5) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/release-checklist` | Pre-release validation | 7 | +| `/launch-checklist` | Full cross-department launch readiness | 7 | +| `/changelog` | Auto-generate internal changelog | 7 | +| `/patch-notes` | Player-facing patch notes | 7 | +| `/hotfix` | Emergency fix workflow | 7+ | + +#### Creative (3) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/prototype` | Throwaway prototype in isolated worktree | 4 | +| `/localize` | String extraction and validation | 6-7 | +| `/onboard` | Onboard new team member | Any | + +#### Team Orchestration (7) + +| Command | Purpose | Phase | +|---------|---------|-------| +| `/team-combat` | Combat feature: design through implementation | 5 | +| `/team-narrative` | Narrative content: structure through dialogue | 5 | +| `/team-ui` | UI feature: UX spec through polished implementation | 5 | +| `/team-level` | Level: layout through dressed encounters | 5 | +| `/team-audio` | Audio: direction through implemented events | 5-6 | +| `/team-polish` | Coordinated polish: perf + art + audio + QA | 6 | +| `/team-release` | Release coordination: build + QA + deployment | 7 | --- @@ -1737,42 +1458,40 @@ conflicts go to `producer`. ### Workflow 1: "I just started and have no game idea" ``` -1. /start (asks where you are, routes you to the right workflow) - — or /brainstorm if you prefer to jump straight to ideation -2. Pick the best concept from the brainstorm output -3. Create a game concept doc (templates/game-concept.md) -4. Define game pillars (templates/game-pillars.md) -5. /design-review on your concept doc -6. /map-systems to decompose concept into systems with dependencies and priorities -7. /design-system to author per-system GDDs (guided, section-by-section) +1. /start (routes you based on where you are) +2. /brainstorm (collaborative ideation, pick a concept) +3. /setup-engine (pin engine and version) +4. /design-review on concept doc (optional, recommended) +5. /map-systems (decompose concept into systems with deps and priorities) +6. /gate-check concept (verify you're ready for Systems Design) +7. /design-system per system (guided GDD authoring) ``` -### Workflow 2: "I have a design and want to start coding" +### Workflow 2: "I have designs and want to start coding" ``` -1. /design-review on each GDD to make sure they're solid -2. /architecture-decision for your first major tech choice -3. /sprint-plan new to plan your first sprint -4. Start implementing with gameplay-programmer / engine-programmer -5. /code-review after each major feature -6. Write tests alongside code -7. Commit frequently (hooks validate automatically) +1. /design-review on each GDD (make sure they're solid) +2. /review-all-gdds (cross-GDD consistency) +3. /gate-check systems-design +4. /create-architecture + /architecture-decision (per major decision) +5. /architecture-review +6. /create-control-manifest +7. /gate-check technical-setup +8. /create-epics-stories (break GDDs into stories) +9. /sprint-plan new +10. /story-readiness -> implement -> /story-done (story lifecycle) ``` -### Workflow 3: "I need to add a complex feature" +### Workflow 3: "I need to add a complex feature mid-production" ``` -1. Create/update the GDD for the feature in design/gdd/ -2. /design-review to validate the design -3. /estimate to understand effort and risk -4. Use the appropriate /team-* skill: - - /team-combat for combat features - - /team-narrative for story content - - /team-ui for UI features - - /team-level for new levels/areas - - /team-audio for audio work -5. /code-review the implementation -6. /balance-check if it affects game balance +1. /design-system or /quick-design (depending on scope) +2. /design-review to validate +3. /propagate-design-change if modifying existing GDDs +4. /estimate for effort and risk +5. /team-combat, /team-narrative, /team-ui, etc. (appropriate team skill) +6. /story-done when complete +7. /balance-check if it affects game balance ``` ### Workflow 4: "Something broke in production" @@ -1786,42 +1505,52 @@ conflicts go to `producer`. 6. Deploy and backport ``` -### Workflow 5: "I'm approaching a milestone" +### Workflow 5: "I have an existing project and want to use this system" ``` -1. /milestone-review to check progress -2. /scope-check to see if scope has crept -3. /tech-debt to assess debt before milestone -4. /perf-profile to check performance targets -5. /team-polish for final polish pass -6. /release-checklist when ready to ship +1. /start (choose Path D -- existing work) +2. /project-stage-detect (determines current phase) +3. /adopt (audits existing artifacts, builds migration plan) +4. /design-system retrofit [path] (fill GDD gaps) +5. /architecture-decision retrofit [path] (fill ADR gaps) +6. /gate-check at appropriate transition ``` ### Workflow 6: "Starting a new sprint" ``` -1. /retrospective to review the last sprint -2. /sprint-plan new to create the next sprint -3. /scope-check to ensure scope is manageable -4. Start working through sprint tasks -5. /sprint-plan status to check progress mid-sprint +1. /retrospective (review last sprint) +2. /sprint-plan new (create next sprint) +3. /scope-check (ensure scope is manageable) +4. /story-readiness per story before pickup +5. Implement stories +6. /story-done per completed story +7. /sprint-status for quick progress checks ``` ### Workflow 7: "Shipping the game" ``` -1. /milestone-review for final milestone -2. /tech-debt to decide what's acceptable at launch -3. /localize for final localization pass -4. Accessibility audit via accessibility-specialist -5. /launch-checklist for full cross-department validation -6. /team-release to coordinate the release -7. /patch-notes and /changelog for player communications +1. /gate-check polish (verify Polish phase is complete) +2. /tech-debt (decide what's acceptable at launch) +3. /localize (final localization pass) +4. /release-checklist v1.0.0 +5. /launch-checklist (full cross-department validation) +6. /team-release (coordinate the release) +7. /patch-notes and /changelog 8. Ship! 9. /hotfix if anything breaks post-launch 10. Post-mortem after launch stabilizes ``` +### Workflow 8: "I'm lost / don't know what to do next" + +``` +1. /help (reads your phase, checks artifacts, tells you what's next) +2. If /help doesn't help: /project-stage-detect (full audit) +3. If stage seems wrong: /gate-check at the transition you think you're at +``` + --- ## Tips for Getting the Most Out of the System @@ -1830,7 +1559,7 @@ conflicts go to `producer`. around the assumption that a design document exists before code is written. Agents reference GDDs constantly. -2. **Use team skills for cross-cutting features.** Don't try to manually +2. **Use team skills for cross-cutting features.** Do not try to manually coordinate 4 agents yourself -- let `/team-combat`, `/team-narrative`, etc. handle the orchestration. @@ -1839,24 +1568,35 @@ conflicts go to `producer`. delta time, accessibility, etc.). 4. **Compact proactively.** At ~65-70% context usage, compact or `/clear`. - The pre-compact hook saves your progress. Don't wait until you're at the + The pre-compact hook saves your progress. Do not wait until you are at the limit. -5. **Use the right tier of agent.** Don't ask `creative-director` to write a - shader. Don't ask `qa-tester` to make design decisions. The hierarchy +5. **Use the right tier of agent.** Do not ask `creative-director` to write a + shader. Do not ask `qa-tester` to make design decisions. The hierarchy exists for a reason. -6. **Run `/design-review` before handing designs to programmers.** This +6. **Run /help when uncertain.** It reads your actual project state and tells + you the single most important next step. + +7. **Run `/design-review` before handing designs to programmers.** This catches incomplete specs early, saving rework. -7. **Run `/code-review` after every major feature.** Catch architectural +8. **Run `/code-review` after every major feature.** Catch architectural issues before they propagate. -8. **Prototype risky mechanics first.** A day of prototyping can save a week - of production on a mechanic that doesn't work. +9. **Prototype risky mechanics first.** A day of prototyping can save a week + of production on a mechanic that does not work. -9. **Keep your sprint plans honest.** Use `/scope-check` regularly. Scope - creep is the #1 killer of indie games. +10. **Keep your sprint plans honest.** Use `/scope-check` regularly. Scope + creep is the number one killer of indie games. -10. **Document decisions with ADRs.** Future-you will thank present-you for +11. **Document decisions with ADRs.** Future-you will thank present-you for recording *why* things were built the way they were. + +12. **Use the story lifecycle religiously.** `/story-readiness` before pickup, + `/story-done` after completion. This catches deviations early and keeps + the pipeline honest. + +13. **Write to files early and often.** Incremental section writing means your + design decisions survive crashes and compactions. The file is the memory, + not the conversation.