358 lines
15 KiB
Markdown
358 lines
15 KiB
Markdown
# 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)
|