Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Shell ai-agentsai-assisted-developmentanthropicclaudeclaude-codegame-designgame-developmentgamedevgodotindie-game-devunityunreal-engine
Examples: add 5 session transcripts + skill flow diagrams covering v0.4.0 skills
Donchitosb1fad395cda6
diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.mdindex a95e6e6b..f36cb69a 100644--- a/.claude/docs/quick-start.md+++ b/.claude/docs/quick-start.md@@ -76,31 +76,50 @@ Ask yourself: "What department would handle this in a real studio?"| Command | What it does ||---------|-------------|| `/start` | First-time onboarding — asks where you are, guides you to the right workflow |+| `/help` | Context-aware "what do I do next?" — reads your current phase and artifacts |+| `/project-stage-detect` | Analyze project state, detect stage, identify gaps |+| `/setup-engine` | Configure engine + version, populate reference docs |+| `/adopt` | Brownfield audit and migration plan for existing projects |+| `/brainstorm` | Guided game concept ideation from scratch |+| `/map-systems` | Decompose concept into systems, map dependencies, guide per-system GDDs |+| `/design-system` | Guided, section-by-section GDD authoring for a single game system |+| `/quick-design` | Lightweight spec for small changes — tuning, tweaks, minor additions |+| `/review-all-gdds` | Cross-GDD consistency and game design theory review |+| `/propagate-design-change` | Find ADRs and stories affected by a GDD change |+| `/ux-design` | Author UX specs (screen/flow, HUD, interaction patterns) |+| `/ux-review` | Validate UX specs for accessibility and GDD alignment |+| `/create-architecture` | Master architecture document for the game |+| `/architecture-decision` | Creates an ADR |+| `/architecture-review` | Validate all ADRs, dependency ordering, GDD traceability |+| `/create-control-manifest` | Flat programmer rules sheet from Accepted ADRs |+| `/create-epics-stories` | Break GDDs + ADRs into implementable story files |+| `/sprint-plan` | Creates or updates sprint plans |+| `/sprint-status` | Quick 30-line sprint snapshot |+| `/story-readiness` | Validate a story is implementation-ready before pickup |+| `/story-done` | End-of-story completion review — verifies acceptance criteria |+| `/estimate` | Produces structured effort estimates || `/design-review` | Reviews a design document || `/code-review` | Reviews code for quality and architecture |-| `/playtest-report` | Creates or analyzes playtest feedback || `/balance-check` | Analyzes game balance data |-| `/sprint-plan` | Creates or updates sprint plans |-| `/architecture-decision` | Creates an ADR || `/asset-audit` | Audits assets for compliance |+| `/content-audit` | GDD-specified content vs. implemented — find gaps |+| `/scope-check` | Detect scope creep against plan |+| `/perf-profile` | Performance profiling and bottleneck ID |+| `/tech-debt` | Scan, track, and prioritize tech debt |+| `/gate-check` | Validate phase readiness (PASS/CONCERNS/FAIL) |+| `/reverse-document` | Generate design/architecture docs from existing code || `/milestone-review` | Reviews milestone progress |+| `/retrospective` | Runs sprint/milestone retrospective |+| `/bug-report` | Structured bug report creation |+| `/playtest-report` | Creates or analyzes playtest feedback || `/onboard` | Generates onboarding docs for a role |-| `/prototype` | Scaffolds a throwaway prototype || `/release-checklist` | Validates pre-release checklist |+| `/launch-checklist` | Complete launch readiness validation || `/changelog` | Generates changelog from git history |-| `/retrospective` | Runs sprint/milestone retrospective |-| `/estimate` | Produces structured effort estimates |+| `/patch-notes` | Generate player-facing patch notes || `/hotfix` | Emergency fix with audit trail |-| `/tech-debt` | Scan, track, and prioritize tech debt |-| `/scope-check` | Detect scope creep against plan |+| `/prototype` | Scaffolds a throwaway prototype || `/localize` | Localization scan, extract, validate |-| `/perf-profile` | Performance profiling and bottleneck ID |-| `/gate-check` | Validate phase readiness (PASS/CONCERNS/FAIL) |-| `/project-stage-detect` | Analyze project state, detect stage, identify gaps |-| `/reverse-document` | Generate design/architecture docs from existing code |-| `/setup-engine` | Configure engine + version, populate reference docs |-| `/map-systems` | Decompose concept into systems, map dependencies, guide per-system GDDs |-| `/design-system` | Guided, section-by-section GDD authoring for a single game system || `/team-combat` | Orchestrate full combat team pipeline || `/team-narrative` | Orchestrate full narrative team pipeline || `/team-ui` | Orchestrate full UI team pipeline |@@ -108,9 +127,6 @@ Ask yourself: "What department would handle this in a real studio?"| `/team-polish` | Orchestrate full polish team pipeline || `/team-audio` | Orchestrate full audio team pipeline || `/team-level` | Orchestrate full level creation pipeline |-| `/launch-checklist` | Complete launch readiness validation |-| `/patch-notes` | Generate player-facing patch notes |-| `/brainstorm` | Guided game concept ideation from scratch |### 4. Use Templates for New Documents@@ -118,6 +134,7 @@ Templates are in `.claude/docs/templates/`:- `game-design-document.md` -- for new mechanics and systems- `architecture-decision-record.md` -- for technical decisions+- `architecture-traceability.md` -- maps GDD requirements to ADRs to story IDs- `risk-register-entry.md` -- for new risks- `narrative-character-sheet.md` -- for new characters- `test-plan.md` -- for feature test plans@@ -142,6 +159,18 @@ Templates are in `.claude/docs/templates/`:- `design-doc-from-implementation.md` -- for reverse-documenting existing code into GDDs- `architecture-doc-from-code.md` -- for reverse-documenting code into architecture docs- `concept-doc-from-prototype.md` -- for reverse-documenting prototypes into concept docs+- `ux-spec.md` -- for per-screen UX specifications (layout zones, states, events)+- `hud-design.md` -- for whole-game HUD philosophy, zones, and element specs+- `accessibility-requirements.md` -- for project-wide accessibility tier and feature matrix+- `interaction-pattern-library.md` -- for standard UI controls and game-specific patterns+- `player-journey.md` -- for 6-phase emotional arc and retention hooks by time scale+- `difficulty-curve.md` -- for difficulty axes, onboarding ramp, and cross-system interactions++Also in `.claude/docs/templates/collaborative-protocols/` (used by agents, not typically edited directly):++- `design-agent-protocol.md` -- question-options-draft-approval cycle for design agents+- `implementation-agent-protocol.md` -- story pickup through /story-done cycle for programming agents+- `leadership-agent-protocol.md` -- cross-department delegation and escalation for director-tier agents### 5. Follow the Coordination Rules@@ -208,9 +237,12 @@ If you have design docs, prototypes, or code already:1. **Run `/start`** (or `/project-stage-detect`) — analyzes what exists,identifies gaps, and recommends next steps-2. **Configure engine if needed** — Run `/setup-engine` if not yet configured-3. **Validate phase readiness** — Run `/gate-check` to see where you stand-4. **Plan the next sprint** — Run `/sprint-plan new`+2. **Run `/adopt`** if you have existing GDDs, ADRs, or stories — audits+ internal format compliance and builds a numbered migration plan to fill gaps+ without overwriting your existing work+3. **Configure engine if needed** — Run `/setup-engine` if not yet configured+4. **Validate phase readiness** — Run `/gate-check` to see where you stand+5. **Plan the next sprint** — Run `/sprint-plan new`## File Structure Referencediff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.mdindex 38d1a9f5..48cad81b 100644--- a/docs/WORKFLOW-GUIDE.md+++ b/docs/WORKFLOW-GUIDE.md@@ -1316,11 +1316,17 @@ Reads existing code and generates GDD-format design documentation from it.| 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 C# help | `unity-csharp-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 Blueprint help | `unreal-blueprint-specialist` | 3 |-| Unreal C++ help | `unreal-cpp-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@@ -1431,13 +1437,12 @@ conflicts go to `producer`.| `/patch-notes` | Player-facing patch notes | 7 || `/hotfix` | Emergency fix workflow | 7+ |-#### Creative (3)+#### Creative (2)| 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)diff --git a/docs/examples/README.md b/docs/examples/README.mdindex 5c31e04c..1a0f6371 100644--- a/docs/examples/README.md+++ b/docs/examples/README.md@@ -4,8 +4,149 @@ This directory contains realistic, end-to-end session transcripts showing how th---+## Visual Reference++**New to the system? Start here:**+[Skill Flow Diagrams](skill-flow-diagrams.md) — visual maps of all 7 phases and how skills chain together.++---+## 📚 **Available Examples**+### CORE WORKFLOW++### [Skill Flow Diagrams](skill-flow-diagrams.md)+**Type:** Visual Reference+**Complexity:** All levels++Full pipeline overview (zero to ship), plus detailed chain diagrams for:+design-system, story lifecycle, UX pipeline, and brownfield onboarding.+**Start here if you want to understand how the pieces fit together.**++---++### [Session: Authoring a GDD with /design-system](session-design-system-skill.md)+**Type:** Design (skill-driven)+**Skill:** `/design-system`+**Duration:** ~60 minutes (14 turns)+**Complexity:** Medium++**Scenario:**+Dev runs `/design-system movement` after `/map-systems` produced the systems index. The skill loads context from the game concept and dependency GDDs, runs a technical feasibility pre-check, then guides through all 8 GDD sections one at a time — drafting, approving, and writing each section to disk before moving to the next.++**Key Moments:**+- Technical feasibility pre-check flags Jolt physics default change (Godot 4.6)+- Incremental writing: each section on disk immediately after approval+- Session crash during section 5 → agent resumes from first empty section+- Dependency signals (stamina, inventory) surfaced during the Dependencies section+- Ends with explicit handoff: "run `/design-review` before the next system"++**Learn:**+- How `/design-system` is different from asking an agent to "write a GDD"+- How the section-by-section cycle prevents 30k-token context bloat+- How incremental file writing survives session crashes+- How the skill surfaces downstream dependency contracts++---++### [Session: Full Story Lifecycle](session-story-lifecycle.md)+**Type:** Full Workflow+**Skills:** `/story-readiness` → implementation → `/story-done`+**Duration:** ~50 minutes (13 turns)+**Complexity:** Medium++**Scenario:**+Dev picks up a story from the sprint backlog. `/story-readiness` catches a roll-direction ambiguity before any code is written. After implementation, `/story-done` verifies 9 acceptance criteria, identifies 2 deferred criteria (inventory not integrated yet), and closes the story with notes.++**Key Moments:**+- `/story-readiness` catches spec ambiguity in Turn 2 — resolved before implementation starts+- ADR status check: story would be BLOCKED if ADR was still Proposed+- Manifest version check: confirms story's guidance hasn't drifted from current architecture+- Deferred criteria tracked (not lost) when integration not yet possible+- `sprint-status.yaml` updated at story close, next ready story surfaced automatically++**Learn:**+- Why `/story-readiness` prevents late-implementation ambiguity+- How deferred criteria work (COMPLETE WITH NOTES vs. BLOCKED)+- How TR-ID references prevent false deviation flags+- The full loop from backlog → implemented → closed++---++### [Session: Gate Check and Phase Transition](session-gate-check-phase-transition.md)+**Type:** Phase Gate+**Skill:** `/gate-check`+**Duration:** ~20 minutes (7 turns)+**Complexity:** Low++**Scenario:**+Dev completes the Systems Design phase and runs `/gate-check` to advance. The gate finds all 6 MVP GDDs complete, cross-review passed with one low-severity concern. Gate passes, `stage.txt` updated, and the agent provides a specific ordered checklist for Technical Setup.++**Key Moments:**+- Gate validates artifact presence AND internal completeness (8 sections per GDD)+- CONCERNS ≠ FAIL: low-severity cross-review note passes the gate+- stage.txt update changes what `/help`, `/sprint-status`, and all skills see going forward+- Agent surfaces the cross-review concern as a concrete ADR to write next+- Next phase checklist is specific and ordered, not generic++**Learn:**+- What a gate check actually validates (not just "do files exist?")+- How PASS/CONCERNS/FAIL verdicts work+- Why stage.txt is the authority for phase tracking+- What changes after a phase transition++---++### [Session: UX Pipeline — /ux-design → /ux-review → /team-ui](session-ux-pipeline.md)+**Type:** UX Design Pipeline+**Skills:** `/ux-design`, `/ux-review`, `/team-ui`+**Duration:** ~90 minutes (16 turns)+**Complexity:** Medium-High++**Scenario:**+Dev designs the HUD and inventory screen. `/ux-design` reads the player journey and GDDs to ground decisions in player emotional state. `/ux-review` catches a blocking accessibility gap (no keyboard alternative to drag-drop) and an advisory colorblind issue. After fixes, `/team-ui` accepts the handoff.++**Key Moments:**+- HUD philosophy choice (diegetic vs. persistent vs. tactical) grounded in survival genre conventions+- `/ux-review` distinguishes BLOCKING (stops handoff) vs. ADVISORY (can fix in visual pass)+- Accessibility caught before implementation, not during QA+- Keyboard alternative added in one turn; review re-runs and passes+- `/team-ui` checks for a passing `/ux-review` before starting visual design++**Learn:**+- How `/ux-design` uses player journey context to ground UI decisions+- What `/ux-review` actually checks (not just "does a spec exist?")+- The difference between HUD doc (`design/ux/hud.md`) and per-screen specs+- How accessibility issues are handled at design time vs. implementation time++---++### [Session: Brownfield Onboarding with /adopt](session-adopt-brownfield.md)+**Type:** Brownfield Adoption+**Skill:** `/adopt`+**Duration:** ~30 minutes (8 turns)+**Complexity:** Low-Medium++**Scenario:**+Dev has 3 months of existing code and rough design notes but nothing in the right format. `/adopt` audits format compliance (not just file existence), classifies 4 gaps by severity, builds an ordered 7-step migration plan, and immediately fixes the BLOCKING gap (missing systems index) by inferring it from the codebase.++**Key Moments:**+- FORMAT audit distinguishes "file exists" from "file has required internal structure"+- BLOCKING gap identified: missing systems index prevents 4+ skills from running+- Migration plan is ordered: blocking gaps first, then high, then medium+- Systems index bootstrapped from code structure — brownfield code contains the answer+- Retrofit mode vs. new authoring: `/design-system retrofit` fills gaps without overwriting++**Learn:**+- The difference between `/adopt` and `/project-stage-detect`+- How format compliance is checked (section detection, not just file presence)+- How brownfield projects can onboard without losing existing work+- When to use retrofit mode vs. full authoring++---++### FOUNDATIONAL EXAMPLES+### [Session: Designing the Crafting System](session-design-crafting-system.md)**Type:** Design**Agent:** game-designer@@ -83,6 +224,17 @@ Solo dev faces crisis: Alpha milestone in 2 weeks, crafting system needs 3 weeks---+### [Reverse Documentation Workflow](reverse-document-workflow-example.md)+**Type:** Brownfield Documentation+**Agent:** game-designer+**Duration:** ~20 minutes+**Complexity:** Low++**Scenario:**+Developer built a skill tree system but never wrote a design doc. Agent reads the code, infers the design intent, asks clarifying questions about ambiguous decisions, and produces a retroactive GDD.++---+## 🎯 **What These Examples Demonstrate**All examples follow the **collaborative workflow pattern:**@@ -135,7 +287,13 @@ Read these examples BEFORE your first session. They show realistic expectations- Agents provide expert guidance and options### For Understanding Specific Workflows:-- **Designing a system?** → Read session-design-crafting-system.md+- **New to the system?** → Read skill-flow-diagrams.md first+- **Running /design-system for the first time?** → Read session-design-system-skill.md+- **Picking up a story?** → Read session-story-lifecycle.md+- **Finishing a phase?** → Read session-gate-check-phase-transition.md+- **Starting UI work?** → Read session-ux-pipeline.md+- **Have an existing project?** → Read session-adopt-brownfield.md+- **Designing a system (agent-driven)?** → Read session-design-crafting-system.md- **Implementing code?** → Read session-implement-combat-damage.md- **Making strategic decisions?** → Read session-scope-crisis-decision.mddiff --git a/docs/examples/session-adopt-brownfield.md b/docs/examples/session-adopt-brownfield.mdnew file mode 100644index 00000000..64bf0eee--- /dev/null+++ b/docs/examples/session-adopt-brownfield.md@@ -0,0 +1,197 @@+# Example Session: /adopt — Brownfield Project Onboarding++**Context:** Developer has been building a game for 3 months before discovering this agent system. They have code, some design docs, and rough notes — but nothing in the right format for the skills to use.++**Starting State:**+- `src/gameplay/` — ~4000 lines of Godot 4.6 GDScript+- `design/` — 3 markdown files with rough design notes (not in GDD template format)+- No `design/gdd/` directory+- No `docs/architecture/` directory+- No `production/` directory+- No `design/gdd/systems-index.md`+- CLAUDE.md exists (engine configured: Godot 4.6)++**Session Duration:** ~30 minutes+**Turns:** 8+**Outcome:** Adoption plan written, most urgent gap (missing system index) fixed immediately++---++## Turn 1: User Invokes /adopt++**User:**+> /adopt++## Turn 2: Agent Detects Project State++**Agent (technical-director, via /adopt, context: fork):**+> Running brownfield audit...+>+> **Phase 1: Project State Detection**+>+> | Artifact Category | Found | Notes |+> |------------------|-------|-------|+> | Engine configuration | ✅ | Godot 4.6 in CLAUDE.md |+> | Source code | ✅ | ~4000 lines in `src/gameplay/` |+> | Design docs | ⚠️ | 3 files in `design/`, not in GDD format |+> | Architecture docs | ❌ | `docs/architecture/` missing |+> | Systems index | ❌ | `design/gdd/systems-index.md` missing |+> | Production tracking | ❌ | `production/` directory missing |+> | Sprint/story files | ❌ | None |+>+> **Phase 2: Format Audit (existing files)**+>+> Checking internal structure of the 3 design files...+>+> *`design/combat-notes.md`:*+> - Has informal notes, no GDD template sections+> - Contains: some rule descriptions, a damage formula, rough balance numbers+> - Missing from GDD template: Overview, Player Fantasy, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria (6 of 8 sections)+>+> *`design/crafting-ideas.md`:*+> - Brainstorm-style notes, no structure+> - No formulas, no acceptance criteria+> - Represents early concept thinking — useful as input for a GDD, not yet a GDD+>+> *`design/inventory.md`:*+> - Closest to a GDD — has Overview and Rules sections+> - Missing: Player Fantasy, Formulas, Edge Cases, Tuning Knobs, Acceptance Criteria (5 of 8 sections)+>+> **Phase 3: Gap Classification**+>+> | Gap | Severity | Reason |+> |-----|----------|--------|+> | No systems index | BLOCKING | `/design-system`, `/create-epics-stories`, `/gate-check` all require it |+> | GDD files not in template format | HIGH | Skills cannot reference TR-IDs from malformed GDDs |+> | No architecture docs | HIGH | Cannot run `/architecture-review` or `/create-control-manifest` |+> | No production tracking | MEDIUM | Sprint and story skills won't work, but not needed until production phase |+> | `design/crafting-ideas.md` — pre-GDD content | LOW | Useful as input; needs full GDD authoring before it blocks anything |++## Turn 3: Agent Presents the Migration Plan++**Agent:**+> **Phase 4: Migration Plan**+>+> 7 ordered steps to bring your project into full alignment. NEVER overwrites your existing content — each step fills gaps only.+>+> | # | Step | Skill | Priority | Notes |+> |---|------|-------|----------|-------|+> | 1 | Create `design/gdd/systems-index.md` | `/map-systems` or `/adopt` inline | BLOCKING | Unblocks all downstream skills |+> | 2 | Retrofit `design/inventory.md` → GDD format | `/design-system retrofit design/inventory.md` | HIGH | Adds 5 missing sections, keeps your existing content |+> | 3 | Retrofit `design/combat-notes.md` → GDD format | `/design-system retrofit design/combat-notes.md` | HIGH | Adds 6 missing sections |+> | 4 | Convert `design/crafting-ideas.md` → full GDD | `/design-system crafting` (new authoring, uses ideas as input) | MEDIUM | Not a retrofit — too informal to retrofit |+> | 5 | Create architecture ADRs from existing code | `/reverse-document` + `/architecture-decision` | HIGH | Captures decisions already made in code |+> | 6 | Create master architecture document | `/create-architecture` | HIGH | After ADRs |+> | 7 | Set up production tracking | `/sprint-plan new` | MEDIUM | After architecture phase |+>+> **Important:** Step 1 must happen before any other step. Everything else can be done in parallel or reordered based on your priorities.+>+> May I write this plan to `docs/adoption-plan-2026-03-12.md`?++**User:**+> Yes. Write it.++**Agent writes adoption plan.**++## Turn 4: Agent Offers to Fix the Most Urgent Gap++**Agent:**+> The BLOCKING gap is the missing `design/gdd/systems-index.md`.+>+> I can create one now by reading your existing code and design docs to infer what systems you've built. This is faster than running `/map-systems` from scratch — I'll populate it based on what already exists, then you confirm or adjust.+>+> Would you like me to do that now?++**User:**+> Yes, do it.++## Turn 5: Agent Reads Codebase and Drafts Systems Index++**Agent:**+> Reading `src/gameplay/` to infer systems...+>+> Found these system boundaries in the code:+>+> - `src/gameplay/combat/` — damage calculation, hit detection, status effects+> - `src/gameplay/inventory/` — item management, weight, stacks+> - `src/gameplay/crafting/` — recipe lookup, result generation (references inventory)+> - `src/gameplay/movement/` — CharacterBody2D, terrain modifiers (referenced by combat for positioning)+> - `src/gameplay/ui/` — HUD, inventory screen, dialogue box+> - `src/gameplay/world/` — tile map, terrain types, chunk loading+>+> **Draft systems index:**+>+> | System | Category | Priority | Dependencies | GDD Status |+> |--------|----------|----------|--------------|------------|+> | Movement | Foundation | MVP | None | ❌ Missing |+> | World/Terrain | Foundation | MVP | Movement | ❌ Missing |+> | Combat | Core | MVP | Movement | ⚠️ Needs retrofit |+> | Inventory | Core | MVP | None | ⚠️ Needs retrofit |+> | Crafting | Feature | MVP | Inventory | ❌ Pre-GDD only |+> | UI / HUD | Presentation | MVP | Combat, Inventory, Movement | ❌ Missing |+>+> Does this look right? Anything I missed or miscategorized?++**User:**+> Looks right. Add a Stamina system — it's in combat/ but should be its own system.++**Agent:**+> Added Stamina as a Core / MVP system:+>+> | Stamina | Core | MVP | Movement, Combat | ❌ Missing |+>+> Updated dependency: Movement depends on Stamina (movement drains it).+>+> May I write this to `design/gdd/systems-index.md`?++## Turn 6: User Approves++**User:**+> Yes++**Agent writes `design/gdd/systems-index.md`.**++## Turn 7: Agent Shows What's Now Unlocked++**Agent:**+> `design/gdd/systems-index.md` created.+>+> **BLOCKING gap resolved.** The following skills can now run:+>+> - ✅ `/design-system [name]` — guided GDD authoring for any system+> - ✅ `/design-system retrofit [path]` — fill missing sections in existing docs+> - ✅ `/gate-check` — now has a systems index to validate+> - ✅ `/help` — can now show correct phase workflow+>+> **Recommended next steps (from adoption plan):**+>+> 1. Run `/design-system retrofit design/inventory.md` — your most complete existing doc, easiest win+> 2. Run `/design-system retrofit design/combat-notes.md`+> 3. Run `/design-system crafting` — author crafting GDD using your ideas file as input+>+> After those 3, you'll have 5 of 7 systems with complete GDDs. Then run `/review-all-gdds` to catch cross-system consistency issues before architecture work.++## Turn 8: User Confirms Plan++**User:**+> Perfect. I'll start with the inventory retrofit.++**Agent:**+> Run:+> ```+> /design-system retrofit design/inventory.md+> ```+>+> The skill will detect your existing Overview and Rules sections, show you which of the 8 sections are missing, and run the section cycle only for the gaps. Your existing content won't be touched.++---++## What This Example Demonstrates++- **FORMAT audit, not existence audit**: `/adopt` doesn't just check whether files exist — it checks whether their internal structure matches what skills expect. A file named `gdd.md` with no template sections is flagged as a gap.+- **Migration, not replacement**: existing content is never overwritten. The plan fills gaps only.+- **BLOCKING gaps surface first**: the missing systems index is identified as BLOCKING because it prevents the most skills from functioning.+- **Inline creation of the urgent gap**: rather than just reporting the gap, the agent offers to fix it immediately in the same session.+- **Inferred from code**: the systems index is bootstrapped from the codebase structure, not written from scratch — brownfield code already contains the answer.+- **Retrofit vs. new authoring**: `/design-system retrofit` handles existing-but-incomplete docs; full `/design-system` handles net-new docs. The adoption plan distinguishes which applies to each file.+- **Context: fork**: `/adopt` runs in a forked context to avoid polluting the main session with large file reads across the whole codebase.diff --git a/docs/examples/session-design-system-skill.md b/docs/examples/session-design-system-skill.mdnew file mode 100644index 00000000..6bd1fb81--- /dev/null+++ b/docs/examples/session-design-system-skill.md@@ -0,0 +1,269 @@+# Example Session: Using /design-system to Author a GDD++**Context:** Solo indie dev, week 3 of project. `/map-systems` already ran and produced `design/gdd/systems-index.md`. The movement system is listed as MVP tier, Foundation priority.++**Starting State:**+- `design/gdd/game-concept.md` exists (survival-crafting game, 2D, Godot 4.6)+- `design/gdd/systems-index.md` exists (15 systems identified, movement is first in design order)+- No per-system GDDs written yet+- No upstream dependencies for movement (it is the foundation)++**Session Duration:** ~60 minutes+**Turns:** 14+**Outcome:** Complete `design/gdd/movement-system.md` with all 8 required sections written to file, ready for `/design-review`++---++## Turn 1: User Invokes the Skill++**User:**+> /design-system movement++## Turn 2: Agent Loads Context and Presents the Plan++**Agent (game-designer, via /design-system):**+> I'm loading context before we start:+>+> - Read `design/gdd/game-concept.md` — survival-crafting, exploration-heavy, lone survivor stranded on alien planet+> - Read `design/gdd/systems-index.md` — movement is **Foundation / MVP**, no upstream deps, downstream: combat, exploration, stamina+> - No prior GDD found for movement — starting fresh+>+> **Technical Feasibility Pre-Check:**+>+> | Domain | Signal |+> |--------|--------|+> | Engine | Godot 4.6 — CharacterBody2D with move_and_slide() is well-supported |+> | Physics | Jolt is now the default in 4.6 — 2D movement unaffected, but note for future 3D work |+> | Downstream risk | Stamina system listed as downstream dep — movement must expose a stamina callback hook |+>+> The GDD template has **8 required sections**. We'll go one at a time:+> `Overview → Player Fantasy → Detailed Rules → Formulas → Edge Cases → Dependencies → Tuning Knobs → Acceptance Criteria`+>+> I'll show you a draft of each section, you approve or revise, then I write it to the file before we move on.+>+> Creating the file skeleton now with empty section headers — may I write `design/gdd/movement-system.md` with placeholders?++**User:**+> Yes++**Agent writes** `design/gdd/movement-system.md` with 8 empty section headers.++---++## Turn 3: Section 1 — Overview++**Agent:**+> **Section 1 draft — Overview:**+>+> > The movement system is the player's primary interface with the world. It governs how the lone survivor walks, runs, rolls, and traverses alien terrain. Movement is physically grounded — the planet has heavier-than-Earth gravity, and the survivor is physically exhausted — but remains responsive enough to stay out of the player's way. The system feeds directly into exploration pacing, combat positioning, and the stamina system.+>+> Does this capture what you want?++**User:**+> Good but add something about the terrain — surfaces slow you down or have friction modifiers.++**Agent:**+> Revised:+>+> > The movement system is the player's primary interface with the world. It governs how the lone survivor walks, runs, rolls, and traverses alien terrain. Movement is physically grounded — the planet has heavier-than-Earth gravity, and the survivor is physically exhausted — but remains responsive enough to stay out of the player's way. Terrain surfaces apply friction and speed modifiers (slick rock, sand, shallow water) that make navigation a meaningful skill. The system feeds directly into exploration pacing, combat positioning, and the stamina system.+>+> May I write this to Section 1 in the file?++**User:**+> Yes++**Agent writes Section 1 to file.**++---++## Turn 4: Section 2 — Player Fantasy++**Agent:**+> **Section 2 draft — Player Fantasy:**+>+> > The player should feel like a tired but capable survivor — not a superhero, not helpless. Early game movement is deliberate and taxing; the player earns fluency over time. When traversing alien terrain, the goal is careful navigation with moments of urgency (running from threats, leaping a gap). The fantasy is "I know this terrain" — every surface type becomes readable and manageable as the player internalizes the friction system.+>+> Approve, revise, or change direction?++**User:**+> Love it. Write it.++**Agent writes Section 2 to file.**++---++## Turn 5: Section 3 — Detailed Rules++**Agent:**+> **Section 3 draft — Detailed Rules:**+>+> > **Base States:**+> > - **Walk** (default): Full directional control, moderate speed, low stamina drain+> > - **Run** (hold Shift): Faster, medium stamina drain per second — cancels automatically when stamina hits 0+> > - **Roll/Dodge** (tap Space): Quick burst in movement direction, brief invincibility frames, high stamina cost (flat)+> > - **Idle**: Zero movement input, stamina regenerates at full rate+> >+> > **Terrain Modifiers:**+> > - Normal ground: 1.0x speed multiplier, standard friction+> > - Sand/loose soil: 0.8x speed, 1.1x stamina drain (harder to move)+> > - Slick rock (wet): 1.1x speed, reduced stop friction (player overshoots)+> > - Shallow water (ankle-deep): 0.7x speed, no friction modifier+> > - Deep water: movement disabled, replaced by swimming (separate system, out of scope)+> >+> > **Collision:**+> > - CharacterBody2D + move_and_slide(); wall slide enabled+> > - Slopes up to 45° walked normally; >45° blocked+> > - One-way platforms supported (drop-through with Down + Jump)+>+> A lot here — want me to trim or expand anything?++**User:**+> Add that running is disabled when carrying a heavy object (like a large resource chunk).++**Agent:**+> Added to Run rule:+> > - **Run** (hold Shift): Faster, medium stamina drain per second — cancels automatically when stamina hits 0. **Disabled when carrying heavy objects** (signals broadcast by inventory system).+>+> Write to file?++**User:**+> Yes++**Agent writes Section 3 to file.**++---++## Turn 6: Section 4 — Formulas++**Agent:**+> **Section 4 draft — Formulas:**+>+> Let me define variables first, then the formulas:+>+> | Variable | Type | Description |+> |----------|------|-------------|+> | `base_walk_speed` | float | Base walk speed in px/s (tunable) |+> | `run_multiplier` | float | Run speed = walk × this |+> | `terrain_speed_mod` | float | Per-terrain multiplier (0.7–1.1) |+> | `stamina_drain_walk` | float | Stamina units/sec while walking |+> | `stamina_drain_run` | float | Stamina units/sec while running |+> | `stamina_cost_roll` | float | Flat stamina cost per roll |+> | `terrain_drain_mod` | float | Per-terrain stamina drain multiplier |+>+> **Effective Speed:**+> ```+> effective_speed = base_walk_speed × run_multiplier (if running, else 1.0) × terrain_speed_mod+> ```+>+> **Stamina Drain (per second):**+> ```+> drain_per_sec = stamina_drain_walk (or stamina_drain_run if running) × terrain_drain_mod+> ```+>+> **Roll Stamina Cost (flat):**+> ```+> stamina_after_roll = current_stamina - stamina_cost_roll+> (clamped to 0 — roll still executes, but player lands with 0 stamina)+> ```+>+> Approve or adjust variable names/formulas?++**User:**+> Looks right. Write it.++**Agent writes Section 4 to file.**++---++## Turn 7–9: Sections 5, 6, 7++*(These follow the same pattern — agent drafts, user approves or requests minor tweaks, agent writes each section to file before moving on. Abbreviated here.)*++**Section 5 — Edge Cases** covered:+- Player rolls into a wall (animation completes, no movement bonus)+- Stamina hits 0 mid-run (transitions to walk, no lurch)+- Two terrain types overlapping (lower multiplier wins)+- Roll on slick rock (still applies slick friction to stopping, not to the roll itself)++**Section 6 — Dependencies** covered:+- **Stamina system** (downstream): movement exposes `on_stamina_event(type: String, amount: float)` signal+- **Inventory system** (downstream): listens to `carrying_heavy_object_changed(is_heavy: bool)` signal+- **Input system**: movement direction from `InputMap` — standard Godot action names (`ui_left`, `ui_right`, etc.)+- **Terrain layer**: tile metadata drives terrain modifier lookup++**Section 7 — Tuning Knobs** covered:+- `base_walk_speed` (default: 120 px/s)+- `run_multiplier` (default: 1.7)+- Per-terrain speed and drain modifiers (table of 4 terrain types)+- `stamina_drain_walk`, `stamina_drain_run`, `stamina_cost_roll`++---++## Turn 10: Section 8 — Acceptance Criteria++**Agent:**+> **Section 8 draft — Acceptance Criteria:**+>+> These are the testable conditions that prove this system is complete:+>+> - [ ] Player walks at `base_walk_speed` on normal ground (measured with debug overlay)+> - [ ] Player runs at `base_walk_speed × run_multiplier` on normal ground+> - [ ] Run automatically cancels when stamina reaches 0, no input required+> - [ ] Roll executes with correct invincibility frames (verify via hitbox debug mode)+> - [ ] Each terrain type applies the correct speed modifier (QA table in sprint plan)+> - [ ] Carrying heavy object disables run (test with inventory integration)+> - [ ] Stamina system receives `on_stamina_event` signals during walk, run, and roll+> - [ ] All movement values come from exported variables — no hardcoded numbers in code+>+> Does this cover what "done" means to you?++**User:**+> Add one for slopes — make sure >45 degree slopes block movement.++**Agent:**+> Added:+> - [ ] Slopes ≤45° traversed normally; slopes >45° block movement (player slides back)+>+> Write to file?++**User:**+> Yes. Write it.++**Agent writes Section 8 to file.**++---++## Turn 11: Completion Summary++**Agent:**+> All 8 sections written to `design/gdd/movement-system.md`.+>+> **GDD Status:**+> - ✅ Overview+> - ✅ Player Fantasy+> - ✅ Detailed Rules+> - ✅ Formulas+> - ✅ Edge Cases+> - ✅ Dependencies (exposes 2 signals: stamina_event, carrying_heavy)+> - ✅ Tuning Knobs+> - ✅ Acceptance Criteria+>+> **Key decisions made:**+> - Terrain modifiers as tile metadata (not code constants)+> - Rolling has a flat stamina cost (not per-second)+> - Heavy carry disables run (signal-driven, not hardcoded check)+>+> **Recommended next step:** Run `/design-review design/gdd/movement-system.md` before moving to the next system in your queue (stamina is next in dependency order, per systems-index).+>+> The review will validate completeness, internal consistency, and catch anything that needs revision before you build on this GDD.++---++## What This Example Demonstrates++- **Incremental file writing**: each section written to disk immediately after approval — a session crash loses at most one in-progress section+- **Template population**: the GDD template's 8 sections become concrete content through dialogue, not bulk generation+- **Dependency signaling**: agent proactively surfaces downstream signal contracts (stamina, inventory) during the Dependencies section+- **Technical feasibility pre-check**: agent notes Jolt physics change before design starts, not after implementation breaks+- **Section-by-section cycle**: no full draft dumped at once — each section is a small, reviewable unit+- **Recovery**: if the session crashes, the agent re-reads the file on restart and resumes from the first empty sectiondiff --git a/docs/examples/session-gate-check-phase-transition.md b/docs/examples/session-gate-check-phase-transition.mdnew file mode 100644index 00000000..6d77258f--- /dev/null+++ b/docs/examples/session-gate-check-phase-transition.md@@ -0,0 +1,152 @@+# Example Session: /gate-check Phase Transition — Systems Design → Technical Setup++**Context:** Solo indie dev, end of week 5. The Systems Design phase feels complete — 6 MVP GDDs written, cross-review done, engine set up. User wants to formally advance to Technical Setup.++**Starting State:**+- `production/stage.txt` — currently `systems-design`+- `design/gdd/systems-index.md` — 6 MVP systems listed, all marked `Status: GDD Complete`+- `design/gdd/` — 6 GDD files present+- `design/gdd/gdd-cross-review-2026-03-10.md` — cross-review report, verdict: CONCERNS (1 low-priority note)+- Engine configured (Godot 4.6, `/setup-engine` complete)++**Session Duration:** ~20 minutes+**Turns:** 7+**Outcome:** Gate passed, `stage.txt` updated to `technical-setup`, clear list of what comes next++---++## Turn 1: User Initiates Gate Check++**User:**+> /gate-check++## Turn 2: Agent Detects Current Phase and Runs the Check++**Agent (via /gate-check):**+> Reading `production/stage.txt` — current phase: **systems-design**+>+> Running gate: **Systems Design → Technical Setup**+>+> ---+> **Required Artifacts Checklist:**+>+> | Artifact | Requirement | Status |+> |----------|-------------|--------|+> | `design/gdd/systems-index.md` | Exists, all MVP systems listed | ✅ |+> | Per-system GDDs | All MVP systems have a GDD | ✅ (6/6) |+> | `/design-review` per GDD | Each GDD reviewed | ✅ (6/6 review comments found) |+> | Cross-GDD review report | `design/gdd/gdd-cross-review-*.md` exists | ✅ |+> | Cross-review verdict | PASS or CONCERNS (not FAIL) | ✅ CONCERNS |+> | Engine configured | `production/stage.txt` or CLAUDE.md engine entry | ✅ Godot 4.6 |+>+> ---+> **Content Scan:**+>+> Checking GDD completeness (8 required sections each)...+>+> | GDD | Missing Sections |+> |-----|-----------------|+> | movement-system.md | None ✅ |+> | stamina-system.md | None ✅ |+> | combat-system.md | None ✅ |+> | inventory-system.md | None ✅ |+> | crafting-system.md | None ✅ |+> | exploration-system.md | None ✅ |+>+> ---+> **Cross-Review Concerns (from `gdd-cross-review-2026-03-10.md`):**+>+> 1. ⚠️ LOW — Crafting and inventory both define "item stack size" independently with different defaults (crafting: 99, inventory: 64). One system should be the authority; the other should reference it. Not blocking — can resolve in ADR.+>+> ---+> **Verdict: PASS**+>+> All required artifacts present. Cross-review concern is LOW severity and can be resolved during Technical Setup via an ADR. This is a normal finding at this stage.+>+> **May I advance `production/stage.txt` to `technical-setup`?**++## Turn 3: User Confirms++**User:**+> Yes, advance it.++## Turn 4: Agent Updates Stage and Presents Next Steps++**Agent:**+> Updated `production/stage.txt` → `technical-setup`+>+> ---+> **You are now in: Technical Setup**+>+> This phase establishes the technical foundation before production coding starts. Your goal is a complete, approved architecture so that every story written in Pre-Production has clear, unambiguous technical guidance.+>+> **Required steps this phase (in order):**+>+> 1. **`/create-architecture`** — Author the master architecture document. Covers system decomposition, data flow, layer boundaries, and module responsibilities.+>+> 2. **`/architecture-decision` (one per significant technical choice)** — At minimum:+> - Rendering approach (2D camera, viewport, etc.)+> - Save/load strategy+> - Audio bus architecture+> - The "item stack size authority" issue from cross-review (crafting vs inventory)+>+> 3. **`/architecture-review`** — Validates all ADRs for completeness, dependency ordering, and GDD traceability. Produces the TR-registry.+>+> 4. **`/create-control-manifest`** — Converts Accepted ADRs into a flat programmer rules sheet. This is what implementation agents will consult during coding.+>+> 5. **`/gate-check`** — Technical Setup → Pre-Production gate. Requires: architecture doc, all ADRs Accepted, control manifest, and dependency ordering resolved.+>+> **Optional but recommended:**+> - `/tech-debt` scan if you have any prototype code you plan to carry forward+> - `/setup-engine` re-run if you haven't yet fetched Godot 4.6 API snapshots+>+> **Tip:** Start with `/architecture-decision` for the item stack size conflict. It's a quick win that closes an open question before it creates ambiguity in two ADRs later.++## Turn 5: User Asks About the Cross-Review Concern++**User:**+> What do I actually write in the ADR for the stack size conflict?++## Turn 6: Agent Advises++**Agent:**+> The ADR decision is: **which system owns the canonical `max_stack_size` value?**+>+> Two options to consider:+>+> **Option A: Inventory owns it**+> - `ItemData` resource (owned by inventory) gets `max_stack_size: int = 64`+> - Crafting system reads from `ItemData`, never sets its own value+> - Pros: inventory is the source of truth for all item properties+> - Cons: crafting team needs to know to look at inventory data+>+> **Option B: Item data resource owns it (shared resource)**+> - `ItemData.max_stack_size` is the authority for both systems+> - Both crafting and inventory import from `ItemData`+> - Pros: single source, no coupling between crafting and inventory modules+> - Cons: one more thing in the shared data layer+>+> Most studios go with B (shared resource) once they have >2 systems touching item data. But either is valid for a solo project.+>+> Run `/architecture-decision` and it will guide you through the ADR format, including the Dependencies section that links this ADR back to the two GDDs.++## Turn 7: User Wraps Up++**User:**+> Got it. I'll start with /architecture-decision for this.++**Agent:**+> Good starting point. The ADR will document the decision, the reasoning, and the GDD requirements it addresses — so when you write code months from now, the rationale is preserved.+>+> Your phase gate is logged. Run `/help` at any time during Technical Setup to see your current progress against the required checklist.++---++## What This Example Demonstrates++- **Gate check is automated, not manual**: agent reads artifacts and checks them — user doesn't fill out a form+- **CONCERNS ≠ FAIL**: the cross-review concern is LOW severity and passes the gate. A FAIL would require resolution before advancing.+- **Stage.txt is the authority**: the status line, `/help`, and all skills read from `production/stage.txt` — updating it here changes what every subsequent skill sees+- **Next steps are phase-specific**: the agent doesn't give a generic "good luck" — it gives the ordered checklist for Technical Setup specifically+- **Gate check surfaces carry-forward work**: the stack size conflict was a cross-review note; the gate check ensures it becomes a concrete ADR rather than getting lost+- **One advance per gate**: the user confirmed advancement explicitly. The gate doesn't auto-advance; human confirmation is required.diff --git a/docs/examples/session-story-lifecycle.md b/docs/examples/session-story-lifecycle.mdnew file mode 100644index 00000000..9c2d6536--- /dev/null+++ b/docs/examples/session-story-lifecycle.md@@ -0,0 +1,245 @@+# Example Session: Full Story Lifecycle — /story-readiness → Implement → /story-done++**Context:** Solo indie dev, mid-production sprint. The movement system GDD and architecture are complete. A story for movement's core implementation has been generated by `/create-epics-stories`.++**Starting State:**+- `design/gdd/movement-system.md` — complete, all 8 sections+- `docs/architecture/movement-adr-001.md` — Status: Accepted+- `production/sprints/sprint-03.md` — lists STORY-MOV-001 in backlog+- `production/stories/STORY-MOV-001.md` — exists but not yet validated+- No implementation code yet++**Session Duration:** ~50 minutes+**Turns:** 13+**Outcome:** Story validated ready, implemented, verified complete with `/story-done`++---++## Phase 1: Story Readiness Check++### Turn 1: User Runs Readiness Check++**User:**+> /story-readiness production/stories/STORY-MOV-001.md++### Turn 2: Agent Validates the Story++**Agent (via /story-readiness):**+> Reading `production/stories/STORY-MOV-001.md`...+>+> **STORY-MOV-001: Implement CharacterBody2D movement with terrain modifiers**+>+> Running 4 validation checks:+>+> **1. Design Completeness**+> - GDD referenced: `design/gdd/movement-system.md` ✅+> - GDD section coverage: Detailed Rules ✅, Formulas ✅, Edge Cases ✅+> - TR-IDs embedded: TR-MOV-001 through TR-MOV-008 ✅+>+> **2. Architecture Completeness**+> - ADR referenced: `docs/architecture/movement-adr-001.md` ✅+> - ADR status: **Accepted** ✅ *(Would be BLOCKED if Proposed)*+> - Control manifest version in story: `2026-03-10` — current manifest is `2026-03-10` ✅+>+> **3. Scope Clarity**+> - Acceptance criteria: 9 items, all measurable ✅+> - Out-of-scope items listed: swimming, climbing ✅+> - Ambiguities found: **1**+> - ⚠️ Story says "roll direction follows last input direction" but GDD says "roll in movement direction" — these conflict when player stops and immediately rolls. Clarify before pickup.+>+> **4. Definition of Done**+> - Tests required: unit tests for formula functions ✅+> - Integration signal: `on_stamina_event` must fire correctly ✅+>+> ---+> **Verdict: NEEDS WORK**+>+> One ambiguity must be resolved before implementation starts. Would you like to resolve it now so I can mark the story as ready?++### Turn 3: User Resolves the Ambiguity++**User:**+> Roll uses last movement direction. If player is standing still, roll uses facing direction instead.++### Turn 4: Agent Updates the Story++**Agent:**+> Updating the story's Detailed Rules section:+>+> > Roll direction: last movement direction. If velocity is zero at roll input, roll uses current facing direction.+>+> May I write this to `production/stories/STORY-MOV-001.md` and set Status to `ready-for-dev`?++**User:**+> Yes++**Agent writes update. Story status: `ready-for-dev`.**++> **Verdict: READY**+> Story is implementation-ready. Pick it up when you're ready to build.++---++## Phase 2: Implementation++### Turn 5: User Starts Implementation++**User:**+> Let's implement STORY-MOV-001. I'm ready to start coding.++### Turn 6: Agent Reads Story and ADR++**Agent (gameplay-programmer):**+> Reading `production/stories/STORY-MOV-001.md`, `design/gdd/movement-system.md`, and `docs/architecture/movement-adr-001.md`...+>+> **Architecture (from ADR-001):**+> - `MovementComponent.gd` — attached to player scene, not a singleton+> - Terrain modifier lookup via `TerrainLayer.get_modifier(tile_position)` helper+> - Stamina events via signal (not direct call to StaminaSystem)+>+> **My proposed file structure:**+> ```+> src/gameplay/movement/+> movement_component.gd # CharacterBody2D logic, state machine+> terrain_modifier_table.gd # Const table: terrain_type -> {speed_mod, drain_mod}+> tests/unit/+> test_movement_formulas.gd # Unit tests for speed/drain calculations+> ```+>+> May I proceed with this structure?++**User:**+> Yes++### Turn 7: Agent Implements and Shows Key Code++**Agent:**+> Implementing `movement_component.gd`. Key excerpt for your review before I write the file:+>+> ```gdscript+> class_name MovementComponent+> extends Node+>+> signal stamina_event(type: String, amount: float)+>+> @export var base_walk_speed: float = 120.0+> @export var run_multiplier: float = 1.7+> @export var stamina_drain_walk: float = 2.0+> @export var stamina_drain_run: float = 6.0+> @export var stamina_cost_roll: float = 15.0+>+> var _is_carrying_heavy: bool = false+>+> func _physics_process(delta: float) -> void:+> var terrain_mod := _get_terrain_modifier()+> var effective_speed := _calculate_speed(terrain_mod)+> # ...+> ```+>+> All values are `@export` — none hardcoded. Is this the direction you want?++**User:**+> Looks good. Write it.++### Turn 8–9: Agent Writes Files and Tests++**Agent writes:**+- `src/gameplay/movement/movement_component.gd`+- `src/gameplay/movement/terrain_modifier_table.gd`+- `tests/unit/test_movement_formulas.gd`++**Agent:**+> Files written. Running available linting checks...+>+> No errors. Tests file created with 6 unit tests covering:+> - Walk speed formula (3 terrain types)+> - Run speed formula+> - Stamina drain calculation+> - Roll stamina cost (with and without zero-velocity edge case)+>+> Manual testing needed for: invincibility frames, slope blocking, terrain integration (requires running scene).++---++## Phase 3: Story Completion++### Turn 10: User Tests Manually and Runs /story-done++**User:**+> I've tested it in the scene — everything works. /story-done production/stories/STORY-MOV-001.md++### Turn 11: Agent Runs Completion Review++**Agent (via /story-done):**+> Reading story, GDD, ADRs...+>+> **Phase 1: Story Located** ✅ `production/stories/STORY-MOV-001.md`+>+> **Phase 2: Acceptance Criteria Verification**+>+> | # | Criterion | Verification | Status |+> |---|-----------|--------------|--------|+> | 1 | Walk speed correct on normal ground | Auto: formula unit tests pass | ✅ AUTO |+> | 2 | Run speed correct | Auto: formula unit tests pass | ✅ AUTO |+> | 3 | Run cancels at stamina 0 | Manual: user confirmed | ✅ MANUAL |+> | 4 | Roll invincibility frames work | Manual: user confirmed | ✅ MANUAL |+> | 5 | Terrain modifiers apply correctly | Manual: user confirmed | ✅ MANUAL |+> | 6 | Heavy carry disables run | Auto: not yet testable (inventory not integrated) | ⏳ DEFERRED |+> | 7 | Stamina signals fire correctly | Auto: integration test pending | ⏳ DEFERRED |+> | 8 | No hardcoded values | Auto: grep for magic numbers → 0 found | ✅ AUTO |+> | 9 | Slopes >45° block movement | Manual: user confirmed | ✅ MANUAL |+>+> **Phase 3: GDD/ADR Deviations**+>+> Scanning implementation against TR-IDs...+>+> - TR-MOV-001 through TR-MOV-007: ✅ Implemented as specified+> - TR-MOV-008 (heavy carry signal): ⚠️ ADVISORY — deferred to inventory integration story. Not a deviation, just unverifiable now.+>+> **Phase 4: Manifest Staleness Check**+>+> Story control manifest version `2026-03-10` matches current manifest `2026-03-10`. ✅+>+> **Phase 5: Code Review Prompt**+>+> Suggest running `/code-review src/gameplay/movement/` before marking complete. Not blocking.+>+> ---+> **Completion Report: COMPLETE WITH NOTES**+>+> Story is complete. Two criteria deferred to inventory integration — log as deferred, not blocked.+>+> May I update the story status to `Status: Complete` and add Completion Notes, and update `production/sprint-status.yaml`?++**User:**+> Yes++### Turn 12: Agent Closes the Story++**Agent writes:**+- Story `Status: Complete` + Completion Notes (deferred criteria noted)+- `production/sprint-status.yaml` — STORY-MOV-001 set to `done`++**Agent:**+> STORY-MOV-001 closed.+>+> **Deferred criteria logged** (will auto-surface in inventory integration story):+> - Heavy carry disables run (requires inventory signal)+> - Stamina signal integration test (requires stamina system)+>+> **Next ready story from sprint:**+> - STORY-MOV-002: Stamina system — this is the logical next story (downstream dep now unblocked)+> - STORY-HUD-001: Movement HUD indicators — also unblocked+>+> Run `/story-readiness` on whichever you pick up next.++---++## What This Example Demonstrates++- **Readiness gate catches real issues**: the roll direction ambiguity would have caused a late implementation decision without `/story-readiness`+- **ADR status is a hard gate**: if `movement-adr-001.md` had been `Proposed` instead of `Accepted`, story would be `BLOCKED` and implementation wouldn't start+- **Deferred criteria**: not every acceptance criterion can be verified at story close — `/story-done` tracks deferred items rather than blocking completion+- **TR-ID references**: story stores `TR-MOV-001` IDs, not quoted GDD text — avoids false deviation flags when GDD wording is cleaned up later+- **sprint-status.yaml**: single source of truth for sprint state, updated by `/story-done` and read by `/sprint-status`+- **Manifest version check**: ensures story's implementation guidance hasn't drifted from current architecture decisionsdiff --git a/docs/examples/session-ux-pipeline.md b/docs/examples/session-ux-pipeline.mdnew file mode 100644index 00000000..05a0e9a1--- /dev/null+++ b/docs/examples/session-ux-pipeline.md@@ -0,0 +1,210 @@+# Example Session: UX Pipeline — /ux-design → /ux-review → /team-ui++**Context:** Solo indie dev, Pre-Production phase. The HUD and inventory screen are the first UI to design. The game has a player journey doc and GDDs for inventory and combat.++**Starting State:**+- `design/gdd/inventory-system.md` — complete+- `design/gdd/combat-system.md` — complete+- `design/player-journey.md` — complete (6-phase arc defined)+- No UX specs yet+- `design/ux/` directory does not exist++**Session Duration:** ~90 minutes across two sessions (HUD design, then inventory screen)+**Turns:** 16+**Outcome:** `design/ux/hud.md` and `design/ux/screens/inventory.md` created and reviewed; team-ui handed off for visual implementation++---++## Part 1: HUD Design with /ux-design++### Turn 1: User Starts HUD Design++**User:**+> /ux-design hud++### Turn 2: Agent Loads Context and Presents the Approach++**Agent (ux-designer, via /ux-design):**+> Starting HUD design. Loading context...+>+> - `design/player-journey.md` read — key states: Calm Exploration, Tension (threat detected), Crisis (low HP/stamina), Combat+> - `design/gdd/combat-system.md` — HUD needs: HP bar, stamina bar, active ability cooldowns (up to 3), damage numbers+> - `design/gdd/inventory-system.md` — HUD needs: quick slots (4 slots), active item indicator+>+> **HUD Philosophy question:** What is the player's primary attention focus during play?+>+> This determines how aggressive the HUD should be:+> - **Option A: Diegetic (low presence)** — HP shown only when damaged, stamina shown only when draining. World-first, HUD recedes unless urgent.+> - **Option B: Persistent minimal** — HP and stamina always visible, small and unobtrusive. Quick reference without mode-switching.+> - **Option C: Full tactical** — All info always visible (HP, stamina, cooldowns, map, inventory slots). Player always has full awareness.+>+> Given your survival game and "lone survivor" fantasy, A or B is most consistent with the genre.++**User:**+> B — I want it always there but minimal. The player is always managing resources.++### Turn 3: Agent Drafts HUD Philosophy Section++**Agent:**+> **HUD Philosophy draft:**+>+> > **Approach: Persistent Minimal**+> > The HUD is always visible but occupies minimal screen real estate. The player is a resource-managing survivor — denying HP/stamina visibility creates frustration, not tension. All critical stats are readable at a glance without interrupting exploration focus. Elements scale in visual weight when they become urgent (HP below 30% pulses, stamina at 0 flashes), then return to minimal state.+>+> May I write this to `design/ux/hud.md` as the Philosophy section?++**User:**+> Yes++**Agent creates `design/ux/hud.md` and writes Philosophy section.**++*(Turns 4–7 continue the section-by-section HUD authoring: Info Architecture, Zones, Element Specs, State Machine, Visual Budget, Platform Adaptation — each drafted, approved, and written to file.)*++---++**Final HUD structure after all sections:**++```+design/ux/hud.md+ - Philosophy: Persistent Minimal+ - Info Architecture: HP (top-left), Stamina (top-left below HP), Quick Slots (bottom-center),+ Ability Cooldowns (bottom-right), Damage Numbers (world-space)+ - Zones: 4 defined (top-left vitals, bottom-center interaction, bottom-right abilities, world-space)+ - Element Specs: 6 elements with dimensions, font sizes, opacity rules+ - State Machine: Calm / Tension / Crisis / Combat (4 states, transition triggers)+ - Visual Budget: Max 8% screen coverage, 3 simultaneous animations+ - Platform Adaptation: Controller (aim reticle added), Mobile (out of scope v1)+```++---++## Part 2: Inventory Screen with /ux-design++### Turn 8: User Starts Inventory Screen++**User:**+> /ux-design screen inventory++### Turn 9: Agent Scans GDD and Player Journey++**Agent:**+> Loading context for inventory screen...+>+> From `design/gdd/inventory-system.md`:+> - Grid inventory, 6×8 slots+> - Items have weight (affects movement) and stack size+> - Player can equip, drop, inspect, split stacks+>+> From `design/player-journey.md`:+> - Inventory opens frequently during Calm Exploration+> - Players should feel "organized and in control" when opening inventory+> - Anxiety moment: "I need to decide what to drop" — should be clear, not panicked+>+> **Player Need (from journey):** *I need to quickly assess what I'm carrying, decide what to keep or drop, and get back into the world.*+>+> **Key design question:** How do players navigate to inventory actions?+> - **Option A: Right-click context menu** — hover item → right-click → menu appears (Escape/common)+> - **Option B: Drag-based** — drag to drop zone to drop; drag to equipment slot to equip (Stardew Valley)+> - **Option C: Inspect panel** — click item → details panel appears on right with action buttons++**User:**+> B — drag-based. I want it tactile.++*(Turns 10–12 continue section-by-section for the inventory screen spec: Player Need, Layout Zones, States, Interaction Map, Data Requirements, Events Fired, Accessibility, Localization.)*++---++## Part 3: /ux-review++### Turn 13: User Runs Review++**User:**+> /ux-review design/ux/++### Turn 14: Agent Reviews Both Documents++**Agent (via /ux-review):**+> Reviewing all UX specs in `design/ux/`...+>+> ---+> **HUD Review (`hud.md`):**+>+> | Check | Status | Notes |+> |-------|--------|-------|+> | GDD alignment — all required elements present | ✅ | HP, stamina, quick slots, cooldowns all specced |+> | State machine coverage | ✅ | All 4 gameplay states covered |+> | Accessibility tier | ⚠️ | No colorblind mode specified for HP/stamina bars (red/yellow convention) |+> | Visual budget | ✅ | 8% screen coverage, within budget |+> | Platform notes | ✅ | Controller variant documented |+>+> **Inventory Screen Review (`screens/inventory.md`):**+>+> | Check | Status | Notes |+> |-------|--------|-------|+> | Player Need stated | ✅ | |+> | All GDD actions covered | ✅ | Equip, drop, inspect, split all in interaction map |+> | Drag-drop interaction fully specified | ⚠️ | Drop target behavior when inventory is full not defined — what happens? |+> | Accessibility: keyboard alternative for drag | ❌ | MISSING — drag-only with no keyboard path fails motor accessibility |+> | Localization: all strings tagged | ✅ | |+> | Data events fired | ✅ | `item_equipped`, `item_dropped`, `stack_split` all mapped |+>+> ---+> **Verdict: NEEDS REVISION**+>+> Two issues must be resolved before handoff to /team-ui:+>+> 1. **BLOCKING (Accessibility):** Inventory screen has no keyboard alternative to drag-drop. Motor accessibility requires a non-drag interaction path. Add a "press X to pick up / press X again to place" toggle, or a details panel with keyboard-accessible action buttons.+>+> 2. **ADVISORY (HUD):** HP/stamina bars use color alone to convey state. Add a secondary indicator (shape, icon, or pattern) for colorblind users. Can be resolved in visual pass.+> 3. **ADVISORY (Inventory):** Full-inventory drop behavior is unspecified. Resolve in GDD before implementation, or document as out-of-scope.++### Turn 15: User Resolves Blocking Issue++**User:**+> For keyboard: press F to pick up item at cursor, press F again on target slot to place it. Add this to the inventory spec.++**Agent:**+> Adding to Interaction Map under "Keyboard / Controller Path":+>+> > Press F (or South button) to pick up item at cursor. Item enters "held" state with visual indicator. Press F again on target slot to place. Press Escape to cancel and return item.+>+> May I write this to `design/ux/screens/inventory.md` and re-run the accessibility check?++**User:**+> Yes++**Agent writes update. Re-checks accessibility — now passes.**++---++## Part 4: Handoff to /team-ui++### Turn 16: User Kicks Off Team UI++**User:**+> /team-ui++**Agent (via /team-ui):**+> Running UX pipeline context check...+>+> - `design/ux/hud.md` — reviewed ✅+> - `design/ux/screens/inventory.md` — reviewed ✅+> - `/ux-review` verdict: NEEDS REVISION was resolved — current state: APPROVED ✅+>+> Proceeding to **Phase 2: Visual Design**+>+> Handing off to `art-director` for visual spec (color palette, typography, iconography aligned to art bible)...+>+> *(team-ui continues through visual design → layout implementation → accessibility audit → final review)*++---++## What This Example Demonstrates++- **Context-driven design**: agent reads player-journey.md to ground HUD decisions in player emotional state, not just feature lists+- **UX review is a hard gate**: `/team-ui` checks for a passing `/ux-review` before proceeding to visual design+- **Accessibility caught early**: the missing keyboard alternative was flagged by review, not discovered by a QA tester in the final week+- **Blocking vs. advisory**: the missing keyboard path was BLOCKING (stops handoff); the colorblind colors were ADVISORY (can be fixed in visual pass)+- **Section-by-section UX authoring**: same incremental pattern as `/design-system` — each section written to file before moving on+- **Separate HUD and screen files**: `design/ux/hud.md` is the whole-game HUD; per-screen specs live in `design/ux/screens/`+- **Pattern library enforced by /team-ui**: after this session, inventory drag-drop becomes a documented pattern in `design/ux/interaction-patterns.md` for all future screens to referencediff --git a/docs/examples/skill-flow-diagrams.md b/docs/examples/skill-flow-diagrams.mdnew file mode 100644index 00000000..172a9624--- /dev/null+++ b/docs/examples/skill-flow-diagrams.md@@ -0,0 +1,227 @@+# Skill Flow Diagrams++Visual maps of how skills chain together across the 7 development phases.+These show what runs before and after each skill, and what artifacts flow between them.++---++## Full Pipeline Overview (Zero to Ship)++```+PHASE 1: CONCEPT+ /start ──────────────────────────────────────────────────────► routes to A/B/C/D+ /brainstorm ──────────────────────────────────────────────────► design/gdd/game-concept.md+ /setup-engine ────────────────────────────────────────────────► CLAUDE.md + technical-preferences.md+ /design-review [game-concept.md] ────────────────────────────► concept validated+ /gate-check ─────────────────────────────────────────────────► PASS → advance to systems-design+ │+ ▼+PHASE 2: SYSTEMS DESIGN+ /map-systems ────────────────────────────────────────────────► design/gdd/systems-index.md+ │+ ▼ (for each system, in dependency order)+ /design-system [name] ──────────────────────────────────────► design/gdd/[system].md+ /design-review [system].md ─────────────────────────────────► per-GDD review comments+ │+ ▼ (after all MVP GDDs done)+ /review-all-gdds ────────────────────────────────────────────► design/gdd/gdd-cross-review-[date].md+ /gate-check ─────────────────────────────────────────────────► PASS → advance to technical-setup+ │+ ▼+PHASE 3: TECHNICAL SETUP+ /create-architecture ────────────────────────────────────────► docs/architecture/master.md+ /architecture-decision (×N) ─────────────────────────────────► docs/architecture/[adr-nnn].md+ /architecture-review ────────────────────────────────────────► review report + docs/architecture/tr-registry.yaml+ /create-control-manifest ────────────────────────────────────► docs/architecture/control-manifest.md+ /gate-check ─────────────────────────────────────────────────► PASS → advance to pre-production+ │+ ▼+PHASE 4: PRE-PRODUCTION+ /ux-design [screen/hud/patterns] ────────────────────────────► design/ux/*.md+ /ux-review ──────────────────────────────────────────────────► UX specs approved+ /create-epics-stories ───────────────────────────────────────► production/stories/STORY-*.md+ /prototype [core-mechanic] ──────────────────────────────────► prototypes/[name]/+ /playtest-report ────────────────────────────────────────────► tests/playtest/vertical-slice.md+ /sprint-plan new ────────────────────────────────────────────► production/sprints/sprint-01.md+ /gate-check ─────────────────────────────────────────────────► PASS → advance to production+ │+ ▼+PHASE 5: PRODUCTION (repeating sprint loop)+ /sprint-status ──────────────────────────────────────────────► sprint snapshot+ /story-readiness [story] ────────────────────────────────────► story validated READY+ │+ ▼ implement (gameplay-programmer, etc.)+ /story-done [story] ─────────────────────────────────────────► story closed + next surfaced+ /sprint-plan [next] ─────────────────────────────────────────► next sprint+ │+ ▼ (after Production milestone)+ /milestone-review ───────────────────────────────────────────► milestone report+ /gate-check ─────────────────────────────────────────────────► PASS → advance to polish+ │+ ▼+PHASE 6: POLISH+ /perf-profile ───────────────────────────────────────────────► perf report + fixes+ /balance-check ──────────────────────────────────────────────► balance report + fixes+ /tech-debt ──────────────────────────────────────────────────► docs/tech-debt-register.md+ /team-polish ────────────────────────────────────────────────► polish sprint orchestrated+ /gate-check ─────────────────────────────────────────────────► PASS → advance to release+ │+ ▼+PHASE 7: RELEASE+ /launch-checklist ───────────────────────────────────────────► launch readiness report+ /release-checklist ──────────────────────────────────────────► platform-specific checklist+ /changelog ──────────────────────────────────────────────────► CHANGELOG.md+ /patch-notes ────────────────────────────────────────────────► player-facing notes+ /team-release ───────────────────────────────────────────────► release pipeline orchestrated+```++---++## Skill Chain: /design-system in Detail++How a single GDD gets authored, reviewed, and handed to architecture:++```+systems-index.md (input)+game-concept.md (input)+upstream GDDs (input, if any)+ │+ ▼+/design-system [name]+ │+ ├── Pre-check: feasibility table + engine risk flags+ │+ ├── Section cycle × 8:+ │ question → options → decision → draft → approval → WRITE+ │ [each section written to file immediately after approval]+ │+ └── Output: design/gdd/[system].md (complete, all 8 sections)+ │+ ▼+ /design-review design/gdd/[system].md+ │+ ├── APPROVED → mark DONE in systems-index, proceed to next system+ ├── NEEDS REVISION → agent shows specific issues, re-enter section cycle+ └── MAJOR REVISION → significant redesign needed before next system+ │+ ▼ (after all MVP GDDs + cross-review)+ /review-all-gdds+ │+ └── Output: gdd-cross-review-[date].md+```++---++## Skill Chain: Story Lifecycle in Detail++How a story gets from backlog to closed:++```+/create-epics-stories+ │+ └── Output: production/stories/STORY-[SYS]-NNN.md+ (Status: backlog or blocked if ADR is Proposed)+ │+ ▼+ /story-readiness [story]+ │+ ├── READY → Status: ready-for-dev → pick up for implementation+ ├── NEEDS WORK → agent shows specific gaps → resolve → re-run readiness+ └── BLOCKED → ADR still Proposed, or upstream story incomplete+ │+ ▼ (after READY)+ Implementation (gameplay-programmer, etc.)+ │+ ▼+ /story-done [story]+ │+ ├── COMPLETE → Status: Complete, sprint-status.yaml updated, next story surfaced+ ├── COMPLETE WITH NOTES → complete but some criteria deferred (logged)+ └── BLOCKED → acceptance criteria cannot be verified → investigate blocker+```++---++## Skill Chain: UX Pipeline in Detail++```+design/gdd/*.md (UX requirements extracted)+design/player-journey.md (emotional arc)+ │+ ▼+/ux-design hud → design/ux/hud.md+/ux-design screen [name] → design/ux/screens/[name].md+/ux-design patterns → design/ux/interaction-patterns.md+ │+ ▼+/ux-review design/ux/+ │+ ├── APPROVED → all specs ready for /team-ui+ ├── NEEDS REVISION → blocking issues listed → fix → re-run review+ └── MAJOR REVISION → fundamental UX problems → significant redesign+ │+ ▼ (after APPROVED)+ /team-ui+ │+ ├── Phase 1: context load + /ux-design (if specs missing)+ ├── Phase 2: visual design (art-director)+ ├── Phase 3: layout implementation (ui-programmer)+ ├── Phase 4: accessibility audit (accessibility-specialist)+ └── Phase 5: final review+```++---++## Brownfield Onboarding Flow++For projects with existing work (use `/start` option D or run directly):++```+/project-stage-detect → stage detection report+ │+ ▼+/adopt+ │+ ├── Phase 1: detect what exists+ ├── Phase 2: FORMAT audit (not just existence)+ ├── Phase 3: classify gaps (BLOCKING / HIGH / MEDIUM / LOW)+ ├── Phase 4: ordered migration plan+ ├── Phase 5: write docs/adoption-plan-[date].md+ └── Phase 6: fix most urgent gap inline (optional)+ │+ ▼+ /design-system retrofit [path] → fills missing GDD sections+ /architecture-decision retrofit [path] → fills missing ADR sections+ /gate-check → where are you in the pipeline?+```++---++## How to Read These Diagrams++| Symbol | Meaning |+|--------|---------|+| `──►` | Produces this artifact |+| `│ ▼` | Flows into next step |+| `├──` | Branch (multiple possible outcomes) |+| `×N` | Runs N times (once per system, story, etc.) |+| `(input)` | Read by the skill but not produced here |+| `[optional]` | Not required for the gate to pass |+| `WRITE` (caps) | File written to disk immediately |++---++## Common Entry Points++| Where you are | Run this |+|---------------|---------|+| Brand new, no idea | `/start` → `/brainstorm` |+| Have a concept, no engine | `/setup-engine` |+| Have concept + engine | `/map-systems` |+| Mid-systems design | `/design-system [next system]` or `/map-systems next` |+| All GDDs done | `/review-all-gdds` → `/gate-check` |+| In technical setup | `/create-architecture` → `/architecture-decision` |+| Have stories, ready to code | `/story-readiness [story]` |+| Story done | `/story-done [story]` |+| Not sure | `/help` |+| Existing project | `/adopt` |