添加 claude code game studios 到项目
This commit is contained in:
panw
357
docs/examples/README.md
Normal file
357
docs/examples/README.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# Collaborative Session Examples
|
||||
|
||||
This directory contains realistic, end-to-end session transcripts showing how the Game Studio Agent Architecture works in practice. Each example demonstrates the **collaborative workflow** where agents ask questions, present options, and wait for user approval rather than autonomously generating content.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
**Duration:** ~45 minutes (12 turns)
|
||||
**Complexity:** Medium
|
||||
|
||||
**Scenario:**
|
||||
Solo dev needs to design a crafting system that serves Pillar 2 ("Emergent Discovery Through Experimentation"). The agent guides them through question/answer, presents 3 design options with game theory analysis, incorporates user modifications, and iteratively drafts the GDD with approval at each step.
|
||||
|
||||
**Key Collaborative Moments:**
|
||||
- Agent asks 5 clarifying questions upfront
|
||||
- Presents 3 distinct options with pros/cons + MDA alignment
|
||||
- User modifies recommended option, agent incorporates immediately
|
||||
- Edge case flagged proactively ("what if non-recipe combo?")
|
||||
- Each GDD section shown for approval before moving to next
|
||||
- Explicit "May I write to [file]?" before creating file
|
||||
|
||||
**Learn:**
|
||||
- How design agents ask about goals, constraints, references
|
||||
- How to present options using game design theory (MDA, SDT, Bartle)
|
||||
- How to iterate on drafts section-by-section
|
||||
- When to delegate to specialists (systems-designer, economy-designer)
|
||||
|
||||
---
|
||||
|
||||
### [Session: Implementing Combat Damage Calculation](session-implement-combat-damage.md)
|
||||
**Type:** Implementation
|
||||
**Agent:** gameplay-programmer
|
||||
**Duration:** ~30 minutes (10 turns)
|
||||
**Complexity:** Low-Medium
|
||||
|
||||
**Scenario:**
|
||||
User has a complete design doc and wants the damage calculation implemented. Agent reads the spec, identifies 7 ambiguities/gaps, asks clarifying questions, proposes architecture for approval, implements with rule enforcement, and proactively writes tests.
|
||||
|
||||
**Key Collaborative Moments:**
|
||||
- Agent reads design doc first, identifies 7 spec ambiguities
|
||||
- Architecture proposed with code samples BEFORE implementation
|
||||
- User requests type safety, agent refines and re-proposes
|
||||
- Rules catch issues (hardcoded values), agent fixes transparently
|
||||
- Tests written proactively following verification-driven development
|
||||
- Agent offers options for next steps rather than assuming
|
||||
|
||||
**Learn:**
|
||||
- How implementation agents clarify specs before coding
|
||||
- How to propose architecture with code samples for approval
|
||||
- How rules enforce standards automatically
|
||||
- How to handle spec gaps (ask, don't assume)
|
||||
- Verification-driven development (tests prove it works)
|
||||
|
||||
---
|
||||
|
||||
### [Session: Scope Crisis - Strategic Decision Making](session-scope-crisis-decision.md)
|
||||
**Type:** Strategic Decision
|
||||
**Agent:** creative-director
|
||||
**Duration:** ~25 minutes (8 turns)
|
||||
**Complexity:** High
|
||||
|
||||
**Scenario:**
|
||||
Solo dev faces crisis: Alpha milestone in 2 weeks, crafting system needs 3 weeks, investor demo is make-or-break. Creative director gathers context, frames the decision, presents 3 strategic options with honest trade-off analysis, makes recommendation but defers to user, then documents decision with ADR and demo script.
|
||||
|
||||
**Key Collaborative Moments:**
|
||||
- Agent reads context docs before proposing solutions
|
||||
- Asks 5 questions to understand decision constraints
|
||||
- Frames decision properly (what's at stake, evaluation criteria)
|
||||
- Presents 3 options with risk analysis and historical precedent
|
||||
- Makes strong recommendation but explicitly: "this is your call"
|
||||
- Documents decision + provides demo script to support user
|
||||
|
||||
**Learn:**
|
||||
- How leadership agents frame strategic decisions
|
||||
- How to present options with trade-off analysis
|
||||
- How to use game dev precedent and theory in recommendations
|
||||
- How to document decisions (ADRs)
|
||||
- How to cascade decisions to affected departments
|
||||
|
||||
---
|
||||
|
||||
### [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:**
|
||||
|
||||
```
|
||||
Question → Options → Decision → Draft → Approval
|
||||
```
|
||||
|
||||
> **Note:** These examples show the collaborative pattern as conversational text.
|
||||
> In practice, agents now use the `AskUserQuestion` tool at decision points to
|
||||
> present structured option pickers (with labels, descriptions, and multi-select).
|
||||
> The pattern is **Explain → Capture**: agents explain their analysis in
|
||||
> conversation first, then present a structured UI picker for the user's decision.
|
||||
|
||||
### ✅ **Collaborative Behaviors Shown:**
|
||||
|
||||
1. **Agents Ask Before Assuming**
|
||||
- Design agents ask about goals, constraints, references
|
||||
- Implementation agents clarify spec ambiguities
|
||||
- Leadership agents gather full context before recommending
|
||||
|
||||
2. **Agents Present Options, Not Dictates**
|
||||
- 2-4 options with pros/cons
|
||||
- Reasoning based on theory, precedent, project pillars
|
||||
- Recommendation made, but user decides
|
||||
|
||||
3. **Agents Show Work Before Finalizing**
|
||||
- Design drafts shown section-by-section
|
||||
- Architecture proposals shown before implementation
|
||||
- Strategic analysis presented before decisions
|
||||
|
||||
4. **Agents Get Approval Before Writing Files**
|
||||
- Explicit "May I write to [file]?" before using Write/Edit tools
|
||||
- Multi-file changes list all affected files first
|
||||
- User says "Yes" before any file is created
|
||||
|
||||
5. **Agents Iterate on Feedback**
|
||||
- User modifications incorporated immediately
|
||||
- No defensiveness when user changes recommendations
|
||||
- Celebrate when user improves agent's suggestion
|
||||
|
||||
---
|
||||
|
||||
## 📖 **How to Use These Examples**
|
||||
|
||||
### For New Users:
|
||||
Read these examples BEFORE your first session. They show realistic expectations for how agents work:
|
||||
- Agents are consultants, not autonomous executors
|
||||
- You make all creative/strategic decisions
|
||||
- Agents provide expert guidance and options
|
||||
|
||||
### For Understanding Specific Workflows:
|
||||
- **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
|
||||
|
||||
### For Training:
|
||||
If you're teaching someone to use this system, walk through one example turn-by-turn to show:
|
||||
- What good questions look like
|
||||
- How to evaluate presented options
|
||||
- When to approve vs. request changes
|
||||
- How to maintain creative control while leveraging AI expertise
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **Common Patterns Across All Examples**
|
||||
|
||||
### Turn 1-2: **Understand Before Acting**
|
||||
- Agent reads context (design docs, specs, constraints)
|
||||
- Agent asks clarifying questions
|
||||
- No assumptions or guesses
|
||||
|
||||
### Turn 3-5: **Present Options with Reasoning**
|
||||
- 2-4 distinct approaches
|
||||
- Pros/cons for each
|
||||
- Theory/precedent supporting the analysis
|
||||
- Recommendation made, decision deferred to user
|
||||
|
||||
### Turn 6-8: **Iterate on Drafts**
|
||||
- Show work incrementally
|
||||
- Incorporate feedback immediately
|
||||
- Flag edge cases or ambiguities proactively
|
||||
|
||||
### Turn 9-10: **Approval and Completion**
|
||||
- "May I write to [file]?"
|
||||
- User: "Yes"
|
||||
- Agent writes files
|
||||
- Agent offers next steps (tests, review, integration)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Try It Yourself**
|
||||
|
||||
After reading these examples, try this exercise:
|
||||
|
||||
1. Pick one of your game systems (combat, inventory, progression, etc.)
|
||||
2. Ask the relevant agent to design or implement it
|
||||
3. Notice if the agent:
|
||||
- ✅ Asks clarifying questions upfront
|
||||
- ✅ Presents options with reasoning
|
||||
- ✅ Shows drafts before finalizing
|
||||
- ✅ Requests approval before writing files
|
||||
|
||||
If the agent skips any of these, remind it:
|
||||
> "Please follow the collaborative protocol from docs/COLLABORATIVE-DESIGN-PRINCIPLE.md"
|
||||
|
||||
---
|
||||
|
||||
## 📝 **Additional Resources**
|
||||
|
||||
- **Full Principle Documentation:** [docs/COLLABORATIVE-DESIGN-PRINCIPLE.md](../COLLABORATIVE-DESIGN-PRINCIPLE.md)
|
||||
- **Workflow Guide:** [docs/WORKFLOW-GUIDE.md](../WORKFLOW-GUIDE.md)
|
||||
- **Agent Roster:** [.claude/docs/agent-roster.md](../../.claude/docs/agent-roster.md)
|
||||
- **CLAUDE.md (Collaboration Protocol):** [CLAUDE.md](../../CLAUDE.md#collaboration-protocol)
|
||||
121
docs/examples/reverse-document-workflow-example.md
Normal file
121
docs/examples/reverse-document-workflow-example.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# Reverse Documentation Workflow Example
|
||||
|
||||
## Scenario
|
||||
Developer built a working skill tree system but never wrote a design doc.
|
||||
Code exists in `src/gameplay/skills/`, but `design/gdd/` has no skill-system.md.
|
||||
|
||||
---
|
||||
|
||||
## Session Transcript
|
||||
|
||||
**User:**
|
||||
```
|
||||
I have a working skill tree system in src/gameplay/skills/ with about 1200 lines
|
||||
of code. I never wrote a design doc. Can we create one from the implementation?
|
||||
```
|
||||
|
||||
**Game-Designer (reads code, analyzes):**
|
||||
```
|
||||
I've analyzed your skill tree implementation. Here's what I found:
|
||||
|
||||
STRUCTURE:
|
||||
- 3 skill trees: Combat, Survival, Tech
|
||||
- 5 tiers per tree (unlock via level + prerequisites)
|
||||
- Total 45 skills (15 per tree)
|
||||
- Cost: skill points (1 per level, can respec for gold)
|
||||
|
||||
MECHANICS:
|
||||
- Passive skills (stat bonuses)
|
||||
- Active skills (abilities with cooldowns)
|
||||
- Synergy bonuses (cross-tree unlocks at tier 4+)
|
||||
|
||||
IMPLEMENTATION DETAILS:
|
||||
- Data-driven (JSON files in assets/data/skills/)
|
||||
- Save-compatible (skill state serialized)
|
||||
- UI shows locked/unlocked/available states
|
||||
|
||||
QUESTIONS before I draft the design doc:
|
||||
|
||||
1. **Design Intent:** Was the 3-tree structure meant to represent player archetypes
|
||||
(fighter/survivor/engineer) or playstyle flexibility?
|
||||
|
||||
2. **Respec Cost:** Respec costs gold - is this meant to:
|
||||
- Discourage frequent respecs (commitment to builds)?
|
||||
- Create a gold sink (economy balance)?
|
||||
- Or should it be free (experimentation encouraged)?
|
||||
|
||||
3. **Synergy System:** Cross-tree synergies appear at tier 4. Was this:
|
||||
- Intentional (reward hybrid builds late-game)?
|
||||
- Or emergent (accidentally creates hybrid meta)?
|
||||
|
||||
4. **Balance Philosophy:** I see some skills are clearly better (tier-5 passive
|
||||
is +50% damage). Is this:
|
||||
- Power fantasy (late-game should feel OP)?
|
||||
- Or unbalanced (needs tuning)?
|
||||
```
|
||||
|
||||
**User:**
|
||||
```
|
||||
Good questions! Here's the intent:
|
||||
|
||||
1. Yes, the 3 trees are archetypes but I want flexibility
|
||||
2. Respec should be cheap - I want experimentation
|
||||
3. Synergies were intentional - hybrid builds are a feature
|
||||
4. Yeah, tier 5 is meant to be powerful, but +50% might be too much
|
||||
```
|
||||
|
||||
**Game-Designer:**
|
||||
```
|
||||
Perfect, that clarifies the vision. Let me draft the design doc:
|
||||
|
||||
[Shows draft of design/gdd/skill-system.md]
|
||||
|
||||
SECTIONS:
|
||||
1. Overview (3-tree system, hybrid-friendly, respec-encouraged)
|
||||
2. Design Pillars:
|
||||
- Archetype clarity (each tree has identity)
|
||||
- Build flexibility (no lock-in, cheap respec)
|
||||
- Synergy rewards (cross-tree combinations viable)
|
||||
3. Detailed Design (tree structure, unlock rules, respec)
|
||||
4. Balance Framework (tier power curve, synergy limits)
|
||||
5. Edge Cases (respec during combat? max skills? cap?)
|
||||
6. Dependencies (UI, save system, tutorial)
|
||||
7. Acceptance Criteria (all trees viable, 10+ hybrid builds, clear tooltips)
|
||||
8. Open Questions:
|
||||
- Should respec cost scale with level or stay flat?
|
||||
- Tier 5 damage bonus: tune to +30% or keep +50%?
|
||||
|
||||
**May I write this to design/gdd/skill-system.md?**
|
||||
```
|
||||
|
||||
**User:**
|
||||
```
|
||||
Yes, write it. But let's tune tier 5 to +30% and make respec cost scale.
|
||||
```
|
||||
|
||||
**Game-Designer:**
|
||||
```
|
||||
✅ Written to design/gdd/skill-system.md
|
||||
✅ Marked as [REVERSE-DOCUMENTED FROM IMPLEMENTATION]
|
||||
✅ Added TODO: Update tier-5 passive to +30% in assets/data/skills/combat-tree.json
|
||||
✅ Added TODO: Implement scaling respec cost formula
|
||||
|
||||
Next steps:
|
||||
- Run /balance-check to validate skill tree progression curve?
|
||||
- Create ADR documenting why 3 trees instead of 5?
|
||||
- Update tutorial to explain hybrid synergies?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Observations
|
||||
|
||||
1. **Agent asked clarifying questions** - didn't just describe code
|
||||
2. **Separated intent from implementation** - user corrected "accidental" imbalance
|
||||
3. **Design doc captures "why"** - not just "what the code does"
|
||||
4. **Identified missing pieces** - edge cases not in code
|
||||
5. **Flagged follow-up work** - balance tuning, ADRs, tutorial
|
||||
|
||||
## Outcome
|
||||
|
||||
The design doc now exists and **matches reality** while also capturing the **intended vision**. Future changes will reference this doc, and new team members understand the *why* behind decisions.
|
||||
197
docs/examples/session-adopt-brownfield.md
Normal file
197
docs/examples/session-adopt-brownfield.md
Normal file
@@ -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-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.
|
||||
262
docs/examples/session-design-crafting-system.md
Normal file
262
docs/examples/session-design-crafting-system.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Example Session: Designing the Crafting System
|
||||
|
||||
**Context:** Solo indie dev, week 2 of project, needs to design the crafting system mentioned in the game pillars.
|
||||
|
||||
**Starting State:**
|
||||
- Game concept and pillars defined
|
||||
- Engine set up (Godot 4.6)
|
||||
- Core combat system designed but not implemented yet
|
||||
- Pillar 2: "Emergent Discovery Through Experimentation"
|
||||
|
||||
**Session Duration:** ~45 minutes
|
||||
**Turns:** 12
|
||||
**Outcome:** Complete crafting system GDD ready for implementation
|
||||
|
||||
---
|
||||
|
||||
## Turn 1: User Initiates Design
|
||||
|
||||
**User:**
|
||||
> I need to design the crafting system. Pillar 2 is "Emergent Discovery Through Experimentation", so I want players to discover recipes by trying combinations.
|
||||
|
||||
## Turn 2: Agent Asks Clarifying Questions
|
||||
|
||||
**Agent (game-designer):**
|
||||
> I'll help design the crafting system with discovery at its core. Before proposing mechanics, I need to understand your vision:
|
||||
>
|
||||
> 1. **Discovery Method**: Should recipes be pure trial-and-error, or should there be hints/clues to guide players?
|
||||
> 2. **Failure Punishment**: When players try an invalid combination, what happens?
|
||||
> - Materials completely lost (harsh)
|
||||
> - Materials partially refunded (moderate)
|
||||
> - No cost to experiment (forgiving)
|
||||
> 3. **Progression**: Does crafting skill improve over time? If so, what does higher skill unlock?
|
||||
> 4. **Scope**: How central is crafting to the game? Core pillar feature or supporting system?
|
||||
> 5. **Reference Games**: Any crafting systems you love or hate? (Minecraft, Terraria, Stardew Valley, Potion Craft?)
|
||||
|
||||
## Turn 3: User Provides Context
|
||||
|
||||
**User:**
|
||||
> 1. I want hints that unlock gradually - start with pure discovery, earn hints through skill
|
||||
> 2. Moderate punishment - waste materials but gain partial XP
|
||||
> 3. Yes, skill unlocks hint system and improves success rates
|
||||
> 4. Core feature - one of the three main loops (combat, exploration, crafting)
|
||||
> 5. Love Potion Craft's deduction mechanic. Hate Minecraft wikis being mandatory.
|
||||
|
||||
## Turn 4: Agent Presents Options
|
||||
|
||||
**Agent:**
|
||||
> Perfect context! Based on "emergent discovery" + "deduction over wikis" + "Potion Craft inspiration", here are three mechanical approaches:
|
||||
>
|
||||
> **Option A: Pure Randomized Discovery**
|
||||
> - **Mechanics**: Try any 2-4 ingredient combo, roll for success based on compatibility
|
||||
> - **Hint System**: None - players document discoveries manually
|
||||
> - **Pros**:
|
||||
> - Maximum emergent discovery
|
||||
> - Community can share findings without breaking core loop
|
||||
> - Aligns strongly with "experimentation" pillar
|
||||
> - **Cons**:
|
||||
> - High frustration for completionists
|
||||
> - Low skill expression (mostly RNG)
|
||||
> - Players may feel "wiki is required" despite your intent
|
||||
> - **Aligns with Pillars**: ✅✅ Emergent Discovery, ⚠️ Meaningful Choices (randomness reduces agency)
|
||||
>
|
||||
> **Option B: Tag-Based Deduction System (Potion Craft-style)**
|
||||
> - **Mechanics**: Each ingredient has hidden "tags" (Fire, Water, Healing, Damage, etc.)
|
||||
> - Recipes require specific tag combinations
|
||||
> - At Skill 0: No tags visible, pure experimentation
|
||||
> - At Skill 5: Can inspect items to see 1 tag
|
||||
> - At Skill 10: See 2 tags, etc.
|
||||
> - **Hint System**: Tags ARE the hint system, unlocked by skill
|
||||
> - **Pros**:
|
||||
> - Rewards observation and pattern recognition (skill expression!)
|
||||
> - Progressive scaffolding - accessible to all player types
|
||||
> - Creates "aha!" moments when patterns click
|
||||
> - No wiki needed - everything discoverable in-game
|
||||
> - **Cons**:
|
||||
> - More complex to implement (tag system + UI)
|
||||
> - Requires careful tag design to avoid degeneracy
|
||||
> - **Aligns with Pillars**: ✅✅ Emergent Discovery, ✅✅ Meaningful Choices
|
||||
>
|
||||
> **Option C: Ingredient Compatibility Matrix**
|
||||
> - **Mechanics**: Each ingredient pairs well/poorly with others
|
||||
> - Success rate = compatibility score
|
||||
> - Skill 0: No compatibility shown, ~30% base success
|
||||
> - Higher skill: See color-coded compatibility (red/yellow/green)
|
||||
> - **Hint System**: Visual compatibility indicators unlock with skill
|
||||
> - **Pros**:
|
||||
> - Simple to implement and understand
|
||||
> - Clear progression arc (skill = more information)
|
||||
> - Feels fair (players understand why they failed)
|
||||
> - **Cons**:
|
||||
> - Less emergent than tag system (more prescriptive)
|
||||
> - Optimal recipes more obvious once you have hints
|
||||
> - **Aligns with Pillars**: ✅ Emergent Discovery, ✅ Meaningful Choices
|
||||
>
|
||||
> **My Recommendation: Option B (Tag-Based Deduction)**
|
||||
>
|
||||
> **Reasoning:**
|
||||
> - It's the only option that creates TRUE emergent discovery through systems interaction
|
||||
> - Players develop mastery by learning tag patterns, not memorizing recipes
|
||||
> - The progressive reveal (tags unlock with skill) serves both Explorers (discovery) and Achievers (progression)
|
||||
> - Potion Craft proved this works and is satisfying
|
||||
> - Avoids wiki-dependency because the deduction is solvable in-game
|
||||
>
|
||||
> Which option resonates with your vision? Or should I explore a hybrid?
|
||||
|
||||
## Turn 5: User Decides with Modification
|
||||
|
||||
**User:**
|
||||
> Option B feels perfect, but I want to add: failed attempts should give hints about which tags were WRONG, not just which were right. Like "You added Fire, but this recipe needs Water instead."
|
||||
|
||||
## Turn 6: Agent Incorporates Feedback and Drafts
|
||||
|
||||
**Agent:**
|
||||
> Excellent modification! That adds a deduction game on TOP of the tag discovery. Now failed attempts aren't just "waste" - they're valuable information.
|
||||
>
|
||||
> Let me draft the **Overview** and **Player Fantasy** sections:
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> ## Overview
|
||||
>
|
||||
> The crafting system uses a tag-based deduction mechanic where players experiment with ingredient combinations to discover recipes. Each ingredient has 1-3 hidden tags (Fire, Water, Earth, Air, Healing, Damage, Poison, etc.). Recipes require specific tag combinations. Failed attempts waste materials but provide feedback ("This needs Water, not Fire") that teaches players tag patterns. As crafting skill increases, players unlock the ability to inspect ingredients to see their tags directly, transforming pure experimentation into informed deduction.
|
||||
>
|
||||
> ## Player Fantasy
|
||||
>
|
||||
> "I'm an alchemist-scientist discovering nature's hidden patterns. Each failed potion teaches me something new about how elements interact. Over time, I develop intuition - I can look at a mushroom and KNOW it contains Earth and Poison tags before even testing it. I don't need recipes from a wiki; I understand the RULES that generate recipes, and I can create my own solutions."
|
||||
>
|
||||
> **Target MDA Aesthetics**:
|
||||
> - Discovery (primary): Uncovering hidden tag patterns
|
||||
> - Challenge (secondary): Deduction puzzle
|
||||
> - Expression (tertiary): Creating custom recipes once rules are mastered
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> Does this capture your intent? Should I continue to **Detailed Rules**?
|
||||
|
||||
## Turn 7: User Approves and Requests Next Section
|
||||
|
||||
**User:**
|
||||
> Yes, that's perfect! Continue to Detailed Rules.
|
||||
|
||||
## Turn 8: Agent Drafts Rules, Asks About Edge Case
|
||||
|
||||
**Agent:**
|
||||
> Drafting Detailed Rules...
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> ## Detailed Rules
|
||||
>
|
||||
> ### Core Loop
|
||||
> 1. Player selects 2-4 ingredients from inventory
|
||||
> 2. Player activates crafting station
|
||||
> 3. System checks ingredient tags against recipe database
|
||||
> 4. **If exact tag match**: Success! Recipe learned, item created, full XP awarded
|
||||
> 5. **If partial match** (some tags correct): Failure. Feedback: "Close! This needs [missing tag]." Materials consumed, 40% XP awarded, recipe marked as "Discovered (Incomplete)"
|
||||
> 6. **If no match**: Failure. Feedback: "Incompatible. Try replacing [wrong tag] with [needed tag]." Materials consumed, 15% XP awarded
|
||||
>
|
||||
> ### Tag System
|
||||
> - 12 core tags: Fire, Water, Earth, Air, Healing, Damage, Poison, Light, Dark, Metal, Plant, Magic
|
||||
> - Each ingredient has 1-3 tags (simple ingredients have 1, rare ingredients have 3)
|
||||
> - Each recipe requires 2-6 total tags (basic potions need 2, advanced need 6)
|
||||
> - Tag combinations must be unique (no two recipes with identical tag sets)
|
||||
>
|
||||
> ### Skill Progression
|
||||
> - Skill 0-4: No inspection ability. Pure experimentation.
|
||||
> - Skill 5-9: Can inspect ingredients to see 1 tag
|
||||
> - Skill 10-14: Can see 2 tags per ingredient
|
||||
> - Skill 15+: Can see all tags per ingredient
|
||||
>
|
||||
> ### XP Gain
|
||||
> ```
|
||||
> success_xp = base_xp * recipe_complexity^1.3
|
||||
> failure_xp_partial = success_xp * 0.40
|
||||
> failure_xp_none = success_xp * 0.15
|
||||
> ```
|
||||
>
|
||||
> Where `recipe_complexity` = number of unique tags required (2-6)
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> **Question before I continue:** What happens if a player discovers a tag combination that DOESN'T match any recipe in the database? Should we:
|
||||
> A) Allow it and create "junk items" (player wasted materials)
|
||||
> B) Always provide feedback steering toward valid recipes
|
||||
> C) Procedurally generate a minor potion for any valid tag combo not in the DB
|
||||
>
|
||||
> This affects the "experimentation" feel - option A is harsh but realistic, option C rewards all experimentation.
|
||||
|
||||
## Turn 9: User Resolves Edge Case
|
||||
|
||||
**User:**
|
||||
> Option C - let's procedurally generate minor potions. If someone finds Fire+Water (not a designed recipe), give them "Warm Water" that restores 5 HP. Rewards experimentation even when "off the beaten path."
|
||||
|
||||
## Turn 10: Agent Completes Remaining Sections
|
||||
|
||||
**Agent:**
|
||||
> Perfect! That keeps experimentation always rewarding. Updating rules with that edge case...
|
||||
>
|
||||
> [Agent continues drafting Formulas, Edge Cases, Dependencies, Tuning Knobs, and Acceptance Criteria sections, showing each and incorporating minor feedback]
|
||||
>
|
||||
> [After all sections complete]
|
||||
>
|
||||
> Complete crafting system GDD ready. Here's the summary:
|
||||
>
|
||||
> **8 Required Sections:**
|
||||
> ✅ Overview - Tag-based deduction system
|
||||
> ✅ Player Fantasy - Alchemist-scientist discovering patterns
|
||||
> ✅ Detailed Rules - Core loop with tag matching and feedback system
|
||||
> ✅ Formulas - XP curves, success rates, skill thresholds
|
||||
> ✅ Edge Cases - Procedural minor potions for non-recipe combos, inventory full, skill at max
|
||||
> ✅ Dependencies - Requires inventory system, integrates with progression system
|
||||
> ✅ Tuning Knobs - XP rates, skill thresholds, tag count per ingredient, feedback verbosity
|
||||
> ✅ Acceptance Criteria - Players discover 10 recipes in 30 minutes without wiki, skill progression feels meaningful
|
||||
>
|
||||
> **Delegations Made:**
|
||||
> - Consulted `systems-designer` for XP curve formula validation
|
||||
> - Consulted `economy-designer` for material cost balancing
|
||||
>
|
||||
> May I write this to `design/gdd/crafting-system.md`?
|
||||
|
||||
## Turn 11: User Approves Writing
|
||||
|
||||
**User:**
|
||||
> Yes, write it!
|
||||
|
||||
## Turn 12: Agent Writes File and Offers Next Steps
|
||||
|
||||
**Agent:**
|
||||
> ✅ Created `design/gdd/crafting-system.md`
|
||||
>
|
||||
> **Next Steps:**
|
||||
> 1. Run `/design-review design/gdd/crafting-system.md` to validate against 8-section standard
|
||||
> 2. Create data file structure in `assets/data/` for ingredients and recipes
|
||||
> 3. When ready to implement, use `/team-combat` pattern but for crafting (game-designer → gameplay-programmer → ui-programmer → qa-tester)
|
||||
>
|
||||
> Would you like me to run the design review now, or would you prefer to read it first?
|
||||
|
||||
---
|
||||
|
||||
## Session Summary
|
||||
|
||||
**What Worked Well:**
|
||||
- Agent asked clarifying questions upfront instead of guessing
|
||||
- Presented 3 distinct options with clear pros/cons and pillar alignment
|
||||
- User's modification ("wrong tag feedback") was incorporated immediately
|
||||
- Edge case (non-recipe combos) was flagged proactively, not assumed
|
||||
- Each section was shown for approval before moving to next
|
||||
- Explicit permission requested before writing file
|
||||
|
||||
**Key Collaborative Moments:**
|
||||
- Turn 2: Agent asked 5 questions to understand vision
|
||||
- Turn 4: Agent presented 3 options, made recommendation but deferred to user
|
||||
- Turn 5: User modified recommended option, agent incorporated it
|
||||
- Turn 8: Agent caught edge case and asked rather than assuming
|
||||
- Turn 9: User's choice (procedural potions) changed design direction
|
||||
- Turn 10: Agent requested approval before writing file
|
||||
|
||||
**Files Created:**
|
||||
- `design/gdd/crafting-system.md` (complete 8-section GDD)
|
||||
|
||||
**Context Usage:** ~35% (estimated)
|
||||
**User Satisfaction:** High - user made all creative decisions, agent provided expert guidance
|
||||
269
docs/examples/session-design-system-skill.md
Normal file
269
docs/examples/session-design-system-skill.md
Normal file
@@ -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
|
||||
152
docs/examples/session-gate-check-phase-transition.md
Normal file
152
docs/examples/session-gate-check-phase-transition.md
Normal file
@@ -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.
|
||||
296
docs/examples/session-implement-combat-damage.md
Normal file
296
docs/examples/session-implement-combat-damage.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Example Session: Implementing Combat Damage Calculation
|
||||
|
||||
**Context:** Solo indie dev, week 4 of project, implementing gameplay systems.
|
||||
|
||||
**Starting State:**
|
||||
- `design/gdd/combat-system.md` exists and reviewed
|
||||
- Godot 4.6 project set up with basic scene structure
|
||||
- No gameplay code written yet
|
||||
- Sprint goal: "Implement core combat damage calculation"
|
||||
|
||||
**Session Duration:** ~30 minutes
|
||||
**Turns:** 10
|
||||
**Outcome:** Working damage calculator with tests, ready for integration
|
||||
|
||||
---
|
||||
|
||||
## Turn 1: User Requests Implementation
|
||||
|
||||
**User:**
|
||||
> Implement the damage calculation system from design/gdd/combat-system.md. The formula is in section 4.
|
||||
|
||||
## Turn 2: Agent Reads Design and Asks Clarifying Questions
|
||||
|
||||
**Agent (gameplay-programmer):**
|
||||
> I've read `design/gdd/combat-system.md`. The damage formula is:
|
||||
>
|
||||
> ```
|
||||
> final_damage = base_damage * (1 + attack_stat * 0.1) * crit_multiplier * type_effectiveness * (1 - target_defense)
|
||||
> ```
|
||||
>
|
||||
> Before implementing, I need to clarify some details that aren't specified in the doc:
|
||||
>
|
||||
> **Architecture Questions:**
|
||||
> 1. Should `DamageCalculator` be a static utility class (no state, just calculations) or an autoload singleton?
|
||||
> 2. Where should `base_damage` come from? (Weapon data? Character stats? Ability data?)
|
||||
> 3. Where should `type_effectiveness` values live? (Per weapon? Per damage type? Separate data file?)
|
||||
>
|
||||
> **Spec Ambiguities:**
|
||||
> 4. Should `attack_stat` be clamped to a range? (Prevents exponential scaling bugs)
|
||||
> 5. The doc says "critical hits do 2x damage" but doesn't specify rounding. Should I `floor()`, `ceil()`, or `round()` the final damage?
|
||||
> 6. What happens if `target_defense` >= 1.0? (100% mitigation or higher) Should damage go negative or clamp to 0?
|
||||
>
|
||||
> **Integration:**
|
||||
> 7. I don't see a design doc for the Health/HP system. Should I create a minimal one, or is that coming separately?
|
||||
>
|
||||
> Please clarify so I can implement this correctly the first time.
|
||||
|
||||
## Turn 3: User Resolves Ambiguities
|
||||
|
||||
**User:**
|
||||
> 1. Static utility - no state needed
|
||||
> 2. Base damage from Weapon resource. I'll create a simple Weapon class.
|
||||
> 3. Type effectiveness in a separate data file `assets/data/combat_damage.json`
|
||||
> 4. Yes, clamp attack_stat to 0-100
|
||||
> 5. Use `floor()` to round down to integers
|
||||
> 6. Clamp damage to minimum of 1 (always do at least 1 damage, even with 100% defense)
|
||||
> 7. Create a minimal health component - just current_hp, max_hp, and take_damage() method
|
||||
|
||||
## Turn 4: Agent Proposes Architecture
|
||||
|
||||
**Agent:**
|
||||
> Got it! Here's my proposed architecture:
|
||||
>
|
||||
> **Files I'll create:**
|
||||
> ```
|
||||
> src/gameplay/combat/damage_calculator.gd # Static damage formula
|
||||
> src/gameplay/combat/health_component.gd # HP tracking node component
|
||||
> src/gameplay/combat/weapon.gd # Weapon resource
|
||||
> assets/data/combat_damage.json # Type effectiveness values
|
||||
> design/gdd/health-system.md # Minimal health doc
|
||||
> tests/combat/test_damage_calculator.gd # Unit tests
|
||||
> ```
|
||||
>
|
||||
> **Architecture Details:**
|
||||
>
|
||||
> **DamageCalculator** (static class):
|
||||
> ```gdscript
|
||||
> class_name DamageCalculator
|
||||
> extends RefCounted
|
||||
>
|
||||
> static func calculate_damage(
|
||||
> attacker_stats: Dictionary,
|
||||
> weapon: Weapon,
|
||||
> defender_stats: Dictionary,
|
||||
> is_crit: bool = false
|
||||
> ) -> int:
|
||||
> # Implementation here
|
||||
> return floori(final_damage)
|
||||
> ```
|
||||
>
|
||||
> **HealthComponent** (node component):
|
||||
> ```gdscript
|
||||
> extends Node
|
||||
> class_name HealthComponent
|
||||
>
|
||||
> signal health_changed(old_hp: int, new_hp: int)
|
||||
> signal died()
|
||||
>
|
||||
> @export var max_hp: int = 100
|
||||
> var current_hp: int:
|
||||
> set(value):
|
||||
> # Clamp and emit signals
|
||||
>
|
||||
> func take_damage(amount: int) -> void:
|
||||
> current_hp -= amount
|
||||
> if current_hp <= 0:
|
||||
> died.emit()
|
||||
> ```
|
||||
>
|
||||
> **Weapon** (resource):
|
||||
> ```gdscript
|
||||
> extends Resource
|
||||
> class_name Weapon
|
||||
>
|
||||
> @export var base_damage: float
|
||||
> @export var damage_type: String # "physical", "fire", "ice", etc.
|
||||
> ```
|
||||
>
|
||||
> **combat_damage.json**:
|
||||
> ```json
|
||||
> {
|
||||
> "crit_multiplier": 2.0,
|
||||
> "attack_stat_min": 0,
|
||||
> "attack_stat_max": 100,
|
||||
> "type_effectiveness": {
|
||||
> "physical": { "armored": 0.5, "flesh": 1.0, "crystal": 1.5 },
|
||||
> "fire": { "armored": 1.0, "flesh": 1.2, "crystal": 0.3 }
|
||||
> }
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> **Question:** This architecture makes `DamageCalculator` easily testable (pure function, no dependencies). The `HealthComponent` uses signals for VFX/SFX hookup. Does this match your expectations, or should I change anything before implementing?
|
||||
|
||||
## Turn 5: User Approves with Minor Change
|
||||
|
||||
**User:**
|
||||
> Looks good, but change `attacker_stats` and `defender_stats` to proper typed dictionaries or classes. I don't want untyped Dictionary bags floating around.
|
||||
|
||||
## Turn 6: Agent Refines Architecture
|
||||
|
||||
**Agent:**
|
||||
> Absolutely - type safety is important. I'll create a `CharacterStats` resource:
|
||||
>
|
||||
> ```gdscript
|
||||
> extends Resource
|
||||
> class_name CharacterStats
|
||||
>
|
||||
> @export var attack_stat: int = 0 # 0-100
|
||||
> @export var defense: float = 0.0 # 0.0-1.0 (0-100% mitigation)
|
||||
> @export var armor_type: String = "flesh" # for type effectiveness lookup
|
||||
> ```
|
||||
>
|
||||
> Then `DamageCalculator.calculate_damage()` signature becomes:
|
||||
> ```gdscript
|
||||
> static func calculate_damage(
|
||||
> attacker: CharacterStats,
|
||||
> weapon: Weapon,
|
||||
> defender: CharacterStats,
|
||||
> is_crit: bool = false
|
||||
> ) -> int
|
||||
> ```
|
||||
>
|
||||
> Much cleaner. May I proceed with implementation?
|
||||
|
||||
## Turn 7: User Approves Implementation
|
||||
|
||||
**User:**
|
||||
> Yes, implement it.
|
||||
|
||||
## Turn 8: Agent Implements and Reports
|
||||
|
||||
**Agent:**
|
||||
> Implementation complete! Here's what I created:
|
||||
>
|
||||
> **Files Created:**
|
||||
> - ✅ `src/gameplay/combat/damage_calculator.gd` (82 lines)
|
||||
> - ✅ `src/gameplay/combat/health_component.gd` (45 lines)
|
||||
> - ✅ `src/gameplay/combat/weapon.gd` (12 lines)
|
||||
> - ✅ `src/gameplay/combat/character_stats.gd` (16 lines)
|
||||
> - ✅ `assets/data/combat_damage.json` (validated JSON)
|
||||
> - ✅ `design/gdd/health-system.md` (minimal 8-section doc)
|
||||
>
|
||||
> **Rules Enforcement Results:**
|
||||
>
|
||||
> The `gameplay-code` rule automatically flagged 2 issues during implementation:
|
||||
> 1. ❌ `crit_multiplier` was hardcoded as `2.0` in damage_calculator.gd
|
||||
> - **Fixed:** Moved to `combat_damage.json` and loaded from config
|
||||
> 2. ❌ `HealthComponent` had direct `print()` debug output
|
||||
> - **Fixed:** Removed hardcoded debug, added proper signals instead
|
||||
>
|
||||
> The `data-files` rule validated:
|
||||
> - ✅ `combat_damage.json` is valid JSON
|
||||
> - ✅ Naming convention matches `[system]_[name].json`
|
||||
> - ✅ All values have comment documentation
|
||||
>
|
||||
> **Implementation Notes:**
|
||||
> - Attack stat is clamped in `calculate_damage()` before use
|
||||
> - Damage always returns minimum of 1 (per your requirement)
|
||||
> - Type effectiveness defaults to 1.0 if combo not found in config
|
||||
> - All numeric values loaded from `combat_damage.json` for designer tuning
|
||||
>
|
||||
> **Manual Testing:**
|
||||
> I created a quick test scene and validated:
|
||||
> - Base damage: 10, attack_stat: 50 → Damage: 15 ✓
|
||||
> - Same but with crit → Damage: 30 ✓
|
||||
> - With 50% defense → Damage: 15 (before defense) → 7 (after) ✓
|
||||
> - With 100% defense → Damage: 1 (clamped) ✓
|
||||
>
|
||||
> **Next Steps - Your Choice:**
|
||||
> A) I can write formal unit tests now (recommended - verification-driven development)
|
||||
> B) You can review the code first via `/code-review src/gameplay/combat/damage_calculator.gd`
|
||||
> C) Skip tests for now and integrate into actual combat
|
||||
>
|
||||
> What would you like?
|
||||
|
||||
## Turn 9: User Requests Tests
|
||||
|
||||
**User:**
|
||||
> A - write unit tests. Cover all the edge cases.
|
||||
|
||||
## Turn 10: Agent Writes Tests and Completes
|
||||
|
||||
**Agent:**
|
||||
> Unit tests created: `tests/combat/test_damage_calculator.gd`
|
||||
>
|
||||
> **Test Coverage (8 tests):**
|
||||
> ```
|
||||
> ✓ test_damage_basic_calculation() - Verify formula with known values
|
||||
> ✓ test_damage_with_crit() - Critical hits double damage
|
||||
> ✓ test_damage_with_defense() - Defense reduces damage correctly
|
||||
> ✓ test_damage_type_effectiveness() - Type modifiers apply
|
||||
> ✓ test_damage_min_clamp() - Never goes below 1
|
||||
> ✓ test_damage_attack_stat_clamp() - Attack stat clamped to 0-100
|
||||
> ✓ test_damage_missing_type_combo() - Defaults to 1.0 if not in config
|
||||
> ✓ test_damage_rounding() - Verifies floor() behavior
|
||||
> ```
|
||||
>
|
||||
> **Test Results:**
|
||||
> ```
|
||||
> Running tests/combat/test_damage_calculator.gd...
|
||||
> ✓ All 8 tests PASSED
|
||||
> Execution time: 12ms
|
||||
> ```
|
||||
>
|
||||
> **Code Review Self-Check:**
|
||||
> - ✅ All tests follow `test_[system]_[scenario]_[expected]` naming
|
||||
> - ✅ Arrange/Act/Assert structure used
|
||||
> - ✅ No external state dependencies
|
||||
> - ✅ Each test is independent and can run in any order
|
||||
>
|
||||
> **System is ready for integration!**
|
||||
>
|
||||
> Files you can now commit:
|
||||
> ```bash
|
||||
> git add src/gameplay/combat/*.gd
|
||||
> git add assets/data/combat_damage.json
|
||||
> git add design/gdd/health-system.md
|
||||
> git add tests/combat/test_damage_calculator.gd
|
||||
> git commit -m "Implement damage calculation system per design/gdd/combat-system.md"
|
||||
> ```
|
||||
>
|
||||
> The `validate-commit` hook will check:
|
||||
> - ✅ Design doc referenced in message
|
||||
> - ✅ JSON validity
|
||||
> - ✅ No hardcoded values (already fixed)
|
||||
>
|
||||
> Ready to commit?
|
||||
|
||||
---
|
||||
|
||||
## Session Summary
|
||||
|
||||
**What Worked Well:**
|
||||
- Agent read design doc first, identified 7 ambiguities upfront
|
||||
- Didn't assume or guess - asked for clarification on every unclear point
|
||||
- Proposed full architecture for user approval before writing code
|
||||
- Incorporated user's type safety feedback immediately
|
||||
- Rules caught issues automatically and agent fixed them transparently
|
||||
- Tests written proactively following verification-driven development
|
||||
- Agent offered next-step options rather than assuming what user wants
|
||||
|
||||
**Key Collaborative Moments:**
|
||||
- Turn 2: Agent identified 7 spec gaps and asked rather than guessing
|
||||
- Turn 4: Full architecture proposal shown before implementation
|
||||
- Turn 5: User requested type safety, agent adapted
|
||||
- Turn 8: Agent transparently reported rule violations and fixes
|
||||
- Turn 10: Agent verified all acceptance criteria with tests
|
||||
|
||||
**Files Created:**
|
||||
- 4 source files (damage_calculator, health_component, weapon, character_stats)
|
||||
- 1 config file (combat_damage.json)
|
||||
- 1 design doc (health-system.md)
|
||||
- 1 test file (test_damage_calculator.gd)
|
||||
|
||||
**Context Usage:** ~25% (focused implementation task)
|
||||
**User Satisfaction:** High - spec ambiguities resolved early, no rework needed
|
||||
360
docs/examples/session-scope-crisis-decision.md
Normal file
360
docs/examples/session-scope-crisis-decision.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# Example Session: Scope Crisis - Strategic Decision Making
|
||||
|
||||
**Context:** Solo indie dev, week 8 of project (month 2), approaching Alpha milestone.
|
||||
|
||||
**Crisis:**
|
||||
- Alpha milestone is in 2 weeks
|
||||
- Crafting system (Pillar 2) not yet implemented
|
||||
- Lead programmer says full crafting will take 3 weeks
|
||||
- Investor demo at Alpha - must show all pillars
|
||||
|
||||
**Session Duration:** ~25 minutes
|
||||
**Turns:** 8
|
||||
**Outcome:** Strategic scope decision with documented ADR
|
||||
|
||||
---
|
||||
|
||||
## Turn 1: User Escalates Problem to Creative Director
|
||||
|
||||
**User:**
|
||||
> We have a problem. Alpha is in 2 weeks. The crafting system (Pillar 2 "Emergent Discovery") isn't implemented yet. Lead programmer says it'll take 3 weeks to implement fully. But the investor demo is at Alpha and they need to see both pillars (Combat + Crafting). What should I do?
|
||||
|
||||
## Turn 2: Creative Director Gathers Full Context
|
||||
|
||||
**Agent (creative-director):**
|
||||
> This is a classic pillar vs. schedule conflict - exactly what I'm here to help resolve. Let me gather the full context before recommending options.
|
||||
>
|
||||
> First, let me review the relevant documents:
|
||||
> - `production/milestones/alpha.md` (milestone definition)
|
||||
> - `design/pillars.md` (what's non-negotiable)
|
||||
> - `design/gdd/crafting-system.md` (what was designed)
|
||||
> - `production/sprints/sprint-current.md` (current work)
|
||||
>
|
||||
> [Reads documents]
|
||||
>
|
||||
> **Context Understood:**
|
||||
> - Pillar 2: "Emergent Discovery Through Experimentation" (crafting is primary expression)
|
||||
> - Alpha success criteria: "All pillars demonstrated in playable form"
|
||||
> - Investor demo purpose: Validate vision and secure next funding round
|
||||
> - Current crafting design: Tag-based deduction system with 12 tags, ~50 recipes, progressive hint unlocking
|
||||
>
|
||||
> **Clarifying Questions:**
|
||||
> 1. Is the Alpha date **hard** (investor won't reschedule) or **soft** (we could ask for 1 more week)?
|
||||
> 2. What's the **minimum crafting** that still demonstrates Pillar 2? (One recipe? Ten recipes? Full tag system?)
|
||||
> 3. What **breaks** if crafting is cut entirely from Alpha? (Does the game still make sense?)
|
||||
> 4. How **critical** is this investor relationship? (Nice-to-have funding vs. make-or-break for project survival?)
|
||||
> 5. What's the **team status**? (Burned out from crunch? Fresh and could push if needed?)
|
||||
|
||||
## Turn 3: User Provides Decision Context
|
||||
|
||||
**User:**
|
||||
> 1. Hard date - investor flying in specifically for demo, can't reschedule
|
||||
> 2. I think minimum is: discovery mechanic working (tag system) + 10 recipes. Doesn't need polish.
|
||||
> 3. Without crafting, Alpha only shows combat. That's 50% of the vision - investor might think it's just another combat game
|
||||
> 4. Make-or-break. This investor is our only lead. No funding = project dies.
|
||||
> 5. Just me solo, I'm not burned out yet.
|
||||
|
||||
## Turn 4: Creative Director Frames the Decision
|
||||
|
||||
**Agent:**
|
||||
> Thank you. Now I understand what's truly at stake. Let me frame this decision properly:
|
||||
>
|
||||
> **The Core Question:**
|
||||
> Do we deliver full crafting and slip Alpha, deliver simplified crafting and make Alpha, or cut crafting and risk the investor not seeing our full vision?
|
||||
>
|
||||
> **What's Really at Stake:**
|
||||
> - **Vision Integrity**: Can investor see Pillar 2 at all?
|
||||
> - **Schedule Trust**: Do we keep our commitment to Alpha date?
|
||||
> - **Project Survival**: No funding = no game
|
||||
> - **Quality Standards**: Is "rough but working" acceptable for this demo?
|
||||
>
|
||||
> **Decision Criteria (in priority order for this scenario):**
|
||||
> 1. **Investor Confidence** (highest - project survival depends on this)
|
||||
> 2. **Pillar Representation** (high - they need to see the full vision)
|
||||
> 3. **Schedule Integrity** (medium - matters, but less than funding)
|
||||
> 4. **Polish Quality** (lowest - vertical slice can be rough)
|
||||
>
|
||||
> Now let me present three strategic options...
|
||||
|
||||
## Turn 5: Creative Director Presents Options with Analysis
|
||||
|
||||
**Agent:**
|
||||
> **Option A: Implement Full Crafting System (3 weeks, slip Alpha by 1 week)**
|
||||
>
|
||||
> **Execution:**
|
||||
> - Implement complete tag-based system with all 50 recipes
|
||||
> - Full UI polish, all features from GDD
|
||||
> - Miss Alpha date, reschedule investor demo (+1 week)
|
||||
>
|
||||
> **Pros:**
|
||||
> - ✅ Pillar 2 fully represented with production quality
|
||||
> - ✅ No design compromises
|
||||
> - ✅ First impression is polished
|
||||
>
|
||||
> **Cons:**
|
||||
> - ❌ Breaks investor commitment (they're flying in for the original date)
|
||||
> - ❌ Signals schedule management issues ("if they slipped Alpha, will they slip release?")
|
||||
> - ❌ May damage investor trust more than rough demo would
|
||||
>
|
||||
> **Risk: CRITICAL**
|
||||
> - Investor may not reschedule (busy schedule, other opportunities)
|
||||
> - Even if they do, the slip damages credibility
|
||||
> - Unlikely to succeed given hard date constraint
|
||||
>
|
||||
> **Verdict: NOT RECOMMENDED** - The date is hard and non-negotiable
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> **Option B: Simplify Crafting to Core Pillar (1.5 weeks, make Alpha)**
|
||||
>
|
||||
> **Execution:**
|
||||
> - Implement core tag discovery mechanic ONLY
|
||||
> - 10 recipes instead of 50 (enough to demonstrate the system)
|
||||
> - Basic UI (functional, not polished)
|
||||
> - No progressive hint unlock (all tags visible at Skill 0 for demo clarity)
|
||||
> - No failed-attempt feedback system (just success/fail)
|
||||
>
|
||||
> **Scope: "Vertical Slice of Pillar 2"**
|
||||
> - Players CAN discover recipes by combining tagged ingredients
|
||||
> - Players CAN learn tag patterns and deduce new recipes
|
||||
> - The SOUL of Pillar 2 is present, just unpolished
|
||||
>
|
||||
> **Pros:**
|
||||
> - ✅ Makes Alpha deadline (schedule integrity maintained)
|
||||
> - ✅ Pillar 2 demonstrated (investor sees full vision)
|
||||
> - ✅ Core mechanic is playable and provable
|
||||
> - ✅ Can use "Alpha → Beta improvement" as narrative ("here's rough, here's polished")
|
||||
>
|
||||
> **Cons:**
|
||||
> - ⚠️ First impression is "rough" (but vertical slices are expected to be rough)
|
||||
> - ⚠️ Investor might think "this feels small" (mitigation: present roadmap showing post-Alpha expansion)
|
||||
>
|
||||
> **Risk: MEDIUM**
|
||||
> - Investor might not "get" the pillar from 10 recipes (mitigation: good demo script explaining the vision)
|
||||
> - Might feel incomplete (mitigation: frame as "vertical slice proving the concept")
|
||||
>
|
||||
> **Verdict: RECOMMENDED** - Balances all constraints
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> **Option C: Cut Crafting from Alpha, Focus on Combat Polish (0 weeks, make Alpha)**
|
||||
>
|
||||
> **Execution:**
|
||||
> - Deliver Alpha with only Pillar 1 (Combat) fully polished
|
||||
> - Use extra 2 weeks to super-polish combat, add content, make it shine
|
||||
> - Present crafting as "design doc + concept art" (not playable)
|
||||
>
|
||||
> **Pros:**
|
||||
> - ✅ Makes deadline with zero stress
|
||||
> - ✅ What's there is AAA-polished
|
||||
> - ✅ No risk of "half-baked" perception
|
||||
>
|
||||
> **Cons:**
|
||||
> - ❌ Pillar 2 not demonstrated (50% of vision missing)
|
||||
> - ❌ Investor sees "another combat game" - not differentiated
|
||||
> - ❌ Harder to secure funding for "potential" vs. "proven concept"
|
||||
> - ❌ If combat alone doesn't wow them, we have no fallback
|
||||
>
|
||||
> **Risk: HIGH**
|
||||
> - Investor won't see what makes this game special
|
||||
> - They might think "Combat is fine, but where's the hook?"
|
||||
> - Competing games have combat - we need to show our differentiator
|
||||
>
|
||||
> **Verdict: NOT RECOMMENDED** - Too risky for make-or-break demo
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> ## My Recommendation: Option B (Simplified Crafting Core)
|
||||
>
|
||||
> **Reasoning:**
|
||||
> 1. **Investor Confidence**: Making the date we committed to shows reliability
|
||||
> 2. **Pillar Visibility**: Rough but working > polished but missing. Investors back VISION, not polish.
|
||||
> 3. **Demo Narrative**: "Here's Alpha vs. Beta progression" is compelling - shows trajectory
|
||||
> 4. **Risk Mitigation**: If crafting doesn't land, combat is still solid. If we cut crafting (Option C) and combat doesn't wow them alone, we have nothing.
|
||||
> 5. **Historical Precedent**: Hades, Dead Cells, Slay the Spire all showed rough Early Access verticals and investors loved the SYSTEMS over polish
|
||||
>
|
||||
> **What Option B Sacrifices:**
|
||||
> - Polish (acceptable for vertical slice)
|
||||
> - Feature completeness (50 recipes → 10)
|
||||
> - Progressive unlocks (deferred to post-Alpha)
|
||||
>
|
||||
> **What Option B Protects:**
|
||||
> - Schedule trust
|
||||
> - Pillar representation
|
||||
> - Vision clarity
|
||||
> - Project survival (funding secured)
|
||||
>
|
||||
> **Implementation Plan if you choose Option B:**
|
||||
> 1. I'll create an ADR documenting this scope decision
|
||||
> 2. I'll update `design/gdd/crafting-system.md` with "Alpha Scope" markers
|
||||
> 3. I'll brief gameplay-programmer on simplified implementation
|
||||
> 4. I'll create a demo script for you: how to PRESENT the 10-recipe system to show the 50-recipe vision
|
||||
>
|
||||
> **But this is your call.** You know this investor better than I do. If you believe they'll value polish over pillar representation, Option C might be right. If you think they'll forgive a 1-week slip, Option A is safest creatively.
|
||||
>
|
||||
> What's your decision?
|
||||
|
||||
## Turn 6: User Makes Decision
|
||||
|
||||
**User:**
|
||||
> Option B. The investor is technical and will appreciate the systems thinking even if it's rough. Let's simplify the crafting scope to make Alpha. Can you create the ADR and update the GDD?
|
||||
|
||||
## Turn 7: Creative Director Documents Decision
|
||||
|
||||
**Agent:**
|
||||
> Excellent decision. I'll document this thoroughly so future-you understands why we made this choice.
|
||||
>
|
||||
> **Creating:**
|
||||
> 1. ADR-007: Alpha Crafting Scope Reduction
|
||||
> 2. Updated design/gdd/crafting-system.md with Alpha/Beta scope markers
|
||||
> 3. Updated production/milestones/alpha.md success criteria
|
||||
> 4. Demo script guidance for investor presentation
|
||||
>
|
||||
> [Creates documents]
|
||||
>
|
||||
> **ADR Summary:**
|
||||
> ```markdown
|
||||
> ## Decision
|
||||
> Simplify crafting system to core tag discovery mechanic (10 recipes)
|
||||
> for Alpha milestone. Defer full implementation (50 recipes + progressive
|
||||
> unlocks) to post-Alpha.
|
||||
>
|
||||
> ## Context
|
||||
> - Alpha in 2 weeks (hard date, investor demo)
|
||||
> - Full crafting requires 3 weeks
|
||||
> - Investor demo is make-or-break for funding
|
||||
>
|
||||
> ## Consequences
|
||||
> Positive:
|
||||
> - Makes Alpha deadline, preserves investor trust
|
||||
> - Both pillars demonstrated (rough but playable)
|
||||
> - Can show Alpha→Beta improvement narrative
|
||||
>
|
||||
> Negative:
|
||||
> - First impression is "rough"
|
||||
> - Limited recipe variety
|
||||
> - Missing progressive unlock system
|
||||
>
|
||||
> ## Validation Criteria
|
||||
> We'll know this was the right choice if:
|
||||
> - Investor demo successfully shows both pillars
|
||||
> - Funding secured for next development phase
|
||||
> - Post-Alpha sprint can implement full system without rework
|
||||
> ```
|
||||
>
|
||||
> **Updated GDD Markers:**
|
||||
> ```markdown
|
||||
> ## Detailed Rules
|
||||
>
|
||||
> ### Core Loop (**ALPHA SCOPE**)
|
||||
> [Core mechanic description]
|
||||
>
|
||||
> ### Progressive Unlocks (**POST-ALPHA**)
|
||||
> [Skill-based hint system - deferred]
|
||||
>
|
||||
> ### Recipe Catalog
|
||||
> - Alpha: 10 recipes (demonstrates tag variety)
|
||||
> - Beta: 50 recipes (full content)
|
||||
> ```
|
||||
>
|
||||
> **Demo Script Guidance:**
|
||||
> ```markdown
|
||||
> ## Presenting Crafting to Investor (10-recipe Alpha)
|
||||
>
|
||||
> **Frame it as proof-of-concept:**
|
||||
> "This is a vertical slice of the crafting pillar. You'll see 10 recipes
|
||||
> here, but the SYSTEM supports unlimited recipes through tag combinations.
|
||||
> Watch how players deduce patterns..."
|
||||
>
|
||||
> **Show, don't tell:**
|
||||
> - Live demo: Discover 2 recipes on the fly
|
||||
> - Explain: "Notice Fire+Water made Steam Potion. Now the player knows
|
||||
> Fire+Water is valid. They can deduce that Fire+Earth might work..."
|
||||
> - Connect to pillar: "This is Emergent Discovery - the game teaches rules,
|
||||
> players become scientists."
|
||||
>
|
||||
> **Roadmap slide:**
|
||||
> "Alpha: 10 recipes (proof of concept)
|
||||
> Beta: 50 recipes (content expansion)
|
||||
> Release: 100+ recipes (includes community-designed recipes)"
|
||||
>
|
||||
> **Emphasize systems:**
|
||||
> "We're not making a content game, we're making a systems game. The tag
|
||||
> system can generate endless combinations. We're building a platform for
|
||||
> discovery, not a recipe database."
|
||||
> ```
|
||||
>
|
||||
> May I proceed to write these documents?
|
||||
|
||||
## Turn 8: User Approves and Agent Completes
|
||||
|
||||
**User:**
|
||||
> Yes, create all those documents and also notify the gameplay-programmer about the scope change.
|
||||
|
||||
**Agent:**
|
||||
> ✅ Complete! Created/Updated:
|
||||
> - `docs/architecture/adr-007-alpha-crafting-scope.md`
|
||||
> - `design/gdd/crafting-system.md` (added Alpha/Beta scope markers)
|
||||
> - `production/milestones/alpha.md` (updated success criteria)
|
||||
> - `production/demo-script-investor-alpha.md` (new file with presentation guide)
|
||||
>
|
||||
> **Notifications Sent:**
|
||||
>
|
||||
> To `gameplay-programmer`:
|
||||
> > "Crafting scope simplified for Alpha: Core tag mechanic + 10 recipes only.
|
||||
> > Progressive unlocks and full recipe set deferred to post-Alpha. Updated
|
||||
> > GDD has implementation guidance. Estimated 1.5 weeks to implement Alpha scope."
|
||||
>
|
||||
> To `producer`:
|
||||
> > "Strategic decision made: Simplified crafting to make Alpha deadline.
|
||||
> > ADR-007 documents rationale. Sprint plan needs updating to reflect new scope."
|
||||
>
|
||||
> **Next Steps:**
|
||||
> 1. Gameplay-programmer can start implementing simplified crafting
|
||||
> 2. You can practice demo script before investor meeting
|
||||
> 3. Producer will update sprint plan with new task breakdown
|
||||
>
|
||||
> **Validation:**
|
||||
> We'll know this decision was correct when:
|
||||
> - Alpha ships on time with both pillars playable
|
||||
> - Investor demo successfully communicates the vision
|
||||
> - Funding secured for continued development
|
||||
>
|
||||
> Good luck with the demo! This was the right call - vision over polish for this audience.
|
||||
|
||||
---
|
||||
|
||||
## Session Summary
|
||||
|
||||
**What Worked Well:**
|
||||
- Creative director read context docs before proposing solutions
|
||||
- Asked 5 clarifying questions to understand constraints
|
||||
- Framed decision properly (what's at stake, evaluation criteria)
|
||||
- Presented 3 distinct options with honest pros/cons
|
||||
- Made clear recommendation with reasoning, but deferred to user
|
||||
- Documented decision thoroughly with ADR and updated all affected docs
|
||||
- Provided demo script to help user present the decision positively
|
||||
|
||||
**Key Collaborative Moments:**
|
||||
- Turn 2: Agent gathered full context before jumping to solutions
|
||||
- Turn 3: User provided decision criteria priority (funding > schedule > polish)
|
||||
- Turn 5: Agent presented 3 options, made recommendation, but explicitly "this is your call"
|
||||
- Turn 6: User made strategic decision
|
||||
- Turn 7: Agent provided demo script to support user's presentation
|
||||
- Turn 8: Agent cascaded decision to affected parties
|
||||
|
||||
**Strategic Decision Quality:**
|
||||
- User made the final call
|
||||
- Agent provided expert analysis using game dev theory and precedent
|
||||
- Trade-offs were explicit and honest
|
||||
- Decision was documented for future reference
|
||||
- Success criteria defined for validation
|
||||
|
||||
**Files Created/Updated:**
|
||||
- ADR-007 (decision record)
|
||||
- Updated crafting GDD with scope markers
|
||||
- Updated Alpha milestone definition
|
||||
- Demo script for investor presentation
|
||||
|
||||
**Context Usage:** ~30%
|
||||
**User Satisfaction:** High - confident decision made with full information
|
||||
245
docs/examples/session-story-lifecycle.md
Normal file
245
docs/examples/session-story-lifecycle.md
Normal file
@@ -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-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
|
||||
210
docs/examples/session-ux-pipeline.md
Normal file
210
docs/examples/session-ux-pipeline.md
Normal file
@@ -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
|
||||
362
docs/examples/skill-flow-diagrams.md
Normal file
362
docs/examples/skill-flow-diagrams.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# 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
|
||||
/prototype [core-mechanic] ───────────────────────────────────► prototypes/[name]-concept/REPORT.md
|
||||
│ PROCEED (validate idea BEFORE writing GDDs)
|
||||
▼
|
||||
/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 — before epics, so specs exist when stories are written]
|
||||
/ux-design [screen/hud/patterns] ────────────────────────────► design/ux/*.md
|
||||
/ux-review ──────────────────────────────────────────────────► UX specs approved (HARD gate for /team-ui)
|
||||
|
||||
[Test infrastructure — scaffold before stories reference tests]
|
||||
/test-setup ─────────────────────────────────────────────────► test framework + CI/CD pipeline
|
||||
/test-helpers ───────────────────────────────────────────────► tests/helpers/[engine-specific].gd
|
||||
|
||||
[Vertical slice — before epics, validate full game loop]
|
||||
/vertical-slice ─────────────────────────────────────────────► prototypes/[name]-vertical-slice/REPORT.md
|
||||
/playtest-report ────────────────────────────────────────────► production/playtests/
|
||||
|
||||
[Stories + sprint plan — only after vertical slice PROCEEDS]
|
||||
/create-epics [layer] ───────────────────────────────────────► production/epics/*/EPIC.md
|
||||
/create-stories [epic-slug] ─────────────────────────────────► production/epics/*/story-*.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
|
||||
│
|
||||
▼ (pick up and implement)
|
||||
/dev-story [story] ──────────────────────────────────────────► routes to correct programmer agent
|
||||
│
|
||||
▼ (during implementation, as needed)
|
||||
/code-review ────────────────────────────────────────────────► code review report
|
||||
/scope-check ────────────────────────────────────────────────► scope creep detected / clear
|
||||
/content-audit ──────────────────────────────────────────────► GDD content gaps identified
|
||||
/bug-report ─────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
|
||||
/bug-triage ─────────────────────────────────────────────────► bugs re-prioritized + assigned
|
||||
|
||||
[Team skills for feature areas — spawn when working a full feature]
|
||||
/team-combat / /team-narrative / /team-ui / /team-level / /team-audio
|
||||
|
||||
[QA cycle per sprint]
|
||||
/qa-plan ────────────────────────────────────────────────────► production/qa/qa-plan-sprint-NN.md
|
||||
/smoke-check ────────────────────────────────────────────────► smoke test gate (PASS/FAIL)
|
||||
/regression-suite ───────────────────────────────────────────► coverage gaps + missing regression tests
|
||||
/test-evidence-review ───────────────────────────────────────► evidence quality report
|
||||
/test-flakiness ─────────────────────────────────────────────► flaky test report
|
||||
│
|
||||
▼
|
||||
/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
|
||||
/asset-audit ────────────────────────────────────────────────► asset compliance report
|
||||
/tech-debt ──────────────────────────────────────────────────► docs/tech-debt-register.md
|
||||
/soak-test ──────────────────────────────────────────────────► soak test protocol + results
|
||||
/localize ───────────────────────────────────────────────────► localization readiness report
|
||||
/team-polish ────────────────────────────────────────────────► polish sprint orchestrated
|
||||
/team-qa ────────────────────────────────────────────────────► full QA cycle sign-off
|
||||
/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
|
||||
│
|
||||
▼ (post-launch, ongoing)
|
||||
/hotfix ─────────────────────────────────────────────────────► emergency fix with audit trail
|
||||
/team-live-ops ──────────────────────────────────────────────► live-ops content plan
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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: UX / UI Pipeline in Detail
|
||||
|
||||
UX specs are authored in Phase 4 (Pre-Production), before epics are written, so
|
||||
that story acceptance criteria can reference specific UX artifacts.
|
||||
|
||||
```
|
||||
design/gdd/*.md (UI/UX requirements extracted)
|
||||
design/player-journey.md (emotional arc, if authored)
|
||||
│
|
||||
▼
|
||||
/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 → UX specs ready, proceed to /create-epics
|
||||
├── NEEDS REVISION → blocking issues listed → fix → re-run review
|
||||
└── MAJOR REVISION → fundamental UX problems → redesign before epics
|
||||
│
|
||||
▼ (after APPROVED — in Phase 5 when implementing UI features)
|
||||
/team-ui
|
||||
│
|
||||
├── Phase 1: /ux-design (if any specs still missing) + /ux-review
|
||||
├── Phase 2: visual design (art-director)
|
||||
├── Phase 3: layout implementation (ui-programmer)
|
||||
├── Phase 4: accessibility audit (accessibility-specialist)
|
||||
└── Phase 5: final review
|
||||
|
||||
Note: /ux-design and /ux-review belong in Phase 4 (Pre-Production).
|
||||
/team-ui belongs in Phase 5 (Production) when a UI feature is being built.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Chain: Dev Story Flow in Detail
|
||||
|
||||
How a story moves from backlog to closed:
|
||||
|
||||
```
|
||||
/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)
|
||||
/dev-story [story]
|
||||
│
|
||||
├── Reads: story file, linked GDD requirement, ADR decisions, control manifest
|
||||
├── Routes to: gameplay-programmer / engine-programmer / ui-programmer / etc.
|
||||
│
|
||||
└── Implementation begins
|
||||
│
|
||||
▼ (optional, during/after implementation)
|
||||
/code-review → architectural review of changeset
|
||||
/scope-check → verify no scope creep vs. original story criteria
|
||||
/test-evidence-review → validate test files and manual evidence quality
|
||||
│
|
||||
▼
|
||||
/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: Story Lifecycle (Backlog to Closed)
|
||||
|
||||
How a story gets from backlog to closed (summary view):
|
||||
|
||||
```
|
||||
/create-epics [layer]
|
||||
│
|
||||
└── Output: production/epics/[slug]/EPIC.md
|
||||
│
|
||||
▼
|
||||
/create-stories [epic-slug]
|
||||
│
|
||||
└── Output: production/epics/[slug]/story-NNN-[slug].md
|
||||
(Status: Ready or Blocked if ADR is Proposed)
|
||||
│
|
||||
▼
|
||||
/story-readiness [story]
|
||||
│
|
||||
├── READY → /dev-story → implement → /story-done
|
||||
├── NEEDS WORK → resolve gaps → re-run
|
||||
└── BLOCKED → fix upstream dependency first
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Chain: QA Pipeline in Detail
|
||||
|
||||
```
|
||||
[Phase 4 — one-time infrastructure setup]
|
||||
/test-setup ────────────────────────────────────────────────────► test framework scaffolded + CI/CD wired
|
||||
/test-helpers ──────────────────────────────────────────────────► tests/helpers/[engine].gd (GDUnit4, NUnit, etc.)
|
||||
|
||||
[Phase 5 — per-sprint QA cycle]
|
||||
/qa-plan [sprint or feature]
|
||||
│
|
||||
├── Reads: story files, GDDs, acceptance criteria
|
||||
├── Classifies each story by test type:
|
||||
│ Logic → automated unit test (BLOCKING)
|
||||
│ Integration → integration test or documented playtest (BLOCKING)
|
||||
│ Visual/Feel → screenshot + lead sign-off (ADVISORY)
|
||||
│ UI → manual walkthrough or interaction test (ADVISORY)
|
||||
│ Config/Data → smoke check (ADVISORY)
|
||||
└── Output: production/qa/qa-plan-sprint-NN.md
|
||||
│
|
||||
▼
|
||||
/smoke-check
|
||||
│
|
||||
├── PASS → QA hand-off cleared
|
||||
└── FAIL → block sprint close → fix critical paths first
|
||||
│
|
||||
▼
|
||||
/regression-suite
|
||||
│
|
||||
└── Coverage gaps + list of fixed bugs without regression tests
|
||||
│
|
||||
▼
|
||||
/test-evidence-review
|
||||
│
|
||||
└── Validates evidence quality, not just existence
|
||||
│
|
||||
▼ (if CI run history available)
|
||||
/test-flakiness
|
||||
│
|
||||
└── Flaky test report + fix recommendations
|
||||
|
||||
[Phase 6 — extended stability testing]
|
||||
/soak-test ─────────────────────────────────────────────────────► soak test protocol + observed results
|
||||
/team-qa ───────────────────────────────────────────────────────► full QA cycle sign-off for release gate
|
||||
|
||||
[Ongoing — bug management]
|
||||
/bug-report ────────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
|
||||
/bug-triage ────────────────────────────────────────────────────► open bugs re-prioritized + assigned
|
||||
|
||||
[Meta — harness validation]
|
||||
/skill-test [lint|spec|catalog] ────────────────────────────────► skill file structural + behavioral check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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` |
|
||||
| Starting UX design | `/ux-design screen [name]` or `/ux-design hud` |
|
||||
| Scaffolding tests | `/test-setup` → `/test-helpers` |
|
||||
| Have stories, ready to code | `/story-readiness [story]` → `/dev-story [story]` |
|
||||
| Story done | `/story-done [story]` |
|
||||
| Running QA for a sprint | `/qa-plan` → `/smoke-check` → `/regression-suite` |
|
||||
| Bug backlog needs sorting | `/bug-triage` |
|
||||
| Extended stability testing | `/soak-test` |
|
||||
| Not sure | `/help` |
|
||||
| Existing project | `/adopt` |
|
||||
Reference in New Issue
Block a user