Examples: add 5 session transcripts + skill flow diagrams covering v0.4.0 skills

Closes the gap where /design-system, story lifecycle, gate-check transitions, UX pipeline, and brownfield adoption had no worked examples. Adds visual ASCII flow diagrams for the full 7-phase pipeline and 4 detailed skill chains. New files: - docs/examples/session-design-system-skill.md - docs/examples/session-story-lifecycle.md - docs/examples/session-gate-check-phase-transition.md - docs/examples/session-ux-pipeline.md - docs/examples/session-adopt-brownfield.md - docs/examples/skill-flow-diagrams.md Updated: - docs/examples/README.md — reorganized with Core Workflow / Foundational sections - .claude/docs/quick-start.md — synced - docs/WORKFLOW-GUIDE.md — synced Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-27 04:51:46 +00:00 · 2026-03-12 21:05:26 +11:00
parent b36eb2728d
commit b1fad395cd
9 changed files with 1528 additions and 33 deletions
--- 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.md

--- a/docs/examples/session-adopt-brownfield.md
+++ 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.
--- a/docs/examples/session-design-system-skill.md
+++ 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 section
--- a/docs/examples/session-gate-check-phase-transition.md
+++ 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.
--- a/docs/examples/session-story-lifecycle.md
+++ 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 decisions
--- a/docs/examples/session-ux-pipeline.md
+++ 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 reference
--- a/docs/examples/skill-flow-diagrams.md
+++ 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` |