ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-06-27 04:51:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Game Studio Agent Architecture — complete setup (Phases 1-7)

Browse Source 
48 coordinated Claude Code subagents for indie game development:
- 3 leadership agents (creative-director, technical-director, producer)
- 10 department leads (game-designer, lead-programmer, art-director, etc.)
- 23 specialist agents (gameplay, engine, AI, networking, UI, tools, etc.)
- 12 engine-specific agents (Godot, Unity, Unreal with sub-specialists)

Infrastructure:
- 34 skills (slash commands) for workflows, reviews, and team orchestration
- 8 hooks for commit validation, asset checks, session management
- 11 path-scoped rules enforcing domain-specific standards
- 28 templates for design docs, reports, and collaborative protocols

Key features:
- User-driven collaboration protocol (Question → Options → Decision → Draft → Approval)
- Engine version awareness with knowledge-gap detection (Godot 4.6 pinned)
- Phase gate system for development milestone validation
- CLAUDE.md kept under 80 lines with extracted doc imports

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-02-13 21:04:24 +11:00
commit ad540fe75d
211 changed files with 32726 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
.claude/docs/CLAUDE-local-template.md Normal file
View File

@@ -0,0 +1,37 @@
# CLAUDE.local.md Template
Copy this file to the project root as `CLAUDE.local.md` for personal overrides.
This file is gitignored and will not be committed.
```markdown
# Personal Preferences
## Model Preferences
- Prefer Opus for complex design tasks
- Use Haiku for quick lookups and simple edits
## Workflow Preferences
- Always run tests after code changes
- Compact context proactively at 60% usage
- Use /clear between unrelated tasks
## Local Environment
- Python command: python (or py / python3)
- Shell: Git Bash on Windows
- IDE: VS Code with Claude Code extension
## Communication Style
- Keep responses concise
- Show file paths in all code references
- Explain architectural decisions briefly
## Personal Shortcuts
- When I say "review", run /code-review on the last changed files
- When I say "status", show git status + sprint progress
```
## Setup
1. Copy this template to your project root: `cp .claude/docs/CLAUDE-local-template.md CLAUDE.local.md`
2. Edit to match your preferences
3. Verify `.claude/CLAUDE.local.md` or `CLAUDE.local.md` is in `.gitignore`

269
.claude/docs/agent-coordination-map.md Normal file
View File

@@ -0,0 +1,269 @@
# Agent Coordination and Delegation Map
## Organizational Hierarchy
```
[Human Developer]
|
+---------------+---------------+
| | |
creative-director technical-director producer
| | |
+--------+--------+ | (coordinates all)
| | | |
game-designer art-dir narr-dir lead-programmer qa-lead audio-dir
| | | | | |
+--+--+ | +--+--+ +--+--+--+--+--+ | |
| | | | | | | | | | | | | |
sys lvl eco ta wrt wrld gp ep ai net tl ui qa-t snd
|
+---+---+
| |
perf-a devops analytics
Additional Leads (report to producer/directors):
release-manager -- Release pipeline, versioning, deployment
localization-lead -- i18n, string tables, translation pipeline
prototyper -- Rapid throwaway prototypes, concept validation
security-engineer -- Anti-cheat, exploits, data privacy, network security
accessibility-specialist -- WCAG, colorblind, remapping, text scaling
live-ops-designer -- Seasons, events, battle passes, retention, live economy
community-manager -- Patch notes, player feedback, crisis comms
Engine Specialists (use the SET matching your engine):
unreal-specialist -- UE5 lead: Blueprint/C++, GAS overview, UE subsystems
ue-gas-specialist -- GAS: abilities, effects, attributes, tags, prediction
ue-blueprint-specialist -- Blueprint: BP/C++ boundary, graph standards, optimization
ue-replication-specialist -- Networking: replication, RPCs, prediction, bandwidth
ue-umg-specialist -- UI: UMG, CommonUI, widget hierarchy, data binding
unity-specialist -- Unity lead: MonoBehaviour/DOTS, Addressables, URP/HDRP
unity-dots-specialist -- DOTS/ECS: Jobs, Burst, hybrid renderer
unity-shader-specialist -- Shaders: Shader Graph, VFX Graph, SRP customization
unity-addressables-specialist -- Assets: async loading, bundles, memory, CDN
unity-ui-specialist -- UI: UI Toolkit, UGUI, UXML/USS, data binding
godot-specialist -- Godot 4 lead: GDScript, node/scene, signals, resources
godot-gdscript-specialist -- GDScript: static typing, patterns, signals, performance
godot-shader-specialist -- Shaders: Godot shading language, visual shaders, VFX
godot-gdextension-specialist -- Native: C++/Rust bindings, GDExtension, build systems
```
### Legend
```
sys = systems-designer gp = gameplay-programmer
lvl = level-designer ep = engine-programmer
eco = economy-designer ai = ai-programmer
ta = technical-artist net = network-programmer
wrt = writer tl = tools-programmer
wrld = world-builder ui = ui-programmer
snd = sound-designer qa-t = qa-tester
narr-dir = narrative-director perf-a = performance-analyst
art-dir = art-director
```
## Delegation Rules
### Who Can Delegate to Whom
| From | Can Delegate To |
|------|----------------|
| creative-director | game-designer, art-director, audio-director, narrative-director |
| technical-director | lead-programmer, devops-engineer, performance-analyst, technical-artist (technical decisions) |
| producer | Any agent (task assignment within their domain only) |
| game-designer | systems-designer, level-designer, economy-designer |
| lead-programmer | gameplay-programmer, engine-programmer, ai-programmer, network-programmer, tools-programmer, ui-programmer |
| art-director | technical-artist, ux-designer |
| audio-director | sound-designer |
| narrative-director | writer, world-builder |
| qa-lead | qa-tester |
| release-manager | devops-engineer (release builds), qa-lead (release testing) |
| localization-lead | writer (string review), ui-programmer (text fitting) |
| prototyper | (works independently, reports findings to producer and relevant leads) |
| security-engineer | network-programmer (security review), lead-programmer (secure patterns) |
| accessibility-specialist | ux-designer (accessible patterns), ui-programmer (implementation), qa-tester (a11y testing) |
| [engine]-specialist | engine sub-specialists (delegates subsystem-specific work) |
| [engine] sub-specialists | (advises all programmers on engine subsystem patterns and optimization) |
| live-ops-designer | economy-designer (live economy), community-manager (event comms), analytics-engineer (engagement metrics) |
| community-manager | (works with producer for approval, release-manager for patch note timing) |
### Escalation Paths
| Situation | Escalate To |
|-----------|------------|
| Two designers disagree on a mechanic | game-designer |
| Game design vs narrative conflict | creative-director |
| Game design vs technical feasibility | producer (facilitates), then creative-director + technical-director |
| Art vs audio tonal conflict | creative-director |
| Code architecture disagreement | technical-director |
| Cross-system code conflict | lead-programmer, then technical-director |
| Schedule conflict between departments | producer |
| Scope exceeds capacity | producer, then creative-director for cuts |
| Quality gate disagreement | qa-lead, then technical-director |
| Performance budget violation | performance-analyst flags, technical-director decides |
## Common Workflow Patterns
### Pattern 1: New Feature (Full Pipeline)
```
1. creative-director -- Approves feature concept aligns with vision
2. game-designer -- Creates design document with full spec
3. producer -- Schedules work, identifies dependencies
4. lead-programmer -- Designs code architecture, creates interface sketch
5. [specialist-programmer] -- Implements the feature
6. technical-artist -- Implements visual effects (if needed)
7. writer -- Creates text content (if needed)
8. sound-designer -- Creates audio event list (if needed)
9. qa-tester -- Writes test cases
10. qa-lead -- Reviews and approves test coverage
11. lead-programmer -- Code review
12. qa-tester -- Executes tests
13. producer -- Marks task complete
```
### Pattern 2: Bug Fix
```
1. qa-tester -- Files bug report with /bug-report
2. qa-lead -- Triages severity and priority
3. producer -- Assigns to sprint (if not S1)
4. lead-programmer -- Identifies root cause, assigns to programmer
5. [specialist-programmer] -- Fixes the bug
6. lead-programmer -- Code review
7. qa-tester -- Verifies fix and runs regression
8. qa-lead -- Closes bug
```
### Pattern 3: Balance Adjustment
```
1. analytics-engineer -- Identifies imbalance from data (or player reports)
2. game-designer -- Evaluates the issue against design intent
3. economy-designer -- Models the adjustment
4. game-designer -- Approves the new values
5. [data file update] -- Change configuration values
6. qa-tester -- Regression test affected systems
7. analytics-engineer -- Monitor post-change metrics
```
### Pattern 4: New Area/Level
```
1. narrative-director -- Defines narrative purpose and beats for the area
2. world-builder -- Creates lore and environmental context
3. level-designer -- Designs layout, encounters, pacing
4. game-designer -- Reviews mechanical design of encounters
5. art-director -- Defines visual direction for the area
6. audio-director -- Defines audio direction for the area
7. [implementation by relevant programmers and artists]
8. writer -- Creates area-specific text content
9. qa-tester -- Tests the complete area
```
### Pattern 5: Sprint Cycle
```
1. producer -- Plans sprint with /sprint-plan new
2. [All agents] -- Execute assigned tasks
3. producer -- Daily status with /sprint-plan status
4. qa-lead -- Continuous testing during sprint
5. lead-programmer -- Continuous code review during sprint
6. producer -- Sprint retrospective with post-sprint hook
7. producer -- Plans next sprint incorporating learnings
```
### Pattern 6: Milestone Checkpoint
```
1. producer -- Runs /milestone-review
2. creative-director -- Reviews creative progress
3. technical-director -- Reviews technical health
4. qa-lead -- Reviews quality metrics
5. producer -- Facilitates go/no-go discussion
6. [All directors] -- Agree on scope adjustments if needed
7. producer -- Documents decisions and updates plans
```
### Pattern 7: Release Pipeline
```text
1. producer -- Declares release candidate, confirms milestone criteria met
2. release-manager -- Cuts release branch, generates /release-checklist
3. qa-lead -- Runs full regression, signs off on quality
4. localization-lead -- Verifies all strings translated, text fitting passes
5. performance-analyst -- Confirms performance benchmarks within targets
6. devops-engineer -- Builds release artifacts, runs deployment pipeline
7. release-manager -- Generates /changelog, tags release, creates release notes
8. technical-director -- Final sign-off on major releases
9. release-manager -- Deploys and monitors for 48 hours
10. producer -- Marks release complete
```
### Pattern 8: Rapid Prototype
```text
1. game-designer -- Defines the hypothesis and success criteria
2. prototyper -- Scaffolds prototype with /prototype
3. prototyper -- Builds minimal implementation (hours, not days)
4. game-designer -- Evaluates prototype against criteria
5. prototyper -- Documents findings report
6. creative-director -- Go/no-go decision on proceeding to production
7. producer -- Schedules production work if approved
```
### Pattern 9: Live Event / Season Launch
```text
1. live-ops-designer -- Designs event/season content, rewards, schedule
2. game-designer -- Validates gameplay mechanics for event
3. economy-designer -- Balances event economy and reward values
4. narrative-director -- Provides seasonal narrative theme
5. writer -- Creates event descriptions and lore
6. producer -- Schedules implementation work
7. [implementation by relevant programmers]
8. qa-lead -- Test event flow end-to-end
9. community-manager -- Drafts event announcement and patch notes
10. release-manager -- Deploys event content
11. analytics-engineer -- Monitors event participation and metrics
12. live-ops-designer -- Post-event analysis and learnings
```
## Cross-Domain Communication Protocols
### Design Change Notification
When a design document changes, the game-designer must notify:
- lead-programmer (implementation impact)
- qa-lead (test plan update needed)
- producer (schedule impact assessment)
- Relevant specialist agents depending on the change
### Architecture Change Notification
When an ADR is created or modified, the technical-director must notify:
- lead-programmer (code changes needed)
- All affected specialist programmers
- qa-lead (testing strategy may change)
- producer (schedule impact)
### Asset Standard Change Notification
When the art bible or asset standards change, the art-director must notify:
- technical-artist (pipeline changes)
- All content creators working with affected assets
- devops-engineer (if build pipeline is affected)
## Anti-Patterns to Avoid
1. **Bypassing the hierarchy**: A specialist agent should never make decisions
that belong to their lead without consultation.
2. **Cross-domain implementation**: An agent should never modify files outside
their designated area without explicit delegation from the relevant owner.
3. **Shadow decisions**: All decisions must be documented. Verbal agreements
without written records lead to contradictions.
4. **Monolithic tasks**: Every task assigned to an agent should be completable
in 1-3 days. If it is larger, it must be broken down first.
5. **Assumption-based implementation**: If a spec is ambiguous, the implementer
must ask the specifier rather than guessing. Wrong guesses are more expensive
than a question.

88
.claude/docs/agent-roster.md Normal file
View File

@@ -0,0 +1,88 @@
# Agent Roster
The following agents are available. Each has a dedicated definition file in
`.claude/agents/`. Use the agent best suited to the task at hand. When a task
spans multiple domains, the coordinating agent (usually `producer` or the
domain lead) should delegate to specialists.
## Tier 1 -- Leadership Agents (Opus)
| Agent | Domain | When to Use |
|-------|--------|-------------|
| `creative-director` | High-level vision | Major creative decisions, pillar conflicts, tone/direction |
| `technical-director` | Technical vision | Architecture decisions, tech stack choices, performance strategy |
| `producer` | Production management | Sprint planning, milestone tracking, risk management, coordination |
## Tier 2 -- Department Lead Agents (Sonnet)
| Agent | Domain | When to Use |
|-------|--------|-------------|
| `game-designer` | Game design | Mechanics, systems, progression, economy, balancing |
| `lead-programmer` | Code architecture | System design, code review, API design, refactoring |
| `art-director` | Visual direction | Style guides, art bible, asset standards, UI/UX direction |
| `audio-director` | Audio direction | Music direction, sound palette, audio implementation strategy |
| `narrative-director` | Story and writing | Story arcs, world-building, character design, dialogue strategy |
| `qa-lead` | Quality assurance | Test strategy, bug triage, release readiness, regression planning |
| `release-manager` | Release pipeline | Build management, versioning, changelogs, deployment, rollbacks |
| `localization-lead` | Internationalization | String externalization, translation pipeline, locale testing |
## Tier 3 -- Specialist Agents (Sonnet or Haiku)
| Agent | Domain | Model | When to Use |
|-------|--------|-------|-------------|
| `systems-designer` | Systems design | Sonnet | Specific mechanic implementation, formula design, loops |
| `level-designer` | Level design | Sonnet | Level layouts, pacing, encounter design, flow |
| `economy-designer` | Economy/balance | Sonnet | Resource economies, loot tables, progression curves |
| `gameplay-programmer` | Gameplay code | Sonnet | Feature implementation, gameplay systems code |
| `engine-programmer` | Engine systems | Sonnet | Core engine, rendering, physics, memory management |
| `ai-programmer` | AI systems | Sonnet | Behavior trees, pathfinding, NPC logic, state machines |
| `network-programmer` | Networking | Sonnet | Netcode, replication, lag compensation, matchmaking |
| `tools-programmer` | Dev tools | Sonnet | Editor extensions, pipeline tools, debug utilities |
| `ui-programmer` | UI implementation | Sonnet | UI framework, screens, widgets, data binding |
| `technical-artist` | Tech art | Sonnet | Shaders, VFX, optimization, art pipeline tools |
| `sound-designer` | Sound design | Haiku | SFX design docs, audio event lists, mixing notes |
| `writer` | Dialogue/lore | Sonnet | Dialogue writing, lore entries, item descriptions |
| `world-builder` | World/lore design | Sonnet | World rules, faction design, history, geography |
| `qa-tester` | Test execution | Haiku | Writing test cases, bug reports, test checklists |
| `performance-analyst` | Performance | Sonnet | Profiling, optimization recs, memory analysis |
| `devops-engineer` | Build/deploy | Haiku | CI/CD, build scripts, version control workflow |
| `analytics-engineer` | Telemetry | Sonnet | Event tracking, dashboards, A/B test design |
| `ux-designer` | UX flows | Sonnet | User flows, wireframes, accessibility, input handling |
| `prototyper` | Rapid prototyping | Sonnet | Throwaway prototypes, mechanic testing, feasibility validation |
| `security-engineer` | Security | Sonnet | Anti-cheat, exploit prevention, save encryption, network security |
| `accessibility-specialist` | Accessibility | Haiku | WCAG compliance, colorblind modes, remapping, text scaling |
| `live-ops-designer` | Live operations | Sonnet | Seasons, events, battle passes, retention, live economy |
| `community-manager` | Community | Haiku | Patch notes, player feedback, crisis comms, community health |
## Engine-Specific Agents (use the set matching your engine)
### Engine Leads
| Agent | Engine | Model | When to Use |
| ---- | ---- | ---- | ---- |
| `unreal-specialist` | Unreal Engine 5 | Sonnet | Blueprint vs C++, GAS overview, UE subsystems, Unreal optimization |
| `unity-specialist` | Unity | Sonnet | MonoBehaviour vs DOTS, Addressables, URP/HDRP, Unity optimization |
| `godot-specialist` | Godot 4 | Sonnet | GDScript patterns, node/scene architecture, signals, Godot optimization |
### Unreal Engine Sub-Specialists
| Agent | Subsystem | Model | When to Use |
| ---- | ---- | ---- | ---- |
| `ue-gas-specialist` | Gameplay Ability System | Sonnet | Abilities, gameplay effects, attribute sets, tags, prediction |
| `ue-blueprint-specialist` | Blueprint Architecture | Sonnet | BP/C++ boundary, graph standards, naming, BP optimization |
| `ue-replication-specialist` | Networking/Replication | Sonnet | Property replication, RPCs, prediction, relevancy, bandwidth |
| `ue-umg-specialist` | UMG/CommonUI | Sonnet | Widget hierarchy, data binding, CommonUI input, UI performance |
### Unity Sub-Specialists
| Agent | Subsystem | Model | When to Use |
| ---- | ---- | ---- | ---- |
| `unity-dots-specialist` | DOTS/ECS | Sonnet | Entity Component System, Jobs, Burst compiler, hybrid renderer |
| `unity-shader-specialist` | Shaders/VFX | Sonnet | Shader Graph, VFX Graph, URP/HDRP customization, post-processing |
| `unity-addressables-specialist` | Asset Management | Sonnet | Addressable groups, async loading, memory, content delivery |
| `unity-ui-specialist` | UI Toolkit/UGUI | Sonnet | UI Toolkit, UXML/USS, UGUI Canvas, data binding, cross-platform input |
### Godot Sub-Specialists
| Agent | Subsystem | Model | When to Use |
| ---- | ---- | ---- | ---- |
| `godot-gdscript-specialist` | GDScript | Sonnet | Static typing, design patterns, signals, coroutines, GDScript performance |
| `godot-shader-specialist` | Shaders/Rendering | Sonnet | Godot shading language, visual shaders, particles, post-processing |
| `godot-gdextension-specialist` | GDExtension | Sonnet | C++/Rust bindings, native performance, custom nodes, build systems |

25
.claude/docs/coding-standards.md Normal file
View File

@@ -0,0 +1,25 @@
# Coding Standards
- All game code must include doc comments on public APIs
- Every system must have a corresponding architecture decision record in `docs/architecture/`
- Gameplay values must be data-driven (external config), never hardcoded
- All public methods must be unit-testable (dependency injection over singletons)
- Commits must reference the relevant design document or task ID
- **Verification-driven development**: Write tests first when adding gameplay systems.
For UI changes, verify with screenshots. Compare expected output to actual output
before marking work complete. Every implementation should have a way to prove it works.
# Design Document Standards
- All design docs use Markdown
- Each mechanic has a dedicated document in `design/gdd/`
- Documents must include these 8 required sections:
1. **Overview** -- one-paragraph summary
2. **Player Fantasy** -- intended feeling and experience
3. **Detailed Rules** -- unambiguous mechanics
4. **Formulas** -- all math defined with variables
5. **Edge Cases** -- unusual situations handled
6. **Dependencies** -- other systems listed
7. **Tuning Knobs** -- configurable values identified
8. **Acceptance Criteria** -- testable success conditions
- Balance values must link to their source formula or rationale

26
.claude/docs/context-management.md Normal file
View File

@@ -0,0 +1,26 @@
# Context Management
Context is the most critical resource in a Claude Code session. Manage it actively:
- **Compact proactively** at ~65-70% context usage, not reactively when at the limit
- **Use `/clear`** between unrelated tasks, or after 2+ failed correction attempts
- **Context budgets by task type**:
- Light (read/review): ~3k tokens startup
- Medium (implement feature): ~8k tokens
- Heavy (multi-system refactor): ~15k tokens
- **Preserve during compaction**: modified file list, active sprint tasks, architectural
decisions made this session, agent invocation outcomes, test results, unresolved blockers
- When delegating to subagents, provide full context in the prompt -- subagents do not
inherit conversation history unless explicitly given it
# Compaction Instructions
When context is compacted, preserve the following in the summary:
- List of files modified in this session and their purpose
- Any architectural decisions made and their rationale
- Active sprint tasks and their current status
- Agent invocations and their outcomes (success/failure/blocked)
- Test results (pass/fail counts, specific failures)
- Unresolved blockers or questions awaiting user input
- The current task and what step we are on

13
.claude/docs/coordination-rules.md Normal file
View File

@@ -0,0 +1,13 @@
# Agent Coordination Rules
1. **Vertical Delegation**: Leadership agents delegate to department leads, who
delegate to specialists. Never skip a tier for complex decisions.
2. **Horizontal Consultation**: Agents at the same tier may consult each other
but must not make binding decisions outside their domain.
3. **Conflict Resolution**: When two agents disagree, escalate to the shared
parent. If no shared parent, escalate to `creative-director` for design
conflicts or `technical-director` for technical conflicts.
4. **Change Propagation**: When a design change affects multiple domains, the
`producer` agent coordinates the propagation.
5. **No Unilateral Cross-Domain Changes**: An agent must never modify files
outside its designated directories without explicit delegation.

16
.claude/docs/directory-structure.md Normal file
View File

