diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md index a95e6e6..f36cb69 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 | -| `/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 | -| `/milestone-review` | Reviews milestone progress | -| `/onboard` | Generates onboarding docs for a role | -| `/prototype` | Scaffolds a throwaway prototype | -| `/release-checklist` | Validates pre-release checklist | -| `/changelog` | Generates changelog from git history | -| `/retrospective` | Runs sprint/milestone retrospective | -| `/estimate` | Produces structured effort estimates | -| `/hotfix` | Emergency fix with audit trail | -| `/tech-debt` | Scan, track, and prioritize tech debt | -| `/scope-check` | Detect scope creep against plan | -| `/localize` | Localization scan, extract, validate | -| `/perf-profile` | Performance profiling and bottleneck ID | -| `/gate-check` | Validate phase readiness (PASS/CONCERNS/FAIL) | +| `/help` | Context-aware "what do I do next?" — reads your current phase and artifacts | | `/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 | +| `/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 | +| `/balance-check` | Analyzes game balance data | +| `/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 | +| `/release-checklist` | Validates pre-release checklist | +| `/launch-checklist` | Complete launch readiness validation | +| `/changelog` | Generates changelog from git history | +| `/patch-notes` | Generate player-facing patch notes | +| `/hotfix` | Emergency fix with audit trail | +| `/prototype` | Scaffolds a throwaway prototype | +| `/localize` | Localization scan, extract, validate | | `/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 Reference diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index 38d1a9f..48cad81 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.md index 5c31e04..1a0f637 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.md diff --git a/docs/examples/session-adopt-brownfield.md b/docs/examples/session-adopt-brownfield.md new file mode 100644 index 0000000..64bf0ee --- /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.md new file mode 100644 index 0000000..6bd1fb8 --- /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 section diff --git a/docs/examples/session-gate-check-phase-transition.md b/docs/examples/session-gate-check-phase-transition.md new file mode 100644 index 0000000..6d77258 --- /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.md new file mode 100644 index 0000000..9c2d653 --- /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 decisions diff --git a/docs/examples/session-ux-pipeline.md b/docs/examples/session-ux-pipeline.md new file mode 100644 index 0000000..05a0e9a --- /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 reference diff --git a/docs/examples/skill-flow-diagrams.md b/docs/examples/skill-flow-diagrams.md new file mode 100644 index 0000000..172a962 --- /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` |