# Claude Code Game Studios -- Complete Workflow Guide > **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 > 49-agent system, 74 slash commands, and 12 automated hooks. It assumes you > have Claude Code installed and are working from the project root. > > The pipeline has 7 phases. At `rigor: standard` and `full`, each phase has > a formal gate (`/gate-check`) that must pass before you advance. At > `rigor: minimal` -- the default -- nothing requires a gate; see > [The Default Path](#the-default-path-rigor-minimal). The authoritative > phase sequence is defined in `.claude/docs/workflow-catalog.yaml` and read > by `/help`. --- ## Table of Contents 1. [Quick Start](#quick-start) 2. [The Default Path: Rigor Minimal](#the-default-path-rigor-minimal) 3. [Phase 1: Concept](#phase-1-concept) 4. [Phase 2: Systems Design](#phase-2-systems-design) 5. [Phase 3: Technical Setup](#phase-3-technical-setup) 6. [Phase 4: Pre-Production](#phase-4-pre-production) 7. [Phase 5: Production](#phase-5-production) 8. [Phase 6: Polish](#phase-6-polish) 9. [Phase 7: Release](#phase-7-release) 10. [Cross-Cutting Concerns](#cross-cutting-concerns) 11. [Appendix A: Agent Quick-Reference](#appendix-a-agent-quick-reference) 12. [Appendix B: Slash Command Quick-Reference](#appendix-b-slash-command-quick-reference) 13. [Appendix C: Common Workflows](#appendix-c-common-workflows) --- ## Quick Start ### What You Need Before you start, make sure you have: - **Claude Code** installed and working - **Git** with Git Bash (Windows) or standard terminal (Mac/Linux) - **jq** (optional but recommended -- hooks fall back to `grep` if missing) - **Python 3** (required -- every skill and hook reads `project.yaml` through it; without it every setting silently falls back to its default) ### Step 1: Clone and Open ```bash git clone my-game cd my-game ``` ### Step 2: Run /start If this is your first session: ``` /start ``` This guided onboarding asks where you are and routes you to the right phase: - **Path A** -- No idea yet: routes to `/brainstorm` - **Path B** -- Vague idea: routes to `/brainstorm` with seed - **Path C** -- Clear concept: routes to `/brainstorm` to write it down, or straight to `/setup-engine` - **Path D1** -- Existing project, few artifacts: normal flow - **Path D2** -- Existing project, GDDs/ADRs exist: runs `/project-stage-detect` then `/adopt` for brownfield migration ### Step 3: Verify Hooks Are Working Start a new Claude Code session. You should see output from the `session-start.sh` hook: ``` === Claude Code Game Studios -- Session Context === Branch: main Recent commits: abc1234 Initial commit =================================== ``` 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 4: Ask for Help Anytime At any point, run: ``` /help ``` This reads your current phase from `project.stage` in `project.yaml` (falling back to `production/stage.txt`) -- at `rigor: minimal`, where the stage never moves, it follows the minimal route instead -- 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 (Godot; Unity: Assets/, Unreal: Source//) core/ # Engine/framework code gameplay/ # Gameplay systems ai/ # AI systems networking/ # Multiplayer code ui/ # UI code tools/ # Dev tools assets/ # Game assets art/ # Sprites, models, textures audio/ # Music, SFX vfx/ # Particle effects shaders/ # Shader files data/ # JSON config/balance data design/ # Design documents gdd/ # Game 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 postmortems/ # Post-mortems tests/ # Test suites prototypes/ # Throwaway prototypes production/ # Sprint plans, milestones, releases sprints/ milestones/ releases/ epics/ # Epic and story files (from /create-epics + /create-stories) playtests/ # Playtest reports session-state/ # Ephemeral session state (gitignored) session-logs/ # Session audit trail (gitignored) ``` > **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, > code in `src/ai/` gets AI rules, and so on — and the same for C# and C++ in > Unity and Unreal `Gameplay/` and `AI/` folders. --- ## The Default Path: Rigor Minimal `modes.rigor` defaults to `minimal` (`/start` asks which tier fits; `/settings` changes it any time). At `minimal` the path to code is four steps: 1. `/setup-engine` -- configure the engine 2. `/brainstorm` -- writes the one-page `design/game-brief.md`, which replaces the full concept doc, the systems decomposition and the per-system GDDs 3. `/create-stories` -- turns the brief's MVP list and build order into stories under `production/epics//`. No `/create-epics`, no `/sprint-plan`: the brief's build order is the plan 4. `/dev-story` then `/story-done`, story by story. `/story-done` names the next story, and `/help` knows this route Nothing on this path runs `/gate-check`, so `project.stage` stays at Concept -- that is expected. Every skill still runs at any tier; rigor changes what is required, not what is allowed. The trade: there are no GDDs to catch design problems before they reach code. Raise rigor with `/settings` when the game outgrows a one-page brief -- several systems that affect each other, a design someone else implements, a team, or a firm release date. Existing files stay where they are, and `/help` shows what the new tier requires next. The rest of this guide describes the `standard`/`full` pipeline. --- ## Phase 1: Concept ### What Happens in This Phase 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**. ### Phase 1 Pipeline ``` /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 project.yaml Player motiv. core loop, USP document | v /prototype (concept prototype — 1-3 days) PROCEED ↓ PIVOT → /brainstorm | v (PROCEED) /map-systems | v systems-index.md (all systems, deps, priority tiers) ``` ### Step 1.1: Brainstorm With /brainstorm This is your starting point. Run the brainstorm skill: ``` /brainstorm ``` Or with a genre hint: ``` /brainstorm roguelike deckbuilder ``` **What happens:** The brainstorm skill guides you through a collaborative 6-phase ideation process using professional studio techniques: 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` The concept document includes: - Elevator pitch (one sentence) - Core fantasy (what the player imagines themselves doing) - MDA breakdown - Target audience (Bartle types, demographics) - 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.2: Review the Concept (Optional but Recommended) ``` /design-review design/gdd/game-concept.md ``` Validates structure and completeness before you proceed. ### Step 1.3: Choose Your Engine ``` /setup-engine ``` Or with a specific engine: ``` /setup-engine godot 4.6 ``` **What /setup-engine does:** - Writes engine, language, specialists, naming conventions, and performance budgets to `project.yaml` (the source of truth) and mirrors them to `.claude/docs/technical-preferences.md` (the human-readable legacy fallback) - 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/` **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: ``` /map-systems ``` 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) 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. ### Step 1.5: Art Bible ``` /art-bible ``` Authors `design/art/art-bible.md`, the visual identity every asset follows. Run it once the concept is approved; `/art-bible` suggests doing it before `/map-systems` (Step 1.4). Sections 1–4 are needed before `/gate-check pre-production`, and all 9 before `/gate-check production`. At `standard` it is required only when the game has visual-asset stories; at `minimal` it is optional. ### Phase 1 Gate ``` /gate-check systems-design ``` **Requirements to pass:** - `design/gdd/game-concept.md` with content, the game pillars, and a Visual Identity Anchor section (at `minimal`: `design/game-brief.md` with content) - Recommended: a concept prototype whose REPORT.md says PROCEED This is the `full` list. `standard` and `minimal` drop items; the gate's own file, `.claude/skills/gate-check/references/gate-systems-design.md`, has the full checklist and what each tier drops. **Verdict:** PASS / CONCERNS / NOT ASSESSED / FAIL. PASS advances the stage. On CONCERNS it advances only if you explicitly accept the risks, which are recorded; a FAIL never advances it. NOT ASSESSED means something required could not be checked. --- ## 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 / NOT ASSESSED / 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. You can also design a specific system directly: ``` /design-system combat-system ``` **What /design-system does:** 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) **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 | | 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. | Plus a **Game Feel** section: feel reference, input responsiveness (ms/frames), animation feel targets (startup/active/recovery), impact moments, weight profile. ### Step 2.2: Review Each GDD Before the next system starts, validate the current one: ``` /design-review design/gdd/combat-system.md ``` Checks the sections your `modes.workflow` tier requires (all 8 at `full`, 5 at `standard`) for completeness, formula clarity, edge case resolution, bidirectional dependencies, and testable acceptance criteria. **Verdict:** APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED / NOT ASSESSED. Only APPROVED GDDs should proceed. ### Step 2.3: Small Changes Without Full GDDs For tuning changes, small additions, or tweaks that do not warrant a full GDD: ``` /quick-design "add 10% damage bonus for flanking attacks" ``` 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. ### Step 2.4: Cross-GDD Consistency Review 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: 1. **World-building** -- Use `world-builder` to define factions, history, geography, and rules of your world 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 ### Phase 2 Gate ``` /gate-check technical-setup ``` **Requirements to pass:** - `design/gdd/systems-index.md` listing at least the MVP systems, with their dependencies mapped - A GDD for every MVP system, each passing `/design-review` (no MAJOR REVISION NEEDED) - A cross-GDD review report from `/review-all-gdds` whose verdict is not FAIL — and not NOT ASSESSED, which means the GDDs could not be compared This is the `full` list. `standard` and `minimal` drop items; the gate's own file, `.claude/skills/gate-check/references/gate-technical-setup.md`, has the full checklist and what each tier drops. --- ## 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 (/ux-design accessibility) Interaction pattern library (/ux-design patterns) /test-setup --> test framework + CI workflow ``` ### 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 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) ADRs go through a lifecycle: Proposed > Accepted > Superseded/Deprecated. **Minimum 3 Foundation-layer ADRs are required** before the gate check. **Retrofitting existing ADRs:** If you already have ADRs from a brownfield project: ``` /architecture-decision retrofit docs/architecture/adr-005.md ``` This detects which template sections are missing and adds only those, never overwriting existing content. ### Step 3.3: Architecture Review ``` /architecture-review ``` 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`) ### 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: 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). This document is required in Phase 3 because UX specs (written in Phase 4) reference this tier — it is a design prerequisite, not a UX deliverable. `/ux-design accessibility` authors it; `/ux-design patterns` starts the interaction pattern library (`design/ux/interaction-patterns.md`), which the same gate checks. ### Step 3.6: Test Framework ``` /test-setup ``` Scaffolds the engine's test root, `.github/workflows/tests.yml` and one example test; the Pre-Production gate checks for them. `/test-helpers` can follow once there are systems to test. ### Phase 3 Gate ``` /gate-check pre-production ``` **Requirements to pass:** - The engine configured, `project.yaml` populated (engine, naming, performance) and the engine reference docs present - Art bible Sections 1–4 (`design/art/art-bible.md`) - `docs/architecture/architecture.md`, at least 3 ADRs covering Foundation-layer systems, an `/architecture-review` report and `docs/architecture/requirements-traceability.md` - The test framework in the engine's test root, `.github/workflows/tests.yml` and one example test (`/test-setup`) - `design/accessibility-requirements.md` and `design/ux/interaction-patterns.md` (`/ux-design accessibility`, `/ux-design patterns`) This is the `full` list. `standard` and `minimal` drop items; the gate's own file, `.claude/skills/gate-check/references/gate-pre-production.md`, has the full checklist and what each tier drops. --- ## Phase 4: Pre-Production ### What Happens in This Phase You create UX specs for key screens, prototype risky mechanics, turn design documents into implementable stories, plan your first sprint, and build a Vertical Slice that proves the core loop is fun. ### Phase 4 Pipeline ``` /ux-design --> /vertical-slice --> /create-epics --> /create-stories --> /sprint-plan | | | | | v v v v v UX specs Production-quality Epic files in Story files in First sprint with design/ux/ end-to-end build production/ production/ prioritized stories in prototypes/ epics/*/EPIC.md epics/*/story-*.md production/sprints/ PROCEED/PIVOT/KILL (one per module) (one per behaviour) sprint-*.md | | v v /ux-review /story-readiness (validates specs (validates each story before epics) before pickup) | v /dev-story (implements the story, routes to right agent) ``` ### Step 4.1: UX Specs for Key Screens Before writing epics, create UX specs so that story authors know what screens exist and what player interactions they must support. **UX Specs:** ``` /ux-design main-menu /ux-design core-gameplay-hud ``` Three modes: screen/flow, HUD, and interaction patterns. Output goes to `design/ux/`. Each spec includes: player need, layout zones, states, interaction map, data requirements, events fired, accessibility, localization. Reads your `accessibility-requirements.md` (written in Phase 3) and your input method config from `project.yaml` (the `platform.*` block, falling back to `technical-preferences.md`) to drive accessibility and input coverage checks — no need to re-specify them per screen. > **Tip:** `/design-system` emits a 📌 UX Flag for every system with UI > requirements. Use those flags as a checklist for which screens need specs. **Interaction Pattern Library:** ``` /ux-design patterns ``` Started in Phase 3 (the Pre-Production gate checks it); extend it here as the key screens add patterns. `design/ux/interaction-patterns.md` holds 16 standard controls plus game-specific patterns (inventory slot, ability icon, HUD bar, dialogue box, etc.) with animation and sound standards. **UX Review:** ``` /ux-review all ``` Validates UX specs for GDD alignment and accessibility tier compliance. Produces APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED verdict. ### Step 4.2: Build the Vertical Slice The vertical slice is the production-quality proof that you can build the full game loop end-to-end before committing to full Production. ``` /vertical-slice ``` **What it proves:** Does a player, starting from nothing, experience the core fantasy within a few minutes, without developer guidance? **What it builds:** A near-production-quality playable build covering at least one complete [start → challenge → resolution] cycle. Uses real architecture layers, real naming conventions, no hardcoded values — but not final art or audio. This is not a throwaway like the concept prototype; it demonstrates production pipeline feasibility. **Note on concept prototyping:** If you ran `/prototype` in Phase 1 (Concept), you already validated the core idea is fun. The vertical slice now validates you can build it properly. They answer different questions. If you skipped the concept prototype, now is a reasonable time to run one first before investing in the full slice. **Verdict:** The vertical slice produces a PROCEED / PIVOT / KILL verdict, or NOT ASSESSED while nobody has played it through. - **PROCEED** → move to Step 4.3 (epics and stories) - **PIVOT** → revise affected GDDs with `/design-system [mechanic]`, then re-run `/vertical-slice` - **KILL** → return to `/brainstorm` with what you learned ### Step 4.3: Create Epics and Stories From Design Artifacts ``` /create-epics layer: foundation /create-stories [epic-slug] # repeat for each epic /create-epics layer: core /create-stories [epic-slug] # repeat for each core epic ``` `/create-epics` reads your GDDs, ADRs, and architecture to define epic scope — one epic per architectural module. Then `/create-stories` breaks each epic into implementable story files in `production/epics/[slug]/`. 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 Once stories exist, run `/dev-story [story-path]` to implement one — it routes automatically to the correct programmer agent. ### Step 4.4: Validate Stories Before Pickup ``` /story-readiness production/epics/combat/story-combat-damage-calc.md ``` Checks: Design completeness, Architecture coverage, Scope clarity, Definition of Done. Verdict: READY / NEEDS WORK / BLOCKED / NOT ASSESSED. ### Step 4.5: Effort Estimation ``` /estimate production/epics/combat/story-combat-damage-calc.md ``` Provides effort estimates with risk assessment. ### Step 4.6: Plan Your First Sprint ``` /sprint-plan new ``` **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-001.md` - Populates `production/sprint-status.yaml` (machine-readable story tracking) ### Step 4.7: Vertical Slice (recommended) Before advancing to Production, build and playtest a Vertical Slice: - One complete end-to-end core loop, playable from start to finish - Representative quality (not placeholder everything) - Played unguided in at least 1 documented session (3+ recommended) - Playtest report written (`/playtest-report`) `/gate-check production` treats it as recommended, not blocking: a skipped slice is CONCERNS, a slice nobody has played is NOT ASSESSED, and a built slice that is broken or not fun is a FAIL. At `workflow: minimal` the slice items drop: the gate asks instead whether the current build's core loop is fun and runs end to end. ### Phase 4 Gate ``` /gate-check production ``` **Requirements to pass:** - A first sprint plan in `production/sprints/`, and Foundation and Core epics with their stories under `production/epics/` - The complete art bible (all 9 sections) with its AD-ART-BIBLE sign-off recorded - Every MVP GDD complete, the master architecture document, Foundation and Core ADRs `Accepted`, and the control manifest - UX specs for the key screens (main menu, HUD, pause menu) that passed `/ux-review` - Recommended, not blocking: a Vertical Slice built and played in at least one documented session. Skipped → CONCERNS; built but broken or not fun → FAIL; built but not yet played → NOT ASSESSED This is the `full` list. `standard` and `minimal` drop items; the gate's own file, `.claude/skills/gate-check/references/gate-production.md`, has the full checklist and what each tier drops. --- ## 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 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/epics/combat/story-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 / NOT ASSESSED. **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/epics/combat/story-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-003.md ``` This compares current scope against the original plan and flags scope increase, recommends cuts. ### 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: ``` /retrospective ``` Analyzes planned vs. completed, velocity, blockers, and actionable improvements. Then plan the next sprint: ``` /sprint-plan new ``` ### Step 5.7: Milestone Reviews At milestone checkpoints: ``` /milestone-review "alpha" ``` Produces feature completeness, quality metrics, risk assessment, and go/no-go recommendation. ### Phase 5 Gate ``` /gate-check polish ``` **Requirements to pass:** - Every core GDD mechanic implemented, and the main gameplay path playable end to end - Tests in the engine's test root covering the Logic and Integration stories, and passing - A smoke-check report in `production/qa/` with PASS or PASS WITH WARNINGS - A `/team-qa` sign-off (APPROVED or APPROVED WITH CONDITIONS) - At least 3 documented playtest sessions (new player, mid-game, difficulty curve) and the fun hypothesis validated or revised - No open S1 Critical bugs, and performance within budget This is the `full` list. `standard` and `minimal` drop items; the gate's own file, `.claude/skills/gate-check/references/gate-polish.md`, has the full checklist and what each tier drops. --- ## Phase 6: Polish ### What Happens in This Phase Your game is feature-complete. Now you make it good. This phase focuses on performance, balance, accessibility, audio, visual polish, and playtesting. ### Phase 6 Pipeline ``` /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 /security-audit --> /localize qa --> /release-checklist --> /changelog (per language) + /patch-notes Release readiness: the Polish -> Release gate checks all four. ``` ### Step 6.1: Performance Profiling ``` /perf-profile ``` 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 ### Step 6.2: Balance Analysis ``` /balance-check assets/data/combat_damage.json ``` Analyzes balance data for statistical outliers, broken progression curves, degenerate strategies, and economy imbalances. ### Step 6.3: Asset Audit ``` /asset-audit ``` Verifies naming conventions, file format standards, and size budgets across all assets. ### Step 6.4: Playtesting (Required: 3 Sessions) ``` /playtest-report ``` Generates structured playtest reports. Three sessions are required, covering: - New player experience - Mid-game systems - Difficulty curve ### Step 6.5: Technical Debt Assessment ``` /tech-debt ``` Scans for TODO/FIXME/HACK comments, code duplication, overly complex functions, missing tests, and outdated dependencies. Each item categorized and prioritized. ### Step 6.6: Coordinated Polish Pass ``` /team-polish "combat system" ``` Coordinates 4 specialists in parallel: 1. Performance optimization (performance-analyst lists the optimisations; a programmer in the active set implements them — at `team.size: individual`, where none is active, the list is handed to `/dev-story`) 2. Visual polish (technical-artist) 3. Audio polish (sound-designer) 4. Feel/juice (gameplay-programmer + technical-artist) You set priorities; the team executes with your approval at each step. ### Step 6.7: Localization and Accessibility ``` /localize scan ``` Scans for hardcoded strings, concatenation that breaks translation, text that does not account for expansion, and missing locale files. Accessibility is audited against the tier committed in Phase 3's accessibility requirements document. ### Step 6.8: Security Audit ``` /security-audit ``` Required for the release gate at `standard` and `full`: the newest report must have no open CRITICAL or HIGH finding. A report whose recommendation is NOT ASSESSED leaves the gate's security item NOT ASSESSED. ### Step 6.9: Localization QA ``` /localize qa ``` Run it for every language you ship. At `full` the release gate needs a PASS (or PASS WITH CONDITIONS) for each; a locale nobody has checked is NOT ASSESSED. ### Step 6.10: Release Checklist ``` /release-checklist all ``` The argument is the platform scope (`pc`, `console`, `mobile` or `all`), not a version. 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 verification ### Step 6.11: Changelog and Patch Notes ``` /patch-notes v1.0.0 ``` Generates player-friendly patch notes from git history and sprint data. Translates developer language into player language. ``` /changelog v1.0.0 ``` Generates an internal changelog (more technical, for the team). The release gate needs the changelog or the patch notes drafted, so write them now; `/team-release` publishes them once the release is a GO. ### Phase 6 Gate ``` /gate-check release ``` **Requirements to pass:** - Every milestone feature implemented and the content complete - A QA test plan and a QA sign-off, and every Must Have story's test evidence (UI: retained screenshots; Visual/Feel: screenshots plus lead sign-off) - Smoke check PASS on the release candidate, and the test suite passing - `/balance-check` run, the release checklist completed, and the changelog or patch notes drafted - No open S1–S3 bugs, the newest `/security-audit` with no open CRITICAL or HIGH finding, and a `/localize qa` pass for every locale you ship This is the `full` list. `standard` and `minimal` drop items; the gate's own file, `.claude/skills/gate-check/references/gate-release.md`, has the full checklist and what each tier drops. --- ## Phase 7: Release ### What Happens in This Phase Your game is polished, tested, and ready. Now you ship it. ### Phase 7 Pipeline ``` /launch-checklist --> /team-release | | v v Full cross-department Coordinate: validation (Go/No-Go build, QA sign-off, per department) deployment, launch The release checklist, security audit and patch notes are done in Polish, before /gate-check release. Also: /hotfix, /day-one-patch ``` ### Step 7.1: Launch Readiness (Full Validation) ``` /launch-checklist ``` Complete cross-department validation: | Department | What Is Checked | |-----------|---------------| | **Engineering** | Build stability, crash rates, memory leaks, load times | | **Design** | Feature completeness, tutorial flow, difficulty curve | | **Art** | Asset quality, missing textures, LOD levels | | **Audio** | Missing sounds, mixing levels, spatial audio | | **QA** | Open bug count by severity, regression suite pass rate | | **Narrative** | Dialogue completeness, lore consistency, typos | | **Localization** | All strings translated, no truncation, locale testing | | **Accessibility** | Compliance checklist, assistive feature testing | | **Store** | Metadata complete, screenshots approved, pricing set | | **Marketing** | Press kit ready, launch trailer, social media scheduled | | **Community** | Patch notes draft, FAQ prepared, support channels ready | | **Infrastructure** | Servers scaled, CDN configured, monitoring active | | **Legal** | EULA finalized, privacy policy, COPPA/GDPR compliance | What no file can settle — the EULA, pricing, the on-call schedule — is asked once per section: yes, no, not yet or N/A. A "no" or "not yet" is a failed item. The overall status is READY, CONDITIONAL (only items with a workaround or an accepted risk remain), NOT ASSESSED (something is still unconfirmed) or NOT READY (a blocking item failed). ### Step 7.2: Coordinate the Release ``` /team-release ``` 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 ### Step 7.3: Ship The `validate-push` hook will warn you when pushing to `main` or a `release/*` branch. This is intentional -- release pushes should be deliberate: ```bash git tag v1.0.0 git push origin main --tags ``` ### Step 7.4: Post-Launch **Hotfix workflow** for critical production bugs: ``` /hotfix "Players losing save data when inventory exceeds 99 items" ``` Bypasses normal sprint processes with a full audit trail: 1. Creates a hotfix branch 2. Implements the fix 3. Ensures the fix is backported to `main` (the trunk) 4. Documents the incident **Post-mortem** after launch stabilizes: ``` Ask Claude to create a post-mortem using the template at .claude/docs/templates/post-mortem.md ``` --- ## Cross-Cutting Concerns These topics apply across all phases. ### Director Review Modes Director gates are specialist agents that review your work at key workflow steps. **By default none run.** `modes.review_mode` follows `modes.rigor`, and the default rigor, `rigor: minimal`, gives `solo`. | Mode | What runs | The default under | Best for | |------|-----------|-------------------|----------| | `full` | All director gates at every step | `rigor: full` | Studio-scale projects, learning the system | | `lean` | Directors only at phase transitions (`/gate-check`) | `rigor: standard` | Experienced devs | | `solo` | No director reviews | `rigor: minimal` | Solo projects, game jams, prototypes | **Change it** with `/settings modes.review_mode=lean` (written to `project.yaml`; an explicit value wins over rigor), or `/settings --local modes.review_mode=full` for your machine only. `/start` does not set it. **Override for a single run** without changing your setting: ``` /brainstorm space horror --review full /architecture-decision --review solo ``` The `--review` flag works on all gate-using skills. The first of these that is set wins: the flag, `project.local.yaml`, `project.yaml`, a legacy `production/review-mode.txt`, then the rigor default. A `review-mode.txt` left from an older version still overrides rigor — delete it if the mode surprises you. Full gate definitions and check pattern: `.claude/docs/director-gates.md` --- ### 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) ``` 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, godot-csharp-specialist, godot-gdextension-specialist, unity-specialist, unity-dots-specialist, unity-shader-specialist, unity-addressables-specialist, unity-ui-specialist, unreal-specialist, ue-blueprint-specialist, ue-gas-specialist, ue-replication-specialist, ue-umg-specialist ``` **Coordination rules:** - 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. ### Automated Hooks (Safety Net) The system has 12 hooks that run automatically: | Hook | Trigger | What It Does | |------|---------|-------------| | `session-start.sh` | Session start | Shows branch, recent commits, detects active.md for recovery | | `detect-gaps.sh` | Session start | Detects fresh projects (no engine, no concept) and suggests `/start` | | `pre-compact.sh` | Before compaction | Logs the compaction (its output does not reach Claude) | | `post-compact.sh` | After compaction | Debug-log reminder only (its output does not reach Claude) | | `notify.sh` | Notification event | Shows Windows toast notification via PowerShell | | `validate-commit.sh` | Before commit | Checks design doc sections, valid JSON, hardcoded values, TODO format | | `validate-push.sh` | Before push | Warns on pushes to main, master or release/* | | `validate-assets.sh` | After a file write | Checks data-file JSON, and asset naming in Godot's `assets/` | | `validate-skill-change.sh` | Skill file written | Advises running `/skill-test` after `.claude/skills/` changes | | `log-agent.sh` | Agent start | Logs agent invocations for audit trail | | `log-agent-stop.sh` | Agent stop | Completes agent audit trail (start + stop) | | `session-stop.sh` | **Every response ends** | Session logging and the subagent spawn tally. Despite the name it fires once per response, not once per session. | ### 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, and runs again after every compaction, so the checkpoint comes back when the conversation is summarised. **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: ``` /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 phase you are entering: ``` /gate-check systems-design # Concept -> Systems Design /gate-check technical-setup # Systems Design -> Technical Setup /gate-check pre-production # Technical Setup -> Pre-Production /gate-check production # Pre-Production -> Production /gate-check polish # Production -> Polish /gate-check release # Polish -> Release ``` **Verdicts:** - **PASS** -- all requirements met, advance to next phase - **CONCERNS** -- risks found; the stage advances only if you explicitly accept them, and the accepted risks are recorded - **NOT ASSESSED** -- something required could not be checked; the report names it, so supply it and re-run - **FAIL** -- requirements not met, blocks advancement with specific remediation When a gate passes — or you accept a CONCERNS verdict's risks — `project.stage` in `project.yaml` is updated (only then; a FAIL never advances it) — mirrored to `production/stage.txt`. At `standard` and `full` the stage drives the status line and `/help`; at `minimal` they follow the brief and stories instead. ### Reverse Documentation For code that exists without design docs (common after brownfield adoption): ``` /reverse-document design src/gameplay/combat/ ``` Reads existing code and generates GDD-format design documentation from it. --- ## Appendix A: Agent Quick-Reference ### "I need to do X -- which agent do I use?" | I need to... | Agent | Tier | |-------------|-------|------| | Come up with a game idea | `/brainstorm` skill | -- | | Design a game mechanic | `game-designer` | 2 | | Design specific formulas/numbers | `systems-designer` | 3 | | Design a game level | `level-designer` | 3 | | Design loot tables / economy | `economy-designer` | 3 | | Build world lore | `world-builder` | 3 | | Write dialogue | `writer` | 3 | | Plan the story | `narrative-director` | 2 | | Plan a sprint | `producer` | 1 | | Make a creative decision | `creative-director` | 1 | | Make a technical decision | `technical-director` | 1 | | Implement gameplay code | `gameplay-programmer` | 3 | | Implement core engine systems | `engine-programmer` | 3 | | Implement AI behavior | `ai-programmer` | 3 | | Implement multiplayer | `network-programmer` | 3 | | Implement UI | `ui-programmer` | 3 | | Build dev tools | `tools-programmer` | 3 | | Review code architecture | `lead-programmer` | 2 | | Create shaders / VFX | `technical-artist` | 3 | | Define visual style | `art-director` | 2 | | Define audio style | `audio-director` | 2 | | Design sound effects | `sound-designer` | 3 | | Design UX flows | `ux-designer` | 3 | | Write test cases | `qa-tester` | 3 | | Plan test strategy | `qa-lead` | 2 | | Profile performance | `performance-analyst` | 3 | | Set up CI/CD | `devops-engineer` | 3 | | Design analytics | `analytics-engineer` | 3 | | Check accessibility | `accessibility-specialist` | 3 | | Plan live operations | `live-ops-designer` | 3 | | Manage a release | `release-manager` | 2 | | Manage localization | `localization-lead` | 2 | | Prototype quickly | `prototyper` | 3 | | 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 | | GDExtension modules | `godot-gdextension-specialist` | 3 | | Unity-specific help | `unity-specialist` | 3 | | Unity DOTS/ECS | `unity-dots-specialist` | 3 | | Unity shaders/VFX | `unity-shader-specialist` | 3 | | Unity Addressables | `unity-addressables-specialist` | 3 | | Unity UI Toolkit | `unity-ui-specialist` | 3 | | Unreal-specific help | `unreal-specialist` | 3 | | Unreal GAS | `ue-gas-specialist` | 3 | | Unreal Blueprints | `ue-blueprint-specialist` | 3 | | Unreal replication | `ue-replication-specialist` | 3 | | Unreal UMG/CommonUI | `ue-umg-specialist` | 3 | ### Agent Hierarchy ``` 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 `creative-director`. Technical conflicts go to `technical-director`. Scope conflicts go to `producer`. --- ## Appendix B: Slash Command Quick-Reference ### All 74 Commands by Category #### Onboarding and Navigation (7) | 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) | | `/settings` | View or change project config (rigor, review mode, ...) | Any | | `/skill-improve` | Improve a skill via test-fix-retest loop | Any | #### 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-4 | | `/ux-review` | Validate UX specs for accessibility and GDD alignment | 4 | #### 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 (8) | Command | Purpose | Phase | |---------|---------|-------| | `/create-epics` | Translate GDDs + ADRs into epics (one per module) | 4 | | `/create-stories` | Break a single epic into story files | 4 | | `/dev-story` | Implement a story — routes to the correct programmer agent | 5 | | `/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 (13) | 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 | | `/asset-spec` | Per-asset visual specs and AI generation prompts | 5-6 | | `/content-audit` | GDD-specified content vs. implemented | 5 | | `/consistency-check` | Cross-GDD entity and formula inconsistency scan | 2+ | | `/scope-check` | Scope creep detection | 5 | | `/perf-profile` | Performance profiling workflow | 6 | | `/tech-debt` | Tech debt scanning and prioritization | 6 | | `/gate-check` | Formal phase gate with PASS/CONCERNS/NOT ASSESSED/FAIL | All transitions | | `/reverse-document` | Generate design docs from existing code | Any | | `/security-audit` | Security vulnerability audit (save, network, input) | 6 | #### QA and Testing (9) | Command | Purpose | Phase | |---------|---------|-------| | `/qa-plan` | Generate QA test plan for a sprint or feature | 5 | | `/smoke-check` | Critical path smoke test gate before QA hand-off | 5-6 | | `/soak-test` | Soak test protocol for extended play sessions | 6 | | `/regression-suite` | Map test coverage, identify fixed bugs lacking regression tests | 5-6 | | `/test-setup` | Scaffold test framework and CI/CD pipeline | 3 | | `/test-helpers` | Generate engine-specific test helper libraries | 3-5 | | `/test-evidence-review` | Quality review of test files and manual evidence | 5 | | `/test-flakiness` | Detect non-deterministic tests from CI logs | 5-6 | | `/skill-test` | Validate skill files for structural and behavioral correctness | Any | #### Production Management (6) | Command | Purpose | Phase | |---------|---------|-------| | `/milestone-review` | Milestone progress and go/no-go | 5 | | `/retrospective` | Sprint retrospective analysis | 5 | | `/bug-report` | Structured bug report creation | 5+ | | `/bug-triage` | Re-evaluate open bugs for priority, severity, and owner | 5+ | | `/playtest-report` | Structured playtest session report | 4-6 | | `/onboard` | Onboard a new team member | Any | #### Release (6) | Command | Purpose | Phase | |---------|---------|-------| | `/release-checklist` | Pre-release validation | 6 | | `/launch-checklist` | Full cross-department launch readiness | 7 | | `/changelog` | Auto-generate internal changelog | 6 | | `/patch-notes` | Player-facing patch notes | 6 | | `/hotfix` | Emergency fix workflow | 7+ | | `/day-one-patch` | Scoped patch for issues found after gold master | 7+ | #### Creative (4) | Command | Purpose | Phase | |---------|---------|-------| | `/prototype` | Concept prototype — validate core idea before GDDs | 1 | | `/art-bible` | Guided Art Bible authoring — visual identity spec | 1-4 | | `/vertical-slice` | Production-quality end-to-end build before Production | 4 | | `/localize` | String extraction and validation | 6-7 | #### Team Orchestration (9) | 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 | | `/team-live-ops` | Live-ops planning: seasonal events, battle pass, retention | 7+ | | `/team-qa` | Full QA cycle: strategy, execution, coverage, sign-off | 6-7 | --- ## Appendix C: Common Workflows ### Workflow 1: "I just started and have no game idea" ``` 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 systems-design (verify you're ready for Systems Design) 7. /design-system per system (guided GDD authoring) ``` ### Workflow 2: "I have designs and want to start coding" ``` 1. /design-review on each GDD (make sure they're solid) 2. /review-all-gdds (cross-GDD consistency) 3. /gate-check technical-setup 4. /create-architecture + /architecture-decision (per major decision) 5. /architecture-review 6. /create-control-manifest 7. /art-bible (sections 1–4 now) + /test-setup + /ux-design accessibility + /ux-design patterns 8. /gate-check pre-production 9. /ux-design per key screen + /ux-review 10. /vertical-slice (recommended before committing to epics) 11. /create-epics layer: foundation + /create-stories [slug] (define epics, break into stories) 12. /sprint-plan new 13. /gate-check production 14. /story-readiness -> implement -> /story-done (story lifecycle) ``` ### Workflow 3: "I need to add a complex feature mid-production" ``` 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" ``` 1. /hotfix "description of the issue" 2. Fix is implemented on hotfix branch 3. /code-review the fix 4. Run tests 5. /release-checklist for hotfix build 6. Deploy and backport ``` ### Workflow 5: "I have an existing project and want to use this system" ``` 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 (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. /tech-debt (decide what's acceptable at launch) 2. /security-audit (the release gate reads the newest report) 3. /localize qa for every language you ship 4. /release-checklist all 5. /changelog and /patch-notes (drafts; /team-release finalizes them) 6. /gate-check release (verify Polish is complete and the game is ready to release) 7. /launch-checklist (full cross-department validation) 8. /team-release (coordinate the release) 9. Ship! 10. /hotfix if anything breaks post-launch 11. 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 1. **Always start with design, then implement.** The agent system is built around the assumption that a design document exists before code is written. Agents reference GDDs constantly. 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. 3. **Trust the rules system.** When a rule flags something in your code, fix it. The rules encode hard-won game development wisdom (data-driven values, delta time, accessibility, etc.). 4. **Compact proactively.** At ~65-70% context usage, compact or `/clear`. Your checkpoint in `active.md` survives it, and `session-start.sh` shows it again afterwards. Do not wait until you are at the limit. 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 /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. 8. **Run `/code-review` after every major feature.** Catch architectural issues before they propagate. 9. **Prototype risky mechanics first.** A day of prototyping can save a week of production on a mechanic that does not work. 10. **Keep your sprint plans honest.** Use `/scope-check` regularly. Scope creep is the number one killer of indie games. 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.