@@ -0,0 +1,16 @@
# Directory Structure
```text
/
├── CLAUDE.md # Master configuration
├── .claude/ # Agent definitions, skills, hooks, rules, docs
├── src/ # Game source code (core, gameplay, ai, networking, ui, tools)
├── assets/ # Game assets (art, audio, vfx, shaders, data)
├── design/ # Game design documents (gdd, narrative, levels, balance)
├── docs/ # Technical documentation (architecture, api, postmortems)
│ └── engine-reference/ # Curated engine API snapshots (version-pinned)
├── tests/ # Test suites (unit, integration, performance, playtest)
├── tools/ # Build and pipeline tools (ci, build, asset-pipeline)
├── prototypes/ # Throwaway prototypes (isolated from src/)
└── production/ # Production management (sprints, milestones, releases)
```

17
.claude/docs/hooks-reference.md Normal file
View File

@@ -0,0 +1,17 @@
# Active Hooks
Hooks are configured in `.claude/settings.json` and fire automatically:
| Hook | Event | Trigger | Action |
| ---- | ----- | ------- | ------ |
| `validate-commit.sh` | PreToolUse (Bash) | `git commit` commands | Validates design doc sections, JSON data files, hardcoded values, TODO format |
| `validate-push.sh` | PreToolUse (Bash) | `git push` commands | Warns on pushes to protected branches (develop/main) |
| `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks naming conventions and JSON validity for files in `assets/` |
| `session-start.sh` | SessionStart | Session begins | Loads current sprint context, active milestone, recent git activity |
| `detect-gaps.sh` | SessionStart | Session begins | Detects missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect |
| `pre-compact.sh` | PreCompact | Context compression | Logs session progress notes before context window compression |
| `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log |
| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail of all subagent invocations with timestamps |
Hook reference documentation: `.claude/docs/hooks-reference/`
Hook input schema documentation: `.claude/docs/hooks-reference/hook-input-schemas.md`

126
.claude/docs/hooks-reference/hook-input-schemas.md Normal file
View File

