mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios
synced 2026-04-21 13:27:18 +00:00
Polish repo for public release
- README: centered header, badge row (license, agents, skills, hooks, rules, Claude Code, Ko-fi), "Why This Exists" motivation section, table of contents, "Collaborative Not Autonomous" section, community section - Add GitHub issue templates (bug report + feature request) - Add pull request template with checklist - Add .github/FUNDING.yml with Ko-fi link - Gitignore internal planning docs, remove from tracking Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
parent
4425d473ea
commit
882b76f942
8 changed files with 187 additions and 1242 deletions
2
.github/FUNDING.yml
vendored
Normal file
2
.github/FUNDING.yml
vendored
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
ko_fi: donchitos
|
||||
# github: Donchitos # Uncomment once GitHub Sponsors is approved
|
||||
49
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
49
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
name: Bug Report
|
||||
about: Something isn't working as expected
|
||||
title: "[Bug] "
|
||||
labels: bug
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
A clear description of what the bug is.
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
1. Open Claude Code in a project using this template
|
||||
2. Run `/<skill>` or trigger `<agent>`
|
||||
3. ...
|
||||
4. See error
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
What you expected to happen.
|
||||
|
||||
## Actual Behavior
|
||||
|
||||
What actually happened. Include any error messages or unexpected output.
|
||||
|
||||
## Environment
|
||||
|
||||
- **OS**: (e.g., Windows 10, macOS 14, Ubuntu 24.04)
|
||||
- **Shell**: (e.g., Git Bash, zsh, bash)
|
||||
- **Claude Code version**: (run `claude --version`)
|
||||
- **Node.js version**: (run `node --version`)
|
||||
- **jq installed?**: Yes / No
|
||||
- **Python installed?**: Yes / No
|
||||
|
||||
## Affected Component
|
||||
|
||||
- [ ] Agent (which one?):
|
||||
- [ ] Skill (which one?):
|
||||
- [ ] Hook (which one?):
|
||||
- [ ] Rule (which one?):
|
||||
- [ ] Template
|
||||
- [ ] Documentation
|
||||
- [ ] Other:
|
||||
|
||||
## Additional Context
|
||||
|
||||
Any other context — screenshots, terminal output, or the session log if relevant.
|
||||
40
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
40
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
name: Feature Request
|
||||
about: Suggest a new agent, skill, hook, or improvement
|
||||
title: "[Feature] "
|
||||
labels: enhancement
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
A brief description of what you'd like added or changed.
|
||||
|
||||
## Type
|
||||
|
||||
- [ ] New agent
|
||||
- [ ] New skill (slash command)
|
||||
- [ ] New hook
|
||||
- [ ] New rule
|
||||
- [ ] New template
|
||||
- [ ] Improvement to existing component
|
||||
- [ ] Other:
|
||||
|
||||
## Problem / Motivation
|
||||
|
||||
What problem does this solve? What workflow does it improve?
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
How do you think this should work? Include details like:
|
||||
- For agents: what domain, what tier, what tools
|
||||
- For skills: what the workflow looks like, what it outputs
|
||||
- For hooks: what event triggers it, what it validates
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
Any other approaches you've thought about.
|
||||
|
||||
## Additional Context
|
||||
|
||||
Examples, references, or screenshots that help explain the request.
|
||||
27
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
27
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
## Summary
|
||||
|
||||
Brief description of what this PR does.
|
||||
|
||||
## Type of Change
|
||||
|
||||
- [ ] New agent
|
||||
- [ ] New skill
|
||||
- [ ] New hook or rule
|
||||
- [ ] Bug fix
|
||||
- [ ] Documentation improvement
|
||||
- [ ] Other:
|
||||
|
||||
## Changes
|
||||
|
||||
-
|
||||
-
|
||||
-
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] I've tested this in a Claude Code session
|
||||
- [ ] New agents include the Collaboration Protocol section
|
||||
- [ ] New skills use the subdirectory format (`.claude/skills/<name>/SKILL.md`)
|
||||
- [ ] Reference docs are updated (agent-roster, skills-reference, hooks-reference, rules-reference)
|
||||
- [ ] Hooks use `grep -E` (POSIX) and fail gracefully without jq/python
|
||||
- [ ] No hardcoded paths or platform-specific assumptions
|
||||
4
.gitignore
vendored
4
.gitignore
vendored
|
|
@ -14,6 +14,10 @@ Desktop.ini
|
|||
.claude/docs/UPGRADE-PLAN.md
|
||||
production/session-logs/
|
||||
|
||||
# === Internal Planning (not for public) ===
|
||||
docs/IMPROVEMENTS-PROPOSAL.md
|
||||
docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md
|
||||
|
||||
# === Build Output ===
|
||||
build/
|
||||
builds/
|
||||
|
|
|
|||
68
README.md
68
README.md
|
|
@ -1,8 +1,49 @@
|
|||
# Claude Code Game Studios
|
||||
<p align="center">
|
||||
<h1 align="center">Claude Code Game Studios</h1>
|
||||
<p align="center">
|
||||
Turn a single Claude Code session into a full game development studio.
|
||||
<br />
|
||||
48 agents. 35 workflows. One coordinated AI team.
|
||||
</p>
|
||||
</p>
|
||||
|
||||
A production-ready [Claude Code](https://docs.anthropic.com/en/docs/claude-code) project template that turns a single AI session into a full game development studio. 48 specialized agents, 35 workflow skills, and a complete coordination system — all wired into Claude Code's native agent architecture.
|
||||
<p align="center">
|
||||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
|
||||
<a href=".claude/agents"><img src="https://img.shields.io/badge/agents-48-blueviolet" alt="48 Agents"></a>
|
||||
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-35-green" alt="35 Skills"></a>
|
||||
<a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-8-orange" alt="8 Hooks"></a>
|
||||
<a href=".claude/rules"><img src="https://img.shields.io/badge/rules-11-red" alt="11 Rules"></a>
|
||||
<a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/built%20for-Claude%20Code-f5f5f5?logo=anthropic" alt="Built for Claude Code"></a>
|
||||
<a href="https://ko-fi.com/donchitos"><img src="https://img.shields.io/badge/Ko--fi-Support%20this%20project-ff5e5b?logo=ko-fi&logoColor=white" alt="Ko-fi"></a>
|
||||
</p>
|
||||
|
||||
Clone the repo, open Claude Code, and start building your game with a team of AI specialists that mirrors a real studio hierarchy: directors, department leads, and domain experts working together with defined roles, delegation rules, and quality gates.
|
||||
---
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Building a game solo with AI is powerful — but a single chat session has no structure. No one stops you from hardcoding magic numbers, skipping design docs, or writing spaghetti code. There's no QA pass, no design review, no one asking "does this actually fit the game's vision?"
|
||||
|
||||
**Claude Code Game Studios** solves this by giving your AI session the structure of a real studio. Instead of one general-purpose assistant, you get 48 specialized agents organized into a studio hierarchy — directors who guard the vision, department leads who own their domains, and specialists who do the hands-on work. Each agent has defined responsibilities, escalation paths, and quality gates.
|
||||
|
||||
The result: you still make every decision, but now you have a team that asks the right questions, catches mistakes early, and keeps your project organized from first brainstorm to launch.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [What's Included](#whats-included)
|
||||
- [Studio Hierarchy](#studio-hierarchy)
|
||||
- [Slash Commands](#slash-commands)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Project Structure](#project-structure)
|
||||
- [How It Works](#how-it-works)
|
||||
- [Design Philosophy](#design-philosophy)
|
||||
- [Customization](#customization)
|
||||
- [Platform Support](#platform-support)
|
||||
- [Community](#community)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## What's Included
|
||||
|
||||
|
|
@ -139,6 +180,18 @@ Agents follow a structured delegation model:
|
|||
4. **Change propagation** — cross-department changes are coordinated by `producer`
|
||||
5. **Domain boundaries** — agents don't modify files outside their domain without explicit delegation
|
||||
|
||||
### Collaborative, Not Autonomous
|
||||
|
||||
This is **not** an auto-pilot system. Every agent follows a strict collaboration protocol:
|
||||
|
||||
1. **Ask** — agents ask questions before proposing solutions
|
||||
2. **Present options** — agents show 2-4 options with pros/cons
|
||||
3. **You decide** — the user always makes the call
|
||||
4. **Draft** — agents show work before finalizing
|
||||
5. **Approve** — nothing gets written without your sign-off
|
||||
|
||||
You stay in control. The agents provide structure and expertise, not autonomy.
|
||||
|
||||
### Automated Safety
|
||||
|
||||
**Hooks** run automatically on every session:
|
||||
|
|
@ -196,6 +249,15 @@ This is a **template**, not a locked framework. Everything is meant to be custom
|
|||
|
||||
Tested on **Windows 10** with Git Bash. All hooks use POSIX-compatible patterns (`grep -E`, not `grep -P`) and include fallbacks for missing tools. Works on macOS and Linux without modification.
|
||||
|
||||
## Community
|
||||
|
||||
- **Discussions** — [GitHub Discussions](https://github.com/Donchitos/Claude-Code-Game-Studios/discussions) for questions, ideas, and showcasing what you've built
|
||||
- **Issues** — [Bug reports and feature requests](https://github.com/Donchitos/Claude-Code-Game-Studios/issues)
|
||||
|
||||
---
|
||||
|
||||
*This project is under active development. The agent architecture, skills, and coordination system are solid and usable today — but there's more coming.*
|
||||
|
||||
## License
|
||||
|
||||
MIT License. See [LICENSE](LICENSE) for details.
|
||||
|
|
|
|||
|
|
@ -1,860 +0,0 @@
|
|||
# Documentation & Workflow Improvements
|
||||
|
||||
## Analysis Date: 2026-02-13
|
||||
|
||||
After analyzing the current workflow guide and system capabilities, here are recommended improvements organized by impact and effort.
|
||||
|
||||
---
|
||||
|
||||
## ✅ RECENTLY IMPLEMENTED (2026-02-13)
|
||||
|
||||
### Best Practices Alignment — Phase 7
|
||||
|
||||
**Implemented Features:**
|
||||
|
||||
1. **CLAUDE.md slimmed from 159 to ~60 lines** — Extracted 6 sections to `@` imports:
|
||||
- `.claude/docs/directory-structure.md`
|
||||
- `.claude/docs/coordination-rules.md`
|
||||
- `.claude/docs/coding-standards.md` (merged coding + design standards, fixed 8-section consistency)
|
||||
- `.claude/docs/review-workflow.md`
|
||||
- `.claude/docs/context-management.md` (merged context management + compaction instructions)
|
||||
- Aligns with Anthropic's recommendation of CLAUDE.md under 80 lines
|
||||
|
||||
2. **Technical Preferences file** — `.claude/docs/technical-preferences.md`
|
||||
- Single source of truth for engine, naming conventions, performance budgets, testing, forbidden patterns
|
||||
- Populated by `/setup-engine`, updated as decisions are made
|
||||
- All agents can reference project-specific standards
|
||||
|
||||
3. **`/gate-check` skill** — Phase gate validation with PASS/CONCERNS/FAIL verdict
|
||||
- 5 phase transitions: Concept -> Pre-production -> Production -> Alpha -> Beta -> Release
|
||||
- Checks required artifacts + quality standards + blockers
|
||||
- Complements `/project-stage-detect` (diagnostic) with prescriptive validation
|
||||
|
||||
4. **`/setup-engine` updated** — Now populates technical preferences with engine-appropriate
|
||||
naming conventions and suggests performance budgets
|
||||
|
||||
5. **Design doc 8-section inconsistency fixed** — CLAUDE.md previously listed 5 sections,
|
||||
design-review skill checked for 8. Now consistently 8 everywhere.
|
||||
|
||||
**Motivation:** Research into BMAD method, Claude Flow, and Anthropic's official guidance
|
||||
identified CLAUDE.md bloat, missing phase gates, and lack of centralized technical
|
||||
preferences as the top gaps vs industry best practices.
|
||||
|
||||
---
|
||||
|
||||
### Project Stage Detection & Reverse Documentation
|
||||
|
||||
**Implemented Features:**
|
||||
|
||||
1. **`/project-stage-detect` skill** — Automatically analyzes project state, classifies stage (Concept/Pre-production/Production/Post-Launch), identifies documentation gaps, and recommends next steps
|
||||
- Template: `project-stage-report.md`
|
||||
- Full gap detection with clarifying questions
|
||||
|
||||
2. **`/reverse-document` skill** — Generates design or architecture docs from existing implementation
|
||||
- Works backwards from code to create missing GDDs or ADRs
|
||||
- Templates: `design-doc-from-implementation.md`, `architecture-doc-from-code.md`, `concept-doc-from-prototype.md`
|
||||
- Follows collaborative protocol (asks about intent vs accidents)
|
||||
|
||||
3. **`detect-gaps.sh` hook** — Runs on session start to flag missing documentation
|
||||
- Detects code without design docs
|
||||
- Detects undocumented prototypes
|
||||
- Detects core systems without ADRs
|
||||
- Suggests `/reverse-document` or `/project-stage-detect`
|
||||
|
||||
**Impact:** Addresses two major user workflow needs:
|
||||
|
||||
- "Does the system understand what stage I'm in?" → Yes, via `/project-stage-detect`
|
||||
- "Can I work backwards from existing code?" → Yes, via `/reverse-document`
|
||||
|
||||
**Files Added:**
|
||||
|
||||
- `.claude/skills/project-stage-detect/SKILL.md`
|
||||
- `.claude/skills/reverse-document/SKILL.md`
|
||||
- `.claude/docs/templates/project-stage-report.md`
|
||||
- `.claude/docs/templates/design-doc-from-implementation.md`
|
||||
- `.claude/docs/templates/architecture-doc-from-code.md`
|
||||
- `.claude/docs/templates/concept-doc-from-prototype.md`
|
||||
- `.claude/hooks/detect-gaps.sh`
|
||||
|
||||
---
|
||||
|
||||
## 🎯 HIGH IMPACT, LOW EFFORT
|
||||
|
||||
### 1. Visual Workflow Diagrams
|
||||
|
||||
**Problem:** The workflow guide is text-heavy and hard to scan quickly.
|
||||
|
||||
**Solution:** Add Mermaid diagrams for key workflows.
|
||||
|
||||
**Example to Add:**
|
||||
|
||||
```markdown
|
||||
### Sprint Workflow (Visual)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Sprint Start] --> B[/sprint-plan new]
|
||||
B --> C[Pick Task]
|
||||
C --> D{Task Type?}
|
||||
D -->|Feature| E[Design → Implement → Test]
|
||||
D -->|Bug| F[Investigate → Fix → Verify]
|
||||
E --> G[/code-review]
|
||||
F --> G
|
||||
G --> H{Review Pass?}
|
||||
H -->|No| C
|
||||
H -->|Yes| I[Commit]
|
||||
I --> J{Sprint Done?}
|
||||
J -->|No| C
|
||||
J -->|Yes| K[/retrospective]
|
||||
```
|
||||
|
||||
**Where to Add:**
|
||||
- Agent selection flowchart (Appendix A)
|
||||
- Phase transition diagram (shows all 10 phases visually)
|
||||
- Team skill orchestration diagram
|
||||
- Context management decision tree
|
||||
|
||||
---
|
||||
|
||||
### 2. Quick-Start Cheat Sheet
|
||||
|
||||
**Problem:** WORKFLOW-GUIDE.md is 1,198 lines. New users are overwhelmed.
|
||||
|
||||
**Solution:** Create `docs/QUICK-START-CHEAT-SHEET.md` - a single-page reference.
|
||||
|
||||
**Contents:**
|
||||
```markdown
|
||||
# Quick-Start Cheat Sheet
|
||||
|
||||
## Your First 10 Minutes
|
||||
1. `/setup-engine godot 4.6` ← Lock your engine
|
||||
2. `/brainstorm` ← Generate game ideas
|
||||
3. Create `design/gdd/core-loop.md` ← Document your core mechanic
|
||||
4. `/design-review` ← Validate design
|
||||
5. `/sprint-plan new` ← Start first sprint
|
||||
|
||||
## Agent Selection (30-Second Rule)
|
||||
- **Design a mechanic?** → `game-designer`
|
||||
- **Write code?** → `gameplay-programmer`
|
||||
- **Review code?** → `lead-programmer`
|
||||
- **Fix a bug?** → `debugger`
|
||||
- **Plan work?** → `producer`
|
||||
- **Make creative decision?** → `creative-director`
|
||||
- **Make technical decision?** → `technical-director`
|
||||
|
||||
## Essential Slash Commands
|
||||
| Command | When to Use |
|
||||
|---------|-------------|
|
||||
| `/design-review` | Before any code is written |
|
||||
| `/code-review` | After any major code change |
|
||||
| `/sprint-plan` | Start of each sprint |
|
||||
| `/team-*` | Multi-agent features (combat, UI, narrative) |
|
||||
| `/balance-check` | After changing game data |
|
||||
|
||||
## Emergency Commands
|
||||
- **Production bug?** → `/hotfix "description"`
|
||||
- **Scope exploding?** → `/scope-check`
|
||||
- **Context full?** → `/clear` (or compact at ~70%)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Troubleshooting Guide
|
||||
|
||||
**Problem:** Users don't know what to do when things go wrong.
|
||||
|
||||
**Solution:** Add `docs/TROUBLESHOOTING.md`.
|
||||
|
||||
**Contents:**
|
||||
|
||||
```markdown
|
||||
# Troubleshooting Guide
|
||||
|
||||
## Hooks Not Working
|
||||
|
||||
**Symptom:** No session-start banner when opening Claude Code
|
||||
|
||||
**Diagnosis:**
|
||||
1. Check `.claude/settings.json` exists
|
||||
2. Verify hook paths use forward slashes even on Windows
|
||||
3. Test hook manually: `bash .claude/hooks/session-start.sh`
|
||||
|
||||
**Fix:** If `jq` missing, hooks fall back to `grep` automatically. No action needed.
|
||||
|
||||
---
|
||||
|
||||
## Agent Gives Wrong Engine Advice
|
||||
|
||||
**Symptom:** Agent suggests Unity API when you're using Godot
|
||||
|
||||
**Root Cause:** CLAUDE.md not properly configured OR wrong agent used
|
||||
|
||||
**Fix:**
|
||||
1. Check `CLAUDE.md` Technology Stack section has engine specified
|
||||
2. Use engine-specific agent (`godot-specialist`, not generic `gameplay-programmer`)
|
||||
3. Pin engine version with `/setup-engine godot 4.6`
|
||||
|
||||
---
|
||||
|
||||
## Context Window Full
|
||||
|
||||
**Symptom:** Claude says "approaching context limit"
|
||||
|
||||
**Prevention (Best):**
|
||||
- Compact proactively at ~65-70% usage
|
||||
- Use `/clear` between unrelated tasks
|
||||
- Delegate to subagents for deep research
|
||||
|
||||
**When It Happens:**
|
||||
1. The `pre-compact.sh` hook saves your session state automatically
|
||||
2. Click "Compact" when prompted
|
||||
3. After compaction, verify: modified files, active tasks, decisions made
|
||||
|
||||
**Recovery:**
|
||||
- Read `~/.claude/sessions/[session-id]/pre-compact-notes.md`
|
||||
- This file has your session summary before compaction
|
||||
|
||||
---
|
||||
|
||||
## Design Review Keeps Failing
|
||||
|
||||
**Symptom:** `/design-review` always reports missing sections
|
||||
|
||||
**Cause:** GDD doesn't match 8-section template
|
||||
|
||||
**Fix:**
|
||||
1. Read `.claude/docs/templates/game-design-document.md`
|
||||
2. Ensure ALL 8 sections exist:
|
||||
- Overview, Player Fantasy, Detailed Rules, Formulas,
|
||||
Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria
|
||||
3. Edge cases cannot say "TBD" - must be explicitly resolved
|
||||
|
||||
---
|
||||
|
||||
## Commit Hook Blocks My Commit
|
||||
|
||||
**Symptom:** `validate-commit.sh` hook fails with error
|
||||
|
||||
**Common Causes:**
|
||||
|
||||
| Error | Meaning | Fix |
|
||||
|-------|---------|-----|
|
||||
| "No design doc reference" | Commit message doesn't link to a GDD | Add `per design/gdd/[file].md` to message |
|
||||
| "Invalid JSON" | Data file in `assets/data/` is malformed | Run `python -m json.tool [file]` to find syntax error |
|
||||
| "Hardcoded value detected" | Code has magic numbers | Move to `assets/data/` config file |
|
||||
| "TODO format invalid" | TODO comment doesn't match standard | Use format: `# TODO(system): description` |
|
||||
|
||||
**Override (Emergency Only):**
|
||||
```bash
|
||||
git commit --no-verify -m "message"
|
||||
# WARNING: Only use when hook is WRONG, not when YOU are wrong
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tests Failing After Refactor
|
||||
|
||||
**Symptom:** Test suite broke after code change
|
||||
|
||||
**Diagnosis Steps:**
|
||||
1. `pytest -v` ← See which specific tests fail
|
||||
2. Read test failure messages carefully
|
||||
3. Check if test expectations need updating (if behavior intentionally changed)
|
||||
4. Check if refactor broke dependency injection (common issue)
|
||||
|
||||
**Prevent:**
|
||||
- Run tests BEFORE committing: `pytest tests/`
|
||||
- Use `/code-review` before major refactors
|
||||
- Keep tests independent (no shared state)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Agent Selection Flowchart
|
||||
|
||||
**Problem:** Users don't know which of 48 agents to use.
|
||||
|
||||
**Solution:** Add to Appendix A of WORKFLOW-GUIDE.md:
|
||||
|
||||
```markdown
|
||||
## Agent Selection Flowchart
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start{What are you doing?}
|
||||
Start -->|Creating/designing| Design
|
||||
Start -->|Coding| Code
|
||||
Start -->|Testing/fixing| Test
|
||||
Start -->|Planning/managing| Plan
|
||||
Start -->|Deciding| Decide
|
||||
|
||||
Design{What kind of design?}
|
||||
Design -->|Game mechanic| A1[game-designer]
|
||||
Design -->|Formulas/balance| A2[systems-designer]
|
||||
Design -->|Level layout| A3[level-designer]
|
||||
Design -->|Story/lore| A4[narrative-director]
|
||||
Design -->|World/factions| A5[world-builder]
|
||||
|
||||
Code{What system?}
|
||||
Code -->|Gameplay| B1[gameplay-programmer]
|
||||
Code -->|AI| B2[ai-programmer]
|
||||
Code -->|UI| B3[ui-programmer]
|
||||
Code -->|Multiplayer| B4[network-programmer]
|
||||
Code -->|Shaders/VFX| B5[technical-artist]
|
||||
Code -->|Engine-specific| B6{Which engine?}
|
||||
B6 -->|Godot| B6a[godot-specialist]
|
||||
B6 -->|Unity| B6b[unity-specialist]
|
||||
B6 -->|Unreal| B6c[unreal-specialist]
|
||||
|
||||
Test{What kind of test?}
|
||||
Test -->|Write tests| C1[qa-tester]
|
||||
Test -->|Debug/fix| C2[debugger]
|
||||
Test -->|Performance| C3[performance-analyst]
|
||||
Test -->|Balance| C4[/balance-check]
|
||||
|
||||
Plan{What scope?}
|
||||
Plan -->|Sprint| D1[producer]
|
||||
Plan -->|Feature estimate| D2[/estimate]
|
||||
Plan -->|Milestone| D3[/milestone-review]
|
||||
|
||||
Decide{What domain?}
|
||||
Decide -->|Creative/design| E1[creative-director]
|
||||
Decide -->|Technical/arch| E2[technical-director]
|
||||
Decide -->|Scope/priority| E3[producer]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 HIGH IMPACT, MEDIUM EFFORT
|
||||
|
||||
### 5. Context Management Deep-Dive
|
||||
|
||||
**Problem:** Context management is mentioned but not deeply explained.
|
||||
|
||||
**Solution:** Add `docs/CONTEXT-MANAGEMENT-GUIDE.md`.
|
||||
|
||||
**Contents:**
|
||||
|
||||
```markdown
|
||||
# Context Management Guide
|
||||
|
||||
Context is your most precious resource. This guide shows how to manage it effectively.
|
||||
|
||||
## Understanding Context Budgets
|
||||
|
||||
| Session Type | Startup Cost | Per-Agent Cost | Recommended Max Turns |
|
||||
|--------------|--------------|----------------|---------------------|
|
||||
| Simple edit | ~2k tokens | N/A | Unlimited |
|
||||
| Feature implementation | ~8k tokens | +2k per agent | 15-20 turns |
|
||||
| Multi-system refactor | ~15k tokens | +2k per agent | 10-15 turns |
|
||||
| Research/exploration | ~5k tokens | +3k per agent (w/ search) | 8-10 turns |
|
||||
|
||||
**Startup cost includes:**
|
||||
- CLAUDE.md (~4k)
|
||||
- Imported docs (~3k)
|
||||
- Memory files (~1k)
|
||||
|
||||
## When to Compact
|
||||
|
||||
**Proactive compaction signals:**
|
||||
- You've completed 3+ unrelated tasks
|
||||
- You're at ~65-70% context usage
|
||||
- You're about to start a new major feature
|
||||
- You've spawned 3+ subagents
|
||||
|
||||
**Reactive compaction signals (too late):**
|
||||
- Claude says "approaching context limit"
|
||||
- You're at 85%+ usage
|
||||
- Responses getting slower
|
||||
|
||||
## What Gets Preserved in Compaction
|
||||
|
||||
The `pre-compact.sh` hook automatically saves:
|
||||
```bash
|
||||
# Saved to ~/.claude/sessions/[id]/pre-compact-notes.md
|
||||
- Modified files list
|
||||
- Active TODO list
|
||||
- Sprint tasks status
|
||||
- Architectural decisions made
|
||||
- Agent invocations and outcomes
|
||||
- Test results
|
||||
- Open blockers
|
||||
```
|
||||
|
||||
## Context-Saving Strategies
|
||||
|
||||
### 1. Use Subagents for Deep Research
|
||||
|
||||
**Bad (fills context):**
|
||||
```
|
||||
User: "Find all uses of 'damage_multiplier' in the codebase"
|
||||
Claude: [searches 20 files, reads 15 files, shows 200 lines of results]
|
||||
Context cost: +8k tokens
|
||||
```
|
||||
|
||||
**Good (delegates):**
|
||||
```
|
||||
User: "Use the Explore agent to find all uses of 'damage_multiplier'"
|
||||
Claude: [spawns subagent]
|
||||
Subagent: [does research in its own context]
|
||||
Subagent result: "Found in 5 files, here's the summary"
|
||||
Context cost: +1k tokens (just the summary)
|
||||
```
|
||||
|
||||
### 2. Clear Between Unrelated Tasks
|
||||
|
||||
**Scenario:** You finish implementing combat, now want to work on UI.
|
||||
|
||||
```
|
||||
User: "/clear" ← Wipes context but keeps files
|
||||
User: "Implement the main menu UI per design/gdd/ui-main-menu.md"
|
||||
```
|
||||
|
||||
You don't need combat context for UI work. Start fresh.
|
||||
|
||||
### 3. Use File References Instead of Reading
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
User: "What does the combat system do?"
|
||||
Claude: [reads 8 combat files, 400 lines]
|
||||
```
|
||||
|
||||
**Good:**
|
||||
```
|
||||
User: "Read design/gdd/combat-system.md and summarize"
|
||||
Claude: [reads 1 file, 50 lines]
|
||||
```
|
||||
|
||||
The design doc is the source of truth. Code is implementation details.
|
||||
|
||||
### 4. Batch Related Work
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
[Implement feature A]
|
||||
[Compact]
|
||||
[Implement feature B] ← Feature B needs Feature A context!
|
||||
```
|
||||
|
||||
**Good:**
|
||||
```
|
||||
[Implement feature A]
|
||||
[Implement feature B] ← Related, keep context
|
||||
[Compact now]
|
||||
```
|
||||
|
||||
## Emergency: Context Limit Reached
|
||||
|
||||
If you hit the limit mid-task:
|
||||
|
||||
1. **Save state manually:**
|
||||
```
|
||||
User: "Summarize what we've done this session and what's left to do"
|
||||
Claude: [provides summary]
|
||||
User: [copy summary to notes.txt]
|
||||
```
|
||||
|
||||
2. **Compact or restart:**
|
||||
- Compact if you need partial context (files modified, decisions made)
|
||||
- `/clear` if starting completely new work
|
||||
|
||||
3. **Resume:**
|
||||
```
|
||||
User: [paste summary from notes.txt]
|
||||
User: "Continue where we left off"
|
||||
```
|
||||
|
||||
## Measuring Context Usage
|
||||
|
||||
You can't see exact percentage, but estimate:
|
||||
|
||||
**Low usage signals:**
|
||||
- Responses instant (<1 sec)
|
||||
- No warnings
|
||||
- <10 tool calls this session
|
||||
|
||||
**Medium usage signals:**
|
||||
- Responses fast (1-2 sec)
|
||||
- 10-20 tool calls
|
||||
- 2-3 subagents spawned
|
||||
|
||||
**High usage signals:**
|
||||
- Responses slower (3-5 sec)
|
||||
- 20+ tool calls
|
||||
- 4+ subagents OR deep file searches
|
||||
|
||||
**Critical signals:**
|
||||
- Claude warns about context
|
||||
- Responses >5 seconds
|
||||
- 30+ tool calls
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **One major feature per session** (unless tightly related)
|
||||
2. **Compact at natural boundaries** (end of sprint, after milestone review)
|
||||
3. **Use `/clear` liberally** (it's fast to reload)
|
||||
4. **Let subagents handle breadth** (searching many files)
|
||||
5. **Keep design docs concise** (they're loaded into context)
|
||||
6. **Archive old ADRs** (move to `docs/architecture/archive/` after 6 months)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Real-World Example Session Logs
|
||||
|
||||
**Problem:** Guide shows commands but not full realistic sessions.
|
||||
|
||||
**Solution:** Add `docs/examples/` directory with complete session transcripts.
|
||||
|
||||
**File: `docs/examples/session-implementing-inventory.md`:**
|
||||
|
||||
```markdown
|
||||
# Example Session: Implementing Inventory System
|
||||
|
||||
**Context:** Solo dev, week 3 of project, implementing inventory per design doc.
|
||||
|
||||
**Starting context:** Fresh session, just design doc loaded.
|
||||
|
||||
---
|
||||
|
||||
## Turn 1: Read Design Doc
|
||||
|
||||
**User:**
|
||||
> Read design/gdd/inventory-system.md and summarize the requirements
|
||||
|
||||
**Claude:**
|
||||
> I've read the inventory design. Key requirements:
|
||||
> - Grid-based inventory (8x6 = 48 slots)
|
||||
> - Items have size (1x1 to 3x3)
|
||||
> - Stackable items (max stack from item data)
|
||||
> - Weight limit (derived from player stats)
|
||||
> - Drag-and-drop UI
|
||||
> - Persistence (save/load)
|
||||
>
|
||||
> Formulas section defines:
|
||||
> - Weight capacity = base_capacity + (strength * 2.5)
|
||||
> - Stack limit per item type in assets/data/items.json
|
||||
|
||||
---
|
||||
|
||||
## Turn 2: Architecture Decision
|
||||
|
||||
**User:**
|
||||
> What's the best way to implement the grid system? I'm using Godot 4.6.
|
||||
|
||||
**Claude:**
|
||||
> I'll use the godot-specialist agent to recommend an architecture.
|
||||
>
|
||||
> [Spawns godot-specialist subagent]
|
||||
>
|
||||
> **godot-specialist recommendation:**
|
||||
> - Use a `GridContainer` node for visual representation
|
||||
> - Backend: 2D array `item_grid: Array[Array[ItemSlot]]`
|
||||
> - Each `ItemSlot` is a custom Resource with properties:
|
||||
> - `item: ItemData` (null if empty)
|
||||
> - `stack_count: int`
|
||||
> - `top_left_of_item: bool` (for multi-slot items)
|
||||
> - Drag-and-drop: Override `_can_drop_data()` and `_drop_data()` on UI
|
||||
>
|
||||
> This follows Godot's node/resource patterns and makes save/load trivial
|
||||
> (Resources auto-serialize).
|
||||
|
||||
---
|
||||
|
||||
## Turn 3: Implementation
|
||||
|
||||
**User:**
|
||||
> Implement that architecture in src/gameplay/inventory/
|
||||
|
||||
**Claude:**
|
||||
> [Creates 4 files]
|
||||
> 1. `src/gameplay/inventory/item_slot.gd` (Resource)
|
||||
> 2. `src/gameplay/inventory/inventory.gd` (Grid logic)
|
||||
> 3. `src/ui/inventory/inventory_ui.gd` (UI scene script)
|
||||
> 4. `assets/data/inventory_config.json` (Constants)
|
||||
>
|
||||
> [Shows code]
|
||||
|
||||
---
|
||||
|
||||
## Turn 4: Validation Against Rules
|
||||
|
||||
**Claude (automatic):**
|
||||
> The `gameplay-code` rule flagged:
|
||||
> - ❌ Grid size hardcoded (8x6) in inventory.gd line 12
|
||||
>
|
||||
> Fixing: Moving to inventory_config.json...
|
||||
> ✓ Fixed
|
||||
|
||||
---
|
||||
|
||||
## Turn 5: Create Tests
|
||||
|
||||
**User:**
|
||||
> Write tests for this
|
||||
|
||||
**Claude:**
|
||||
> [Delegates to qa-tester]
|
||||
> [Creates tests/inventory/test_inventory_grid.gd with 8 test cases covering acceptance criteria]
|
||||
|
||||
---
|
||||
|
||||
## Turn 6: Review
|
||||
|
||||
**User:**
|
||||
> /code-review src/gameplay/inventory/inventory.gd
|
||||
|
||||
**Claude:**
|
||||
> **Review Result:**
|
||||
> ✓ Coding standards: PASS
|
||||
> ✓ Architecture: Follows ADR for resource-based inventory
|
||||
> ✓ SOLID principles: PASS (Single responsibility clear)
|
||||
> ✓ Testability: PASS (Dependency injection used)
|
||||
> ⚠️ Performance concern: `_find_empty_slot()` is O(n²) for 8x6 grid.
|
||||
> This is fine for 48 slots, but document the constraint.
|
||||
>
|
||||
> **Recommendation:** Add comment documenting grid size limit (max 20x20).
|
||||
|
||||
---
|
||||
|
||||
## Turn 7: Commit
|
||||
|
||||
**User:**
|
||||
> Commit this with message "Implement grid-based inventory system per design/gdd/inventory-system.md"
|
||||
|
||||
**Claude:**
|
||||
> [Runs git add, git commit]
|
||||
> `validate-commit.sh` hook:
|
||||
> ✓ Design doc referenced
|
||||
> ✓ JSON files valid
|
||||
> ✓ No hardcoded values
|
||||
> ✓ TODO format correct
|
||||
>
|
||||
> Commit successful: abc1234
|
||||
|
||||
---
|
||||
|
||||
**Session stats:**
|
||||
- Turns: 7
|
||||
- Time: ~15 minutes
|
||||
- Files created: 4 source + 1 test + 1 config
|
||||
- Context usage: ~40% (estimated)
|
||||
- Blockers: 0
|
||||
- Result: ✓ Working inventory system
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Timing Estimates for Phases
|
||||
|
||||
**Problem:** Users don't know how long each phase takes.
|
||||
|
||||
**Solution:** Add realistic timelines to WORKFLOW-GUIDE.md Phase headers.
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
## Phase 1: Ideation & Concept
|
||||
|
||||
**Typical Duration:**
|
||||
- Solo dev: 1-3 days
|
||||
- Small team (2-4 people): 3-7 days
|
||||
- Large team (5+ people): 1-2 weeks
|
||||
|
||||
**Depends on:**
|
||||
- How clear your vision is (clearer = faster)
|
||||
- How many concepts you explore (more = slower)
|
||||
- How much research you do on comparables
|
||||
|
||||
**Output:**
|
||||
- Game concept document
|
||||
- Game pillars + anti-pillars
|
||||
- Core loop diagram
|
||||
- Audience definition
|
||||
|
||||
**When to move on:**
|
||||
You can explain your game in one sentence AND you have 3-5 non-negotiable
|
||||
design pillars. If you can't do both, you're not ready for pre-production.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 MEDIUM IMPACT, LOW EFFORT
|
||||
|
||||
### 8. Migration Guide for Existing Projects
|
||||
|
||||
**Problem:** Users with existing games don't know how to adopt this system.
|
||||
|
||||
**Solution:** Add `docs/MIGRATION-GUIDE.md`.
|
||||
|
||||
**Contents:**
|
||||
|
||||
```markdown
|
||||
# Migrating Existing Projects to Agent Architecture
|
||||
|
||||
## Option 1: Fresh Start (Recommended for Small Projects <10k LOC)
|
||||
|
||||
Best if: Your project is small and structure is messy.
|
||||
|
||||
1. Create new repo from this template
|
||||
2. Copy over working code to `src/`
|
||||
3. Reverse-engineer design docs from code
|
||||
4. `/setup-engine` to match your current engine
|
||||
5. `/sprint-plan` to organize remaining work
|
||||
|
||||
**Time:** 1-2 days
|
||||
**Risk:** Low
|
||||
|
||||
---
|
||||
|
||||
## Option 2: Incremental Adoption (Recommended for Large Projects >10k LOC)
|
||||
|
||||
Best if: You have significant working code and can't afford disruption.
|
||||
|
||||
### Week 1: Add Infrastructure
|
||||
|
||||
1. Copy `.claude/` directory to your project root
|
||||
2. Copy `CLAUDE.md` and customize Technology Stack section
|
||||
3. Add `.claude/settings.json`
|
||||
4. Test hooks: Start a session, check for session-start banner
|
||||
|
||||
No code changes yet.
|
||||
|
||||
### Week 2: Add Design Docs
|
||||
|
||||
1. Create `design/gdd/` directory
|
||||
2. For each major system, create a GDD using the template
|
||||
3. Run `/design-review` on each
|
||||
4. Fix gaps
|
||||
|
||||
You now have documentation.
|
||||
|
||||
### Week 3: Adopt Rules Gradually
|
||||
|
||||
1. Move one system's code to match directory structure (e.g., `src/gameplay/`)
|
||||
2. The relevant rule (e.g., `gameplay-code.md`) now applies
|
||||
3. Fix violations flagged by rules
|
||||
4. Repeat for other systems
|
||||
|
||||
Incremental code cleanup.
|
||||
|
||||
### Week 4: Start Using Agents
|
||||
|
||||
1. Next new feature: Use `/team-*` skills
|
||||
2. Bug fixes: Use `debugger` agent
|
||||
3. Code reviews: Use `/code-review`
|
||||
|
||||
From this point forward, new work uses the system. Old code migrates gradually.
|
||||
|
||||
**Time:** 4+ weeks
|
||||
**Risk:** Medium (phased rollout reduces risk)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. Common Pitfalls Section
|
||||
|
||||
**Problem:** New users make predictable mistakes.
|
||||
|
||||
**Solution:** Add to WORKFLOW-GUIDE.md or QUICK-START-CHEAT-SHEET.md:
|
||||
|
||||
```markdown
|
||||
## 10 Common Pitfalls (and How to Avoid Them)
|
||||
|
||||
### 1. Coding Before Designing
|
||||
❌ **Mistake:** Jump straight to implementation without a GDD
|
||||
✅ **Fix:** ALWAYS create design/gdd/[system].md first, then /design-review it
|
||||
|
||||
### 2. Using the Wrong Agent Tier
|
||||
❌ **Mistake:** Asking `creative-director` to write shader code
|
||||
✅ **Fix:** Use the agent hierarchy - specialists for implementation, leads for decisions
|
||||
|
||||
### 3. Ignoring Hook Warnings
|
||||
❌ **Mistake:** Committing despite `validate-commit.sh` errors
|
||||
✅ **Fix:** Hooks encode best practices - fix the issue, don't bypass with --no-verify
|
||||
|
||||
### 4. Hardcoding Balance Values
|
||||
❌ **Mistake:** `var damage = 15` in code
|
||||
✅ **Fix:** `var damage = Config.get("combat.base_damage")` from assets/data/
|
||||
|
||||
### 5. Letting Context Fill Up
|
||||
❌ **Mistake:** Working until Claude says "context limit reached"
|
||||
✅ **Fix:** Compact proactively at ~70%, or /clear between unrelated tasks
|
||||
|
||||
### 6. Skipping Tests
|
||||
❌ **Mistake:** "I'll write tests later"
|
||||
✅ **Fix:** Use verification-driven development - tests prove it works
|
||||
|
||||
### 7. Scope Creep in Sprints
|
||||
❌ **Mistake:** Adding "just one more small feature" to a sprint
|
||||
✅ **Fix:** Run `/scope-check` weekly - protect your scope religiously
|
||||
|
||||
### 8. Not Using Team Skills for Cross-Cutting Features
|
||||
❌ **Mistake:** Manually coordinating 5 agents yourself
|
||||
✅ **Fix:** `/team-combat`, `/team-ui`, etc. handle orchestration
|
||||
|
||||
### 9. Treating Prototypes as Production Code
|
||||
❌ **Mistake:** Shipping prototype code with hardcoded values
|
||||
✅ **Fix:** Prototypes in `prototypes/` are throwaway - rewrite for production
|
||||
|
||||
### 10. Forgetting to Pin Engine Version
|
||||
❌ **Mistake:** "I'm using Godot" without version
|
||||
✅ **Fix:** `/setup-engine godot 4.6` - version matters for API correctness
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. Success Metrics
|
||||
|
||||
**Problem:** Users don't know if they're using the system effectively.
|
||||
|
||||
**Solution:** Add to docs/WORKFLOW-GUIDE.md:
|
||||
|
||||
```markdown
|
||||
## How to Know If You're Using the System Effectively
|
||||
|
||||
### Green Flags (You're doing great!)
|
||||
|
||||
✅ Every commit references a design doc
|
||||
✅ Hooks catch issues before you notice them
|
||||
✅ You `/design-review` before implementing
|
||||
✅ You `/code-review` after implementing
|
||||
✅ Sprint scope stays stable (no more than +10% growth)
|
||||
✅ Tests exist for all gameplay systems
|
||||
✅ Context never hits limit (you compact proactively)
|
||||
✅ You use team skills for multi-agent work
|
||||
✅ Architecture decisions are documented in ADRs
|
||||
✅ You can onboard a contributor in <1 hour
|
||||
|
||||
### Yellow Flags (Needs improvement)
|
||||
|
||||
⚠️ Commits sometimes lack design doc references
|
||||
⚠️ You bypass hooks with `--no-verify` occasionally
|
||||
⚠️ Context hits 90%+ before compacting
|
||||
⚠️ Some systems lack tests
|
||||
⚠️ Sprint scope grows by 20-30%
|
||||
⚠️ You manually coordinate 3+ agents instead of using team skills
|
||||
⚠️ Some major decisions aren't in ADRs
|
||||
|
||||
### Red Flags (Major issues)
|
||||
|
||||
❌ No design docs exist for major systems
|
||||
❌ Hooks disabled or frequently bypassed
|
||||
❌ No tests
|
||||
❌ Sprint scope doubles mid-sprint
|
||||
❌ Context constantly maxed out
|
||||
❌ No ADRs for any technical decisions
|
||||
❌ Balance values hardcoded in gameplay code
|
||||
❌ You don't know which agent to use for a task
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
| Metric | Target | How to Measure |
|
||||
|--------|--------|----------------|
|
||||
| Design coverage | 100% of systems | Every src/ directory has corresponding design/gdd/ doc |
|
||||
| Test coverage | 80%+ for gameplay | Run coverage tool |
|
||||
| Hook compliance | 95%+ | Check git log for `--no-verify` |
|
||||
| Sprint scope stability | ±15% | /scope-check at sprint end |
|
||||
| ADR coverage | 1 per major decision | Count docs/architecture/ files |
|
||||
| Hardcoded values | 0 in gameplay code | grep -r "TODO.*hardcoded" src/ |
|
||||
|
|
@ -1,379 +0,0 @@
|
|||
# Multi-Stage Document Workflow
|
||||
|
||||
**Problem:** Some design documents are too large or complex to complete in a single session. An inventory system GDD might need multiple rounds of work across several days.
|
||||
|
||||
**Solution:** Use incremental document creation with clear WIP markers.
|
||||
|
||||
---
|
||||
|
||||
## 📋 **When to Use Multi-Stage Workflow**
|
||||
|
||||
Use this approach when:
|
||||
- **Document is large** (inventory + items + crafting might be one big GDD)
|
||||
- **Design needs time to evolve** (you want to think on it overnight)
|
||||
- **Multiple stakeholders need input** (waiting for feedback before continuing)
|
||||
- **Context is getting full** (~70%) before doc is complete
|
||||
- **User explicitly wants to work incrementally** ("Let's do sections 1-4 today")
|
||||
|
||||
---
|
||||
|
||||
## ✅ **How It Works: Incremental Document Creation**
|
||||
|
||||
### **Session 1: Start the Document**
|
||||
|
||||
```
|
||||
User: "Let's design the inventory system, but I only have 30 minutes today.
|
||||
Can we do the first few sections and continue tomorrow?"
|
||||
|
||||
Agent: "Absolutely! For an inventory GDD, here's my proposed session breakdown:
|
||||
|
||||
**Session 1 (today, ~30 min):**
|
||||
- Overview
|
||||
- Player Fantasy
|
||||
- Core Rules (basic structure)
|
||||
|
||||
**Session 2 (tomorrow):**
|
||||
- Formulas
|
||||
- Edge Cases
|
||||
- Dependencies
|
||||
|
||||
**Session 3 (when ready):**
|
||||
- Tuning Knobs
|
||||
- Acceptance Criteria
|
||||
|
||||
Does this work?"
|
||||
|
||||
User: "Yes, let's do Session 1 sections today"
|
||||
|
||||
Agent: [Works through Overview, Player Fantasy, Core Rules with Q&A]
|
||||
|
||||
Agent: "Session 1 sections complete. Should I:
|
||||
A) Save this as a WIP document with sections 4-8 marked as TODO
|
||||
B) Wait and only write the file when all sections are done
|
||||
C) Something else?"
|
||||
|
||||
User: "A - save it as WIP so I can review tonight"
|
||||
|
||||
Agent: "I'll create design/gdd/inventory-system.md with WIP markers:
|
||||
|
||||
[Shows draft with this structure]
|
||||
|
||||
---
|
||||
# Inventory System (WIP)
|
||||
|
||||
**Status:** INCOMPLETE - Sections 1-3 complete, 4-8 pending
|
||||
**Last Updated:** 2026-02-13
|
||||
**Next Session:** Complete Formulas and Edge Cases
|
||||
|
||||
## 1. Overview
|
||||
[Complete content]
|
||||
|
||||
## 2. Player Fantasy
|
||||
[Complete content]
|
||||
|
||||
## 3. Detailed Rules
|
||||
[Complete content]
|
||||
|
||||
## 4. Formulas
|
||||
**TODO:** Define capacity formulas, stack size calculations, weight calculations
|
||||
|
||||
## 5. Edge Cases
|
||||
**TODO:** Full inventory, item pickup while full, stack splitting behavior
|
||||
|
||||
## 6. Dependencies
|
||||
**TODO:** List integration points
|
||||
|
||||
## 7. Tuning Knobs
|
||||
**TODO:** List designer-facing values
|
||||
|
||||
## 8. Acceptance Criteria
|
||||
**TODO:** How to validate this works
|
||||
|
||||
---
|
||||
|
||||
May I write this WIP document to design/gdd/inventory-system.md?"
|
||||
|
||||
User: "Yes"
|
||||
|
||||
Agent: [Writes file with WIP status clearly marked]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Session 2: Resume Work**
|
||||
|
||||
```
|
||||
User: "Let's continue the inventory GDD from yesterday"
|
||||
|
||||
Agent: "I'll read the current state of design/gdd/inventory-system.md...
|
||||
|
||||
[Reads file]
|
||||
|
||||
Current status:
|
||||
✓ Section 1-3: Complete
|
||||
⏸ Section 4-8: Pending
|
||||
|
||||
Today we're tackling Formulas and Edge Cases. Before we start, any
|
||||
changes to sections 1-3 based on your review last night?"
|
||||
|
||||
User: "Actually, change the grid size from 8x6 to 10x8 in section 3"
|
||||
|
||||
Agent: [Updates section 3]
|
||||
|
||||
"Updated. Now let's continue with Formulas. For capacity calculation,
|
||||
I need to know: Should it be based on weight, slot count, or both?"
|
||||
|
||||
[Agent works through sections 4-5 with same collaborative process]
|
||||
|
||||
Agent: "Sections 4-5 complete. Should I:
|
||||
A) Update the WIP doc with 1-5 complete, 6-8 pending
|
||||
B) Continue to sections 6-8 now
|
||||
C) Stop here and finish later?"
|
||||
|
||||
User: "A - update the WIP. I'll finish 6-8 tomorrow."
|
||||
|
||||
Agent: [Updates doc, changes status to "Sections 1-5 complete, 6-8 pending"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Session 3: Finalize Document**
|
||||
|
||||
```
|
||||
User: "Let's finish the inventory GDD"
|
||||
|
||||
Agent: [Reads current WIP state]
|
||||
|
||||
"Current status:
|
||||
✓ Sections 1-5: Complete
|
||||
⏸ Sections 6-8: Pending
|
||||
|
||||
Finishing up with Dependencies, Tuning Knobs, Acceptance Criteria..."
|
||||
|
||||
[Agent completes final sections]
|
||||
|
||||
Agent: "All 8 sections complete! Should I:
|
||||
A) Remove WIP markers and mark as FINAL
|
||||
B) Run /design-review first to validate
|
||||
C) Keep as WIP for one more review cycle?"
|
||||
|
||||
User: "B - review it first"
|
||||
|
||||
Agent: [Runs /design-review design/gdd/inventory-system.md]
|
||||
|
||||
"Design review passed! All 8 sections present and complete.
|
||||
Should I remove WIP markers now?"
|
||||
|
||||
User: "Yes"
|
||||
|
||||
Agent: [Updates doc, removes WIP status, marks as complete with final date]
|
||||
|
||||
"Document finalized: design/gdd/inventory-system.md
|
||||
Status: COMPLETE
|
||||
Completed: 2026-02-15"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ **WIP Document Structure**
|
||||
|
||||
When saving incomplete documents, ALWAYS include:
|
||||
|
||||
```markdown
|
||||
# [System Name] (WIP)
|
||||
|
||||
**Status:** INCOMPLETE - Sections [X-Y] complete, [Z-W] pending
|
||||
**Last Updated:** [Date]
|
||||
**Last Session Summary:** [What was accomplished]
|
||||
**Next Session Plan:** [What to work on next]
|
||||
|
||||
---
|
||||
|
||||
## Completed Sections
|
||||
|
||||
[Sections with full content]
|
||||
|
||||
---
|
||||
|
||||
## Pending Sections
|
||||
|
||||
[Sections with TODO markers explaining what's needed]
|
||||
|
||||
## 4. Formulas
|
||||
**TODO:** [Specific guidance on what to address]
|
||||
- Capacity calculation formula
|
||||
- Stack size limits
|
||||
- Weight-based restrictions
|
||||
|
||||
## 5. Edge Cases
|
||||
**TODO:** Address these scenarios:
|
||||
- Full inventory behavior
|
||||
- Partial stack pickup
|
||||
- Item swapping logic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📌 **WIP Markers Reference**
|
||||
|
||||
Use these status markers in documents:
|
||||
|
||||
```markdown
|
||||
**Status:** INCOMPLETE - Section 3 partial, 4-8 pending
|
||||
**Status:** IN REVIEW - All sections complete, awaiting feedback
|
||||
**Status:** COMPLETE - All sections finalized and reviewed
|
||||
**Status:** DEPRECATED - Replaced by [new doc]
|
||||
```
|
||||
|
||||
For sections:
|
||||
```markdown
|
||||
## 4. Formulas
|
||||
**STATUS: COMPLETE** - Reviewed 2026-02-13
|
||||
|
||||
## 5. Edge Cases
|
||||
**STATUS: DRAFT** - Needs review
|
||||
|
||||
## 6. Dependencies
|
||||
**STATUS: TODO** - Not started
|
||||
|
||||
## 7. Tuning Knobs
|
||||
**STATUS: BLOCKED** - Waiting for systems-designer input on balance values
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 **Git Workflow for WIP Docs**
|
||||
|
||||
### **Committing WIP Work:**
|
||||
|
||||
```bash
|
||||
git add design/gdd/inventory-system.md
|
||||
git commit -m "WIP: Inventory GDD sections 1-3 complete
|
||||
|
||||
Completed:
|
||||
- Overview: Grid-based inventory (10x8)
|
||||
- Player Fantasy: Spatial puzzle + organization
|
||||
- Detailed Rules: Core pickup, drop, stack, swap logic
|
||||
|
||||
Pending:
|
||||
- Formulas (session 2)
|
||||
- Edge cases (session 2)
|
||||
- Dependencies, Tuning, Acceptance (session 3)
|
||||
|
||||
per design/pillars.md Pillar 3"
|
||||
```
|
||||
|
||||
**Why commit WIP work?**
|
||||
- Preserves progress if you need to /clear context
|
||||
- Allows review by others
|
||||
- You can revert if you change direction
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Best Practices**
|
||||
|
||||
### ✅ **DO:**
|
||||
- **Mark WIP status clearly** at the top of the doc
|
||||
- **Commit WIP versions** so progress isn't lost
|
||||
- **Document what's done and what's pending** explicitly
|
||||
- **Provide context** for the next session (what to address)
|
||||
- **Update status** as you progress (INCOMPLETE → IN REVIEW → COMPLETE)
|
||||
- **Use TODO with specifics** ("TODO: Define edge case for X" not just "TODO")
|
||||
|
||||
### ❌ **DON'T:**
|
||||
- **Don't leave TODO sections blank** - always explain what needs to be addressed
|
||||
- **Don't assume incomplete = bad** - WIP is normal for complex systems
|
||||
- **Don't skip WIP markers** - future-you needs to know what's finished
|
||||
- **Don't mix WIP and COMPLETE** status without clear section markers
|
||||
- **Don't run `/design-review` on WIP docs** - it will fail (intentionally, not all 8 sections complete)
|
||||
|
||||
---
|
||||
|
||||
## 🧩 **Multi-Document Systems**
|
||||
|
||||
Sometimes one "system" spans multiple documents:
|
||||
|
||||
```
|
||||
Inventory System (umbrella concept):
|
||||
├── design/gdd/inventory-grid.md (COMPLETE)
|
||||
├── design/gdd/item-types.md (WIP - 60% done)
|
||||
├── design/gdd/equipment-slots.md (TODO - not started)
|
||||
└── design/gdd/inventory-ui.md (BLOCKED - waiting for ux-designer)
|
||||
```
|
||||
|
||||
**How to manage:**
|
||||
1. Create a **tracker doc** in `design/gdd/inventory-system-TRACKER.md`
|
||||
2. List all sub-documents with status
|
||||
3. Update tracker as each doc completes
|
||||
4. When all complete, the "system" is complete
|
||||
|
||||
**Example Tracker:**
|
||||
|
||||
```markdown
|
||||
# Inventory System - Document Tracker
|
||||
|
||||
**Overall Status:** 60% Complete
|
||||
|
||||
| Document | Status | Owner | Blocker |
|
||||
|----------|--------|-------|---------|
|
||||
| inventory-grid.md | ✅ COMPLETE | game-designer | None |
|
||||
| item-types.md | 🔄 WIP (60%) | systems-designer | Needs formula review |
|
||||
| equipment-slots.md | ⏸ TODO | game-designer | Waiting for inventory-grid finalization |
|
||||
| inventory-ui.md | 🚫 BLOCKED | ux-designer | Needs wireframes |
|
||||
|
||||
**Next Steps:**
|
||||
1. Complete item-types formulas (systems-designer consultation)
|
||||
2. Get ux-designer wireframes for UI doc
|
||||
3. Start equipment-slots once grid is implemented
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 **Example: Large Inventory System Across 3 Sessions**
|
||||
|
||||
### **Session 1 (30 min):**
|
||||
```
|
||||
User: "Start inventory GDD, do first 3 sections"
|
||||
Agent: [Creates sections 1-3]
|
||||
Agent: "May I save as WIP with sections 4-8 pending?"
|
||||
User: "Yes"
|
||||
Result: design/gdd/inventory-system.md (WIP, 3/8 sections)
|
||||
```
|
||||
|
||||
### **Session 2 (45 min):**
|
||||
```
|
||||
User: "Continue inventory GDD"
|
||||
Agent: [Reads WIP, completes sections 4-6]
|
||||
Agent: "Sections 1-6 done. Continue to 7-8 or stop?"
|
||||
User: "Stop here, I need to think about acceptance criteria"
|
||||
Agent: "Updating WIP doc..."
|
||||
Result: design/gdd/inventory-system.md (WIP, 6/8 sections)
|
||||
```
|
||||
|
||||
### **Session 3 (20 min):**
|
||||
```
|
||||
User: "Finish the inventory GDD"
|
||||
Agent: [Reads WIP, completes sections 7-8]
|
||||
Agent: "All sections complete. Run /design-review?"
|
||||
User: "Yes"
|
||||
Agent: [Review passes]
|
||||
Agent: "Removing WIP markers, marking as COMPLETE"
|
||||
Result: design/gdd/inventory-system.md (COMPLETE, 8/8 sections)
|
||||
```
|
||||
|
||||
**Total time:** ~95 minutes across 3 days
|
||||
**Result:** High-quality, reviewed GDD without rushing
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Key Takeaway**
|
||||
|
||||
**You DON'T have to finish documents in one session!**
|
||||
|
||||
- Save WIP versions with clear markers
|
||||
- Resume across multiple sessions
|
||||
- Keep progress tracked and visible
|
||||
- Commit WIP work to preserve it
|
||||
- Agents support incremental workflows
|
||||
|
||||
The collaborative protocol works **within** sessions AND **across** sessions.
|
||||
Loading…
Reference in a new issue