@@ -0,0 +1,126 @@
# Hook Input/Output Schemas
This documents the JSON payloads each Claude Code hook receives on stdin for every event type.
## PreToolUse
Fired before a tool is executed. Can **allow** (exit 0) or **block** (exit 2).
### PreToolUse: Bash
```json
{
"tool_name": "Bash",
"tool_input": {
"command": "git commit -m 'feat: add player health system'",
"description": "Commit changes with message",
"timeout": 120000
}
}
```
### PreToolUse: Write
```json
{
"tool_name": "Write",
"tool_input": {
"file_path": "src/gameplay/health.gd",
"content": "extends Node\n..."
}
}
```
### PreToolUse: Edit
```json
{
"tool_name": "Edit",
"tool_input": {
"file_path": "src/gameplay/health.gd",
"old_string": "var health = 100",
"new_string": "var health: int = 100"
}
}
```
### PreToolUse: Read
```json
{
"tool_name": "Read",
"tool_input": {
"file_path": "src/gameplay/health.gd"
}
}
```
## PostToolUse
Fired after a tool completes. **Cannot block** (exit code ignored for blocking). Stderr messages are shown as warnings.
### PostToolUse: Write
```json
{
"tool_name": "Write",
"tool_input": {
"file_path": "assets/data/enemy_stats.json",
"content": "{\"goblin\": {\"health\": 50}}"
},
"tool_output": "File written successfully"
}
```
### PostToolUse: Edit
```json
{
"tool_name": "Edit",
"tool_input": {
"file_path": "assets/data/enemy_stats.json",
"old_string": "\"health\": 50",
"new_string": "\"health\": 75"
},
"tool_output": "File edited successfully"
}
```
## SubagentStart
Fired when a subagent is spawned via the Task tool.
```json
{
"agent_name": "game-designer",
"model": "sonnet",
"description": "Design the combat healing mechanic"
}
```
## SessionStart
Fired when a Claude Code session begins. **No stdin input** — the hook just runs and its stdout is shown to Claude as context.
## PreCompact
Fired before context window compression. **No stdin input** — the hook runs to save state before compression occurs.
## Stop
Fired when the Claude Code session ends. **No stdin input** — the hook runs for cleanup and logging.
## Exit Code Reference
| Exit Code | Meaning | Applicable Events |
|-----------|---------|-------------------|
| 0 | Allow / Success | All events |
| 2 | Block (stderr shown to Claude) | PreToolUse only |
| Other | Treated as error, tool proceeds | All events |
## Notes
- Hooks receive JSON on **stdin** (pipe). Use `INPUT=$(cat)` to capture.
- Parse with `jq` if available, fall back to `grep` for cross-platform compatibility.
- On Windows, `grep -P` (Perl regex) is often unavailable. Use `grep -E` (POSIX extended) instead.
- Path separators may be `\` on Windows. Normalize with `sed 's|\\|/|g'` when comparing paths.

84
.claude/docs/hooks-reference/post-merge-asset-validation.md Normal file
View File

@@ -0,0 +1,84 @@
# Hook: post-merge-asset-validation
## Trigger
Runs after any merge to the `develop` or `main` branch that includes changes
to `assets/`.
## Purpose
Validates that all assets in the merged branch conform to naming conventions,
size budgets, and format requirements. Prevents non-compliant assets from
accumulating on integration branches.
## Implementation
```bash
#!/bin/bash
# Post-merge hook: Asset validation
# Checks merged assets against project standards
MERGED_ASSETS=$(git diff --name-only HEAD@{1} HEAD | grep -E '^assets/')
if [ -z "$MERGED_ASSETS" ]; then
exit 0
fi
EXIT_CODE=0
WARNINGS=""
for file in $MERGED_ASSETS; do
filename=$(basename "$file")
# Check naming convention (lowercase with underscores)
if echo "$filename" | grep -qP '[A-Z\s-]'; then
WARNINGS="$WARNINGS\nNAMING: $file -- must be lowercase with underscores"
EXIT_CODE=1
fi
# Check texture sizes (must be power of 2)
if [[ "$file" == *.png || "$file" == *.jpg ]]; then
# Requires ImageMagick
if command -v identify &> /dev/null; then
dims=$(identify -format "%w %h" "$file" 2>/dev/null)
if [ -n "$dims" ]; then
w=$(echo "$dims" | cut -d' ' -f1)
h=$(echo "$dims" | cut -d' ' -f2)
if (( (w & (w-1)) != 0 || (h & (h-1)) != 0 )); then
WARNINGS="$WARNINGS\nSIZE: $file -- dimensions ${w}x${h} not power-of-2"
fi
fi
fi
fi
# Check file size budgets
size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
if [ -n "$size" ]; then
# Textures: max 4MB
if [[ "$file" == assets/art/* ]] && [ "$size" -gt 4194304 ]; then
WARNINGS="$WARNINGS\nBUDGET: $file -- ${size} bytes exceeds 4MB texture budget"
EXIT_CODE=1
fi
# Audio: max 10MB for music, 512KB for SFX
if [[ "$file" == assets/audio/sfx* ]] && [ "$size" -gt 524288 ]; then
WARNINGS="$WARNINGS\nBUDGET: $file -- ${size} bytes exceeds 512KB SFX budget"
fi
fi
done
if [ -n "$WARNINGS" ]; then
echo "=== Asset Validation Report ==="
echo -e "$WARNINGS"
echo "================================"
echo "Run /asset-audit for a full report."
fi
exit $EXIT_CODE
```
## Agent Integration
When this hook reports issues:
1. For naming violations: fix manually or invoke `art-director` for guidance
2. For size violations: invoke `technical-artist` for optimization advice
3. For a full audit: run `/asset-audit` skill

78
.claude/docs/hooks-reference/post-sprint-retrospective.md Normal file
View File

@@ -0,0 +1,78 @@
# Hook: post-sprint-retrospective
## Trigger
Manual trigger at the end of each sprint (typically invoked by the producer
agent or the human developer).
## Purpose
Automatically generates a retrospective starting point by analyzing the sprint
data: what was planned vs completed, velocity changes, bug trends, and common
blockers. This is not a git hook but a workflow hook invoked through the
`producer` agent.
## Implementation
This is a workflow hook, not a git hook. It is invoked by running:
```
@producer Generate sprint retrospective for Sprint [N]
```
The producer agent should:
1. **Read the sprint plan** from `production/sprints/sprint-[N].md`
2. **Calculate metrics**:
- Tasks planned vs completed
- Story points planned vs completed (if used)
- Carryover items from previous sprint
- New tasks added mid-sprint
- Average task completion time
3. **Analyze patterns**:
- Most common blockers
- Which agent/area had the most incomplete work
- Which estimates were most inaccurate
4. **Generate the retrospective**:
```markdown
# Sprint [N] Retrospective
## Metrics
| Metric | Value |
|--------|-------|
| Tasks Planned | [N] |
| Tasks Completed | [N] |
| Completion Rate | [X%] |
| Carryover from Previous | [N] |
| New Tasks Added | [N] |
| Bugs Found | [N] |
| Bugs Fixed | [N] |
## Velocity Trend
[Sprint N-2]: [X] | [Sprint N-1]: [Y] | [Sprint N]: [Z]
Trend: [Improving / Stable / Declining]
## What Went Well
- [Automatically detected: tasks completed ahead of estimate]
- [Facilitator adds team observations]
## What Went Poorly
- [Automatically detected: tasks that were carried over or cut]
- [Automatically detected: areas with significant estimate overruns]
- [Facilitator adds team observations]
## Blockers
| Blocker | Frequency | Resolution Time | Prevention |
|---------|-----------|----------------|-----------|
## Action Items for Next Sprint
| # | Action | Owner | Priority |
|---|--------|-------|----------|
## Estimation Accuracy
| Area | Avg Planned | Avg Actual | Accuracy |
|------|------------|-----------|----------|
```
5. **Save** to `production/sprints/sprint-[N]-retro.md`

60
.claude/docs/hooks-reference/pre-commit-code-quality.md Normal file
View File

@@ -0,0 +1,60 @@
# Hook: pre-commit-code-quality
## Trigger
Runs before any commit that modifies files in `src/`.
## Purpose
Enforces coding standards before code enters version control. Catches style
violations, missing documentation, overly complex methods, and hardcoded
values that should be data-driven.
## Implementation
```bash
#!/bin/bash
# Pre-commit hook: Code quality checks
# Adapt the specific checks to your language and tooling
CODE_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^src/')
EXIT_CODE=0
if [ -n "$CODE_FILES" ]; then
for file in $CODE_FILES; do
# Check for hardcoded magic numbers in gameplay code
if [[ "$file" == src/gameplay/* ]]; then
# Look for numeric literals that are likely balance values
# Adjust the pattern for your language
if grep -nP '(?<![\w.])(?:damage|health|speed|rate|chance|cost|duration)\s*[:=]\s*\d+' "$file"; then
echo "WARNING: $file may contain hardcoded gameplay values. Use data files."
# Warning only, not blocking
fi
fi
# Check for TODO/FIXME without assignee
if grep -nP '(TODO|FIXME|HACK)(?!\()' "$file"; then
echo "WARNING: $file has TODO/FIXME without owner tag. Use TODO(name) format."
fi
# Run language-specific linter (uncomment appropriate line)
# For GDScript: gdlint "$file" || EXIT_CODE=1
# For C#: dotnet format --check "$file" || EXIT_CODE=1
# For C++: clang-format --dry-run -Werror "$file" || EXIT_CODE=1
done
# Run unit tests for modified systems
# Uncomment and adapt for your test framework
# python -m pytest tests/unit/ -x --quiet || EXIT_CODE=1
fi
exit $EXIT_CODE
```
## Agent Integration
When this hook fails:
1. For style violations: auto-fix with your formatter or invoke `lead-programmer`
2. For hardcoded values: invoke `gameplay-programmer` to externalize the values
3. For test failures: invoke `qa-tester` to diagnose and `gameplay-programmer` to fix

62
.claude/docs/hooks-reference/pre-commit-design-check.md Normal file
View File

@@ -0,0 +1,62 @@
# Hook: pre-commit-design-check
## Trigger
Runs before any commit that modifies files in `design/` or `assets/data/`.
## Purpose
Ensures design documents and game data files maintain consistency and
completeness before they enter version control. Catches missing sections,
broken cross-references, and invalid data before they propagate.
## Implementation
```bash
#!/bin/bash
# Pre-commit hook: Design document and game data validation
# Place in .git/hooks/pre-commit or configure via your hook manager
DESIGN_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^design/')
DATA_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^assets/data/')
EXIT_CODE=0
# Check design documents for required sections
if [ -n "$DESIGN_FILES" ]; then
for file in $DESIGN_FILES; do
if [[ "$file" == *.md ]]; then
# Check for required sections in GDD documents
if [[ "$file" == design/gdd/* ]]; then
for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do
if ! grep -qi "$section" "$file"; then
echo "ERROR: $file missing required section: $section"
EXIT_CODE=1
fi
done
fi
fi
done
fi
# Validate JSON data files
if [ -n "$DATA_FILES" ]; then
for file in $DATA_FILES; do
if [[ "$file" == *.json ]]; then
if ! python -m json.tool "$file" > /dev/null 2>&1; then
echo "ERROR: $file is not valid JSON"
EXIT_CODE=1
fi
fi
done
fi
exit $EXIT_CODE
```
## Agent Integration
When this hook fails, the committer should:
1. For missing design sections: invoke the `game-designer` agent to complete
the document
2. For invalid JSON: invoke the `tools-programmer` agent or fix manually

80
.claude/docs/hooks-reference/pre-push-test-gate.md Normal file
View File

@@ -0,0 +1,80 @@
# Hook: pre-push-test-gate
## Trigger
Runs before any push to a remote branch. Mandatory for pushes to `develop`
and `main`.
## Purpose
Ensures the build compiles, unit tests pass, and critical smoke tests pass
before code reaches shared branches. This is the last automated quality gate
before code affects other developers.
## Implementation
```bash
#!/bin/bash
# Pre-push hook: Build and test gate
REMOTE="$1"
URL="$2"
# Only enforce full gate for develop and main
PROTECTED_BRANCHES="develop main"
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
FULL_GATE=false
for branch in $PROTECTED_BRANCHES; do
if [ "$CURRENT_BRANCH" = "$branch" ]; then
FULL_GATE=true
break
fi
done
echo "=== Pre-Push Quality Gate ==="
# Step 1: Build
echo "Building..."
# Adapt to your build system:
# make build || exit 1
# dotnet build || exit 1
# cargo build || exit 1
echo "Build: PASS"
# Step 2: Unit tests
echo "Running unit tests..."
# Adapt to your test framework:
# python -m pytest tests/unit/ -x || exit 1
# dotnet test tests/unit/ || exit 1
# cargo test || exit 1
echo "Unit tests: PASS"
if [ "$FULL_GATE" = true ]; then
# Step 3: Integration tests (only for protected branches)
echo "Running integration tests..."
# python -m pytest tests/integration/ -x || exit 1
echo "Integration tests: PASS"
# Step 4: Smoke tests
echo "Running smoke tests..."
# python -m pytest tests/playtest/smoke/ -x || exit 1
echo "Smoke tests: PASS"
# Step 5: Performance regression check
echo "Checking performance baselines..."
# python tools/ci/perf_check.py || exit 1
echo "Performance: PASS"
fi
echo "=== All gates passed ==="
exit 0
```
## Agent Integration
When this hook fails:
1. Build failure: invoke `lead-programmer` to diagnose
2. Unit test failure: invoke `qa-tester` to identify the failing test and
`gameplay-programmer` or relevant programmer to fix
3. Performance regression: invoke `performance-analyst` to analyze

216
.claude/docs/quick-start.md Normal file
View File

@@ -0,0 +1,216 @@
# Game Studio Agent Architecture -- Quick Start Guide
## What Is This?
This is a complete Claude Code agent architecture for game development. It
organizes 48 specialized AI agents into a studio hierarchy that mirrors
real game development teams, with defined responsibilities, delegation
rules, and coordination protocols. It includes engine-specialist agents
for Godot, Unity, and Unreal — each with dedicated sub-specialists for
major engine subsystems. All design agents and templates are grounded in
established game design theory (MDA Framework, Self-Determination Theory,
Flow State, Bartle Player Types). Use whichever engine set matches your project.
## How to Use
### 1. Understand the Hierarchy
There are three tiers of agents:
- **Tier 1 (Opus)**: Directors who make high-level decisions
- `creative-director` -- vision and creative conflict resolution
- `technical-director` -- architecture and technology decisions
- `producer` -- scheduling, coordination, and risk management
- **Tier 2 (Sonnet)**: Department leads who own their domain
- `game-designer`, `lead-programmer`, `art-director`, `audio-director`,
`narrative-director`, `qa-lead`, `release-manager`, `localization-lead`
- **Tier 3 (Sonnet/Haiku)**: Specialists who execute within their domain
- Designers, programmers, artists, writers, testers, engineers
### 2. Pick the Right Agent for the Job
Ask yourself: "What department would handle this in a real studio?"
| I need to... | Use this agent |
|-------------|---------------|
| Design a new mechanic | `game-designer` |
| Write combat code | `gameplay-programmer` |
| Create a shader | `technical-artist` |
| Write dialogue | `writer` |
| Plan the next sprint | `producer` |
| Review code quality | `lead-programmer` |
| Write test cases | `qa-tester` |
| Design a level | `level-designer` |
| Fix a performance problem | `performance-analyst` |
| Set up CI/CD | `devops-engineer` |
| Design a loot table | `economy-designer` |
| Resolve a creative conflict | `creative-director` |
| Make an architecture decision | `technical-director` |
| Manage a release | `release-manager` |
| Prepare strings for translation | `localization-lead` |
| Test a mechanic idea quickly | `prototyper` |
| Review code for security issues | `security-engineer` |
| Check accessibility compliance | `accessibility-specialist` |
| Get Unreal Engine advice | `unreal-specialist` |
| Get Unity advice | `unity-specialist` |
| Get Godot advice | `godot-specialist` |
| Design GAS abilities/effects | `ue-gas-specialist` |
| Define BP/C++ boundaries | `ue-blueprint-specialist` |
| Implement UE replication | `ue-replication-specialist` |
| Build UMG/CommonUI widgets | `ue-umg-specialist` |
| Design DOTS/ECS architecture | `unity-dots-specialist` |
| Write Unity shaders/VFX | `unity-shader-specialist` |
| Manage Addressable assets | `unity-addressables-specialist` |
| Build UI Toolkit/UGUI screens | `unity-ui-specialist` |
| Write idiomatic GDScript | `godot-gdscript-specialist` |
| Create Godot shaders | `godot-shader-specialist` |
| Build GDExtension modules | `godot-gdextension-specialist` |
| Plan live events and seasons | `live-ops-designer` |
| Write patch notes for players | `community-manager` |
| Brainstorm a new game idea | Use `/brainstorm` skill |
### 3. Use Slash Commands for Common Tasks
| Command | What it does |
|---------|-------------|
| `/design-review` | Reviews a design document |
| `/code-review` | Reviews code for quality and architecture |
| `/playtest-report` | Creates or analyzes playtest feedback |
| `/balance-check` | Analyzes game balance data |
| `/sprint-plan` | Creates or updates sprint plans |
| `/architecture-decision` | Creates an ADR |
| `/asset-audit` | Audits assets for compliance |
| `/milestone-review` | Reviews milestone progress |
| `/onboard` | Generates onboarding docs for a role |
| `/prototype` | Scaffolds a throwaway prototype |
| `/release-checklist` | Validates pre-release checklist |
| `/changelog` | Generates changelog from git history |
| `/retrospective` | Runs sprint/milestone retrospective |
| `/estimate` | Produces structured effort estimates |
| `/hotfix` | Emergency fix with audit trail |
| `/tech-debt` | Scan, track, and prioritize tech debt |
| `/scope-check` | Detect scope creep against plan |
| `/localize` | Localization scan, extract, validate |
| `/perf-profile` | Performance profiling and bottleneck ID |
| `/gate-check` | Validate phase readiness (PASS/CONCERNS/FAIL) |
| `/project-stage-detect` | Analyze project state, detect stage, identify gaps |
| `/reverse-document` | Generate design/architecture docs from existing code |
| `/setup-engine` | Configure engine + version, populate reference docs |
| `/team-combat` | Orchestrate full combat team pipeline |
| `/team-narrative` | Orchestrate full narrative team pipeline |
| `/team-ui` | Orchestrate full UI team pipeline |
| `/team-release` | Orchestrate full release team pipeline |
| `/team-polish` | Orchestrate full polish team pipeline |
| `/team-audio` | Orchestrate full audio team pipeline |
| `/team-level` | Orchestrate full level creation pipeline |
| `/launch-checklist` | Complete launch readiness validation |
| `/patch-notes` | Generate player-facing patch notes |
| `/brainstorm` | Guided game concept ideation from scratch |
### 4. Use Templates for New Documents
Templates are in `.claude/docs/templates/`:
- `game-design-document.md` -- for new mechanics and systems
- `architecture-decision-record.md` -- for technical decisions
- `risk-register-entry.md` -- for new risks
- `narrative-character-sheet.md` -- for new characters
- `test-plan.md` -- for feature test plans
- `sprint-plan.md` -- for sprint planning
- `milestone-definition.md` -- for new milestones
- `level-design-document.md` -- for new levels
- `game-pillars.md` -- for core design pillars
- `art-bible.md` -- for visual style reference
- `technical-design-document.md` -- for per-system technical designs
- `post-mortem.md` -- for project/milestone retrospectives
- `sound-bible.md` -- for audio style reference
- `release-checklist-template.md` -- for platform release checklists
- `changelog-template.md` -- for player-facing patch notes
- `release-notes.md` -- for player-facing release notes
- `incident-response.md` -- for live incident response playbooks
- `game-concept.md` -- for initial game concepts (MDA, SDT, Flow, Bartle)
- `pitch-document.md` -- for pitching the game to stakeholders
- `economy-model.md` -- for virtual economy design (sink/faucet model)
- `faction-design.md` -- for faction identity, lore, and gameplay role
### 5. Follow the Coordination Rules
1. Work flows down the hierarchy: Directors -> Leads -> Specialists
2. Conflicts escalate up the hierarchy
3. Cross-department work is coordinated by the `producer`
4. Agents do not modify files outside their domain without delegation
5. All decisions are documented
## First Steps for a New Project
### Path A: "I have no idea what to build"
Start from zero — the system will guide you through the entire process:
1. **Discover your game** — Run `/brainstorm` (or `/brainstorm open`)
- Guided creative exploration: what excites you, what you've played, your constraints
- Generates 3 concepts, helps you pick one, defines core loop and pillars
- Produces a game concept document and recommends an engine
2. **Set up the engine** — Run `/setup-engine` (uses the brainstorm recommendation)
- Configures CLAUDE.md, detects knowledge gaps, populates reference docs
- Creates `.claude/docs/technical-preferences.md` with naming conventions,
performance budgets, and engine-specific defaults
- If the engine version is newer than the LLM's training data, it fetches
current docs from the web so agents suggest correct APIs
3. **Validate the concept** — Run `/design-review design/gdd/game-concept.md`
4. **Test the core loop** — Run `/prototype [core-mechanic]`
5. **Playtest it** — Run `/playtest-report` to validate the hypothesis
6. **Plan the first sprint** — Run `/sprint-plan new`
7. Start building
### Path B: "I know what I want to build"
If you already have a game concept and engine choice:
1. **Set up the engine** — Run `/setup-engine [engine] [version]`
(e.g., `/setup-engine godot 4.6`) — also creates technical preferences
2. **Write the Game Pillars** — delegate to `creative-director`
3. **Create the initial ADR** — Run `/architecture-decision`
4. **Create the first milestone** in `production/milestones/`
5. **Plan the first sprint** — Run `/sprint-plan new`
6. Start building
### Path C: "I know the game but not the engine"
If you have a concept but don't know which engine fits:
1. **Run `/setup-engine`** with no arguments — it will ask about your game's
needs (2D/3D, platforms, team size, language preferences) and recommend
an engine based on your answers
2. Follow Path B from step 2 onward
## File Structure Reference
```
CLAUDE.md -- Master config (read this first, ~60 lines)
.claude/
settings.json -- Claude Code hooks and project settings
agents/ -- 48 agent definitions (YAML frontmatter)
skills/ -- 34 slash command definitions (YAML frontmatter)
hooks/ -- 8 hook scripts (.sh) wired by settings.json
rules/ -- 11 path-specific rule files
docs/
quick-start.md -- This file
technical-preferences.md -- Project-specific standards (populated by /setup-engine)
coding-standards.md -- Coding and design doc standards
coordination-rules.md -- Agent coordination rules
context-management.md -- Context budgets and compaction instructions
review-workflow.md -- Review and sign-off process
directory-structure.md -- Project directory layout
agent-roster.md -- Full agent list with tiers
skills-reference.md -- All slash commands
rules-reference.md -- Path-specific rules
hooks-reference.md -- Active hooks
agent-coordination-map.md -- Full delegation and workflow map
setup-requirements.md -- System prerequisites (Git Bash, jq, Python)
settings-local-template.md -- Personal settings.local.json guide
hooks-reference/ -- Hook documentation and git hook examples
templates/ -- 28 document templates
```

6
.claude/docs/review-workflow.md Normal file
View File

@@ -0,0 +1,6 @@
# Review Workflow
1. Code changes require review by the relevant department lead agent
2. Design changes require sign-off from `game-designer` and `creative-director`
3. Architecture changes require sign-off from `technical-director`
4. Cross-domain changes require sign-off from `producer`

17
.claude/docs/rules-reference.md Normal file
View File

@@ -0,0 +1,17 @@
# Path-Specific Rules
Rules in `.claude/rules/` are automatically enforced when editing files in matching paths:
| Rule File | Path Pattern | Enforces |
| ---- | ---- | ---- |
| `gameplay-code.md` | `src/gameplay/**` | Data-driven values, delta time, no UI references |
| `engine-code.md` | `src/core/**` | Zero allocs in hot paths, thread safety, API stability |
| `ai-code.md` | `src/ai/**` | Performance budgets, debuggability, data-driven params |
| `network-code.md` | `src/networking/**` | Server-authoritative, versioned messages, security |
| `ui-code.md` | `src/ui/**` | No game state ownership, localization-ready, accessibility |
| `design-docs.md` | `design/gdd/**` | Required 8 sections, formula format, edge cases |
| `narrative.md` | `design/narrative/**` | Lore consistency, character voice, canon levels |
| `data-files.md` | `assets/data/**` | JSON validity, naming conventions, schema rules |
| `test-standards.md` | `tests/**` | Test naming, coverage requirements, fixture patterns |
| `prototype-code.md` | `prototypes/**` | Relaxed standards, README required, hypothesis documented |
| `shader-code.md` | `assets/shaders/**` | Naming conventions, performance targets, cross-platform rules |

63
.claude/docs/settings-local-template.md Normal file
View File

@@ -0,0 +1,63 @@
# settings.local.json Template
Create `.claude/settings.local.json` for personal overrides that should NOT
be committed to version control. Add it to `.gitignore`.
## Example settings.local.json
```json
{
"permissions": {
"allow": [
"Bash(git *)",
"Bash(npm *)",
"Read",
"Glob",
"Grep"
],
"deny": [
"Bash(rm -rf *)",
"Bash(git push --force *)"
]
}
}
```
## Permission Modes
Claude Code supports different permission modes. Recommended for game dev:
### During Development (Default)
Use **normal mode** — Claude asks before running most commands. This is safest
for production code.
### During Prototyping
Use **auto-accept mode** with limited scope — faster iteration on throwaway code.
Only use this when working in `prototypes/` directory.
### During Code Review
Use **read-only** permissions — Claude can read and search but not modify files.
## Customizing Hooks Locally
You can add personal hooks in `settings.local.json` that extend (not override)
the project hooks. For example, adding a notification when builds complete:
```json
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash -c 'echo Session ended at $(date)'",
"timeout": 5
}
]
}
]
}
}
```

80
.claude/docs/setup-requirements.md Normal file
View File

@@ -0,0 +1,80 @@
# Setup Requirements
This template requires a few tools to be installed for full functionality.
All hooks fail gracefully if tools are missing — nothing will break, but
you'll lose validation features.
## Required
| Tool | Purpose | Install |
| ---- | ---- | ---- |
| **Git** | Version control, branch management | [git-scm.com](https://git-scm.com/) |
| **Claude Code** | AI agent CLI | `npm install -g @anthropic-ai/claude-code` |
## Recommended
| Tool | Used By | Purpose | Install |
| ---- | ---- | ---- | ---- |
| **jq** | Hooks (4 of 8) | JSON parsing in commit/push/asset/agent hooks | See below |
| **Python 3** | Hooks (2 of 8) | JSON validation for data files | [python.org](https://www.python.org/) |
| **Bash** | All hooks | Shell script execution | Included with Git for Windows |
### Installing jq
**Windows** (any of these):
```
winget install jqlang.jq
choco install jq
scoop install jq
```
**macOS**:
```
brew install jq
```
**Linux**:
```
sudo apt install jq # Debian/Ubuntu
sudo dnf install jq # Fedora
sudo pacman -S jq # Arch
```
## Platform Notes
### Windows
- Git for Windows includes **Git Bash**, which provides the `bash` command
used by all hooks in `settings.json`
- Ensure Git Bash is on your PATH (default if installed via the Git installer)
- Hooks use `bash .claude/hooks/[name].sh` — this works on Windows because
Claude Code invokes commands through a shell that can find `bash.exe`
### macOS / Linux
- Bash is available natively
- Install `jq` via your package manager for full hook support
## Verifying Your Setup
Run these commands to check prerequisites:
```bash
git --version # Should show git version
bash --version # Should show bash version
jq --version # Should show jq version (optional)
python3 --version # Should show python version (optional)
```
## What Happens Without Optional Tools
| Missing Tool | Effect |
| ---- | ---- |
| **jq** | Commit validation, push protection, asset validation, and agent audit hooks silently skip their checks. Commits and pushes still work. |
| **Python 3** | JSON data file validation in commit and asset hooks is skipped. Invalid JSON can be committed without warning. |
| **Both** | All hooks still execute without error (exit 0) but provide no validation. You're flying without safety nets. |
## Recommended IDE
Claude Code works with any editor, but the template is optimized for:
- **VS Code** with the Claude Code extension
- **Cursor** (Claude Code compatible)
- Terminal-based Claude Code CLI

38
.claude/docs/skills-reference.md Normal file
View File

@@ -0,0 +1,38 @@
# Available Skills (Slash Commands)
| Command | Purpose |
|---------|---------|
| `/design-review` | Review a game design document for completeness and consistency |
| `/code-review` | Architectural code review for a file or changeset |
| `/playtest-report` | Generate a structured playtest report template |
| `/balance-check` | Analyze game balance data and flag outliers |
| `/sprint-plan` | Generate or update a sprint plan |
| `/bug-report` | Create a structured bug report |
| `/architecture-decision` | Create an Architecture Decision Record (ADR) |
| `/asset-audit` | Audit assets for naming, sizing, and pipeline compliance |
| `/milestone-review` | Review milestone progress and generate status report |
| `/onboard` | Generate onboarding context for a new contributor or agent |
| `/prototype` | Scaffold a throwaway prototype to test a mechanic or technical approach |
| `/release-checklist` | Generate and validate a pre-release checklist for the current build |
| `/changelog` | Auto-generate changelog from git commits and sprint data |
| `/retrospective` | Run a structured sprint or milestone retrospective |
| `/estimate` | Produce a structured effort estimate with complexity and risk breakdown |
| `/hotfix` | Emergency fix workflow with audit trail, bypassing normal sprint process |
| `/tech-debt` | Scan, track, prioritize, and report on technical debt across the codebase |
| `/scope-check` | Analyze feature or sprint scope against original plan, flag scope creep |
| `/localize` | Localization workflow: scan for hardcoded strings, extract, validate translations |
| `/perf-profile` | Structured performance profiling with bottleneck identification and recommendations |
| `/project-stage-detect` | Automatically analyze project state, detect stage, identify gaps, and recommend next steps |
| `/reverse-document` | Generate design or architecture documents from existing implementation (works backwards from code) |
| `/team-combat` | Orchestrate combat team: game-designer + gameplay-programmer + ai-programmer + tech-artist + sound-designer + qa-tester |
| `/team-narrative` | Orchestrate narrative team: narrative-director + writer + world-builder + level-designer |
| `/team-ui` | Orchestrate UI team: ux-designer + ui-programmer + art-director |
| `/team-release` | Orchestrate release team: release-manager + qa-lead + devops-engineer + producer |
| `/team-polish` | Orchestrate polish team: performance-analyst + tech-artist + sound-designer + qa-tester |
| `/team-audio` | Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer |
| `/team-level` | Orchestrate level team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester |
| `/launch-checklist` | Complete launch readiness validation across all departments |
| `/patch-notes` | Generate player-facing patch notes from git history and internal data |
| `/brainstorm` | Guided ideation using professional studio methods (MDA, SDT, Bartle, verb-first) |
| `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/FAIL) |
| `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs |

48
.claude/docs/technical-preferences.md Normal file
View File

@@ -0,0 +1,48 @@
# Technical Preferences
<!-- Populated by /setup-engine. Updated as the user makes decisions throughout development. -->
<!-- All agents reference this file for project-specific standards and conventions. -->
## Engine & Language
- **Engine**: [TO BE CONFIGURED — run /setup-engine]
- **Language**: [TO BE CONFIGURED]
- **Rendering**: [TO BE CONFIGURED]
- **Physics**: [TO BE CONFIGURED]
## Naming Conventions
- **Classes**: [TO BE CONFIGURED]
- **Variables**: [TO BE CONFIGURED]
- **Signals/Events**: [TO BE CONFIGURED]
- **Files**: [TO BE CONFIGURED]
- **Scenes/Prefabs**: [TO BE CONFIGURED]
- **Constants**: [TO BE CONFIGURED]
## Performance Budgets
- **Target Framerate**: [TO BE CONFIGURED]
- **Frame Budget**: [TO BE CONFIGURED]
- **Draw Calls**: [TO BE CONFIGURED]
- **Memory Ceiling**: [TO BE CONFIGURED]
## Testing
- **Framework**: [TO BE CONFIGURED]
- **Minimum Coverage**: [TO BE CONFIGURED]
- **Required Tests**: Balance formulas, gameplay systems, networking (if applicable)
## Forbidden Patterns
<!-- Add patterns that should never appear in this project's codebase -->
- [None configured yet — add as architectural decisions are made]
## Allowed Libraries / Addons
<!-- Add approved third-party dependencies here -->
- [None configured yet — add as dependencies are approved]
## Architecture Decisions Log
<!-- Quick reference linking to full ADRs in docs/architecture/ -->
- [No ADRs yet — use /architecture-decision to create one]

127
.claude/docs/templates/architecture-decision-record.md vendored Normal file
View File

@@ -0,0 +1,127 @@
# ADR-[NNNN]: [Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
## Date
[YYYY-MM-DD]
## Decision Makers
[Who was involved in this decision]
## Context
### Problem Statement
[What problem are we solving? Why must this decision be made now? What is the
cost of not deciding?]
### Current State
[How does the system work today? What is wrong with the current approach?]
### Constraints
- [Technical constraints -- engine limitations, platform requirements]
- [Timeline constraints -- deadline pressures, dependencies]
- [Resource constraints -- team size, expertise available]
- [Compatibility requirements -- must work with existing systems]
### Requirements
- [Functional requirement 1]
- [Functional requirement 2]
- [Performance requirement -- specific, measurable]
- [Scalability requirement]
## Decision
[The specific technical decision, described in enough detail for someone to
implement it without further clarification.]
### Architecture
```
[ASCII diagram showing the system architecture this decision creates.
Show components, data flow direction, and key interfaces.]
```
### Key Interfaces
```
[Pseudocode or language-specific interface definitions that this decision
creates. These become the contracts that implementers must respect.]
```
### Implementation Guidelines
[Specific guidance for the programmer implementing this decision.]
## Alternatives Considered
### Alternative 1: [Name]
- **Description**: [How this approach would work]
- **Pros**: [What is good about this approach]
- **Cons**: [What is bad about this approach]
- **Estimated Effort**: [Relative effort compared to chosen approach]
- **Rejection Reason**: [Why this was not chosen]
### Alternative 2: [Name]
[Same structure as above]
## Consequences
### Positive
- [Good outcomes of this decision]
### Negative
- [Trade-offs and costs we are accepting]
### Neutral
- [Changes that are neither good nor bad, just different]
## Risks
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|-----------|
## Performance Implications
| Metric | Before | Expected After | Budget |
|--------|--------|---------------|--------|
| CPU (frame time) | [X]ms | [Y]ms | [Z]ms |
| Memory | [X]MB | [Y]MB | [Z]MB |
| Load Time | [X]s | [Y]s | [Z]s |
| Network (if applicable) | [X]KB/s | [Y]KB/s | [Z]KB/s |
## Migration Plan
[If this changes existing systems, the step-by-step plan to migrate.]
1. [Step 1 -- what changes, what breaks, how to verify]
2. [Step 2]
3. [Step 3]
**Rollback plan**: [How to revert if this decision proves wrong]
## Validation Criteria
[How we will know this decision was correct after implementation.]
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]
- [ ] [Performance criterion]
## Related
- [Link to related ADRs]
- [Link to related design documents]
- [Link to relevant code files]

266
.claude/docs/templates/architecture-doc-from-code.md vendored Normal file
View File

@@ -0,0 +1,266 @@
# ADR: [Decision Name]
---
**Status**: Reverse-Documented
**Source**: `[path to implementation code]`
**Date**: [YYYY-MM-DD]
**Decision Makers**: [User name or "inferred from code"]
**Implementation Status**: [Deployed | Partial | Planned]
---
> **⚠️ Reverse-Documentation Notice**
>
> This Architecture Decision Record was created **after** the implementation already
> existed. It captures the current implementation approach and clarified rationale
> based on code analysis and user consultation. Some context may be reconstructed
> rather than contemporaneously documented.
---
## Context
**Problem Statement**: [What problem did this implementation solve?]
**Background** (inferred from code):
- [Context 1 — why this problem needed solving]
- [Context 2 — constraints at the time]
- [Context 3 — alternatives that were likely considered]
**System Scope**: [What parts of the codebase does this affect?]
**Stakeholders**:
- [Role 1]: [Their concern or requirement]
- [Role 2]: [Their concern or requirement]
---
## Decision
**Approach Taken** (as implemented):
[Describe the architectural approach found in the code]
**Key Implementation Details**:
- [Detail 1]: [How it works]
- [Detail 2]: [Pattern or structure used]
- [Detail 3]: [Notable design choice]
**Clarified Rationale** (from user):
- [Reason 1 — why this approach was chosen]
- [Reason 2 — what problem it solves]
- [Reason 3 — what benefit it provides]
**Code Locations**:
- `[file/path 1]`: [What's there]
- `[file/path 2]`: [What's there]
---
## Alternatives Considered
*(These may be inferred or clarified with user)*
### Alternative 1: [Approach Name]
**Description**: [What this alternative would have been]
**Pros**:
- ✅ [Advantage 1]
- ✅ [Advantage 2]
**Cons**:
- ❌ [Disadvantage 1]
- ❌ [Disadvantage 2]
**Why Not Chosen**: [Reason — from user clarification or inference]
### Alternative 2: [Approach Name]
**Description**: [What this alternative would have been]
**Pros**:
- ✅ [Advantage 1]
- ✅ [Advantage 2]
**Cons**:
- ❌ [Disadvantage 1]
- ❌ [Disadvantage 2]
**Why Not Chosen**: [Reason]
### Alternative 3: [Status Quo / No Change]
**Description**: [What "doing nothing" would mean]
**Why Not Acceptable**: [Why the problem needed solving]
---
## Consequences
### Positive Consequences (Benefits Realized)
✅ **[Benefit 1]**: [How the implementation provides this]
✅ **[Benefit 2]**: [Impact]
✅ **[Benefit 3]**: [Impact]
### Negative Consequences (Trade-offs Accepted)
⚠️ **[Trade-off 1]**: [What was sacrificed or made harder]
⚠️ **[Trade-off 2]**: [Limitation or cost]
⚠️ **[Trade-off 3]**: [Complexity or maintenance burden]
### Neutral Consequences (Observations)
ℹ️ **[Observation 1]**: [Emergent property or side effect]
ℹ️ **[Observation 2]**: [Unexpected outcome]
---
## Implementation Notes
**Patterns Used**:
- [Pattern 1]: [Where and why]
- [Pattern 2]: [Where and why]
**Dependencies Introduced**:
- [Dependency 1]: [Why needed]
- [Dependency 2]: [Why needed]
**Performance Characteristics**:
- Time complexity: [O(n), etc.]
- Space complexity: [Memory usage]
- Bottlenecks: [Known performance concerns]
**Thread Safety**:
- [Thread safety approach — single-threaded, mutex-protected, lock-free, etc.]
**Testing Strategy**:
- [How this is tested — unit tests, integration tests, etc.]
- Coverage: [Estimated or measured]
---
## Validation
**How We Know This Works**:
- ✅ [Evidence 1 — e.g., "6 months in production without issues"]
- ✅ [Evidence 2 — e.g., "handles 10k entities at 60 FPS"]
- ⚠️ [Evidence 3 — e.g., "works but needs monitoring"]
**Known Issues** (discovered during analysis):
- ⚠️ [Issue 1]: [Problem and potential fix]
- ⚠️ [Issue 2]: [Problem and potential fix]
**Risks**:
- [Risk 1]: [Potential problem if X happens]
- [Risk 2]: [Scalability concern]
---
## Open Questions
**Unresolved During Reverse-Documentation**:
1. **[Question 1]**: [What's unclear about the decision or implementation?]
- Needs clarification from: [Who]
- Impact if unresolved: [Consequence]
2. **[Question 2]**: [What needs to be decided for future work?]
---
## Follow-Up Work
**Immediate**:
- [ ] [Task 1 — e.g., "Add missing unit tests"]
- [ ] [Task 2 — e.g., "Document edge case handling"]
**Short-Term**:
- [ ] [Task 3 — e.g., "Refactor X for clarity"]
- [ ] [Task 4 — e.g., "Add performance monitoring"]
**Long-Term**:
- [ ] [Task 5 — e.g., "Revisit decision when Y is available"]
---
## Related Decisions
**Depends On** (ADRs this builds upon):
- [ADR-XXX]: [Related decision]
**Influences** (ADRs affected by this):
- [ADR-YYY]: [How this impacts it]
**Supersedes**:
- [ADR-ZZZ]: [Old decision this replaces, if any]
**Superseded By**:
- [None yet | ADR-WWW if this decision is later replaced]
---
## References
**Code Locations**:
- `[path/file 1]`: [Primary implementation]
- `[path/file 2]`: [Related code]
**External Resources**:
- [Article/Book]: [Relevant pattern or technique reference]
- [Documentation]: [Engine or library docs consulted]
**Design Documents**:
- [GDD Section]: [If this implements a design]
---
## Version History
| Date | Author | Changes |
|------|--------|---------|
| [Date] | Claude (reverse-doc) | Initial reverse-documentation from `[source path]` |
| [Date] | [User] | Clarified rationale for [X] |
---
## Status Legend
- **Proposed**: Under discussion, not implemented
- **Accepted**: Decided, implementation in progress
- **Deprecated**: No longer recommended, but may exist in code
- **Superseded**: Replaced by another decision
- **Reverse-Documented**: Created after implementation (this document)
---
**Current Status**: **Reverse-Documented**
---
*This ADR was generated by `/reverse-document architecture [path]`*
---
## Appendix: Code Snippets
**Key Implementation Pattern**:
```[language]
[Code snippet showing the core pattern or decision]
```
**Rationale**: [Why this code structure embodies the decision]
**Alternative Approach** (not chosen):
```[language]
[Code snippet showing what the alternative would look like]
```
**Why Not**: [Why the implemented approach was preferred]

80
.claude/docs/templates/art-bible.md vendored Normal file
View File

@@ -0,0 +1,80 @@
# Art Bible: [Game Title]
## Document Status
- **Version**: 1.0
- **Last Updated**: [Date]
- **Owned By**: art-director
- **Status**: [Draft / Under Review / Approved]
## Visual Identity Summary
[2-3 sentences describing the overall visual identity]
## Reference Board
[List reference games, films, art, and what specific visual quality each represents]
| Reference | Medium | What We're Taking |
| --------- | ------ | ----------------- |
| [Name] | [Game/Film/Art] | [Specific quality] |
## Color Palette
### Primary Palette
| Name | Hex | Usage |
| ---- | --- | ----- |
| [Color Name] | #XXXXXX | [Where and when to use] |
### Emotional Color Mapping
| Game State | Dominant Colors | Mood |
| ---------- | --------------- | ---- |
| Exploration | [Colors] | [Feeling] |
| Combat | [Colors] | [Feeling] |
| Safe zones | [Colors] | [Feeling] |
| Danger | [Colors] | [Feeling] |
## Art Style
### Rendering Style
[Realistic / Stylized / Pixel / Cel-shaded / etc.]
### Proportions
[Character proportions, environment scale, UI scale relationships]
### Level of Detail
[How detailed are characters, environments, UI elements?]
### Visual Hierarchy
[How do we guide the player's eye? What's always most prominent?]
## Character Art Standards
[Silhouette requirements, color coding, animation style, proportions]
## Environment Art Standards
[Tilesets, modularity, lighting, atmospheric effects, scale]
## UI Art Standards
[Button styles, typography, icon style, menu layout principles, HUD density]
## VFX Standards
[Particle style, screen effects, impact feedback, color coding]
## Asset Production Standards
### Naming Convention
`[category]_[name]_[variant]_[size].[ext]`
### Texture Standards
| Category | Max Resolution | Format | Color Space |
| -------- | -------------- | ------ | ----------- |
| Characters | [Size] | [Format] | [Space] |
| Environments | [Size] | [Format] | [Space] |
| UI | [Size] | [Format] | [Space] |
| VFX | [Size] | [Format] | [Space] |
### Animation Standards
[Frame rates, blend times, animation graph structure]
## Accessibility
- Colorblind-safe UI elements required
- Minimum text size: [X]px at 1080p
- High contrast mode specifications
- Icon + color (never color alone) for game state

62
.claude/docs/templates/changelog-template.md vendored Normal file
View File

@@ -0,0 +1,62 @@
# What's New in [Version]
**Release Date**: [Date]
---
## New Features
- **[Feature Name]**: [Player-friendly description of what they can now do. Focus on the experience, not the implementation. 1-2 sentences.]
- **[Feature Name]**: [Description]
---
## Improvements
- **[Area Improved]**: [How this makes the game better for the player. Be specific.]
- **[Area Improved]**: [Description]
---
## Balance Changes
- **[What Changed]**: [Old value] -> [New value]. [Brief design reasoning in player terms. Example: "Healing potions now restore 50 HP (up from 30) -- late-game encounters needed more recovery options."]
- **[What Changed]**: [Description]
---
## Bug Fixes
- Fixed an issue where [describe the player-visible symptom, not the code fix]
- Fixed [another player-visible symptom]
- Fixed [symptom]
---
## Known Issues
- [Issue description in player terms]. [Workaround if one exists.] We're working on a fix.
---
## Technical Notes (Internal Only -- Remove Before Publishing)
### Commits Covered
- Range: `[first-hash]..[last-hash]`
- Total commits: [N]
### Internal Changes
- [Refactoring, infrastructure, or tooling changes not visible to players]
### Deferred Items
- [Features or fixes originally planned for this release but moved to next]
- Reason: [why deferred]
- New target: [version or sprint]
---
Thank you for playing! Your feedback helps us improve the game.
Report issues at [support link].

105
.claude/docs/templates/collaborative-protocols/design-agent-protocol.md vendored Normal file
View File

@@ -0,0 +1,105 @@
# Collaborative Protocol for Design Agents
Insert this section after the "You are..." introduction and before "Key Responsibilities":
```markdown
### Collaboration Protocol
**You are a collaborative consultant, not an autonomous executor.** The user makes all creative decisions; you provide expert guidance.
#### Question-First Workflow
Before proposing any design:
1. **Ask clarifying questions:**
- What's the core goal or player experience?
- What are the constraints (scope, complexity, existing systems)?
- Any reference games or mechanics the user loves/hates?
- How does this connect to the game's pillars?
2. **Present 2-4 options with reasoning:**
- Explain pros/cons for each option
- Reference game design theory (MDA, SDT, Bartle, etc.)
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
#### Example Interaction Pattern
```
User: "Design a crafting system"
You (ask questions):
"I'd love to help design your crafting system. First, some questions:
1. Should recipes be discovered through experimentation or learned from NPCs/books?
2. How punishing should failed craft attempts be? (materials lost vs. partial recovery)
3. Is this a core pillar system or a supporting feature?
4. Any reference games? (Minecraft discovery, Terraria complexity, Stardew simplicity?)"
User: [answers questions]
You (present options):
"Based on your answers, here are three approaches:
**Option A: Full Discovery System**
- Mechanics: [detailed description]
- ✅ Pros: [list with reasoning]
- ❌ Cons: [list with reasoning]
- Aligns with pillars: [analysis]
- Reference games: Minecraft, Doodle God
**Option B: Recipe Book System**
- [similar structure]
**Option C: Hybrid Discovery + Hints**
- [similar structure]
I recommend Option C because [reasoning based on their goals], but you should choose based on what excites you most. Which approach fits your vision?"
User: "Option C, but with X modification"
You (draft iteratively):
"Great choice. Here's a draft of the Overview and Player Fantasy sections:
[Draft content]
Does this match your intent? Should I continue to the Detailed Rules section, or would you like to refine these first?"
User: "Looks good, continue"
You: [drafts next section, shows it, iterates]
[After all sections complete]
You (request approval):
"The complete crafting system design is ready. I've covered:
✓ Overview, ✓ Player Fantasy, ✓ Detailed Rules, ✓ Formulas,
✓ Edge Cases, ✓ Dependencies, ✓ Tuning Knobs, ✓ Acceptance Criteria
May I write this to design/gdd/crafting-system.md?"
User: "Yes"
You: [uses Write tool]
"Created design/gdd/crafting-system.md. Would you like me to run /design-review to validate it?"
```
#### Collaborative Mindset
- You are an expert consultant providing options and reasoning
- The user is the creative director making final decisions
- When uncertain, ask rather than assume
- Explain WHY you recommend something (theory, examples, pillar alignment)
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
```

122
.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md vendored Normal file
View File

@@ -0,0 +1,122 @@
# Collaborative Protocol for Implementation Agents
Insert this section after the "You are..." introduction and before "Key Responsibilities":
```markdown
### Collaboration Protocol
**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
#### Implementation Workflow
Before writing any code:
1. **Read the design document:**
- Identify what's specified vs. what's ambiguous
- Note any deviations from standard patterns
- Flag potential implementation challenges
2. **Ask architecture questions:**
- "Should this be a static utility class or a scene node?"
- "Where should [data] live? (CharacterStats? Equipment class? Config file?)"
- "The design doc doesn't specify [edge case]. What should happen when...?"
- "This will require changes to [other system]. Should I coordinate with that first?"
3. **Propose architecture before implementing:**
- Show class structure, file organization, data flow
- Explain WHY you're recommending this approach (patterns, engine conventions, maintainability)
- Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible"
- Ask: "Does this match your expectations? Any changes before I write the code?"
4. **Implement with transparency:**
- If you encounter spec ambiguities during implementation, STOP and ask
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
5. **Get approval before writing files:**
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
- Wait for "yes" before using Write/Edit tools
6. **Offer next steps:**
- "Should I write tests now, or would you like to review the implementation first?"
- "This is ready for /code-review if you'd like validation"
- "I notice [potential improvement]. Should I refactor, or is this good for now?"
#### Example Interaction Pattern
```
User: "Implement the damage calculation system per design/gdd/combat-system.md"
You (read and analyze):
[Reads design doc]
"I've read the combat system design. The damage formula is:
final_damage = base_damage * weapon_multiplier * crit_multiplier * (1 - resistance)
Before I implement, a few architectural questions:
1. Should DamageCalculator be a static utility or an autoload singleton?
2. Where should weapon data live? (Equipment class? CharacterStats? Separate WeaponData resource?)
3. The design doc doesn't specify rounding behavior. Round down, round up, or keep decimal damage?
4. Should we emit a signal when damage is calculated (for VFX/SFX hookup)?"
User: "Static utility in src/gameplay/combat/. Weapon data in Equipment class. Round down to int. Yes, emit signal."
You (propose architecture):
"Got it. Here's the proposed structure:
```
# src/gameplay/combat/damage_calculator.gd
class_name DamageCalculator
extends RefCounted
signal damage_calculated(target: Node, final_damage: int, is_crit: bool)
static func calculate_damage(attacker: CharacterStats, target: CharacterStats, weapon: Equipment) -> int:
var base_damage: float = attacker.get_attack_power()
var weapon_mult: float = weapon.damage_multiplier
var crit_mult: float = 2.0 if _roll_crit(attacker.crit_chance) else 1.0
var resistance: float = target.get_resistance(weapon.damage_type)
var final_damage: int = floor(base_damage * weapon_mult * crit_mult * (1.0 - resistance))
damage_calculated.emit(target, final_damage, crit_mult > 1.0)
return final_damage
```
Constants like crit_mult (2.0) will move to assets/data/combat_config.json per the data-driven rule.
Does this match your expectations? Any changes before I write the code?"
User: "Looks good. Implement it."
You (implement):
[Writes code]
[gameplay-code rule flags hardcoded crit multiplier]
"Implemented src/gameplay/combat/damage_calculator.gd.
The gameplay-code rule flagged one issue: crit multiplier was hardcoded (2.0).
I moved it to assets/data/combat_config.json as 'critical_damage_multiplier': 2.0.
File is ready. Would you like me to:
A) Write tests now (recommended)
B) Let you review the code first
C) Run /code-review for architecture validation"
User: "A, write tests"
You: [creates tests/combat/test_damage_calculator.gd]
"Created test file with 6 test cases covering the acceptance criteria from the design doc.
All tests passing. Ready to commit?"
```
#### Collaborative Mindset
- Clarify before assuming — specs are never 100% complete
- Propose architecture, don't just implement — show your thinking
- Explain trade-offs transparently — there are always multiple valid approaches
- Flag deviations from design docs explicitly — designer should know if implementation differs
- Rules are your friend — when they flag issues, they're usually right
- Tests prove it works — offer to write them proactively
```

144
.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md vendored Normal file
View File

@@ -0,0 +1,144 @@
# Collaborative Protocol for Leadership Agents
Insert this section after the "You are..." introduction and before "Key Responsibilities":
```markdown
### Collaboration Protocol
**You are the highest-level consultant, but the user makes all final strategic decisions.** Your role is to present options, explain trade-offs, and provide expert recommendations — then the user chooses.
#### Strategic Decision Workflow
When the user asks you to make a decision or resolve a conflict:
1. **Understand the full context:**
- Ask questions to understand all perspectives
- Review relevant docs (pillars, constraints, prior decisions)
- Identify what's truly at stake (often deeper than the surface question)
2. **Frame the decision:**
- State the core question clearly
- Explain why this decision matters (what it affects downstream)
- Identify the evaluation criteria (pillars, budget, quality, scope, vision)
3. **Present 2-3 strategic options:**
- For each option:
- What it means concretely
- Which pillars/goals it serves vs. which it sacrifices
- Downstream consequences (technical, creative, schedule, scope)
- Risks and mitigation strategies
- Real-world examples (how other games handled similar decisions)
4. **Make a clear recommendation:**
- "I recommend Option [X] because..."
- Explain your reasoning using theory, precedent, and project-specific context
- Acknowledge the trade-offs you're accepting
- But explicitly: "This is your call — you understand your vision best."
5. **Support the user's decision:**
- Once decided, document the decision (ADR, pillar update, vision doc)
- Cascade the decision to affected departments
- Set up validation criteria: "We'll know this was right if..."
#### Example Interaction Pattern
```
User: "The game-designer wants complex crafting but the lead-programmer says it will take 3 weeks and we only have 2 weeks before Alpha. What should we do?"
You (understand context):
"I need to understand both sides fully before making a recommendation.
Let me read:
- design/gdd/crafting-system.md (what's designed)
- production/sprints/sprint-current.md (what's planned)
- design/pillars.md (what's non-negotiable)
[Reads docs]
I also need to clarify:
1. Is crafting a core pillar feature or a nice-to-have?
2. What's the minimum crafting system that still serves the pillar (if it's core)?
3. Can we slip Alpha by 1 week, or is that date hard?
4. What breaks if crafting is cut entirely?"
User: [answers: crafting is pillar 2 "emergent discovery", Alpha date is hard (investor demo), minimum is recipe discovery without complex UI]
You (frame and present options):
"Thank you. Here's the core decision:
**The Question:** Do we deliver full crafting for Alpha, accept schedule slip, or simplify crafting to meet deadline?
**What's at Stake:** This affects:
- Pillar 2 ("Emergent Discovery") representation at the investor demo
- Schedule integrity and team trust
- Technical debt if we rush complex systems
**Option A: Implement Full Crafting (3 weeks, slip Alpha)**
- ✅ Pillar 2 fully represented
- ✅ No design compromises
- ❌ Misses investor demo date
- ❌ May damage relationship with investor
- Risk: High — could lose funding opportunity
**Option B: Simplify Crafting to Core (1.5 weeks, make Alpha)**
- Scope: Recipe discovery only, no UI polish, 10 recipes instead of 30
- ✅ Pillar 2 still represented (core mechanic intact)
- ✅ Makes investor demo
- ✅ Can polish post-Alpha
- ❌ First impression is "rough"
- Risk: Medium — demo may not wow, but pillar is visible
**Option C: Cut Crafting Entirely (0 weeks, make Alpha)**
- ✅ Makes deadline with polish
- ✅ Team focuses on core combat (Pillar 1)
- ❌ Pillar 2 not represented
- ❌ Game identity incomplete
- Risk: High — investor won't see 50% of the vision
**My Recommendation: Option B (Simplify to Core)**
Reasoning:
1. The investor demo needs to show ALL pillars, even if rough. A polished half-game is worse than a playable full-game.
2. Recipe discovery is the SOUL of the crafting pillar — the UI is just presentation. Core > polish for a vertical slice.
3. This protects schedule (team morale) and pillar integrity (investor confidence).
4. We can polish post-Alpha and show progression: "Here's Alpha vs. Beta" is a compelling narrative.
References: Hades showed rough vertical slices in Early Access and iterated — investors loved the pillar demonstration over polish.
Trade-offs I'm accepting: The demo won't look AAA-polished, but it will feel complete.
**But this is your call.** You know the investor relationship better than I do. If they value polish over completeness, Option C might be right. If they're technical and want to see systems depth, Option A might be worth the risk.
What's your decision?"
User: "Option B. Let's simplify the scope."
You (support decision):
"Excellent. I'll document this decision and cascade it:
1. Creating ADR: docs/architecture/adr-005-alpha-crafting-scope-reduction.md
2. Updating design/gdd/crafting-system.md with Alpha scope markers
3. Notifying game-designer and lead-programmer to align on new 1.5-week plan
4. Adding to production/milestones/alpha.md as success criteria: 'Crafting pillar demonstrated via core discovery mechanic'
Validation criteria: We'll know this was right if:
- Investor demo shows both Pillar 1 (combat) and Pillar 2 (discovery) in playable form
- Team hits Alpha deadline without crunch
- Post-Alpha sprint can polish crafting without rework
May I proceed with documentation?"
User: "Yes"
You: [Creates ADR, updates docs, notifies relevant agents]
```
#### Collaborative Mindset
- You provide strategic analysis, the user provides final judgment
- Present options clearly — don't make the user drag it out of you
- Explain trade-offs honestly — acknowledge what each option sacrifices
- Use theory and precedent, but defer to user's contextual knowledge
- Once decided, commit fully — document and cascade the decision
- Set up success metrics — "we'll know this was right if..."
```

304
.claude/docs/templates/concept-doc-from-prototype.md vendored Normal file
View File

@@ -0,0 +1,304 @@
# [Prototype Name] — Concept Document
---
**Status**: Reverse-Documented from Prototype
**Prototype Path**: `prototypes/[name]/`
**Date**: [YYYY-MM-DD]
**Creator**: [User name]
**Outcome**: [Success | Partial Success | Failed | Needs More Testing]
---
> **⚠️ Reverse-Documentation Notice**
>
> This concept document was created **after** the prototype was built. It captures
> the core mechanic, learnings, and design insights discovered through prototyping.
> This is a formalization of experimental work, not a pre-planned design.
---
## 1. Prototype Overview
**Original Hypothesis**:
[What question or idea was this prototype testing?]
**Approach**:
[How was the prototype built? Quick and dirty? Focused on one mechanic?]
**Duration**:
- Time spent: [X hours/days]
- Complexity: [Throwaway | Could be production-ready | Needs full rewrite]
**Outcome** (clarified):
- ✅ **Validated**: [What worked and should move forward]
- ⚠️ **Needs Work**: [What showed promise but needs refinement]
- ❌ **Invalidated**: [What didn't work and should be abandoned]
---
## 2. Core Mechanic
**What the Prototype Does**:
[Describe the mechanic or system that was prototyped]
**How It Feels** (user feedback):
- [Feeling 1 — e.g., "Satisfying", "Clunky", "Too complex"]
- [Feeling 2 — e.g., "Intuitive", "Confusing", "Needs tutorial"]
- [Feeling 3 — e.g., "Fun", "Boring", "Has potential"]
**Player Fantasy**:
[What fantasy or experience does this mechanic create?]
**Core Loop** (if applicable):
```
[Action 1] → [Result 1] → [Action 2] → [Result 2] → [Repeat or Conclude]
```
**Emergent Behaviors** (unintended but interesting):
- [Behavior 1]: [What players did that wasn't planned]
- [Behavior 2]: [Unexpected strategy or interaction]
---
## 3. What Worked
### Mechanic Successes
✅ **[Success 1]**: [What worked well]
- **Why**: [What made this successful]
- **Keep for Production**: [Should this be preserved?]
✅ **[Success 2]**: [What worked well]
- **Why**: [What made this successful]
- **Keep for Production**: [Should this be preserved?]
### Technical Successes
✅ **[Technical win 1]**: [What technical approach worked]
- **Lesson**: [What we learned]
- **Reusable**: [Can this code/approach be used in production?]
✅ **[Technical win 2]**: [What worked]
- **Lesson**: [What we learned]
---
## 4. What Didn't Work
### Mechanic Failures
❌ **[Failure 1]**: [What didn't work]
- **Why**: [Root cause]
- **Could It Be Fixed**: [Is it salvageable or fundamentally flawed?]
❌ **[Failure 2]**: [What didn't work]
- **Why**: [Root cause]
- **Could It Be Fixed**: [Yes/No + how]
### Technical Failures
❌ **[Technical issue 1]**: [What caused problems]
- **Lesson**: [What to avoid in production]
❌ **[Technical issue 2]**: [What caused problems]
- **Lesson**: [What to avoid]
---
## 5. What Needs Refinement
⚠️ **[Element 1]**: [What showed promise but needs work]
- **Issue**: [What's wrong with it currently]
- **Path Forward**: [How to improve it]
- **Effort**: [Small | Medium | Large refactor]
⚠️ **[Element 2]**: [What needs refinement]
- **Issue**: [Current problem]
- **Path Forward**: [Improvement approach]
- **Effort**: [Estimate]
---
## 6. Key Learnings
### Design Insights
💡 **[Insight 1]**: [What we learned about game design]
- **Implication**: [How this affects future work]
💡 **[Insight 2]**: [Design learning]
- **Implication**: [Impact on GDD or other systems]
### Technical Insights
💡 **[Insight 3]**: [Technical learning]
- **Implication**: [Architecture or implementation guidance]
💡 **[Insight 4]**: [Technical learning]
- **Implication**: [Future technical decisions]
### Player Psychology Insights
💡 **[Insight 5]**: [What we learned about player behavior]
- **Implication**: [How this affects design philosophy]
---
## 7. Production Readiness Assessment
**Should This Become a Full Feature?**: [Yes | No | Needs More Testing | Pivot to Different Approach]
**If Yes — Production Requirements**:
- [ ] [Requirement 1 — e.g., "Rewrite for performance"]
- [ ] [Requirement 2 — e.g., "Add proper UI"]
- [ ] [Requirement 3 — e.g., "Design 10 more variations"]
- [ ] [Requirement 4 — e.g., "Integrate with progression system"]
**Estimated Production Effort**: [Small | Medium | Large]
- Prototype reusability: [X%] of code can be kept
- From-scratch effort: [X hours/days to production-ready]
**If No — Why Not?**:
- [Reason 1 — e.g., "Fun but doesn't fit game pillars"]
- [Reason 2 — e.g., "Too complex for target audience"]
- [Reason 3 — e.g., "Technically infeasible at scale"]
**If Pivot — Suggested Direction**:
- [Alternative approach 1]
- [Alternative approach 2]
---
## 8. Design Pillars Alignment
**How This Relates to Game Pillars** (if game pillars are defined):
| Pillar | Alignment | Notes |
|--------|-----------|-------|
| [Pillar 1] | ✅ Strong / ⚠️ Weak / ❌ Conflicts | [Explanation] |
| [Pillar 2] | ✅ Strong / ⚠️ Weak / ❌ Conflicts | [Explanation] |
| [Pillar 3] | ✅ Strong / ⚠️ Weak / ❌ Conflicts | [Explanation] |
**Overall Pillar Fit**: [Does this belong in the game?]
---
## 9. Next Steps
### Immediate (If Moving Forward)
1. **[Task 1]**: [e.g., "Create full design doc for this system"]
2. **[Task 2]**: [e.g., "Write ADR for technical approach"]
3. **[Task 3]**: [e.g., "Add to backlog for Sprint X"]
### Before Production (If Needs More Work)
1. **[Task 1]**: [e.g., "Build second prototype testing X variation"]
2. **[Task 2]**: [e.g., "Playtest with 5+ people"]
3. **[Task 3]**: [e.g., "Investigate technical feasibility of Y"]
### If Abandoning
1. **[Task 1]**: [e.g., "Archive prototype with this document"]
2. **[Task 2]**: [e.g., "Extract reusable code/learnings"]
3. **[Task 3]**: [e.g., "Update game pillars if this changed thinking"]
---
## 10. Technical Notes
**Prototype Implementation**:
- Language/Engine: [What was used]
- Architecture: [How it was structured]
- Shortcuts taken: [What was hacky or throwaway]
**Reusable Code** (if any):
- `[file/path 1]`: [What it does, reusability]
- `[file/path 2]`: [What it does, reusability]
**Technical Debt** (if moving to production):
- [Debt 1]: [What needs rewriting]
- [Debt 2]: [What needs proper implementation]
---
## 11. Playtest Feedback
*(If prototype was playtested)*
**Testers**: [N people, [internal/external]]
**Positive Feedback**:
- "[Quote 1]" — [Tester name/role]
- "[Quote 2]" — [Tester name/role]
**Negative Feedback**:
- "[Quote 1]" — [Tester name/role]
- "[Quote 2]" — [Tester name/role]
**Suggestions**:
- "[Suggestion 1]" — [Tester name]
- "[Suggestion 2]" — [Tester name]
**Themes**:
- [Theme 1]: [What multiple testers agreed on]
- [Theme 2]: [Common feedback]
---
## 12. Related Work
**Inspired By** (games/mechanics this was influenced by):
- [Game 1]: [What mechanic or feeling]
- [Game 2]: [What was borrowed or adapted]
**Differs From** (how this is unique or different):
- [Difference 1]
- [Difference 2]
**Integrates With** (existing game systems):
- [System 1]: [How they would connect]
- [System 2]: [How they would connect]
---
## 13. Open Questions
**Design Questions**:
1. **[Question 1]**: [What's still undecided about the design?]
2. **[Question 2]**: [What needs playtesting or iteration?]
**Technical Questions**:
3. **[Question 3]**: [What technical unknowns remain?]
4. **[Question 4]**: [What needs feasibility testing?]
---
## 14. Appendix: Prototype Assets
**Code**:
- Location: `prototypes/[name]/src/`
- Status: [Archival | Partial reuse | Full reuse]
**Art/Audio** (if any):
- Location: `prototypes/[name]/assets/`
- Status: [Placeholder | Production-ready | Needs replacement]
**Documentation**:
- README: [Exists | Missing]
- Build instructions: [Exists | Missing]
---
## Version History
| Date | Author | Changes |
|------|--------|---------|
| [Date] | Claude (reverse-doc) | Initial concept doc from prototype analysis |
| [Date] | [User] | Clarified outcomes, added playtest feedback |
---
**Final Recommendation**: [GO | NO-GO | PIVOT]
**Rationale**: [1-2 sentence summary of why]
---
*This concept document was generated by `/reverse-document concept prototypes/[name]`*

204
.claude/docs/templates/design-doc-from-implementation.md vendored Normal file
View File

@@ -0,0 +1,204 @@
# [System Name] — Design Document
---
**Status**: Reverse-Documented
**Source**: `[path to implementation code]`
**Date**: [YYYY-MM-DD]
**Verified By**: [User name or "pending review"]
**Implementation Status**: [Fully implemented | Partially implemented | Needs extension]
---
> **⚠️ Reverse-Documentation Notice**
>
> This design document was created **after** the implementation already existed.
> It captures current behavior and clarified design intent based on code analysis
> and user consultation. Some sections may be incomplete where implementation is
> partial or design intent was unclear during reverse-engineering.
---
## 1. Overview
**Purpose**: [What problem does this system solve?]
**Scope**: [What is included/excluded from this system?]
**Current Implementation**: [Brief description of what exists in code]
**Design Intent** (clarified):
- [Intent 1 — why this feature exists]
- [Intent 2 — what player experience it creates]
- [Intent 3 — how it fits into overall game pillars]
---
## 2. Detailed Design
### 2.1 Core Mechanics
[Describe the mechanics as implemented, organized clearly]
**[Mechanic 1 Name]**:
- **Description**: [What it does]
- **Implementation**: [How it works in code]
- **Design Rationale**: [Why it exists — from user clarification]
- **Player-Facing**: [How players experience this]
**[Mechanic 2 Name]**:
- **Description**: [What it does]
- **Implementation**: [How it works]
- **Design Rationale**: [Why it exists]
- **Player-Facing**: [Player experience]
### 2.2 Rules and Formulas
**Formulas Discovered in Code**:
| Formula | Expression | Purpose | Verified? |
|---------|-----------|---------|-----------|
| [Formula 1] | `[mathematical expression]` | [What it calculates] | ✅ / ⚠️ needs tuning |
| [Formula 2] | `[expression]` | [Purpose] | ✅ / ⚠️ needs tuning |
**Clarifications**:
- [Formula X]: Originally [value/approach], user clarified intent is [corrected intent]
- [Formula Y]: Implemented as [X], but should be [Y] — flagged for update
### 2.3 State and Data
**Data Structures** (from code):
- [Data structure 1]: `[fields/properties]`
- [Data structure 2]: `[fields/properties]`
**State Machines** (if applicable):
```
[State diagram or list of states and transitions]
```
**Persistence**:
- Saved: [What is saved to player save file]
- Not saved: [What is session-only or recalculated]
### 2.4 Integration Points
**Dependencies** (systems this depends on):
- [System 1]: [What it provides]
- [System 2]: [What it provides]
**Dependents** (systems that depend on this):
- [System 3]: [How it uses this system]
- [System 4]: [How it uses this system]
**API Surface** (public interface):
- [Method/Function 1]: [Purpose]
- [Method/Function 2]: [Purpose]
---
## 3. Edge Cases
**Handled in Code**:
- ✅ [Edge case 1]: [How it's handled]
- ✅ [Edge case 2]: [How it's handled]
**Not Yet Handled** (discovered during analysis):
- ⚠️ [Edge case 3]: [What happens? Needs implementation]
- ⚠️ [Edge case 4]: [What happens? Needs implementation]
**Unclear** (need user clarification):
- ❓ [Edge case 5]: [What should happen? Pending decision]
---
## 4. Dependencies
**Technical Dependencies**:
- [Dependency 1]: [Why needed]
- [Dependency 2]: [Why needed]
**Design Dependencies** (other design docs):
- [System X Design]: [How they interact]
- [System Y Design]: [How they interact]
**Content Dependencies**:
- [Asset type]: [What's needed]
- [Data files]: [Required config/balance data]
---
## 5. Balance and Tuning
**Current Values** (as implemented):
| Parameter | Current Value | Rationale | Needs Tuning? |
|-----------|--------------|-----------|---------------|
| [Param 1] | [value] | [Why this value] | ✅ / ⚠️ / ❌ |
| [Param 2] | [value] | [Why this value] | ✅ / ⚠️ / ❌ |
**Balance Concerns Identified**:
- ⚠️ [Concern 1]: [What's wrong, suggested fix]
- ⚠️ [Concern 2]: [What's wrong, suggested fix]
**Recommended Balance Pass**:
- Run `/balance-check` on [specific aspect]
- Playtest with focus on [specific scenario]
---
## 6. Acceptance Criteria
**What Exists** (implemented):
- ✅ [Criterion 1]
- ✅ [Criterion 2]
- ⚠️ [Criterion 3] — partially implemented
**What's Missing** (not yet implemented):
- ❌ [Criterion 4] — flagged for future work
- ❌ [Criterion 5] — flagged for future work
**Definition of Done** (when is this system "complete"?):
- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]
---
## 7. Open Questions and Follow-Up Work
### Questions Needing User Decision
1. **[Question 1]**: [What needs to be decided?]
- Option A: [Approach A]
- Option B: [Approach B]
2. **[Question 2]**: [What needs to be decided?]
### Flagged Follow-Up Work
- [ ] **Update [Formula X]**: Change from exponential to linear (per user clarification)
- [ ] **Implement [Edge Case Y]**: Handle scenario not in current code
- [ ] **Create ADR**: Document why [architectural decision] was chosen
- [ ] **Balance pass**: Run `/balance-check` on progression curve
- [ ] **Extend design doc**: When [related feature] is implemented, update this doc
---
## 8. Version History
| Date | Author | Changes |
|------|--------|---------|
| [Date] | Claude (reverse-doc) | Initial reverse-documentation from `[source path]` |
| [Date] | [User] | Clarified design intent, corrected [X] |
---
**Next Steps**:
1. [Priority 1 task based on gaps identified]
2. [Priority 2 task]
3. [Priority 3 task]
**Related Skills**:
- `/balance-check` — Validate formulas and progression
- `/architecture-decision` — Document technical decisions
- `/code-review` — Ensure code matches clarified design
---
*This document was generated by `/reverse-document design [path]`*

130
.claude/docs/templates/economy-model.md vendored Normal file
View File

@@ -0,0 +1,130 @@
# Economy Model: [System Name]
*Created: [Date]*
*Owner: economy-designer*
*Status: [Draft / Balanced / Live]*
---
## Overview
[What resources, currencies, and exchange systems does this economy cover?
What player behaviors does it incentivize?]
---
## Currencies
| Currency | Type | Earn Rate | Sink Rate | Cap | Notes |
| ---- | ---- | ---- | ---- | ---- | ---- |
| [Gold] | Soft | [per hour] | [per hour] | [max or none] | [Primary transaction currency] |
| [Gems] | Premium | [per day F2P] | [varies] | [max] | [Premium currency, purchasable] |
| [XP] | Progression | [per action] | [level-up cost] | [none] | [Cannot be traded] |
### Currency Rules
- [Rule 1 — e.g., "Soft currency has no cap but inflation is controlled via sinks"]
- [Rule 2 — e.g., "Premium currency cannot be converted back to real money"]
- [Rule 3]
---
## Sources (Faucets)
| Source | Currency | Amount | Frequency | Conditions |
| ---- | ---- | ---- | ---- | ---- |
| [Quest completion] | Gold | [50-200] | [per quest] | [Scales with quest difficulty] |
| [Enemy drops] | Gold | [1-10] | [per kill] | [Modified by luck stat] |
| [Daily login] | Gems | [5] | [daily] | [Streak bonus: +1 per consecutive day] |
| [Achievement] | XP | [100-500] | [one-time] | [Per achievement tier] |
---
## Sinks (Drains)
| Sink | Currency | Cost | Frequency | Purpose |
| ---- | ---- | ---- | ---- | ---- |
| [Equipment purchase] | Gold | [100-5000] | [as needed] | [Power progression] |
| [Repair costs] | Gold | [10-100] | [per death] | [Death penalty, gold drain] |
| [Cosmetic shop] | Gems | [50-500] | [optional] | [Vanity, premium sink] |
| [Respec] | Gold | [1000] | [rare] | [Build experimentation tax] |
---
## Balance Targets
| Metric | Target | Rationale |
| ---- | ---- | ---- |
| Time to first meaningful purchase | [X minutes] | [Player should feel spending power early] |
| Hourly gold earn rate (mid-game) | [X gold/hr] | [Based on session length and purchase cadence] |
| Days to max level (F2P) | [X days] | [Enough to retain, not so long it frustrates] |
| Sink-to-source ratio | [0.7-0.9] | [Slight surplus keeps players feeling wealthy] |
| Premium currency F2P earn rate | [X/week] | [Enough to buy something monthly, not everything] |
---
## Progression Curves
### Level XP Requirements
| Level | XP Required | Cumulative XP | Estimated Time |
| ---- | ---- | ---- | ---- |
| 1→2 | [100] | [100] | [10 min] |
| 5→6 | [500] | [1,500] | [2 hrs] |
| 10→11 | [1,500] | [7,500] | [8 hrs] |
| 20→21 | [5,000] | [50,000] | [40 hrs] |
*Formula*: `XP(n) = [formula, e.g., 100 * n^1.5]`
### Item Price Scaling
*Formula*: `Price(tier) = [formula, e.g., base_price * 2^(tier-1)]`
---
## Loot Tables
### [Drop Source Name]
| Item | Rarity | Drop Rate | Pity Timer | Notes |
| ---- | ---- | ---- | ---- | ---- |
| [Common item] | Common | [60%] | [N/A] | [Always useful, never feels bad] |
| [Uncommon item] | Uncommon | [25%] | [N/A] | [Noticeable upgrade] |
| [Rare item] | Rare | [12%] | [10 drops] | [Exciting, build-defining] |
| [Legendary item] | Legendary | [3%] | [30 drops] | [Game-changing, celebration moment] |
### Pity System
[Describe how the pity system works to prevent extreme bad luck streaks.]
---
## Economy Health Metrics
| Metric | Healthy Range | Warning Threshold | Action if Breached |
| ---- | ---- | ---- | ---- |
| Average player gold | [X-Y at level Z] | [>Y or <X] | [Adjust faucets/sinks] |
| Gold Gini coefficient | [<0.4] | [>0.5] | [Wealth too concentrated] |
| % players hitting currency cap | [<5%] | [>10%] | [Raise cap or add sinks] |
| Premium conversion rate | [2-5%] | [<1% or >10%] | [Rebalance F2P earn rate] |
| Average time between purchases | [X minutes] | [>Y minutes] | [Nothing worth buying] |
---
## Ethical Guardrails
- [No pay-to-win: premium currency cannot buy gameplay power advantages]
- [Pity timers on all random drops: guaranteed outcome within X attempts]
- [Transparent drop rates displayed to players]
- [Spending limits for minor accounts]
- [No artificial scarcity pressure (FOMO timers) on essential items]
---
## Simulation Results
[Include results from economy simulations if available: player wealth
distribution over time, sink effectiveness, inflation rate, etc.]
---
## Dependencies
- Depends on: [combat balance, quest design, crafting system]
- Affects: [difficulty curve, player retention, monetization]
- Must coordinate with: `game-designer`, `live-ops-designer`, `analytics-engineer`

166
.claude/docs/templates/faction-design.md vendored Normal file
View File

@@ -0,0 +1,166 @@
# Faction Design: [Faction Name]
*Created: [Date]*
*Owner: world-builder*
*Status: [Draft / Approved / Implemented]*
---
## Identity
| Aspect | Detail |
| ---- | ---- |
| **Full Name** | [Official faction name] |
| **Common Name** | [What people call them] |
| **Type** | [Nation / Guild / Cult / Corporation / Tribe / etc.] |
| **Alignment** | [Not D&D alignment — their moral complexity in 1 sentence] |
| **Symbol** | [Description of their emblem/flag/sigil] |
| **Colors** | [Primary and secondary colors associated with this faction] |
| **Motto** | [Their defining phrase or creed] |
---
## Overview
[2-3 paragraphs describing who this faction is, what they want, and why they
matter to the game world. Write as if briefing someone who knows nothing.]
---
## History
### Origin
[How did this faction form? What event or need brought them together?]
### Key Historical Events
1. **[Event Name]** ([Date/Era]): [What happened and how it shaped the faction]
2. **[Event Name]** ([Date/Era]): [Impact]
3. **[Event Name]** ([Date/Era]): [Impact]
### Current State
[Where is this faction now? Are they ascendant, declining, stable, fractured?]
---
## Beliefs and Values
### Core Beliefs
- [Belief 1 — what they hold as fundamental truth]
- [Belief 2]
- [Belief 3]
### What They Value
- [Value 1 — what they reward and respect]
- [Value 2]
### What They Despise
- [Thing 1 — what they punish or reject]
- [Thing 2]
---
## Structure and Leadership
### Hierarchy
[How is the faction organized? Military ranks? Council of elders? Meritocracy?
Describe the power structure.]
### Key Figures
| Name | Role | Personality | Motivation |
| ---- | ---- | ---- | ---- |
| [Leader] | [Title] | [2-3 adjectives] | [What drives them] |
| [Second] | [Title] | [Personality] | [Motivation] |
| [Notable] | [Title] | [Personality] | [Motivation] |
### Membership
- **How to join**: [Birth? Initiation? Purchase? Invitation?]
- **How to leave**: [Can they? What happens?]
- **Population**: [Rough size and composition]
---
## Territory and Resources
### Holdings
[Where does this faction control territory? What are their key locations?]
### Resources
- **Primary resource**: [What they have abundance of]
- **Scarcity**: [What they lack and need]
- **Trade goods**: [What they export/sell]
### Military Strength
[How powerful are they? Standing army? Special forces? Magical capabilities?
Technology level?]
---
## Relationships
| Faction | Relationship | Reason | Trend |
| ---- | ---- | ---- | ---- |
| [Faction A] | [Allied / Friendly / Neutral / Tense / Hostile / War] | [Why] | [Improving / Stable / Deteriorating] |
| [Faction B] | [Relationship] | [Why] | [Trend] |
| [Player] | [Starting disposition] | [Why] | [Player-influenced] |
---
## Reputation System (if applicable)
| Tier | Points | Benefits | Requirements |
| ---- | ---- | ---- | ---- |
| Hostile | [-1000 to -500] | [Attacked on sight] | [Betrayal, war crimes] |
| Unfriendly | [-500 to -100] | [No services, higher prices] | [Opposing actions] |
| Neutral | [-100 to 100] | [Basic services] | [Default] |
| Friendly | [100 to 500] | [Discounts, quests] | [Complete tasks] |
| Honored | [500 to 1000] | [Unique items, areas, abilities] | [Major questline] |
| Exalted | [1000+] | [Best rewards, title, housing] | [Full faction commitment] |
---
## Gameplay Role
### Player Interaction
[How does the player encounter and interact with this faction? Quests?
Trading? Combat? Diplomacy?]
### Unique Mechanics
[Does this faction introduce any unique gameplay mechanics? Crafting recipes?
Combat styles? Magic systems?]
### Questlines
[Brief overview of the major questlines associated with this faction.]
---
## Aesthetic Guide
### Architecture
[What do their buildings look like? Materials, shapes, scale.]
### Clothing/Armor
[What do members wear? Identifying visual elements.]
### Technology/Magic Level
[What tools, weapons, and abilities do they use?]
### Audio Palette
[What sounds are associated with this faction? Musical themes, ambient sounds.]
---
## Lore Consistency Notes
- **Canon level**: [Core / Extended / Flavor — how important is this to the main story?]
- **Contradictions to watch**: [Any potential conflicts with other lore]
- **Open questions**: [Things not yet decided about this faction]
- **Off-limits**: [Things that must NOT be true about this faction]
---
## Dependencies
- Related factions: [List factions that interact with this one]
- Related areas: [Levels/regions where this faction appears]
- Related questlines: [Story arcs involving this faction]
- Affects: [economy, combat encounters, narrative branches]

315
.claude/docs/templates/game-concept.md vendored Normal file
View File

@@ -0,0 +1,315 @@
# Game Concept: [Working Title]
*Created: [Date]*
*Status: [Draft / Under Review / Approved]*
---
## Elevator Pitch
> [1-2 sentences that capture the entire game. Should be compelling enough to
> make someone want to hear more. Format: "It's a [genre] where you [core
> action] in a [setting] to [goal]."
>
> Test: Can someone who has never heard of this game understand what they'd
> be doing in 10 seconds? If not, simplify.]
---
## Core Identity
| Aspect | Detail |
| ---- | ---- |
| **Genre** | [Primary genre + subgenre(s)] |
| **Platform** | [PC / Console / Mobile / Cross-platform] |
| **Target Audience** | [See Player Profile section below] |
| **Player Count** | [Single-player / Co-op / Multiplayer / MMO] |
| **Session Length** | [Typical play session: 10 min / 30 min / 1 hr / 2+ hr] |
| **Monetization** | [Premium / F2P / Subscription / none yet] |
| **Estimated Scope** | [Small (1-3 months) / Medium (3-9 months) / Large (9+ months)] |
| **Comparable Titles** | [2-3 existing games in the same space] |
---
## Core Fantasy
[What power, experience, or feeling does the player get from this game?
What can they do here that they can't do anywhere else?
The core fantasy is the emotional promise. It's not a feature list — it's the
answer to "why would someone choose THIS game over anything else they could
be doing?"
Examples of strong core fantasies:
- "You are a lone survivor building a new life in a hostile wilderness" (survival)
- "You command a civilization across millennia" (strategy)
- "You explore a vast, beautiful world at your own pace" (open world)
- "You master intricate combat and overcome impossible odds" (soulslike)]
---
## Unique Hook
[What makes this game different from everything else in its genre? This is
the single most important differentiator.
A strong hook passes the "and also" test: "It's like [comparable game],
AND ALSO [unique thing]." If the "and also" doesn't spark curiosity, the
hook needs work.
The hook should be:
- Explainable in one sentence
- Genuinely novel (not just a combination of existing features)
- Connected to the core fantasy (not a gimmick bolted on)
- Something that affects gameplay, not just aesthetics]
---
## Player Experience Analysis (MDA Framework)
The MDA (Mechanics-Dynamics-Aesthetics) framework ensures we design from the
player's emotional experience backward to the systems that create it.
### Target Aesthetics (What the player FEELS)
Rank the following aesthetic goals for this game (1 = primary, mark N/A if not
relevant). These come from the MDA framework's 8 aesthetic categories:
| Aesthetic | Priority | How We Deliver It |
| ---- | ---- | ---- |
| **Sensation** (sensory pleasure) | [1-8 or N/A] | [Visual beauty, audio design, haptics] |
| **Fantasy** (make-believe, role-playing) | [Priority] | [World, characters, player identity] |
| **Narrative** (drama, story arc) | [Priority] | [Plot structure, player-driven stories] |
| **Challenge** (obstacle course, mastery) | [Priority] | [Difficulty curve, skill ceiling] |
| **Fellowship** (social connection) | [Priority] | [Co-op, guilds, shared experiences] |
| **Discovery** (exploration, secrets) | [Priority] | [Hidden areas, emergent systems, lore] |
| **Expression** (self-expression, creativity) | [Priority] | [Build variety, cosmetics, creation tools] |
| **Submission** (relaxation, comfort zone) | [Priority] | [Low-stress loops, ambient gameplay] |
### Key Dynamics (Emergent player behaviors)
[What behaviors do we WANT to emerge from our mechanics? What should players
naturally start doing without being told?
Example: "Players will experiment with ability combinations to find synergies"
Example: "Players will share discoveries with the community"]
### Core Mechanics (Systems we build)
[What are the 3-5 mechanical systems that generate the dynamics and aesthetics
above? These are the rules, verbs, and systems we actually implement.]
1. [Mechanic 1 — e.g., "Real-time combat with stamina management"]
2. [Mechanic 2 — e.g., "Procedurally generated dungeons with hand-crafted rooms"]
3. [Mechanic 3 — e.g., "Crafting system with discoverable recipes"]
---
## Player Motivation Profile
Understanding WHY players play helps us make every design decision. Based on
Self-Determination Theory (SDT) and the Player Experience of Need Satisfaction
(PENS) model.
### Primary Psychological Needs Served
| Need | How This Game Satisfies It | Strength |
| ---- | ---- | ---- |
| **Autonomy** (freedom, meaningful choice) | [How does the player feel in control?] | [Core / Supporting / Minimal] |
| **Competence** (mastery, skill growth) | [How does the player feel skilled?] | [Core / Supporting / Minimal] |
| **Relatedness** (connection, belonging) | [How does the player feel connected?] | [Core / Supporting / Minimal] |
### Player Type Appeal (Bartle Taxonomy)
Which player types does this game primarily serve?
- [ ] **Achievers** (goal completion, collection, progression) — How: [...]
- [ ] **Explorers** (discovery, understanding systems, finding secrets) — How: [...]
- [ ] **Socializers** (relationships, cooperation, community) — How: [...]
- [ ] **Killers/Competitors** (domination, PvP, leaderboards) — How: [...]
### Flow State Design
Flow occurs when challenge matches skill. How does this game maintain flow?
- **Onboarding curve**: [How do the first 10 minutes teach the player?]
- **Difficulty scaling**: [How does challenge grow with player skill?]
- **Feedback clarity**: [How does the player know they're improving?]
- **Recovery from failure**: [How quickly can they try again? Is failure punishing or educational?]
---
## Core Loop
### Moment-to-Moment (30 seconds)
[What is the player physically doing most of the time? The most basic, repeated
action. This MUST be intrinsically satisfying — if the 30-second loop isn't
fun in isolation, no amount of progression will save the game.]
### Short-Term (5-15 minutes)
[What objective or cycle structures the moment-to-moment play? Encounters,
puzzles, rounds, quests. This is where "one more turn" or "one more run"
psychology lives.]
### Session-Level (30-120 minutes)
[What does a full play session look like? What does the player accomplish?
This should end with a natural stopping point AND a reason to come back.]
### Long-Term Progression
[How does the player grow over days/weeks? Character progression, unlocks,
story advancement, mastery. What is the player working toward?]
### Retention Hooks
[What specifically brings the player back for their next session?]
- **Curiosity**: [Unanswered questions, unexplored areas, locked content]
- **Investment**: [Progress they don't want to lose, characters they care about]
- **Social**: [Friends playing, guild obligations, shared goals]
- **Mastery**: [Skills to improve, challenges to overcome, rankings to climb]
---
## Game Pillars
Design pillars are non-negotiable principles that guide EVERY decision. When
two design choices conflict, pillars break the tie. Keep to 3-5 pillars.
Real AAA examples:
- God of War: "Intense combat", "Father-son story", "World exploration"
- Hades: "Fast fluid combat", "Narrative depth through repeated runs"
- The Last of Us: "Story as essential", "AI partners build relationships", "Stealth encouraged"
### Pillar 1: [Name]
[One sentence defining this non-negotiable design principle.]
*Design test*: [A concrete decision this pillar would resolve. "If we're
debating between X and Y, this pillar says we choose __."]
### Pillar 2: [Name]
[Definition]
*Design test*: [Decision it resolves]
### Pillar 3: [Name]
[Definition]
*Design test*: [Decision it resolves]
### Anti-Pillars (What This Game Is NOT)
Anti-pillars are equally important — they prevent scope creep and keep the
vision focused. Every "no" protects the "yes."
- **NOT [thing]**: [Why this is explicitly excluded and what it would compromise]
- **NOT [thing]**: [Why]
- **NOT [thing]**: [Why]
---
## Inspiration and References
| Reference | What We Take From It | What We Do Differently | Why It Matters |
| ---- | ---- | ---- | ---- |
| [Game 1] | [Specific mechanic, feeling, or approach] | [Our twist] | [What it validates about our concept] |
| [Game 2] | [What we learn] | [Our twist] | [Validation] |
| [Game 3] | [What we learn] | [Our twist] | [Validation] |
**Non-game inspirations**: [Films, books, music, art, real-world experiences
that influence the tone, world, or feel. Great games often pull from outside
the medium.]
---
## Target Player Profile
[Be specific. "Gamers" is not a target audience.]
| Attribute | Detail |
| ---- | ---- |
| **Age range** | [e.g., 18-35] |
| **Gaming experience** | [Casual / Mid-core / Hardcore] |
| **Time availability** | [e.g., "30-minute sessions on weeknights, longer on weekends"] |
| **Platform preference** | [Where they play most] |
| **Current games they play** | [2-3 specific titles] |
| **What they're looking for** | [The unmet need this game fills] |
| **What would turn them away** | [Dealbreakers for this audience] |
---
## Technical Considerations
| Consideration | Assessment |
| ---- | ---- |
| **Recommended Engine** | [Godot / Unity / Unreal and why — consider scope, team expertise, platform targets] |
| **Key Technical Challenges** | [What's technically hard about this game?] |
| **Art Style** | [Pixel / 2D / 2.5D / 3D stylized / 3D realistic] |
| **Art Pipeline Complexity** | [Low (asset store + modifications) / Medium (custom 2D) / High (custom 3D)] |
| **Audio Needs** | [Minimal / Moderate / Music-heavy / Adaptive] |
| **Networking** | [None / P2P / Client-Server / Dedicated Servers] |
| **Content Volume** | [Estimate: X levels, Y items, Z hours of gameplay] |
| **Procedural Systems** | [Any procedural generation? What scope?] |
---
## Risks and Open Questions
### Design Risks
[Things that could make the game unfun or uncompelling]
- [Risk 1 — e.g., "Core loop may not sustain sessions > 30 minutes"]
- [Risk 2 — e.g., "Player motivation unclear after main story ends"]
### Technical Risks
[Things that could be hard or impossible to build]
- [Risk 1 — e.g., "Procedural generation quality is unproven"]
- [Risk 2 — e.g., "Networking for 100+ players may require dedicated infrastructure"]
### Market Risks
[Things that could prevent commercial success]
- [Risk 1 — e.g., "Genre is saturated with established competitors"]
- [Risk 2 — e.g., "Target audience may be too niche for financial sustainability"]
### Scope Risks
[Things that could blow the timeline]
- [Risk 1 — e.g., "Content volume exceeds team capacity"]
- [Risk 2 — e.g., "Feature X depends on technology we haven't prototyped"]
### Open Questions
[Things that need prototyping or research before we can answer]
- [Question 1 — and how we plan to answer it]
- [Question 2 — and what prototype would resolve it]
---
## MVP Definition
[The absolute minimum version that validates the core hypothesis. The MVP
answers ONE question: "Is the core loop fun?"]
**Core hypothesis**: [The single statement the MVP tests, e.g., "Players find
the combat-crafting loop engaging for 30+ minute sessions"]
**Required for MVP**:
1. [Essential feature 1 — directly tests the hypothesis]
2. [Essential feature 2]
3. [Essential feature 3]
**Explicitly NOT in MVP** (defer to later):
- [Feature that's nice but doesn't test the hypothesis]
- [Feature that adds scope without validating the core]
### Scope Tiers (if budget/time shrinks)
| Tier | Content | Features | Timeline |
| ---- | ---- | ---- | ---- |
| **MVP** | [Minimal] | [Core loop only] | [X weeks] |
| **Vertical Slice** | [One complete area] | [Core + progression] | [X weeks] |
| **Alpha** | [All areas, placeholder] | [All features, rough] | [X weeks] |
| **Full Vision** | [Complete content] | [All features, polished] | [X weeks] |
---
## Next Steps
- [ ] Get concept approval from creative-director
- [ ] Fill in CLAUDE.md technology stack based on engine choice
- [ ] Create game pillars document (`/design-review` to validate)
- [ ] Create first architecture decision record (`/architecture-decision`)
- [ ] Prototype core loop (`/prototype [core-mechanic]`)
- [ ] Validate core loop with playtest (`/playtest-report`)
- [ ] Plan first milestone (`/sprint-plan new`)

116
.claude/docs/templates/game-design-document.md vendored Normal file
View File

@@ -0,0 +1,116 @@
# [Mechanic/System Name]
> **Status**: Draft | In Review | Approved | Implemented
> **Author**: [Agent or person]
> **Last Updated**: [Date]
> **Implements Pillar**: [Which game pillar this supports]
## Overview
[One paragraph that explains this mechanic to someone who knows nothing about
the project. What is it, what does the player do, and why does it exist?]
## Player Fantasy
[What should the player FEEL when engaging with this mechanic? What is the
emotional or power fantasy being served? This section guides all detail
decisions below.]
## Detailed Design
### Core Rules
[Precise, unambiguous rules. A programmer should be able to implement this
section without asking questions. Use numbered rules for sequential processes
and bullet points for properties.]
### States and Transitions
[If this system has states (e.g., weapon states, status effects, phases),
document every state and every valid transition between states.]
| State | Entry Condition | Exit Condition | Behavior |
|-------|----------------|----------------|----------|
### Interactions with Other Systems
[How does this system interact with combat? Inventory? Progression? UI?
For each interaction, specify the interface: what data flows in, what flows
out, and who is responsible for what.]
## Formulas
[Every mathematical formula used by this system. For each formula:]
### [Formula Name]
```
result = base_value * (1 + modifier_sum) * scaling_factor
```
| Variable | Type | Range | Source | Description |
|----------|------|-------|--------|-------------|
| base_value | float | 1-100 | data file | The base amount before modifiers |
| modifier_sum | float | -0.9 to 5.0 | calculated | Sum of all active modifiers |
| scaling_factor | float | 0.5-2.0 | data file | Level-based scaling |
**Expected output range**: [min] to [max]
**Edge case**: When modifier_sum < -0.9, clamp to -0.9 to prevent negative results.
## Edge Cases
[Explicitly document what happens in unusual situations. Each edge case
should have a clear resolution.]
| Scenario | Expected Behavior | Rationale |
|----------|------------------|-----------|
| [What if X is zero?] | [This happens] | [Because of this reason] |
| [What if both effects trigger?] | [Priority rule] | [Design reasoning] |
## Dependencies
[List every system this mechanic depends on or that depends on this mechanic.]
| System | Direction | Nature of Dependency |
|--------|-----------|---------------------|
| [Combat] | This depends on Combat | Needs damage calculation results |
| [Inventory] | Inventory depends on this | Provides item effect data |
## Tuning Knobs
[Every value that should be adjustable for balancing. Include the current
value, the safe range, and what happens at the extremes.]
| Parameter | Current Value | Safe Range | Effect of Increase | Effect of Decrease |
|-----------|--------------|------------|-------------------|-------------------|
## Visual/Audio Requirements
[What visual and audio feedback does this mechanic need?]
| Event | Visual Feedback | Audio Feedback | Priority |
|-------|----------------|---------------|----------|
## UI Requirements
[What information needs to be displayed to the player and when?]
| Information | Display Location | Update Frequency | Condition |
|-------------|-----------------|-----------------|-----------|
## Acceptance Criteria
[Testable criteria that confirm this mechanic is working as designed.]
- [ ] [Criterion 1: specific, measurable, testable]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
- [ ] Performance: System update completes within [X]ms
- [ ] No hardcoded values in implementation
## Open Questions
[Anything not yet decided. Each question should have an owner and deadline.]
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|

313
.claude/docs/templates/game-pillars.md vendored Normal file
View File

@@ -0,0 +1,313 @@
# Game Pillars: [Game Title]
## Document Status
- **Version**: 1.0
- **Last Updated**: [Date]
- **Approved By**: creative-director
- **Status**: [Draft / Under Review / Approved]
---
## What Are Game Pillars?
Pillars are the 3-5 non-negotiable principles that define this game's identity.
Every design, art, audio, narrative, and technical decision must serve at least
one pillar. If a feature doesn't serve a pillar, it doesn't belong in the game.
**Why pillars matter**: In a typical development cycle, the team makes thousands
of small creative decisions. Pillars ensure all those decisions push in the same
direction, creating a coherent player experience rather than a collection of
disconnected features.
### What Makes a Good Pillar
A good pillar is:
- **Falsifiable**: "Fun gameplay" is not a pillar. "Combat rewards patience over
aggression" is — it makes a testable claim about design choices.
- **Constraining**: If a pillar never forces you to say no to something, it's
too vague. Good pillars eliminate options.
- **Cross-departmental**: A pillar that only constrains game design but says
nothing about art, audio, or narrative is incomplete. Real pillars shape
every discipline.
- **Memorable**: The team should be able to recite the pillars from memory.
If they can't, the pillars are too numerous or too complex.
### Real AAA Examples
These studios publicly shared their game pillars, showing how concrete and
specific effective pillars can be:
| Game | Pillars | Why They Work |
| ---- | ---- | ---- |
| **God of War (2018)** | Visceral combat; Father-son emotional journey; Continuous camera (no cuts); Norse mythology reimagined | "Continuous camera" is radical — it cut a standard cinematic tool. "Father-son journey" constrains narrative, level design, AND combat (Atreus as companion). |
| **Hades** | Fast fluid combat; Story depth through repetition; Every run teaches something new | "Story through repetition" justified the roguelike structure narratively — death IS the story. "Every run teaches" constrains level and encounter design. |
| **The Last of Us** | Story is essential, not optional; AI partners build relationships; Stealth is always an option | "AI partners build relationships" drove massive investment in companion AI — not just pathfinding, but emotional presence. |
| **Celeste** | Tough but fair; Accessibility without compromise; Story and mechanics are the same thing | "Story and mechanics are the same thing" — climbing IS the struggle, the dash IS the anxiety. Pillar prevented mechanics from being "just gameplay." |
| **Hollow Knight** | Atmosphere over explanation; Earned mastery; World tells its own story | "Atmosphere over explanation" — no tutorials, no hand-holding, the world teaches through environmental design. |
| **Dead Cells** | Every weapon is viable; Combat is a dance; Permanent death creates meaning | "Every weapon is viable" is extremely constraining — it demands constant balance work across hundreds of items. |
---
## Core Fantasy
> [What power, experience, or feeling does the player get from this game? What
> can they do here that they can't do anywhere else? The core fantasy is the
> emotional promise — the answer to "why would someone choose THIS game?"
>
> Strong core fantasies are visceral and immediate:
> - "You are a lone survivor building a new life in a hostile wilderness"
> - "You command a civilization across millennia"
> - "You explore a vast, beautiful world at your own pace"
> - "You master intricate combat and overcome impossible odds"]
---
## Target MDA Aesthetics
[Rank the aesthetic goals this game serves, from the MDA Framework. This ranking
guides every pillar — your pillars should collectively deliver your top 2-3
aesthetics.]
| Rank | Aesthetic | How Our Game Delivers It |
| ---- | ---- | ---- |
| 1 | [e.g., Challenge] | [Specific delivery mechanism] |
| 2 | [e.g., Discovery] | [Specific delivery mechanism] |
| 3 | [e.g., Fantasy] | [Specific delivery mechanism] |
| 4 | [e.g., Narrative] | [Specific delivery mechanism] |
| N/A | [Aesthetics not targeted] | [Why this isn't a priority] |
**Aesthetics reference** (Hunicke, LeBlanc, Zubek):
- **Sensation**: Sensory pleasure (visual beauty, satisfying audio, haptic feedback)
- **Fantasy**: Make-believe, inhabiting a role or world
- **Narrative**: Drama, story arcs, emotional plot progression
- **Challenge**: Obstacle course, skill mastery, overcoming difficulty
- **Fellowship**: Social connection, cooperation, shared experience
- **Discovery**: Exploration, uncovering secrets, understanding hidden systems
- **Expression**: Self-expression, creativity, personal identity
- **Submission**: Relaxation, comfort, meditative play
---
## The Pillars
### Pillar 1: [Name]
**One-Sentence Definition**: [A clear, falsifiable statement of what this pillar
means. Must be specific enough that two people would reach the same conclusion
when applying it to a design question.]
**Target Aesthetics Served**: [Which MDA aesthetics from the ranking above does
this pillar primarily deliver?]
**Design Test**: [A concrete decision this pillar resolves. "If we're debating
between X and Y, this pillar says we choose __."]
#### What This Means for Each Department
| Department | This Pillar Says... | Example |
| ---- | ---- | ---- |
| **Game Design** | [How this constrains and inspires mechanics] | [Concrete example] |
| **Art** | [How this constrains and inspires visuals] | [Concrete example] |
| **Audio** | [How this constrains and inspires sound/music] | [Concrete example] |
| **Narrative** | [How this constrains and inspires story/writing] | [Concrete example] |
| **Engineering** | [Technical implications and priorities] | [Concrete example] |
#### Serving This Pillar
- [Concrete example of a feature/decision that embodies this pillar]
- [Another example]
#### Violating This Pillar
- [Concrete example of what would betray this pillar — things we must never do]
- [Another example]
---
### Pillar 2: [Name]
**One-Sentence Definition**: [Specific, falsifiable statement]
**Target Aesthetics Served**: [MDA aesthetics]
**Design Test**: [Concrete decision it resolves]
#### What This Means for Each Department
| Department | This Pillar Says... | Example |
| ---- | ---- | ---- |
| **Game Design** | [Constraint/inspiration] | [Example] |
| **Art** | [Constraint/inspiration] | [Example] |
| **Audio** | [Constraint/inspiration] | [Example] |
| **Narrative** | [Constraint/inspiration] | [Example] |
| **Engineering** | [Constraint/inspiration] | [Example] |
#### Serving This Pillar
- [Example]
- [Example]
#### Violating This Pillar
- [Example]
- [Example]
---
### Pillar 3: [Name]
**One-Sentence Definition**: [Specific, falsifiable statement]
**Target Aesthetics Served**: [MDA aesthetics]
**Design Test**: [Concrete decision it resolves]
#### What This Means for Each Department
| Department | This Pillar Says... | Example |
| ---- | ---- | ---- |
| **Game Design** | [Constraint/inspiration] | [Example] |
| **Art** | [Constraint/inspiration] | [Example] |
| **Audio** | [Constraint/inspiration] | [Example] |
| **Narrative** | [Constraint/inspiration] | [Example] |
| **Engineering** | [Constraint/inspiration] | [Example] |
#### Serving This Pillar
- [Example]
- [Example]
#### Violating This Pillar
- [Example]
- [Example]
---
### Pillar 4: [Name] (Optional)
[Same structure as Pillars 1-3]
### Pillar 5: [Name] (Optional)
[Same structure as Pillars 1-3]
---
## Anti-Pillars (What This Game Is NOT)
Anti-pillars are equally important as pillars — they prevent scope creep and
keep the vision focused. Every "no" protects the "yes."
Great anti-pillars are things the team might actually want to do. "NOT a racing
game" is obvious and useless. "NOT an open-world game" is useful if the genre
could plausibly support it.
- **NOT [thing]**: [Why this is explicitly excluded, what pillar it would
compromise, and what it would cost in development focus]
- **NOT [thing]**: [Why excluded]
- **NOT [thing]**: [Why excluded]
---
## Pillar Conflict Resolution
When two pillars conflict (and they will), use this priority order. The ranking
reflects which aspects of the experience are most essential to the core fantasy.
| Priority | Pillar | Rationale |
| ---- | ---- | ---- |
| 1 | [Highest priority pillar] | [Why this wins when it conflicts with others] |
| 2 | [Second priority] | [Why] |
| 3 | [Third priority] | [Why] |
**Resolution Process**:
1. Identify which pillars are in tension
2. Consult the priority ranking above
3. If the lower-priority pillar can be served partially without compromising the
higher-priority one, do so
4. If not, the higher-priority pillar wins
5. Document the decision and rationale in the relevant design document
6. If the conflict is fundamental (two pillars are irreconcilable), escalate to
the creative-director to consider revising the pillars themselves
---
## Player Motivation Alignment
[Verify that the pillars collectively serve the target player's psychological needs.
Based on Self-Determination Theory (Deci & Ryan) and the Player Experience of
Need Satisfaction model.]
| Need | Which Pillar Serves It | How |
| ---- | ---- | ---- |
| **Autonomy** (meaningful choice, player agency) | [Pillar name] | [How this pillar creates autonomy] |
| **Competence** (mastery, skill growth, clear feedback) | [Pillar name] | [How this pillar creates competence] |
| **Relatedness** (connection, belonging, emotional bond) | [Pillar name] | [How this pillar creates relatedness] |
**Gap check**: If any of the three needs is not served by at least one pillar,
consider whether the pillar set is complete. A game that satisfies all three
SDT needs has the strongest foundation for sustained engagement.
---
## Emotional Arc
[Map the intended emotional journey of a play session. This should be a
deliberate design, not an accident.]
### Session Emotional Arc
| Phase | Duration | Target Emotion | Pillar(s) Driving It | Mechanics Delivering It |
| ---- | ---- | ---- | ---- | ---- |
| Opening | [e.g., 0-5 min] | [e.g., Curiosity, anticipation] | [Which pillar] | [What the player does] |
| Rising | [e.g., 5-20 min] | [e.g., Tension, focus, flow] | [Which pillar] | [What the player does] |
| Climax | [e.g., 20-30 min] | [e.g., Triumph, relief, awe] | [Which pillar] | [What the player does] |
| Resolution | [e.g., 30-40 min] | [e.g., Satisfaction, reflection] | [Which pillar] | [What the player does] |
| Hook | [End of session] | [e.g., Curiosity, unfinished business] | [Which pillar] | [What makes them return] |
### Long-Term Emotional Progression
[How does the emotional experience evolve across the full game? Early game vs
mid game vs late game vs endgame should each feel distinct.]
---
## Reference Games
| Reference | What We Take From It | What We Do Differently | Which Pillar It Validates |
| ---- | ---- | ---- | ---- |
| [Game 1] | [Specific mechanic, feeling, or approach] | [Our twist] | [Pillar name] |
| [Game 2] | [What we learn] | [Our twist] | [Pillar name] |
| [Game 3] | [What we learn] | [Our twist] | [Pillar name] |
**Non-game inspirations**: [Films, books, music, art, real-world experiences
that inform the tone, world, or feel. Great games pull from outside the medium.]
---
## Pillar Validation Checklist
Before finalizing the pillars, verify:
- [ ] **Count**: 3-5 pillars (no more, no fewer)
- [ ] **Falsifiable**: Each pillar makes a claim that could be wrong
- [ ] **Constraining**: Each pillar forces saying "no" to some plausible ideas
- [ ] **Cross-departmental**: Each pillar has implications for design, art, audio, narrative, AND engineering
- [ ] **Design-tested**: Each pillar has a concrete design test that resolves a real decision
- [ ] **Anti-pillars defined**: At least 3 explicit "this game is NOT" statements
- [ ] **Priority-ranked**: Clear order for resolving conflicts between pillars
- [ ] **MDA-aligned**: Pillars collectively deliver the top-ranked target aesthetics
- [ ] **SDT coverage**: At least one pillar serves Autonomy, one Competence, one Relatedness
- [ ] **Memorable**: The team can recite all pillars from memory
- [ ] **Core fantasy served**: Every pillar traces back to the core fantasy promise
---
## Next Steps
- [ ] Get pillar approval from creative-director
- [ ] Distribute to all department leads for sign-off
- [ ] Create design tests for each pillar using real upcoming decisions
- [ ] Schedule first pillar review (after 2 weeks of development)
- [ ] Add pillars to the game-concept document and pitch document
---
*This document is the creative north star. It lives in `design/gdd/game-pillars.md`
and is referenced by every design, art, audio, and narrative document in the project.
Review quarterly or after major milestone pivots.*

135
.claude/docs/templates/incident-response.md vendored Normal file
View File

@@ -0,0 +1,135 @@
# Incident Response: [Incident Title]
**Severity**: [S1-Critical / S2-Major / S3-Moderate / S4-Minor]
**Status**: [Active / Mitigated / Resolved / Post-Mortem Complete]
**Detected**: [Date Time UTC]
**Resolved**: [Date Time UTC or ONGOING]
**Duration**: [Total time from detection to resolution]
**Incident Commander**: [Name/Role]
---
## Impact Summary
[2-3 sentences describing what players experienced. Write from the player
perspective, not the technical perspective.]
- **Players affected**: [estimated count or percentage]
- **Platforms affected**: [PC / Console / Mobile / All]
- **Regions affected**: [All / specific regions]
- **Revenue impact**: [estimated if applicable]
---
## Timeline
| Time (UTC) | Event | Action Taken |
| ---- | ---- | ---- |
| [HH:MM] | Incident detected via [monitoring/player report/etc.] | Incident commander assigned |
| [HH:MM] | Root cause identified | [Brief description of cause] |
| [HH:MM] | Mitigation deployed | [What was done] |
| [HH:MM] | Service restored / Fix confirmed | Monitoring for recurrence |
| [HH:MM] | All-clear declared | Post-mortem scheduled |
---
## Root Cause
### What Happened
[Technical description of the root cause. Be specific about the chain of events
that led to the incident.]
### Why It Happened
[Systemic cause — why did existing processes, tests, or safeguards fail to
prevent this? This is more important than the technical cause.]
### Contributing Factors
- [Factor 1 — e.g., "Insufficient load testing for the new matchmaking system"]
- [Factor 2 — e.g., "Monitoring alert threshold was set too high"]
- [Factor 3]
---
## Mitigation and Resolution
### Immediate Actions (during incident)
1. [Action taken to stop the bleeding]
2. [Action taken to restore service]
3. [Action taken to verify resolution]
### Follow-Up Actions (after resolution)
1. [Permanent fix if immediate action was a workaround]
2. [Additional testing or monitoring added]
3. [Process changes to prevent recurrence]
---
## Player Communication
### Initial Acknowledgment
*Sent: [Time] via [channel]*
> [Exact text of the first public message acknowledging the issue]
### Status Updates
*Sent: [Time] via [channel]*
> [Text of each subsequent update]
### Resolution Notice
*Sent: [Time] via [channel]*
> [Text announcing the fix and any compensation]
### Compensation (if applicable)
- **What**: [description of compensation — e.g., "500 premium currency + 24-hour XP boost"]
- **Who**: [all players / affected players only / players who logged in during incident]
- **When**: [delivery date and method]
- **Rationale**: [why this compensation is appropriate for the impact]
---
## Prevention
### What We Are Changing
| Action Item | Owner | Deadline | Status |
| ---- | ---- | ---- | ---- |
| [Specific preventive measure] | [Role] | [Date] | [TODO/Done] |
| [Add monitoring for X] | [Role] | [Date] | [TODO/Done] |
| [Add test coverage for Y] | [Role] | [Date] | [TODO/Done] |
| [Update runbook for Z] | [Role] | [Date] | [TODO/Done] |
### Process Improvements
- [Process change to prevent similar incidents]
- [Monitoring/alerting improvement]
- [Testing improvement]
---
## Lessons Learned
### What Went Well
- [Positive aspect of incident response — e.g., "Detection was fast due to
monitoring alerts"]
- [Positive aspect]
### What Went Poorly
- [Problem with response — e.g., "Took 20 minutes to identify the correct
on-call person"]
- [Problem]
### Where We Got Lucky
- [Factor that reduced impact by chance rather than design — these are hidden
risks to address]
---
## Sign-Offs
- [ ] Technical Director — Root cause accurate, prevention plan sufficient
- [ ] QA Lead — Test coverage gaps addressed
- [ ] Producer — Timeline and communication reviewed
- [ ] Community Manager — Player communication reviewed
---
*This document is filed in `production/hotfixes/` and linked from the
release notes for the fix version.*

111
.claude/docs/templates/level-design-document.md vendored Normal file
View File

@@ -0,0 +1,111 @@
# Level: [Level Name]
## Quick Reference
- **Area/Region**: [Where in the game world]
- **Type**: [Combat / Exploration / Puzzle / Hub / Boss / Mixed]
- **Estimated Play Time**: [X-Y minutes]
- **Difficulty**: [1-10 relative scale]
- **Prerequisite**: [What the player must have done to reach this level]
- **Status**: [Concept | Layout | Graybox | Art Pass | Polish | Final]
## Narrative Context
- **Story Moment**: [Where in the narrative arc does this level occur]
- **Narrative Purpose**: [What story beat this level delivers]
- **Emotional Target**: [What the player should feel during this level]
- **Lore Discoveries**: [What world-building the player can find here]
## Layout
### Overview Map
```
[ASCII diagram of the level layout. Use these symbols:]
[S] = Start point
[E] = Exit/end point
[C] = Combat encounter
[P] = Puzzle
[R] = Reward/loot
[!] = Story beat
[?] = Secret/optional
[>] = One-way passage
[=] = Two-way passage
[@] = NPC
[B] = Boss encounter
```
### Critical Path
[The mandatory route through the level, step by step.]
1. Player enters at [S]
2. [Description of what happens along the path]
3. Player exits at [E]
### Optional Paths
| Path | Access Requirement | Reward | Discovery Hint |
|------|-------------------|--------|---------------|
### Points of Interest
| Location | Type | Description | Purpose |
|----------|------|-------------|---------|
## Encounters
### Combat Encounters
| ID | Position | Enemy Composition | Difficulty | Arena Notes |
|----|----------|------------------|-----------|-------------|
| E-01 | [Map ref] | [2x Grunt, 1x Ranged] | 3/10 | Open area, cover on flanks |
| E-02 | [Map ref] | [1x Elite, 3x Grunt] | 5/10 | Narrow corridor, no retreat |
### Non-Combat Encounters
| ID | Position | Type | Description | Solution Hint |
|----|----------|------|-------------|---------------|
## Pacing Chart
```
Intensity
10 | *
8 | * * *
6 | * * * * * *
4 | * * * ** * * *
2 | * ** ** * * * * *
0 |S-----------------------------------------E
[Start] [Mid] [Climax] [Exit]
```
[Describe the intended rhythm: where are the peaks, valleys, rest points?]
## Audio Direction
| Zone/Moment | Music Track | Ambience | Key SFX |
|-------------|------------|----------|---------|
| [Entry] | [Track] | [Ambient sounds] | [Door opening] |
| [Combat] | [Combat music] | [Muted ambience] | [Combat SFX] |
| [Post-combat] | [Calm transition] | [Return to ambience] | |
## Visual Direction
- **Lighting**: [Key, fill, ambient description]
- **Color Palette**: [Dominant colors and why]
- **Mood Board References**: [Description of visual references]
- **Landmarks**: [Visible navigation aids and their locations]
- **Sight Lines**: [What the player should see from key positions]
## Collectibles and Secrets
| Item | Location | Visibility | Hint | Required For |
|------|----------|-----------|------|-------------|
## Technical Notes
- **Estimated Object Count**: [N]
- **Streaming Zones**: [Where to break the level for streaming]
- **Performance Concerns**: [Any known heavy areas]
- **Required Systems**: [What game systems are active in this level]

79
.claude/docs/templates/milestone-definition.md vendored Normal file
View File

@@ -0,0 +1,79 @@
# Milestone: [Name]
## Overview
- **Target Date**: [Date]
- **Type**: [Prototype | Vertical Slice | Alpha | Beta | Gold | Post-Launch]
- **Duration**: [N weeks]
- **Number of Sprints**: [N]
## Milestone Goal
[2-3 sentences describing what this milestone achieves and why it matters.
What can we demonstrate or evaluate at the end of this milestone?]
## Success Criteria
[Specific, measurable criteria. The milestone is complete ONLY when all of
these are met.]
- [ ] [Criterion 1 -- specific and testable]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
- [ ] All S1 and S2 bugs resolved
- [ ] Performance within budget on target hardware
- [ ] Build stable for [X] consecutive days
## Feature List
### Must Ship (Milestone Fails Without These)
| Feature | Design Doc | Owner | Sprint Target | Status |
|---------|-----------|-------|--------------|--------|
### Should Ship (Planned but Cuttable)
| Feature | Design Doc | Owner | Sprint Target | Cut Impact | Status |
|---------|-----------|-------|--------------|-----------|--------|
### Stretch Goals (Only if Ahead of Schedule)
| Feature | Design Doc | Owner | Value Add |
|---------|-----------|-------|----------|
## Quality Gates
| Gate | Threshold | Measurement Method |
|------|-----------|-------------------|
| Crash rate | < [X] per hour | Automated crash reporting |
| Frame rate | > [X] FPS on min spec | Performance profiling |
| Load time | < [X] seconds | Automated timing |
| Critical bugs | 0 open S1 | Bug tracker |
| Major bugs | < [X] open S2 | Bug tracker |
| Test coverage | > [X]% | Test framework report |
## Risk Register
| Risk | Probability | Impact | Mitigation | Owner | Status |
|------|------------|--------|-----------|-------|--------|
## Dependencies
### Internal Dependencies
| Feature | Depends On | Owner of Dependency | Status |
|---------|-----------|-------------------|--------|
### External Dependencies
| Dependency | Provider | Status | Risk if Delayed |
|-----------|---------|--------|----------------|
## Review Schedule
| Date | Review Type | Attendees |
|------|-----------|-----------|
| [Week 2] | Early progress check | Producer, Directors |
| [Midpoint] | Mid-milestone review | Full team |
| [Week N-1] | Pre-milestone review | Full team |
| [Target Date] | Milestone review | Full team |

111
.claude/docs/templates/narrative-character-sheet.md vendored Normal file
View File

@@ -0,0 +1,111 @@
# Character: [Name]
## Quick Reference
- **Full Name**: [Name]
- **Role in Story**: [Protagonist / Antagonist / Ally / Mentor / etc.]
- **Role in Gameplay**: [Playable / NPC / Boss / Merchant / Quest Giver / etc.]
- **First Appearance**: [Level/Area/Quest]
- **Status**: [Canon Level: Established / Provisional / Under Review]
## Concept
[One paragraph describing who this character is, what they want, and why the
player should care about them.]
## Appearance
[Physical description sufficient for the art team to create concept art.
Reference the art bible for style constraints.]
- **Build**: [Body type, height relative to player]
- **Distinguishing Features**: [What makes them visually recognizable at a distance]
- **Color Palette**: [Key colors associated with this character]
- **Costume/Armor**: [What they wear and why it makes sense for them]
## Personality
### Core Traits
- [Trait 1 -- e.g., Loyal to a fault]
- [Trait 2 -- e.g., Distrusts authority]
- [Trait 3 -- e.g., Dark sense of humor]
### Voice Profile
- **Speech Pattern**: [Formal/casual, verbose/terse, accent/dialect notes]
- **Vocabulary Level**: [Simple/educated/archaic/technical]
- **Verbal Tics**: [Any recurring phrases or speech habits]
- **Tone Reference**: [Reference character from another work, if helpful]
### Emotional Range
| Emotion | Trigger | Expression | Example Line |
|---------|---------|-----------|-------------|
## Motivation and Arc
### Primary Motivation
[What does this character want more than anything? This drives every scene.]
### Character Arc
| Phase | State | Turning Point |
|-------|-------|---------------|
| Introduction | [Who they are when the player meets them] | [What event starts their arc] |
| Development | [How they change through the middle] | [Key moment of growth/change] |
| Resolution | [Who they become by the end] | [Final transformative event] |
### Internal Conflict
[What contradictory desires or beliefs create internal tension?]
## Relationships
| Character | Relationship | Dynamic | Player Can Affect? |
|-----------|-------------|---------|-------------------|
## Gameplay Function
### What This Character Provides to the Player
- [Services: shop, training, quests, etc.]
- [Information: lore, hints, quest objectives]
- [Mechanical interactions: buffs, unlocks, gates]
### Encounter Design Notes
[If this character is fought as an enemy or boss, include combat design notes
or reference the relevant combat design document.]
## Dialogue Notes
### Topics This Character Can Discuss
- [Topic 1 -- what they know and their perspective]
- [Topic 2]
### Topics This Character Avoids or Lies About
- [Topic -- and why]
### Dialogue State Dependencies
[What game states affect this character's dialogue?]
| Game State | Dialogue Change |
|-----------|----------------|
## Lore Connections
- [Connection to world history]
- [Connection to factions]
- [Connection to locations]
## Cross-References
- **Design Doc**: [Link to relevant gameplay design]
- **Quest Doc**: [Link to quests involving this character]
- **Art Reference**: [Link to concept art or art bible section]
- **Audio Reference**: [Link to voice/theme direction]

140
.claude/docs/templates/pitch-document.md vendored Normal file
View File

@@ -0,0 +1,140 @@
# Game Pitch: [Title]
*Version: [Draft Number]*
*Date: [Date]*
---
## The Hook
> [One powerful sentence. If someone reads nothing else, this should make them
> curious.]
---
## What Is It?
[2-3 sentences expanding the hook into a clear picture. Genre, setting, core
mechanic, and what makes it special.]
---
## Why Now?
[Why is this the right game at the right time? Market trends, audience gaps,
technology enablers, cultural relevance.]
---
## Target Audience
**Primary**: [Who is the core audience? Be specific — not "gamers" but
"roguelike fans who enjoy build-crafting and short sessions"]
**Secondary**: [Adjacent audience who would also enjoy this]
**Market Size**: [Estimated TAM based on comparable titles]
---
## Comparable Titles
| Title | Similarity | Our Differentiation | Commercial Performance |
| ---- | ---- | ---- | ---- |
| [Game 1] | [What's similar] | [What's different/better] | [Revenue/units if known] |
| [Game 2] | [What's similar] | [What's different/better] | [Performance] |
| [Game 3] | [What's similar] | [What's different/better] | [Performance] |
---
## Core Experience
### The Player Fantasy
[What does the player get to BE or DO? The emotional promise.]
### Core Loop (30 seconds)
[Describe the primary activity]
### Session Flow (30 minutes)
[What does a typical session look like start to finish?]
### Progression Hook
[Why do players come back tomorrow?]
---
## Key Features
1. **[Feature Name]**: [1-2 sentence description of what it is and why it
matters to the player]
2. **[Feature Name]**: [Description]
3. **[Feature Name]**: [Description]
4. **[Feature Name]**: [Description]
5. **[Feature Name]**: [Description]
---
## Visual Identity
[Brief description of the art style, mood, and visual tone. Include reference
images or mood board link if available.]
**Art Style**: [e.g., "Hand-painted 2D with dynamic lighting, inspired by
Hollow Knight's atmosphere but with warmer colors"]
---
## Audio Identity
[Brief description of the sonic palette and musical direction.]
**Music**: [e.g., "Adaptive orchestral with folk instruments, shifting based
on biome and combat intensity"]
**SFX**: [e.g., "Crunchy, satisfying impact sounds. Tactile feedback on every
player action."]
---
## Business Model
| Aspect | Plan |
| ---- | ---- |
| **Model** | [Premium $X / F2P / etc.] |
| **Platforms** | [Steam, Console, Mobile] |
| **Price Point** | [$X.XX] |
| **DLC/Expansion Plans** | [Post-launch content strategy] |
| **Monetization Ethics** | [What we will and won't do] |
---
## Development Plan
| Milestone | Duration | Deliverable |
| ---- | ---- | ---- |
| Concept & Pre-production | [X weeks] | Game concept, pillars, vertical slice plan |
| Vertical Slice | [X weeks] | Playable slice demonstrating core loop |
| Alpha | [X weeks] | All features in, content placeholder |
| Beta | [X weeks] | Content complete, polish pass |
| Launch | [Date] | Release build |
**Team Size**: [X people, roles]
**Engine**: [Godot / Unity / Unreal]
**Estimated Budget**: [Range if applicable]
---
## Risks and Mitigation
| Risk | Likelihood | Impact | Mitigation |
| ---- | ---- | ---- | ---- |
| [Risk 1] | [H/M/L] | [H/M/L] | [How we handle it] |
| [Risk 2] | [H/M/L] | [H/M/L] | [Mitigation] |
| [Risk 3] | [H/M/L] | [H/M/L] | [Mitigation] |
---
## The Ask
[What do you need? Funding, publishing deal, team members, feedback? Be
specific about what you're looking for and what you're offering in return.]

69
.claude/docs/templates/post-mortem.md vendored Normal file
View File

@@ -0,0 +1,69 @@
# Post-Mortem: [Milestone/Project Name]
## Document Status
- **Date**: [Date]
- **Facilitator**: producer
- **Participants**: [List of agents/people involved]
- **Period Covered**: [Start date] to [End date]
## Summary
[2-3 sentence summary of what this milestone/project accomplished]
## Goals vs Results
| Goal | Target | Result | Status |
| ---- | ------ | ------ | ------ |
| [Goal 1] | [Metric] | [Actual] | [Met / Partially / Missed] |
## Timeline
| Date | Event | Impact |
| ---- | ----- | ------ |
| [Date] | [What happened] | [How it affected the project] |
## What Went Well
### [Category 1: e.g., Technical Execution]
**What**: [Description]
**Why it worked**: [Root cause of success]
**How to repeat**: [What to keep doing]
### [Category 2: e.g., Team Coordination]
**What**: [Description]
**Why it worked**: [Root cause]
**How to repeat**: [Action]
## What Went Poorly
### [Category 1: e.g., Scope Management]
**What**: [Description]
**Root cause**: [Why this happened]
**Impact**: [Time/quality/morale cost]
**Prevention**: [How to avoid next time]
### [Category 2]
[Same structure]
## Key Metrics
| Metric | Target | Actual | Notes |
| ------ | ------ | ------ | ----- |
| Tasks completed | [N] | [N] | |
| Bugs found | — | [N] | |
| Bugs fixed | — | [N] | |
| Estimation accuracy | 100% | [N%] | |
| Scope changes | 0 | [N] | |
## Lessons Learned
1. **[Lesson]**: [Explanation and how it changes future work]
2. **[Lesson]**: [Explanation]
## Action Items
| # | Action | Owner | Deadline | Status |
| - | ------ | ----- | -------- | ------ |
| 1 | [Action] | [Who] | [When] | [Open/Done] |
## Acknowledgments
[Call out exceptional contributions]

199
.claude/docs/templates/project-stage-report.md vendored Normal file
View File

@@ -0,0 +1,199 @@
# Project Stage Analysis Report
**Generated**: [DATE]
**Stage**: [Concept | Pre-production | Production | Post-Launch]
**Analysis Scope**: [Full project | Specific role: programmer/designer/producer]
---
## Executive Summary
[1-2 paragraph overview of project state, primary gaps, and recommended priority]
**Current Focus**: [What the project is actively working on]
**Blocking Issues**: [Critical gaps preventing progress]
**Estimated Time to Next Stage**: [If applicable]
---
## Completeness Overview
### Design Documentation
- **Status**: [X%] complete
- **Files Found**: [N] documents in `design/`
- GDD sections: [N] files in `design/gdd/`
- Narrative docs: [N] files in `design/narrative/`
- Level designs: [N] files in `design/levels/`
- **Key Gaps**:
- [ ] [Missing doc 1 + why it matters]
- [ ] [Missing doc 2 + why it matters]
### Source Code
- **Status**: [X%] complete
- **Files Found**: [N] source files in `src/`
- **Major Systems Identified**:
- ✅ [System 1] (`src/path/`) — [brief status]
- ✅ [System 2] (`src/path/`) — [brief status]
- ⚠️ [System 3] (`src/path/`) — [issue or incomplete]
- **Key Gaps**:
- [ ] [Missing system 1 + impact]
- [ ] [Missing system 2 + impact]
### Architecture Documentation
- **Status**: [X%] complete
- **ADRs Found**: [N] decisions documented in `docs/architecture/`
- **Coverage**:
- ✅ [Decision area 1] — documented
- ⚠️ [Decision area 2] — undocumented but implemented
- ❌ [Decision area 3] — neither documented nor decided
- **Key Gaps**:
- [ ] [Missing ADR 1 + why it's needed]
- [ ] [Missing ADR 2 + why it's needed]
### Production Management
- **Status**: [X%] complete
- **Found**:
- Sprint plans: [N] in `production/sprints/`
- Milestones: [N] in `production/milestones/`
- Roadmap: [Exists | Missing]
- **Key Gaps**:
- [ ] [Missing production artifact + impact]
### Testing
- **Status**: [X%] coverage (estimated)
- **Test Files**: [N] in `tests/`
- **Coverage by System**:
- [System 1]: [X%] (estimated)
- [System 2]: [X%] (estimated)
- **Key Gaps**:
- [ ] [Missing test area + risk]
### Prototypes
- **Active Prototypes**: [N] in `prototypes/`
- ✅ [Prototype 1] — documented with README
- ⚠️ [Prototype 2] — no README, unclear status
- **Archived**: [N] (experiments completed)
- **Key Gaps**:
- [ ] [Undocumented prototype + why it matters]
---
## Stage Classification Rationale
**Why [Stage]?**
[Explain why the project is classified at this stage based on indicators found]
**Indicators for this stage**:
- [Indicator 1 that matches this stage]
- [Indicator 2 that matches this stage]
**Next stage requirements**:
- [ ] [Requirement 1 to reach next stage]
- [ ] [Requirement 2 to reach next stage]
- [ ] [Requirement 3 to reach next stage]
---
## Gaps Identified (with Clarifying Questions)
### Critical Gaps (block progress)
1. **[Gap Name]**
- **Impact**: [Why this blocks progress]
- **Question**: [Clarifying question before assuming solution]
- **Suggested Action**: [What could be done, pending clarification]
### Important Gaps (affect quality/velocity)
2. **[Gap Name]**
- **Impact**: [Why this matters]
- **Question**: [Clarifying question]
- **Suggested Action**: [Proposed solution]
### Nice-to-Have Gaps (polish/best practices)
3. **[Gap Name]**
- **Impact**: [Minor but valuable]
- **Question**: [Clarifying question]
- **Suggested Action**: [Optional improvement]
---
## Recommended Next Steps
### Immediate Priority (Do First)
1. **[Action 1]** — [Why it's priority 1]
- Suggested skill: `/[skill-name]` or manual work
- Estimated effort: [S/M/L]
2. **[Action 2]** — [Why it's priority 2]
- Suggested skill: `/[skill-name]`
- Estimated effort: [S/M/L]
### Short-Term (This Sprint/Week)
3. **[Action 3]** — [Why it's important soon]
4. **[Action 4]** — [Why it's important soon]
### Medium-Term (Next Milestone)
5. **[Action 5]** — [Future need]
6. **[Action 6]** — [Future need]
---
## Role-Specific Recommendations
[If role filter was used, provide role-specific guidance]
### For [Role]:
- **Focus areas**: [What this role should prioritize]
- **Blockers**: [What's blocking this role's work]
- **Next tasks**:
1. [Task 1]
2. [Task 2]
---
## Follow-Up Skills to Run
Based on gaps identified, consider running:
- `/reverse-document [type] [path]` — [For which gap]
- `/architecture-decision` — [For which gap]
- `/sprint-plan` — [If production planning missing]
- `/milestone-review` — [If approaching deadline]
- `/onboard [role]` — [If new contributor joining]
---
## Appendix: File Counts by Directory
```
design/
gdd/ [N] files
narrative/ [N] files
levels/ [N] files
src/
core/ [N] files
gameplay/ [N] files
ai/ [N] files
networking/ [N] files
ui/ [N] files
docs/
architecture/ [N] ADRs
production/
sprints/ [N] plans
milestones/ [N] definitions
tests/ [N] test files
prototypes/ [N] directories
```
---
**End of Report**
*Generated by `/project-stage-detect` skill*

125
.claude/docs/templates/release-checklist-template.md vendored Normal file
View File

@@ -0,0 +1,125 @@
# Release Checklist: [Version] -- [Platform]
**Release Date**: [Target Date]
**Release Manager**: [Name]
**Status**: [ ] GO / [ ] NO-GO
---
## Build Verification
- [ ] Clean build succeeds on all target platforms
- [ ] No compiler warnings (zero-warning policy)
- [ ] Build version number set correctly: `[version]`
- [ ] Build is reproducible from tagged commit: `[commit hash]`
- [ ] Build size within budget: [actual] / [budget]
- [ ] All assets included and loading correctly
- [ ] No debug/development features enabled in release build
---
## Quality Gates
### Critical Bugs
- [ ] Zero S1 (Critical) bugs open
- [ ] Zero S2 (Major) bugs -- or documented exceptions below:
| Bug ID | Description | Exception Rationale | Approved By |
| ---- | ---- | ---- | ---- |
| | | | |
### Test Coverage
- [ ] All critical path features tested and signed off
- [ ] Full regression suite passed: [pass rate]%
- [ ] Soak test passed (4+ hours continuous play)
- [ ] Edge case testing complete
### Performance
- [ ] Target FPS met on minimum spec: [actual] / [target] FPS
- [ ] Memory usage within budget: [actual] / [budget] MB
- [ ] Load times within budget: [actual] / [target] seconds
- [ ] No memory leaks over extended play (soak test)
- [ ] No frame drops below [threshold] in normal gameplay
---
## Content Complete
- [ ] All placeholder assets replaced with final versions
- [ ] All player-facing text proofread
- [ ] All text localization-ready (no hardcoded strings)
- [ ] Localization complete for: [list locales]
- [ ] Audio mix finalized and approved
- [ ] Credits complete and accurate
- [ ] Legal notices and third-party attributions complete
---
## Platform: PC
- [ ] Minimum and recommended specs documented
- [ ] Keyboard+mouse controls fully functional
- [ ] Controller support tested (Xbox, PlayStation, generic)
- [ ] Resolution scaling tested: 1080p, 1440p, 4K, ultrawide
- [ ] Windowed, borderless, fullscreen modes working
- [ ] Graphics settings save and load correctly
- [ ] Store SDK integrated and tested: [Steam/Epic/GOG]
- [ ] Achievements functional
- [ ] Cloud saves functional
## Platform: Console (if applicable)
- [ ] TRC/TCR/Lotcheck requirements met
- [ ] Platform controller prompts correct
- [ ] Suspend/resume works
- [ ] User switching handled
- [ ] Network loss handled gracefully
- [ ] Storage full scenario handled
- [ ] Parental controls respected
- [ ] Certification submission prepared
---
## Store and Distribution
- [ ] Store page metadata complete and proofread
- [ ] Screenshots current and meet platform requirements
- [ ] Trailer current
- [ ] Key art and capsule images final
- [ ] Age ratings obtained: [ ] ESRB [ ] PEGI [ ] Other
- [ ] Legal: EULA, Privacy Policy, Terms of Service
- [ ] Pricing configured for all regions
---
## Launch Readiness
- [ ] Analytics/telemetry verified and receiving data
- [ ] Crash reporting configured: [service name]
- [ ] Day-one patch prepared (if needed)
- [ ] On-call team schedule set for first 72 hours
- [ ] Community announcements drafted
- [ ] Press/influencer keys prepared
- [ ] Support team briefed on known issues
- [ ] Rollback plan documented and tested
---
## Sign-offs
| Role | Name | Status | Date |
| ---- | ---- | ---- | ---- |
| QA Lead | | [ ] Approved | |
| Technical Director | | [ ] Approved | |
| Producer | | [ ] Approved | |
| Creative Director | | [ ] Approved | |
---
## Final Decision
**GO / NO-GO**: ____________
**Rationale**: [Summary of readiness. If NO-GO, list specific blocking items and estimated time to resolve.]
**Notes**: [Any additional context, known risks accepted, or conditions on the release.]

103
.claude/docs/templates/release-notes.md vendored Normal file
View File

@@ -0,0 +1,103 @@
# Release Notes: [Game Title] v[Version]
*Released: [Date]*
---
## Headline
> [One compelling sentence summarizing the most exciting part of this release.
> This is what appears in store update notifications and social media.]
---
## What's New
### [Major Feature 1 Name]
[2-4 sentences describing the feature. Focus on what players can DO, not
how it works internally. Include a screenshot or GIF reference if applicable.]
### [Major Feature 2 Name]
[Description]
---
## Gameplay Changes
### Balance Adjustments
| Target | Change | Before | After | Context |
| ---- | ---- | ---- | ---- | ---- |
| [Weapon/Ability/Item] | [What changed] | [Old value] | [New value] | [Why — 1 sentence] |
| | | | | |
### Mechanic Changes
- **[Change Name]**: [What changed and how it affects gameplay. Be specific
about what players will experience differently.]
---
## Quality of Life
- [Improvement 1 — describe the player benefit, not the technical change]
- [Improvement 2]
- [Improvement 3]
---
## Bug Fixes
### Critical Fixes
- Fixed [describe what players experienced, e.g., "a crash when loading
saved games from version 1.0"]
### Gameplay Fixes
- Fixed [describe the incorrect behavior and the correct behavior now]
### UI Fixes
- Fixed [description]
### Audio Fixes
- Fixed [description]
### Platform-Specific Fixes
- **[Platform]**: Fixed [description]
---
## Performance Improvements
- [Improvement players will notice, e.g., "Reduced load times by approximately
30% on all platforms"]
- [Improvement]
---
## Known Issues
We are aware of the following issues and are working on fixes for a future update:
- **[Issue]**: [Brief description and workaround if available]
- **[Issue]**: [Description]
---
## Coming Next
[Optional — tease upcoming content to build anticipation. Keep it vague enough
to not create binding commitments.]
> [1-2 sentences about what the team is working on next]
---
## Thank You
[Brief message thanking the community. Reference specific community feedback
that influenced changes in this release if applicable.]
---
*For the full changelog with technical details, see the [developer changelog](link).*
*Report bugs: [link to bug report channel/form]*
*Join the community: [link to Discord/forum]*

58
.claude/docs/templates/risk-register-entry.md vendored Normal file
View File

@@ -0,0 +1,58 @@
# Risk: [Short Title]
## Identification
- **ID**: RISK-[NNNN]
- **Identified By**: [Agent or person]
- **Date Identified**: [Date]
- **Category**: [Technical | Design | Schedule | Resource | External | Quality]
## Assessment
- **Probability**: [Very Low | Low | Medium | High | Very High]
- **Impact**: [Minimal | Minor | Moderate | Major | Critical]
- **Risk Score**: [Probability x Impact = Low / Medium / High / Critical]
## Description
[Detailed description of the risk. What could go wrong? Under what conditions?]
## Trigger Conditions
[What observable conditions would indicate this risk is materializing?]
- [Condition 1]
- [Condition 2]
## Impact Analysis
### If This Risk Materializes
- **Schedule Impact**: [How many days/weeks of delay]
- **Quality Impact**: [What quality degradation]
- **Scope Impact**: [What features affected]
- **Cost Impact**: [Resource cost of dealing with it]
### Affected Systems/Features
- [System 1]
- [System 2]
## Mitigation Strategy
### Prevention (reduce probability)
- [Action to prevent this risk from occurring]
- [Owner and deadline for prevention action]
### Contingency (reduce impact if it occurs)
- [Action to take if this risk materializes]
- [Owner responsible for contingency execution]
## Current Status
- **Status**: [Open | Mitigating | Occurred | Closed]
- **Last Reviewed**: [Date]
- **Trend**: [Increasing | Stable | Decreasing]
- **Notes**: [Any updates]

130
.claude/docs/templates/sound-bible.md vendored Normal file
View File

@@ -0,0 +1,130 @@
# Sound Bible: [Project Name]
## Audio Vision
### Sonic Identity
[Describe the overall audio personality of the game in 2-3 sentences. What does the game "sound like"? What emotions should the audio evoke?]
### Audio Pillars
1. **[Pillar 1]**: [How this pillar manifests in audio]
2. **[Pillar 2]**: [How this pillar manifests in audio]
3. **[Pillar 3]**: [How this pillar manifests in audio]
### Reference Games / Media
| Reference | What to Take From It | What to Avoid |
| ---- | ---- | ---- |
| [Game/Film 1] | [Specific audio quality to emulate] | [What doesn't fit our vision] |
| [Game/Film 2] | [Specific audio quality to emulate] | [What doesn't fit our vision] |
---
## Music Direction
### Style and Genre
[Primary musical style, instrumentation palette, tempo ranges]
### Instrumentation Palette
- **Core instruments**: [List the primary instruments/synths that define the sound]
- **Accent instruments**: [Used for emphasis, transitions, special moments]
- **Avoid**: [Instruments or styles that do NOT fit the game]
### Adaptive Music System
| Game State | Music Behavior | Transition |
| ---- | ---- | ---- |
| Exploration | [Tempo, energy, instrumentation] | [How it transitions to next state] |
| Combat | [Tempo, energy, instrumentation] | [Trigger condition and crossfade time] |
| Stealth/Tension | [Tempo, energy, instrumentation] | [Trigger and transition] |
| Victory/Reward | [Stinger or transition behavior] | [Return to exploration] |
| Menu/UI | [Style for menus] | [Fade on game start] |
### Music Rules
- [Rule about looping, e.g., "All exploration tracks must loop seamlessly after 2-4 minutes"]
- [Rule about silence, e.g., "Allow 10-15 seconds of silence between exploration loops"]
- [Rule about intensity, e.g., "Combat music must reach full intensity within 3 seconds of combat start"]
- [Rule about transitions, e.g., "All music transitions use 1.5 second crossfades"]
---
## Sound Effects
### SFX Palette
| Category | Description | Style Notes |
| ---- | ---- | ---- |
| Player Actions | [Movement, attacks, abilities] | [Punchy, responsive, front-of-mix] |
| Enemy Actions | [Attacks, abilities, death] | [Distinct from player, slightly recessed] |
| UI | [Button clicks, menu transitions, notifications] | [Clean, subtle, never annoying on repeat] |
| Environment | [Ambient loops, weather, objects] | [Immersive, layered, spatial] |
| Feedback | [Damage taken, item pickup, level up] | [Clear, satisfying, non-fatiguing] |
### Audio Feedback Priority
When multiple sounds compete, this priority determines what plays:
1. Player damage / critical warnings (always audible)
2. Player actions (attacks, abilities)
3. Enemy actions (nearby enemies first)
4. UI feedback
5. Environment / ambient
### SFX Rules
- [Rule about repetition, e.g., "Every SFX with >3 plays/minute needs 3+ variations"]
- [Rule about spatial audio, e.g., "All gameplay SFX must be 3D positioned, UI SFX are 2D"]
- [Rule about ducking, e.g., "Player hit SFX ducks all other SFX by 3dB for 200ms"]
- [Rule about response time, e.g., "Action SFX must trigger within 1 frame of the action"]
---
## Mixing
### Mix Bus Structure
| Bus | Content | Target Level |
| ---- | ---- | ---- |
| Master | Everything | 0 dB |
| Music | All music tracks | [target dBFS] |
| SFX | All sound effects | [target dBFS] |
| Dialogue | All voice/narration | [target dBFS] |
| UI | All interface sounds | [target dBFS] |
| Ambient | Environment loops | [target dBFS] |
### Mixing Rules
- Dialogue always takes priority — duck music and SFX during dialogue
- Music should be felt, not dominate — if players can't hear SFX over music, music is too loud
- Master output must never clip — use a limiter on the master bus
- All volumes must be adjustable by the player (per bus)
- Default mix should sound good on both speakers and headphones
### Dynamic Range
- [Specify loudness targets, e.g., "Target -14 LUFS integrated, -1 dBTP true peak"]
- [Specify compression policy, e.g., "Light compression on SFX bus, no compression on music"]
---
## Technical Specifications
### Format Requirements
| Type | Format | Sample Rate | Bit Depth | Notes |
| ---- | ---- | ---- | ---- | ---- |
| Music | [OGG/WAV] | [44.1/48 kHz] | [16/24 bit] | [Streaming from disk] |
| SFX | [WAV/OGG] | [44.1/48 kHz] | [16 bit] | [Loaded into memory] |
| Ambient | [OGG] | [44.1 kHz] | [16 bit] | [Streaming, loopable] |
| Dialogue | [OGG/WAV] | [44.1 kHz] | [16 bit] | [Streaming] |
### Naming Convention
`[category]_[subcategory]_[name]_[variation].ext`
- Example: `sfx_weapon_sword_swing_01.wav`
- Example: `music_exploration_forest_loop.ogg`
- Example: `amb_environment_cave_drip_loop.ogg`
### Memory Budget
- Total audio memory: [target, e.g., 128 MB]
- SFX pool: [target]
- Music streaming buffer: [target]
- Voice streaming buffer: [target]
---
## Accessibility
- All critical audio cues must have visual alternatives (subtitles, screen flash, icon)
- Mono audio option for hearing-impaired players
- Separate volume controls for all buses
- Option to disable sudden loud sounds
- Subtitle support for all dialogue with speaker identification

75
.claude/docs/templates/sprint-plan.md vendored Normal file
View File

@@ -0,0 +1,75 @@
# Sprint [N] -- [Start Date] to [End Date]
## Sprint Goal
[One sentence: what does this sprint achieve toward the current milestone?]
## Milestone Context
- **Current Milestone**: [Name]
- **Milestone Deadline**: [Date]
- **Sprints Remaining**: [N]
## Capacity
| Resource | Available Days | Allocated | Buffer (20%) | Remaining |
|----------|---------------|-----------|-------------|-----------|
| Programming | | | | |
| Design | | | | |
| Art | | | | |
| Audio | | | | |
| QA | | | | |
| **Total** | | | | |
## Tasks
### Must Have (Critical Path)
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
|----|------|-------------|-----------|-------------|-------------------|--------|
| S[N]-001 | | | | None | | Not Started |
| S[N]-002 | | | | S[N]-001 | | Not Started |
### Should Have
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
|----|------|-------------|-----------|-------------|-------------------|--------|
| S[N]-010 | | | | | | Not Started |
### Nice to Have (Cut First)
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
|----|------|-------------|-----------|-------------|-------------------|--------|
| S[N]-020 | | | | | | Not Started |
## Carryover from Sprint [N-1]
| Original ID | Task | Reason for Carryover | New Estimate | Priority Change |
|------------|------|---------------------|-------------|----------------|
## Risks to This Sprint
| Risk | Probability | Impact | Mitigation | Owner |
|------|------------|--------|-----------|-------|
## External Dependencies
| Dependency | Status | Impact if Delayed | Contingency |
|-----------|--------|------------------|-------------|
## Definition of Done
- [ ] All Must Have tasks completed and passing acceptance criteria
- [ ] No S1 or S2 bugs in delivered features
- [ ] Code reviewed and merged to develop
- [ ] Design documents updated for any deviations from spec
- [ ] Test cases written and executed for all new features
- [ ] Asset naming and format standards met
## Daily Status Tracking
| Day | Tasks Completed | Tasks In Progress | Blockers | Notes |
|-----|----------------|------------------|----------|-------|
| Day 1 | | | | |
| Day 2 | | | | |
| Day 3 | | | | |

82
.claude/docs/templates/technical-design-document.md vendored Normal file
View File

@@ -0,0 +1,82 @@
# Technical Design: [System Name]
## Document Status
- **Version**: 1.0
- **Last Updated**: [Date]
- **Author**: [Agent/Person]
- **Reviewer**: lead-programmer
- **Related ADR**: [ADR-XXXX if applicable]
- **Related Design Doc**: [Link to game design doc this implements]
## Overview
[2-3 sentence summary of what this system does and why it exists]
## Requirements
### Functional Requirements
- [FR-1]: [Description]
- [FR-2]: [Description]
### Non-Functional Requirements
- **Performance**: [Budget — e.g., "< 1ms per frame"]
- **Memory**: [Budget — e.g., "< 50MB at peak"]
- **Scalability**: [Limits — e.g., "Support up to 1000 entities"]
- **Thread Safety**: [Requirements]
## Architecture
### System Diagram
```
[ASCII diagram showing components and data flow]
```
### Component Breakdown
| Component | Responsibility | Owns |
| --------- | -------------- | ---- |
| [Name] | [What it does] | [What data it owns] |
### Public API
```
[Interface/API definition in pseudocode or target language]
```
### Data Structures
```
[Key data structures with field descriptions]
```
### Data Flow
[Step by step: how data moves through the system during a typical frame]
## Implementation Plan
### Phase 1: [Core Functionality]
- [ ] [Task 1]
- [ ] [Task 2]
### Phase 2: [Extended Features]
- [ ] [Task 3]
- [ ] [Task 4]
### Phase 3: [Optimization/Polish]
- [ ] [Task 5]
## Dependencies
| Depends On | For What |
| ---------- | -------- |
| [System] | [Reason] |
| Depended On By | For What |
| -------------- | -------- |
| [System] | [Reason] |
## Testing Strategy
- **Unit Tests**: [What to test at unit level]
- **Integration Tests**: [Cross-system tests needed]
- **Performance Tests**: [Benchmarks to create]
- **Edge Cases**: [Specific scenarios to test]
## Known Limitations
[What this design intentionally does NOT support and why]
## Future Considerations
[What might need to change if requirements evolve — but do NOT build for this now]

97
.claude/docs/templates/test-plan.md vendored Normal file
View File

@@ -0,0 +1,97 @@
# Test Plan: [Feature/System Name]
## Overview
- **Feature**: [Name]
- **Design Doc**: [Link to design document]
- **Implementation**: [Link to code or PR]
- **Author**: [QA owner]
- **Date**: [Date]
- **Priority**: [Critical / High / Medium / Low]
## Scope
### In Scope
- [What is being tested]
### Out of Scope
- [What is explicitly NOT being tested and why]
### Dependencies
- [Other systems that must be working for these tests to be valid]
## Test Environment
- **Build**: [Minimum build version]
- **Platform**: [Target platforms]
- **Preconditions**: [Required game state, save files, etc.]
## Test Cases
### Functional Tests -- Happy Path
| ID | Test Case | Steps | Expected Result | Status |
|----|-----------|-------|----------------|--------|
| TC-001 | [Description] | 1. [Step] 2. [Step] | [Expected] | [ ] |
| TC-002 | [Description] | 1. [Step] 2. [Step] | [Expected] | [ ] |
### Functional Tests -- Edge Cases
| ID | Test Case | Steps | Expected Result | Status |
|----|-----------|-------|----------------|--------|
| TC-010 | [Boundary value] | 1. [Step] | [Expected] | [ ] |
| TC-011 | [Zero/null input] | 1. [Step] | [Expected] | [ ] |
| TC-012 | [Maximum values] | 1. [Step] | [Expected] | [ ] |
### Negative Tests
| ID | Test Case | Steps | Expected Result | Status |
|----|-----------|-------|----------------|--------|
| TC-020 | [Invalid input] | 1. [Step] | [Graceful handling] | [ ] |
| TC-021 | [Interrupted action] | 1. [Step] | [No corruption] | [ ] |
### Integration Tests
| ID | Test Case | Systems Involved | Steps | Expected Result | Status |
|----|-----------|-----------------|-------|----------------|--------|
| TC-030 | [Cross-system interaction] | [System A, System B] | 1. [Step] | [Expected] | [ ] |
### Performance Tests
| ID | Test Case | Metric | Budget | Steps | Status |
|----|-----------|--------|--------|-------|--------|
| TC-040 | [Load time] | Seconds | [X]s | 1. [Step] | [ ] |
| TC-041 | [Frame rate] | FPS | [X] | 1. [Step] | [ ] |
| TC-042 | [Memory usage] | MB | [X]MB | 1. [Step] | [ ] |
### Regression Tests
| ID | Related Bug | Test Case | Steps | Expected Result | Status |
|----|------------|-----------|-------|----------------|--------|
| TC-050 | BUG-[XXXX] | [Verify fix holds] | 1. [Step] | [Expected] | [ ] |
## Test Results Summary
| Category | Total | Passed | Failed | Blocked | Skipped |
|----------|-------|--------|--------|---------|---------|
| Happy Path | | | | | |
| Edge Cases | | | | | |
| Negative | | | | | |
| Integration | | | | | |
| Performance | | | | | |
| Regression | | | | | |
| **Total** | | | | | |
## Bugs Found
| Bug ID | Severity | Test Case | Description | Status |
|--------|----------|-----------|-------------|--------|
## Sign-Off
- **QA Tester**: [Name] -- [Date]
- **QA Lead**: [Name] -- [Date]
- **Feature Owner**: [Name] -- [Date]