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

100
.claude/skills/architecture-decision/SKILL.md Normal file
View File

@@ -0,0 +1,100 @@
---
name: architecture-decision
description: "Creates an Architecture Decision Record (ADR) documenting a significant technical decision, its context, alternatives considered, and consequences. Every major technical choice should have an ADR."
argument-hint: "[title]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When this skill is invoked:
1. **Determine the next ADR number** by scanning `docs/architecture/` for
existing ADRs.
2. **Gather context** by reading related code and existing ADRs.
3. **Guide the user through the decision** by asking clarifying questions if
the title alone is not sufficient.
4. **Generate the ADR** following this format:
```markdown
# ADR-[NNNN]: [Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
## Date
[Date of decision]
## Context
### Problem Statement
[What problem are we solving? Why does this decision need to be made now?]
### Constraints
- [Technical constraints]
- [Timeline constraints]
- [Resource constraints]
- [Compatibility requirements]
### Requirements
- [Must support X]
- [Must perform within Y budget]
- [Must integrate with Z]
## Decision
[The specific technical decision made, described in enough detail for someone
to implement it.]
### Architecture Diagram
[ASCII diagram or description of the system architecture this creates]
### Key Interfaces
[API contracts or interface definitions this decision creates]
## Alternatives Considered
### Alternative 1: [Name]
- **Description**: [How this would work]
- **Pros**: [Advantages]
- **Cons**: [Disadvantages]
- **Rejection Reason**: [Why this was not chosen]
### Alternative 2: [Name]
- **Description**: [How this would work]
- **Pros**: [Advantages]
- **Cons**: [Disadvantages]
- **Rejection Reason**: [Why this was not chosen]
## Consequences
### Positive
- [Good outcomes of this decision]
### Negative
- [Trade-offs and costs accepted]
### Risks
- [Things that could go wrong]
- [Mitigation for each risk]
## Performance Implications
- **CPU**: [Expected impact]
- **Memory**: [Expected impact]
- **Load Time**: [Expected impact]
- **Network**: [Expected impact, if applicable]
## Migration Plan
[If this changes existing code, how do we get from here to there?]
## Validation Criteria
[How will we know this decision was correct? What metrics or tests?]
## Related Decisions
- [Links to related ADRs]
- [Links to related design documents]
```
5. **Save the ADR** to `docs/architecture/adr-[NNNN]-[slug].md`.

75
.claude/skills/asset-audit/SKILL.md Normal file
View File

@@ -0,0 +1,75 @@
---
name: asset-audit
description: "Audits game assets for compliance with naming conventions, file size budgets, format standards, and pipeline requirements. Identifies orphaned assets, missing references, and standard violations."
argument-hint: "[category|all]"
user-invocable: true
allowed-tools: Read, Glob, Grep
---
When this skill is invoked:
1. **Read the art bible or asset standards** from the relevant design docs and
the CLAUDE.md naming conventions.
2. **Scan the target asset directory** using Glob:
- `assets/art/**/*` for art assets
- `assets/audio/**/*` for audio assets
- `assets/vfx/**/*` for VFX assets
- `assets/shaders/**/*` for shaders
- `assets/data/**/*` for data files
3. **Check naming conventions**:
- Art: `[category]_[name]_[variant]_[size].[ext]`
- Audio: `[category]_[context]_[name]_[variant].[ext]`
- All files must be lowercase with underscores
4. **Check file standards**:
- Textures: Power-of-two dimensions, correct format (PNG for UI, compressed
for 3D), within size budget
- Audio: Correct sample rate, format (OGG for SFX, OGG/MP3 for music),
within duration limits
- Data: Valid JSON/YAML, schema-compliant
5. **Check for orphaned assets** by searching code for references to each
asset file.
6. **Check for missing assets** by searching code for asset references and
verifying the files exist.
7. **Output the audit**:
```markdown
# Asset Audit Report -- [Category] -- [Date]
## Summary
- **Total assets scanned**: [N]
- **Naming violations**: [N]
- **Size violations**: [N]
- **Format violations**: [N]
- **Orphaned assets**: [N]
- **Missing assets**: [N]
- **Overall health**: [CLEAN / MINOR ISSUES / NEEDS ATTENTION]
## Naming Violations
| File | Expected Pattern | Issue |
|------|-----------------|-------|
## Size Violations
| File | Budget | Actual | Overage |
|------|--------|--------|---------|
## Format Violations
| File | Expected Format | Actual Format |
|------|----------------|---------------|
## Orphaned Assets (no code references found)
| File | Last Modified | Size | Recommendation |
|------|-------------|------|---------------|
## Missing Assets (referenced but not found)
| Reference Location | Expected Path |
|-------------------|---------------|
## Recommendations
[Prioritized list of fixes]
```

72
.claude/skills/balance-check/SKILL.md Normal file
View File

@@ -0,0 +1,72 @@
---
name: balance-check
description: "Analyzes game balance data files, formulas, and configuration to identify outliers, broken progressions, degenerate strategies, and economy imbalances. Use after modifying any balance-related data or design."
argument-hint: "[system-name|path-to-data-file]"
user-invocable: true
allowed-tools: Read, Glob, Grep
---
When this skill is invoked:
1. **Identify the balance domain** from the argument.
2. **Read relevant data files** from `assets/data/` and `design/balance/`.
3. **Read the design document** for the system being checked from `design/gdd/`.
4. **Perform analysis**:
For **combat balance**:
- Calculate DPS for all weapons/abilities at each power tier
- Check time-to-kill at each tier
- Identify any options that dominate all others (strictly better)
- Check if defensive options can create unkillable states
- Verify damage type/resistance interactions are balanced
For **economy balance**:
- Map all resource faucets and sinks with flow rates
- Project resource accumulation over time
- Check for infinite resource loops
- Verify gold sinks scale with gold generation
- Check if any items are never worth purchasing
For **progression balance**:
- Plot the XP curve and power curve
- Check for dead zones (no meaningful progression for too long)
- Check for power spikes (sudden jumps in capability)
- Verify content gates align with expected player power
- Check if skip/grind strategies break intended pacing
For **loot balance**:
- Calculate expected time to acquire each rarity tier
- Check pity timer math
- Verify no loot is strictly useless at any stage
- Check inventory pressure vs acquisition rate
5. **Output the analysis**:
```
## Balance Check: [System Name]
### Data Sources Analyzed
- [List of files read]
### Health Summary: [HEALTHY / CONCERNS / CRITICAL ISSUES]
### Outliers Detected
| Item/Value | Expected Range | Actual | Issue |
|-----------|---------------|--------|-------|
### Degenerate Strategies Found
- [Strategy description and why it is problematic]
### Progression Analysis
[Graph description or table showing progression curve health]
### Recommendations
| Priority | Issue | Suggested Fix | Impact |
|----------|-------|--------------|--------|
### Values That Need Attention
[Specific values with suggested adjustments and rationale]
```

200
.claude/skills/brainstorm/SKILL.md Normal file
View File

@@ -0,0 +1,200 @@
---
name: brainstorm
description: "Guided game concept ideation — from zero idea to a structured game concept document. Uses professional studio ideation techniques, player psychology frameworks, and structured creative exploration."
argument-hint: "[genre or theme hint, or 'open' for fully open brainstorm]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, WebSearch
---
When this skill is invoked:
1. **Parse the argument** for an optional genre/theme hint (e.g., `roguelike`,
`space survival`, `cozy farming`). If `open` or no argument, start from
scratch.
2. **Check for existing concept work**:
- Read `design/gdd/game-concept.md` if it exists (resume, don't restart)
- Read `design/gdd/game-pillars.md` if it exists (build on established pillars)
3. **Run through ideation phases** interactively, asking the user questions at
each phase. Do NOT generate everything silently — the goal is **collaborative
exploration** where the AI acts as a creative facilitator, not a replacement
for the human's vision.
Professional studio brainstorming principles to follow:
- Withhold judgment — no idea is bad during exploration
- Encourage unusual ideas — outside-the-box thinking sparks better concepts
- Build on each other — "yes, and..." responses, not "but..."
- Use constraints as creative fuel — limitations often produce the best ideas
- Time-box each phase — keep momentum, don't over-deliberate early
---
### Phase 1: Creative Discovery
Start by understanding the person, not the game. Ask these questions
conversationally (not as a checklist):
**Emotional anchors**:
- What's a moment in a game that genuinely moved you, thrilled you, or made
you lose track of time? What specifically created that feeling?
- Is there a fantasy or power trip you've always wanted in a game but never
quite found?
**Taste profile**:
- What 3 games have you spent the most time with? What kept you coming back?
- Are there genres you love? Genres you avoid? Why?
- Do you prefer games that challenge you, relax you, tell you stories,
or let you express yourself?
**Practical constraints** (shape the sandbox before brainstorming):
- Solo developer or team? What skills are available?
- Timeline: weeks, months, or years?
- Any platform constraints? (PC only? Mobile? Console?)
- First game or experienced developer?
**Synthesize** the answers into a **Creative Brief** — a 3-5 sentence
summary of the person's emotional goals, taste profile, and constraints.
Read the brief back and confirm it captures their intent.
---
### Phase 2: Concept Generation
Using the creative brief as a foundation, generate **3 distinct concepts**
that each take a different creative direction. Use these ideation techniques:
**Technique 1: Verb-First Design**
Start with the core player verb (build, fight, explore, solve, survive,
create, manage, discover) and build outward from there. The verb IS the game.
**Technique 2: Mashup Method**
Combine two unexpected elements: [Genre A] + [Theme B]. The tension between
the two creates the unique hook. (e.g., "farming sim + cosmic horror",
"roguelike + dating sim", "city builder + real-time combat")
**Technique 3: Experience-First Design (MDA Backward)**
Start from the desired player emotion (aesthetic goal from MDA framework:
sensation, fantasy, narrative, challenge, fellowship, discovery, expression,
submission) and work backward to the dynamics and mechanics that produce it.
For each concept, present:
- **Working Title**
- **Elevator Pitch** (1-2 sentences — must pass the "10-second test")
- **Core Verb** (the single most common player action)
- **Core Fantasy** (the emotional promise)
- **Unique Hook** (passes the "and also" test: "Like X, AND ALSO Y")
- **Primary MDA Aesthetic** (which emotion dominates?)
- **Estimated Scope** (small / medium / large)
- **Why It Could Work** (1 sentence on market/audience fit)
- **Biggest Risk** (1 sentence on the hardest unanswered question)
Present all three. Ask the user to pick one, combine elements, or request
new concepts. Never pressure toward a choice — let them sit with it.
---
### Phase 3: Core Loop Design
For the chosen concept, use structured questioning to build the core loop.
The core loop is the beating heart of the game — if it isn't fun in
isolation, no amount of content or polish will save the game.
**30-Second Loop** (moment-to-moment):
- What is the player physically doing most often?
- Is this action intrinsically satisfying? (Would they do it with no
rewards, no progression, no story — just for the feel of it?)
- What makes this action feel good? (Audio feedback, visual juice,
timing satisfaction, tactical depth?)
**5-Minute Loop** (short-term goals):
- What structures the moment-to-moment play into cycles?
- Where does "one more turn" / "one more run" psychology kick in?
- What choices does the player make at this level?
**Session Loop** (30-120 minutes):
- What does a complete session look like?
- Where are the natural stopping points?
- What's the "hook" that makes them think about the game when not playing?
**Progression Loop** (days/weeks):
- How does the player grow? (Power? Knowledge? Options? Story?)
- What's the long-term goal? When is the game "done"?
**Player Motivation Analysis** (based on Self-Determination Theory):
- **Autonomy**: How much meaningful choice does the player have?
- **Competence**: How does the player feel their skill growing?
- **Relatedness**: How does the player feel connected (to characters,
other players, or the world)?
---
### Phase 4: Pillars and Boundaries
Game pillars are used by real AAA studios (God of War, Hades, The Last of
Us) to keep hundreds of team members making decisions that all point the
same direction. Even for solo developers, pillars prevent scope creep and
keep the vision sharp.
Collaboratively define **3-5 pillars**:
- Each pillar has a **name** and **one-sentence definition**
- Each pillar has a **design test**: "If we're debating between X and Y,
this pillar says we choose __"
- Pillars should feel like they create tension with each other — if all
pillars point the same way, they're not doing enough work
Then define **3+ anti-pillars** (what this game is NOT):
- Anti-pillars prevent the most common form of scope creep: "wouldn't it
be cool if..." features that don't serve the core vision
- Frame as: "We will NOT do [thing] because it would compromise [pillar]"
---
### Phase 5: Player Type Validation
Using the Bartle taxonomy and Quantic Foundry motivation model, validate
who this game is actually for:
- **Primary player type**: Who will LOVE this game? (Achievers, Explorers,
Socializers, Competitors, Creators, Storytellers)
- **Secondary appeal**: Who else might enjoy it?
- **Who is this NOT for**: Being clear about who won't like this game is as
important as knowing who will
- **Market validation**: Are there successful games that serve a similar
player type? What can we learn from their audience size?
---
### Phase 6: Scope and Feasibility
Ground the concept in reality:
- **Engine recommendation** (Godot / Unity / Unreal) with reasoning based
on concept needs, team expertise, and platform targets
- **Art pipeline**: What's the art style and how labor-intensive is it?
- **Content scope**: Estimate level/area count, item count, gameplay hours
- **MVP definition**: What's the absolute minimum build that tests "is the
core loop fun?"
- **Biggest risks**: Technical risks, design risks, market risks
- **Scope tiers**: What's the full vision vs. what ships if time runs out?
---
4. **Generate the game concept document** using the template at
`.claude/docs/templates/game-concept.md`. Fill in ALL sections from the
brainstorm conversation, including the MDA analysis, player motivation
profile, and flow state design sections.
5. **Save to** `design/gdd/game-concept.md`, creating directories as needed.
6. **Suggest next steps** (in this order — this is the professional studio
pre-production pipeline):
- "Run `/setup-engine [engine] [version]` to configure the engine and populate version-aware reference docs"
- "Use `/design-review design/gdd/game-concept.md` to validate completeness"
- "Discuss vision with the `creative-director` agent for pillar refinement"
- "Prototype the core loop with `/prototype [core-mechanic]`"
- "Playtest the prototype with `/playtest-report` to validate the hypothesis"
- "If validated, plan the first sprint with `/sprint-plan new`"
7. **Output a summary** with the chosen concept's elevator pitch, pillars,
primary player type, engine recommendation, biggest risk, and file path.

75
.claude/skills/bug-report/SKILL.md Normal file
View File

@@ -0,0 +1,75 @@
---
name: bug-report
description: "Creates a structured bug report from a description, or analyzes code to identify potential bugs. Ensures every bug report has full reproduction steps, severity assessment, and context."
argument-hint: "[description]
/bug-report analyze [path-to-file]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When invoked with a description:
1. **Parse the description** for key information.
2. **Search the codebase** for related files using Grep/Glob to add context.
3. **Generate the bug report**:
```markdown
# Bug Report
## Summary
**Title**: [Concise, descriptive title]
**ID**: BUG-[NNNN]
**Severity**: [S1-Critical / S2-Major / S3-Minor / S4-Trivial]
**Priority**: [P1-Immediate / P2-Next Sprint / P3-Backlog / P4-Wishlist]
**Status**: Open
**Reported**: [Date]
**Reporter**: [Name]
## Classification
- **Category**: [Gameplay / UI / Audio / Visual / Performance / Crash / Network]
- **System**: [Which game system is affected]
- **Frequency**: [Always / Often (>50%) / Sometimes (10-50%) / Rare (<10%)]
- **Regression**: [Yes/No/Unknown -- was this working before?]
## Environment
- **Build**: [Version or commit hash]
- **Platform**: [OS, hardware if relevant]
- **Scene/Level**: [Where in the game]
- **Game State**: [Relevant state -- inventory, quest progress, etc.]
## Reproduction Steps
**Preconditions**: [Required state before starting]
1. [Exact step 1]
2. [Exact step 2]
3. [Exact step 3]
**Expected Result**: [What should happen]
**Actual Result**: [What actually happens]
## Technical Context
- **Likely affected files**: [List of files based on codebase search]
- **Related systems**: [What other systems might be involved]
- **Possible root cause**: [If identifiable from the description]
## Evidence
- **Logs**: [Relevant log output if available]
- **Visual**: [Description of visual evidence]
## Related Issues
- [Links to related bugs or design documents]
## Notes
[Any additional context or observations]
```
When invoked with `analyze`:
1. **Read the target file(s)**.
2. **Identify potential bugs**: null references, off-by-one errors, race
conditions, unhandled edge cases, resource leaks, incorrect state
transitions.
3. **For each potential bug**, generate a bug report with the likely trigger
scenario and recommended fix.

133
.claude/skills/changelog/SKILL.md Normal file
View File

@@ -0,0 +1,133 @@
---
name: changelog
description: "Auto-generates a changelog from git commits, sprint data, and design documents. Produces both internal and player-facing versions."
argument-hint: "[version|sprint-number]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash
context: |
!git log --oneline -30 2>/dev/null
!git tag --list --sort=-v:refname 2>/dev/null | head -5
---
When this skill is invoked:
1. **Read the argument** for the target version or sprint number. If a version
is given, use the corresponding git tag. If a sprint number is given, use
the sprint date range.
1b. **Check git availability** — Verify the repository is initialized:
- Run `git rev-parse --is-inside-work-tree` to confirm git is available
- If not a git repo, inform the user and abort gracefully
2. **Read the git log** since the last tag or release:
```
git log --oneline [last-tag]..HEAD
```
If no tags exist, read the full log or a reasonable recent range (last 100
commits).
3. **Read sprint reports** from `production/sprints/` for the relevant period
to understand planned work and context behind changes.
4. **Read completed design documents** from `design/gdd/` for any new features
that were implemented during this period.
5. **Categorize every change** into one of these categories:
- **New Features**: Entirely new gameplay systems, modes, or content
- **Improvements**: Enhancements to existing features, UX improvements,
performance gains
- **Bug Fixes**: Corrections to broken behavior
- **Balance Changes**: Tuning of gameplay values, difficulty, economy
- **Known Issues**: Issues the team is aware of but have not yet resolved
6. **Generate the INTERNAL changelog** (full technical detail):
```markdown
# Internal Changelog: [Version]
Date: [Date]
Sprint(s): [Sprint numbers covered]
Commits: [Count] ([first-hash]..[last-hash])
## New Features
- [Feature Name] -- [Technical description, affected systems]
- Commits: [hash1], [hash2]
- Owner: [who implemented it]
- Design doc: [link if applicable]
## Improvements
- [Improvement] -- [What changed technically and why]
- Commits: [hashes]
- Owner: [who]
## Bug Fixes
- [BUG-ID] [Description of bug and root cause]
- Fix: [What was changed]
- Commits: [hashes]
- Owner: [who]
## Balance Changes
- [What was tuned] -- [Old value -> New value] -- [Design intent]
- Owner: [who]
## Technical Debt / Refactoring
- [What was cleaned up and why]
- Commits: [hashes]
## Known Issues
- [Issue description] -- [Severity] -- [ETA for fix if known]
## Metrics
- Total commits: [N]
- Files changed: [N]
- Lines added: [N]
- Lines removed: [N]
```
7. **Generate the PLAYER-FACING changelog** (friendly, non-technical):
```markdown
# What is New in [Version]
## New Features
- **[Feature Name]**: [Player-friendly description of what they can now do
and why it is exciting. Focus on the experience, not the implementation.]
## Improvements
- **[What improved]**: [How this makes the game better for the player.
Be specific but avoid jargon.]
## Bug Fixes
- Fixed an issue where [describe what the player experienced, not what was
wrong in the code]
- Fixed [player-visible symptom]
## Balance Changes
- [What changed in player-understandable terms and the design intent.
Example: "Healing potions now restore 50 HP (up from 30) -- we felt
players needed more recovery options in late-game encounters."]
## Known Issues
- We are aware of [issue description in player terms] and are working on a
fix. [Workaround if one exists.]
---
Thank you for playing! Your feedback helps us make the game better.
Report issues at [link].
```
8. **Output both changelogs** to the user. The internal changelog is the
primary working document. The player-facing changelog is ready for
community posting after review.
### Guidelines
- Never expose internal code references, file paths, or developer names in
the player-facing changelog
- Group related changes together rather than listing individual commits
- If a commit message is unclear, check the associated files and sprint data
for context
- Balance changes should always include the design reasoning, not just the
numbers
- Known issues should be honest -- players appreciate transparency
- If the git history is messy (merge commits, reverts, fixup commits), clean
up the narrative rather than listing every commit literally

74
.claude/skills/code-review/SKILL.md Normal file
View File

@@ -0,0 +1,74 @@
---
name: code-review
description: "Performs an architectural and quality code review on a specified file or set of files. Checks for coding standard compliance, architectural pattern adherence, SOLID principles, testability, and performance concerns."
argument-hint: "[path-to-file-or-directory]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash
---
When this skill is invoked:
1. **Read the target file(s)** in full.
2. **Read the CLAUDE.md** for project coding standards.
3. **Identify the system category** (engine, gameplay, AI, networking, UI, tools)
and apply category-specific standards.
4. **Evaluate against coding standards**:
- [ ] Public methods and classes have doc comments
- [ ] Cyclomatic complexity under 10 per method
- [ ] No method exceeds 40 lines (excluding data declarations)
- [ ] Dependencies are injected (no static singletons for game state)
- [ ] Configuration values loaded from data files
- [ ] Systems expose interfaces (not concrete class dependencies)
5. **Check architectural compliance**:
- [ ] Correct dependency direction (engine <- gameplay, not reverse)
- [ ] No circular dependencies between modules
- [ ] Proper layer separation (UI does not own game state)
- [ ] Events/signals used for cross-system communication
- [ ] Consistent with established patterns in the codebase
6. **Check SOLID compliance**:
- [ ] Single Responsibility: Each class has one reason to change
- [ ] Open/Closed: Extendable without modification
- [ ] Liskov Substitution: Subtypes substitutable for base types
- [ ] Interface Segregation: No fat interfaces
- [ ] Dependency Inversion: Depends on abstractions, not concretions
7. **Check for common game development issues**:
- [ ] Frame-rate independence (delta time usage)
- [ ] No allocations in hot paths (update loops)
- [ ] Proper null/empty state handling
- [ ] Thread safety where required
- [ ] Resource cleanup (no leaks)
8. **Output the review** in this format:
```
## Code Review: [File/System Name]
### Standards Compliance: [X/6 passing]
[List failures with line references]
### Architecture: [CLEAN / MINOR ISSUES / VIOLATIONS FOUND]
[List specific architectural concerns]
### SOLID: [COMPLIANT / ISSUES FOUND]
[List specific violations]
### Game-Specific Concerns
[List game development specific issues]
### Positive Observations
[What is done well -- always include this section]
### Required Changes
[Must-fix items before approval]
### Suggestions
[Nice-to-have improvements]
### Verdict: [APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED]
```

64
.claude/skills/design-review/SKILL.md Normal file
View File

@@ -0,0 +1,64 @@
---
name: design-review
description: "Reviews a game design document for completeness, internal consistency, implementability, and adherence to project design standards. Run this before handing a design document to programmers."
argument-hint: "[path-to-design-doc]"
user-invocable: true
allowed-tools: Read, Glob, Grep
---
When this skill is invoked:
1. **Read the target design document** in full.
2. **Read the master CLAUDE.md** to understand project context and standards.
3. **Read related design documents** referenced or implied by the target doc
(check `design/gdd/` for related systems).
4. **Evaluate against the Design Document Standard checklist**:
- [ ] Has Overview section (one-paragraph summary)
- [ ] Has Player Fantasy section (intended feeling)
- [ ] Has Detailed Rules section (unambiguous mechanics)
- [ ] Has Formulas section (all math defined with variables)
- [ ] Has Edge Cases section (unusual situations handled)
- [ ] Has Dependencies section (other systems listed)
- [ ] Has Tuning Knobs section (configurable values identified)
- [ ] Has Acceptance Criteria section (testable success conditions)
5. **Check for internal consistency**:
- Do the formulas produce values that match the described behavior?
- Do edge cases contradict the main rules?
- Are dependencies bidirectional (does the other system know about this one)?
6. **Check for implementability**:
- Are the rules precise enough for a programmer to implement without guessing?
- Are there any "hand-wave" sections where details are missing?
- Are performance implications considered?
7. **Check for cross-system consistency**:
- Does this conflict with any existing mechanic?
- Does this create unintended interactions with other systems?
- Is this consistent with the game's established tone and pillars?
8. **Output the review** in this format:
```
## Design Review: [Document Title]
### Completeness: [X/8 sections present]
[List missing sections]
### Consistency Issues
[List any internal or cross-system contradictions]
### Implementability Concerns
[List any vague or unimplementable sections]
### Balance Concerns
[List any obvious balance risks]
### Recommendations
[Prioritized list of improvements]
### Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]
```

163
.claude/skills/estimate/SKILL.md Normal file
View File

@@ -0,0 +1,163 @@
---
name: estimate
description: "Estimates task effort by analyzing complexity, dependencies, historical velocity, and risk factors. Produces a structured estimate with confidence levels."
argument-hint: "[task-description]"
user-invocable: true
allowed-tools: Read, Glob, Grep
---
When this skill is invoked:
1. **Read the task description** from the argument. If the description is too
vague to estimate meaningfully, ask for clarification before proceeding.
2. **Read CLAUDE.md** for project context: tech stack, coding standards,
architectural patterns, and any estimation guidelines.
3. **Read relevant design documents** from `design/gdd/` if the task relates
to a documented feature or system.
4. **Scan the codebase** to understand the systems affected by this task:
- Identify files and modules that would need to change
- Assess the complexity of those files (size, dependency count, cyclomatic
complexity)
- Identify integration points with other systems
- Check for existing test coverage in the affected areas
5. **Read past sprint data** from `production/sprints/` if available:
- Look for similar completed tasks and their actual effort
- Calculate historical velocity (planned vs actual)
- Identify any estimation bias patterns (consistently over or under)
6. **Analyze the following factors**:
**Code Complexity**:
- Lines of code in affected files
- Number of dependencies and coupling level
- Whether this touches core/engine code vs leaf/feature code
- Whether existing patterns can be followed or new patterns are needed
**Scope**:
- Number of systems touched
- New code vs modification of existing code
- Amount of new test coverage required
- Data migration or configuration changes needed
**Risk**:
- New technology or unfamiliar libraries
- Unclear or ambiguous requirements
- Dependencies on unfinished work
- Cross-system integration complexity
- Performance sensitivity
7. **Generate the estimate**:
```markdown
## Task Estimate: [Task Name]
Generated: [Date]
### Task Description
[Restate the task clearly in 1-2 sentences]
### Complexity Assessment
| Factor | Assessment | Notes |
|--------|-----------|-------|
| Systems affected | [List] | [Core, gameplay, UI, etc.] |
| Files likely modified | [Count] | [Key files listed below] |
| New code vs modification | [Ratio, e.g., 70% new / 30% modification] | |
| Integration points | [Count] | [Which systems interact] |
| Test coverage needed | [Low / Medium / High] | [Unit, integration, manual] |
| Existing patterns available | [Yes / Partial / No] | [Can follow existing code or new ground] |
**Key files likely affected:**
- `[path/to/file1]` -- [what changes here]
- `[path/to/file2]` -- [what changes here]
- `[path/to/file3]` -- [what changes here]
### Effort Estimate
| Scenario | Days | Assumption |
|----------|------|------------|
| Optimistic | [X] | Everything goes right, no surprises, requirements are clear |
| Expected | [Y] | Normal pace, minor issues, one round of review feedback |
| Pessimistic | [Z] | Significant unknowns surface, blocked for a day, requirements change |
**Recommended budget: [Y days]**
[If historical data is available: "Based on [N] similar tasks that averaged
[X] days actual vs [Y] days estimated, a [correction factor] adjustment has
been applied."]
### Confidence: [High / Medium / Low]
**High** -- Clear requirements, familiar systems, follows existing patterns,
similar tasks completed before.
**Medium** -- Some unknowns, touches moderately complex systems, partial
precedent from previous work.
**Low** -- Significant unknowns, new technology, unclear requirements, or
cross-cutting concerns across many systems.
[Explain which factors drive the confidence level for this specific task.]
### Risk Factors
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Specific risk] | [High/Med/Low] | [Days added if realized] | [How to reduce] |
| [Another risk] | [Likelihood] | [Impact] | [Mitigation] |
### Dependencies
| Dependency | Status | Impact if Delayed |
|-----------|--------|-------------------|
| [What must be done first] | [Done / In Progress / Not Started] | [How it affects this task] |
### Suggested Breakdown
| # | Sub-task | Estimate | Notes |
|---|----------|----------|-------|
| 1 | [Research / spike] | [X days] | [If unknowns need investigation first] |
| 2 | [Core implementation] | [X days] | [The main work] |
| 3 | [Integration with system X] | [X days] | [Connecting to existing code] |
| 4 | [Testing and validation] | [X days] | [Writing tests, manual verification] |
| 5 | [Code review and iteration] | [X days] | [Review feedback, fixes] |
| | **Total** | **[Y days]** | |
### Historical Comparison
[If similar tasks exist in sprint history:]
| Similar Task | Estimated | Actual | Relevant Difference |
|-------------|-----------|--------|-------------------|
| [Past task 1] | [X days] | [Y days] | [What makes it similar/different] |
| [Past task 2] | [X days] | [Y days] | [What makes it similar/different] |
### Notes and Assumptions
- [Key assumption that affects the estimate]
- [Another assumption]
- [Any caveats about scope boundaries -- what is included vs excluded]
- [Recommendations: e.g., "Consider a spike first if requirement X is unclear"]
```
8. **Output the estimate** to the user with a brief summary: recommended
budget, confidence level, and the single biggest risk factor.
### Guidelines
- Always give a range (optimistic / expected / pessimistic), never a single
number. Single-point estimates create false precision.
- The recommended budget should be the expected estimate, not the optimistic
one. Padding is not dishonest -- it is realistic.
- If confidence is Low, recommend a time-boxed spike or prototype before
committing to the full estimate.
- Be explicit about what is included and excluded. Scope ambiguity is the
most common source of estimation error.
- Round to half-day increments. Estimating in hours implies false precision
for tasks longer than a day.
- If the task is too large to estimate confidently (more than 10 days
expected), recommend breaking it into smaller tasks and estimating those
individually.
- Do not pad estimates silently. If risk exists, call it out explicitly in
the risk factors section so the team can decide how to handle it.

209
.claude/skills/gate-check/SKILL.md Normal file
View File

@@ -0,0 +1,209 @@
---
name: gate-check
description: "Validate readiness to advance between development phases. Produces a PASS/CONCERNS/FAIL verdict with specific blockers and required artifacts."
argument-hint: "[target-phase: pre-production | production | alpha | beta | release]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash
---
# Phase Gate Validation
This skill validates whether the project is ready to advance to the next development
phase. It checks for required artifacts, quality standards, and blockers.
**Distinct from `/project-stage-detect`**: That skill is diagnostic ("where are we?").
This skill is prescriptive ("are we ready to advance?" with a formal verdict).
---
## 1. Parse Arguments
- **With argument**: `/gate-check production` — validate readiness for that specific phase
- **No argument**: Auto-detect current stage using the same heuristics as
`/project-stage-detect`, then validate the NEXT phase transition
---
## 2. Phase Gate Definitions
### Gate: Concept → Pre-production
**Required Artifacts:**
- [ ] `design/gdd/game-concept.md` exists and has content
- [ ] Game pillars defined (in concept doc or `design/gdd/game-pillars.md`)
- [ ] Engine chosen (CLAUDE.md Technology Stack is not `[CHOOSE]`)
- [ ] Technical preferences configured (`.claude/docs/technical-preferences.md` populated)
**Quality Checks:**
- [ ] Game concept has been reviewed (`/design-review` verdict not MAJOR REVISION NEEDED)
- [ ] Core loop is described and understood
- [ ] Target audience is identified
---
### Gate: Pre-production → Production
**Required Artifacts:**
- [ ] At least 1 GDD in `design/gdd/` (beyond game-concept.md)
- [ ] At least 1 Architecture Decision Record in `docs/architecture/`
- [ ] At least 1 prototype in `prototypes/` with a README
- [ ] Engine reference docs exist in `docs/engine-reference/`
- [ ] First sprint plan exists in `production/sprints/`
**Quality Checks:**
- [ ] GDD(s) pass design review (8 required sections present)
- [ ] Prototype validates the core loop hypothesis
- [ ] Architecture decisions cover core systems (rendering, input, state management)
- [ ] Technical preferences have naming conventions and performance budgets set
---
### Gate: Production → Alpha
**Required Artifacts:**
- [ ] `src/` has active code organized into subsystems
- [ ] All core mechanics from GDD are implemented (cross-reference `design/gdd/` with `src/`)
- [ ] Main gameplay path is playable end-to-end
- [ ] Test files exist in `tests/`
- [ ] At least 1 playtest report (or `/playtest-report` has been run)
**Quality Checks:**
- [ ] Tests are passing (run test suite via Bash)
- [ ] No critical/blocker bugs in any bug tracker or known issues
- [ ] Core loop plays as designed (compare to GDD acceptance criteria)
- [ ] Performance is within budget (check technical-preferences.md targets)
---
### Gate: Alpha → Beta
**Required Artifacts:**
- [ ] All features from milestone plan are implemented
- [ ] Content is complete (all levels, assets, dialogue referenced in design docs exist)
- [ ] Localization strings are externalized (no hardcoded player-facing text in `src/`)
- [ ] QA test plan exists
- [ ] Balance data has been reviewed (`/balance-check` run)
**Quality Checks:**
- [ ] All tests passing
- [ ] Performance targets met (frame rate, memory, load times)
- [ ] No critical or high-severity bugs
- [ ] Accessibility basics covered (remapping, text scaling if applicable)
- [ ] Save/load system works reliably
---
### Gate: Beta → Release
**Required Artifacts:**
- [ ] Release checklist completed (`/release-checklist` or `/launch-checklist` run)
- [ ] Store metadata prepared (if applicable)
- [ ] Changelog / patch notes drafted
- [ ] Post-launch support plan exists
**Quality Checks:**
- [ ] Full QA pass signed off by `qa-lead`
- [ ] Performance targets met across all target platforms
- [ ] No known critical, high, or medium-severity bugs
- [ ] Localization verified for all target languages
- [ ] Legal requirements met (EULA, privacy policy, age ratings if applicable)
- [ ] Build compiles and packages cleanly
---
## 3. Run the Gate Check
For each item in the target gate:
### Artifact Checks
- Use `Glob` and `Read` to verify files exist and have meaningful content
- Don't just check existence — verify the file has real content (not just a template header)
- For code checks, verify directory structure and file counts
### Quality Checks
- For test checks: Run the test suite via `Bash` if a test runner is configured
- For design review checks: `Read` the GDD and check for the 8 required sections
- For performance checks: `Read` technical-preferences.md and compare against any
profiling data in `tests/performance/` or recent `/perf-profile` output
- For localization checks: `Grep` for hardcoded strings in `src/`
### Cross-Reference Checks
- Compare `design/gdd/` documents against `src/` implementations
- Check that every system referenced in architecture docs has corresponding code
- Verify sprint plans reference real work items
---
## 4. Collaborative Assessment
For items that can't be automatically verified, **ask the user**:
- "I can't automatically verify that the core loop plays well. Has it been playtested?"
- "No playtest report found. Has informal testing been done?"
- "Performance profiling data isn't available. Would you like to run `/perf-profile`?"
**Never assume PASS for unverifiable items.** Mark them as MANUAL CHECK NEEDED.
---
## 5. Output the Verdict
```
## Gate Check: [Current Phase] → [Target Phase]
**Date**: [date]
**Checked by**: gate-check skill
### Required Artifacts: [X/Y present]
- [x] design/gdd/game-concept.md — exists, 2.4KB
- [ ] docs/architecture/ — MISSING (no ADRs found)
- [x] production/sprints/ — exists, 1 sprint plan
### Quality Checks: [X/Y passing]
- [x] GDD has 8/8 required sections
- [ ] Tests — FAILED (3 failures in tests/unit/)
- [?] Core loop playtested — MANUAL CHECK NEEDED
### Blockers
1. **No Architecture Decision Records** — Run `/architecture-decision` to create one
covering core system architecture before entering production.
2. **3 test failures** — Fix failing tests in tests/unit/ before advancing.
### Recommendations
- [Priority actions to resolve blockers]
- [Optional improvements that aren't blocking]
### Verdict: [PASS / CONCERNS / FAIL]
- **PASS**: All required artifacts present, all quality checks passing
- **CONCERNS**: Minor gaps exist but can be addressed during the next phase
- **FAIL**: Critical blockers must be resolved before advancing
```
---
## 6. Follow-Up Actions
Based on the verdict, suggest specific next steps:
- **Missing design docs?** → `/reverse-document` or delegate to `game-designer`
- **Missing ADRs?** → `/architecture-decision`
- **Tests failing?** → delegate to `lead-programmer` or `qa-tester`
- **No playtest data?** → `/playtest-report`
- **Performance unknown?** → `/perf-profile`
- **Not localized?** → `/localize`
- **Ready for release?** → `/launch-checklist`
---
## Collaborative Protocol
This skill follows the collaborative design principle:
1. **Scan first**: Check all artifacts and quality gates
2. **Ask about unknowns**: Don't assume PASS for things you can't verify
3. **Present findings**: Show the full checklist with status
4. **User decides**: The verdict is a recommendation — the user makes the final call
5. **Get approval**: "May I write this gate check report to production/gate-checks/?"
**Never** block a user from advancing — the verdict is advisory. Document the risks
and let the user decide whether to proceed despite concerns.

70
.claude/skills/hotfix/SKILL.md Normal file
View File

@@ -0,0 +1,70 @@
---
name: hotfix
description: "Emergency fix workflow that bypasses normal sprint processes with a full audit trail. Creates hotfix branch, tracks approvals, and ensures the fix is backported correctly."
argument-hint: "[bug-id or description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
---
When this skill is invoked:
> **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/hotfix`. Do not auto-invoke based on context matching.
1. **Assess the emergency** — Read the bug description or ID. Determine severity:
- **S1 (Critical)**: Game unplayable, data loss, security vulnerability — hotfix immediately
- **S2 (Major)**: Significant feature broken, workaround exists — hotfix within 24 hours
- If severity is S3 or lower, recommend using the normal bug fix workflow instead
2. **Create the hotfix record** at `production/hotfixes/hotfix-[date]-[short-name].md`:
```markdown
## Hotfix: [Short Description]
Date: [Date]
Severity: [S1/S2]
Reporter: [Who found it]
Status: IN PROGRESS
### Problem
[Clear description of what is broken and the player impact]
### Root Cause
[To be filled during investigation]
### Fix
[To be filled during implementation]
### Testing
[What was tested and how]
### Approvals
- [ ] Fix reviewed by lead-programmer
- [ ] Regression test passed (qa-tester)
- [ ] Release approved (producer)
### Rollback Plan
[How to revert if the fix causes new issues]
```
3. **Create the hotfix branch** (if git is initialized):
```
git checkout -b hotfix/[short-name] [release-tag-or-main]
```
4. **Investigate and implement the fix** — Focus on the minimal change that resolves the issue. Do NOT refactor, clean up, or add features alongside the hotfix.
5. **Validate the fix** — Run targeted tests for the affected system. Check for regressions in adjacent systems.
6. **Update the hotfix record** with root cause, fix details, and test results.
6b. **Collect approvals** — Use the Task tool to request sign-off:
- `subagent_type: lead-programmer` — Review the fix for correctness and side effects
- `subagent_type: qa-tester` — Run targeted regression tests on the affected system
- `subagent_type: producer` — Approve deployment timing and communication plan
7. **Output a summary** with: severity, root cause, fix applied, testing status, and what approvals are still needed before deployment.
### Rules
- Hotfixes must be the MINIMUM change to fix the issue — no cleanup, no refactoring, no "while we're here" changes
- Every hotfix must have a rollback plan documented before deployment
- Hotfix branches merge to BOTH the release branch AND the development branch
- All hotfixes require a post-incident review within 48 hours
- If the fix is complex enough to need more than 4 hours, escalate to technical-director for a scope decision

221
.claude/skills/launch-checklist/SKILL.md Normal file
View File

@@ -0,0 +1,221 @@
---
name: launch-checklist
description: "Complete launch readiness validation covering every department: code, content, store, marketing, community, infrastructure, legal, and go/no-go sign-offs."
argument-hint: "[launch-date or 'dry-run']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When this skill is invoked:
> **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/launch-checklist`. Do not auto-invoke based on context matching.
1. **Read the argument** for the launch date or `dry-run` mode. Dry-run mode
generates the checklist without creating sign-off entries.
2. **Gather project context**:
- Read `CLAUDE.md` for tech stack, target platforms, and team structure
- Read the latest milestone in `production/milestones/`
- Read any existing release checklist in `production/releases/`
- Read the content calendar in `design/live-ops/content-calendar.md` if it exists
3. **Scan codebase health**:
- Count `TODO`, `FIXME`, `HACK` comments and their locations
- Check for any `console.log`, `print()`, or debug output left in production code
- Check for placeholder assets (search for `placeholder`, `temp_`, `WIP_`)
- Check for hardcoded test/dev values (localhost, test credentials, debug flags)
4. **Generate the launch checklist**:
```markdown
# Launch Checklist: [Game Title]
Target Launch: [Date or DRY RUN]
Generated: [Date]
---
## 1. Code Readiness
### Build Health
- [ ] Clean build on all target platforms
- [ ] Zero compiler warnings
- [ ] All unit tests passing
- [ ] All integration tests passing
- [ ] Performance benchmarks within targets
- [ ] No memory leaks (verified via extended soak test)
- [ ] Build size within platform limits
- [ ] Build version correctly set and tagged in source control
### Code Quality
- [ ] TODO count: [N] (zero required for launch, or documented exceptions)
- [ ] FIXME count: [N] (zero required)
- [ ] HACK count: [N] (each must have documented justification)
- [ ] No debug output in production code
- [ ] No hardcoded dev/test values
- [ ] All feature flags set to production values
- [ ] Error handling covers all critical paths
- [ ] Crash reporting integrated and verified
### Security
- [ ] No exposed API keys or credentials in source
- [ ] Save data encrypted
- [ ] Network communication secured (TLS/DTLS)
- [ ] Anti-cheat measures active (if multiplayer)
- [ ] Input validation on all server endpoints (if multiplayer)
- [ ] Privacy policy compliance verified
---
## 2. Content Readiness
### Assets
- [ ] All placeholder art replaced with final assets
- [ ] All placeholder audio replaced with final audio
- [ ] Audio mix finalized and approved by audio director
- [ ] All VFX polished and performance-verified
- [ ] No missing or broken asset references
- [ ] Asset naming conventions enforced
### Text and Localization
- [ ] All player-facing text proofread
- [ ] No hardcoded strings (all externalized for localization)
- [ ] All supported languages translated and verified
- [ ] Text fits UI in all languages (text fitting pass complete)
- [ ] Font coverage verified for all supported languages
- [ ] Credits complete, accurate, and up to date
### Game Content
- [ ] All levels/maps playable from start to finish
- [ ] Tutorial flow complete and tested with new players
- [ ] All achievements/trophies implemented and tested
- [ ] Save/load works correctly for all game states
- [ ] Difficulty settings balanced and tested
- [ ] End-game/credits sequence complete
---
## 3. Quality Assurance
### Testing
- [ ] Full regression test suite passed
- [ ] Zero S1 (Critical) bugs open
- [ ] Zero S2 (Major) bugs open (or documented exceptions)
- [ ] Soak test passed (8+ hours continuous play)
- [ ] Multiplayer stress test passed (if applicable)
- [ ] All critical user paths tested on every platform
- [ ] Edge cases tested (full storage, no network, suspend/resume)
### Platform Certification
- [ ] PC: Steam/Epic/GOG SDK requirements met
- [ ] Console: TRC/TCR/Lotcheck submission prepared
- [ ] Mobile: App Store/Play Store guidelines compliant
- [ ] Accessibility: minimum standards met (remapping, text scaling, colorblind)
- [ ] Age ratings obtained (ESRB, PEGI, regional)
### Performance
- [ ] Target FPS met on minimum spec hardware
- [ ] Load times within budget on all platforms
- [ ] Memory usage within budget on all platforms
- [ ] Network bandwidth within targets (if multiplayer)
- [ ] No frame hitches in critical gameplay moments
---
## 4. Store and Distribution
### Store Pages
- [ ] Store page copy finalized and proofread
- [ ] Screenshots current and per-platform resolution
- [ ] Trailers current and approved
- [ ] Key art and capsule images finalized
- [ ] System requirements accurate (PC)
- [ ] Pricing configured for all regions
- [ ] Pre-purchase/wishlist campaigns active (if applicable)
### Legal
- [ ] EULA finalized and approved by legal
- [ ] Privacy policy published and linked
- [ ] Third-party license attributions complete
- [ ] Music/audio licensing verified
- [ ] Trademark/IP clearance confirmed
- [ ] GDPR/CCPA compliance verified (data collection, consent, deletion)
---
## 5. Infrastructure
### Servers (if multiplayer/online)
- [ ] Production servers provisioned and load-tested
- [ ] Auto-scaling configured and tested
- [ ] Database backups configured
- [ ] CDN configured for content delivery
- [ ] DDoS protection active
- [ ] Monitoring and alerting configured
### Analytics and Monitoring
- [ ] Analytics pipeline verified and receiving data
- [ ] Crash reporting active and dashboard accessible
- [ ] Server monitoring dashboards live
- [ ] Key metrics tracked: DAU, session length, retention, crashes
- [ ] Alerts configured for critical thresholds
---
## 6. Community and Marketing
### Community Readiness
- [ ] Community guidelines published
- [ ] Moderation team briefed and tools ready
- [ ] Discord/forum/social channels set up
- [ ] FAQ and known issues page prepared
- [ ] Support email/ticketing system active
### Marketing
- [ ] Launch trailer published
- [ ] Press/influencer review keys distributed
- [ ] Social media launch posts scheduled
- [ ] Launch day blog post/dev update drafted
- [ ] Patch notes for launch version published
---
## 7. Operations
### Team Readiness
- [ ] On-call schedule set for first 72 hours post-launch
- [ ] Incident response playbook reviewed by team
- [ ] Rollback plan documented and tested
- [ ] Hotfix pipeline tested (can ship emergency fix within 4 hours)
- [ ] Communication plan for launch issues (who posts, where, how fast)
### Day-One Plan
- [ ] Day-one patch prepared (if needed)
- [ ] Server unlock/go-live procedure documented
- [ ] Launch monitoring dashboard bookmarked by all leads
- [ ] War room/channel established for launch day
---
## Go / No-Go Decision
**Overall Status**: [READY / NOT READY / CONDITIONAL]
### Blocking Items
[List any items that must be resolved before launch]
### Conditional Items
[List items that have documented workarounds or accepted risk]
### Sign-Offs Required
- [ ] Creative Director — Content and experience quality
- [ ] Technical Director — Technical health and stability
- [ ] QA Lead — Quality and test coverage
- [ ] Producer — Schedule and overall readiness
- [ ] Release Manager — Build and deployment readiness
```
5. **Save the checklist** to
`production/releases/launch-checklist-[date].md`, creating directories as needed.
6. **Output a summary** to the user: total items, blocking items count,
conditional items count, departments with incomplete sections, and the file path.

70
.claude/skills/localize/SKILL.md Normal file
View File

@@ -0,0 +1,70 @@
---
name: localize
description: "Run the localization workflow: extract strings, validate localization readiness, check for hardcoded text, and generate translation-ready string tables."
argument-hint: "[scan|extract|validate|status]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
---
When this skill is invoked:
1. **Parse the subcommand** from the argument:
- `scan` — Scan for localization issues (hardcoded strings, missing keys)
- `extract` — Extract new strings and generate/update string tables
- `validate` — Validate existing translations for completeness and format
- `status` — Report overall localization status
2. **For `scan`**:
- Search `src/` for hardcoded user-facing strings:
- String literals in UI code that are not wrapped in a localization function
- Concatenated strings that should be parameterized
- Strings with positional placeholders (`%s`, `%d`) instead of named ones (`{playerName}`)
- Search for localization anti-patterns:
- Date/time formatting not using locale-aware functions
- Number formatting without locale awareness
- Text embedded in images or textures (flag asset files)
- Strings that assume left-to-right text direction
- Report all findings with file paths and line numbers
3. **For `extract`**:
- Scan all source files for localized string references
- Compare against the existing string table (if any) in `assets/data/`
- Generate new entries for strings that don't have keys yet
- Suggest key names following the convention: `[category].[subcategory].[description]`
- Output a diff of new strings to add to the string table
4. **For `validate`**:
- Read all string table files in `assets/data/`
- Check each entry for:
- Missing translations (key exists but no translation for a locale)
- Placeholder mismatches (source has `{name}` but translation is missing it)
- String length violations (exceeds character limits for UI elements)
- Orphaned keys (translation exists but nothing references the key in code)
- Report validation results grouped by locale and severity
5. **For `status`**:
- Count total localizable strings
- Per locale: count translated, untranslated, and stale (source changed since translation)
- Generate a coverage matrix:
```markdown
## Localization Status
Generated: [Date]
| Locale | Total | Translated | Missing | Stale | Coverage |
|--------|-------|-----------|---------|-------|----------|
| en (source) | [N] | [N] | 0 | 0 | 100% |
| [locale] | [N] | [N] | [N] | [N] | [X]% |
### Issues
- [N] hardcoded strings found in source code
- [N] strings exceeding character limits
- [N] placeholder mismatches
- [N] orphaned keys (can be cleaned up)
```
### Rules
- English (en) is always the source locale
- Every string table entry must include a translator comment explaining context
- Never modify translation files directly — generate diffs for review
- Character limits must be defined per-UI-element and enforced automatically
- Right-to-left (RTL) language support should be considered from the start, not bolted on later

91
.claude/skills/milestone-review/SKILL.md Normal file
View File

@@ -0,0 +1,91 @@
---
name: milestone-review
description: "Generates a comprehensive milestone progress review including feature completeness, quality metrics, risk assessment, and go/no-go recommendation. Use at milestone checkpoints or when evaluating readiness for a milestone deadline."
argument-hint: "[milestone-name|current]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When this skill is invoked:
1. **Read the milestone definition** from `production/milestones/`.
2. **Read all sprint reports** for sprints within this milestone from
`production/sprints/`.
3. **Scan the codebase** for TODO, FIXME, HACK markers that indicate
incomplete work.
4. **Check the risk register** at `production/risk-register/`.
5. **Generate the milestone review**:
```markdown
# Milestone Review: [Milestone Name]
## Overview
- **Target Date**: [Date]
- **Current Date**: [Today]
- **Days Remaining**: [N]
- **Sprints Completed**: [X/Y]
## Feature Completeness
### Fully Complete
| Feature | Acceptance Criteria | Test Status |
|---------|-------------------|-------------|
### Partially Complete
| Feature | % Done | Remaining Work | Risk to Milestone |
|---------|--------|---------------|------------------|
### Not Started
| Feature | Priority | Can Cut? | Impact of Cutting |
|---------|----------|----------|------------------|
## Quality Metrics
- **Open S1 Bugs**: [N] -- [List]
- **Open S2 Bugs**: [N]
- **Open S3 Bugs**: [N]
- **Test Coverage**: [X%]
- **Performance**: [Within budget? Details]
## Code Health
- **TODO count**: [N across codebase]
- **FIXME count**: [N]
- **HACK count**: [N]
- **Technical debt items**: [List critical ones]
## Risk Assessment
| Risk | Status | Impact if Realized | Mitigation Status |
|------|--------|-------------------|------------------|
## Velocity Analysis
- **Planned vs Completed** (across all sprints): [X/Y tasks = Z%]
- **Trend**: [Improving / Stable / Declining]
- **Adjusted estimate for remaining work**: [Days needed at current velocity]
## Scope Recommendations
### Protect (Must ship with milestone)
- [Feature and why]
### At Risk (May need to cut or simplify)
- [Feature and risk]
### Cut Candidates (Can defer without compromising milestone)
- [Feature and impact of cutting]
## Go/No-Go Assessment
**Recommendation**: [GO / CONDITIONAL GO / NO-GO]
**Conditions** (if conditional):
- [Condition 1 that must be met]
- [Condition 2 that must be met]
**Rationale**: [Explanation of the recommendation]
## Action Items
| # | Action | Owner | Deadline |
|---|--------|-------|----------|
```

71
.claude/skills/onboard/SKILL.md Normal file
View File

@@ -0,0 +1,71 @@
---
name: onboard
description: "Generates a contextual onboarding document for a new contributor or agent joining the project. Summarizes project state, architecture, conventions, and current priorities relevant to the specified role or area."
argument-hint: "[role|area]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When this skill is invoked:
1. **Read the CLAUDE.md** for project overview and standards.
2. **Read the relevant agent definition** from `.claude/agents/` if a specific
role is specified.
3. **Scan the codebase** for the relevant area:
- For programmers: scan `src/` for architecture, patterns, key files
- For designers: scan `design/` for existing design documents
- For narrative: scan `design/narrative/` for world-building and story docs
- For QA: scan `tests/` for existing test coverage
- For production: scan `production/` for current sprint and milestone
4. **Read recent changes** (git log if available) to understand current momentum.
5. **Generate the onboarding document**:
```markdown
# Onboarding: [Role/Area]
## Project Summary
[2-3 sentence summary of what this game is and its current state]
## Your Role
[What this role does on this project, key responsibilities, who you report to]
## Project Architecture
[Relevant architectural overview for this role]
### Key Directories
| Directory | Contents | Your Interaction |
|-----------|----------|-----------------|
### Key Files
| File | Purpose | Read Priority |
|------|---------|--------------|
## Current Standards and Conventions
[Summary of conventions relevant to this role from CLAUDE.md and agent definition]
## Current State of Your Area
[What has been built, what is in progress, what is planned next]
## Current Sprint Context
[What the team is working on now and what is expected of this role]
## Key Dependencies
[What other roles/systems this role interacts with most]
## Common Pitfalls
[Things that trip up new contributors in this area]
## First Tasks
[Suggested first tasks to get oriented and productive]
1. [Read these documents first]
2. [Review this code/content]
3. [Start with this small task]
## Questions to Ask
[Questions the new contributor should ask to get fully oriented]
```

120
.claude/skills/patch-notes/SKILL.md Normal file
View File

@@ -0,0 +1,120 @@
---
name: patch-notes
description: "Generate player-facing patch notes from git history, sprint data, and internal changelogs. Translates developer language into clear, engaging player communication."
argument-hint: "[version] [--style brief|detailed|full]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
---
When this skill is invoked:
1. **Parse the arguments**:
- `version`: the release version to generate notes for (e.g., `1.2.0`)
- `--style`: output style — `brief` (bullet points), `detailed` (with context),
`full` (with developer commentary). Default: `detailed`.
2. **Gather change data from multiple sources**:
- Read the internal changelog at `production/releases/[version]/changelog.md` if it exists
- Run `git log` between the previous release tag and current tag/HEAD
- Read sprint retrospectives in `production/sprints/` for context
- Read any balance change documents in `design/balance/`
- Read bug fix records from QA if available
3. **Categorize all changes** into player-facing categories:
- **New Content**: new features, maps, characters, items, modes
- **Gameplay Changes**: balance adjustments, mechanic changes, progression changes
- **Quality of Life**: UI improvements, convenience features, accessibility
- **Bug Fixes**: grouped by system (combat, UI, networking, etc.)
- **Performance**: optimization improvements players might notice
- **Known Issues**: transparency about unresolved problems
4. **Translate developer language to player language**:
- "Refactored damage calculation pipeline" → "Improved hit detection accuracy"
- "Fixed null reference in inventory manager" → "Fixed a crash when opening inventory"
- "Reduced GC allocations in combat loop" → "Improved combat performance"
- Remove purely internal changes that don't affect players
- Preserve specific numbers for balance changes (damage: 50 → 45)
5. **Generate the patch notes** using the appropriate style:
### Brief Style
```markdown
# Patch [Version] — [Title]
**New**
- [Feature 1]
- [Feature 2]
**Changes**
- [Balance/mechanic change with before → after values]
**Fixes**
- [Bug fix 1]
- [Bug fix 2]
**Known Issues**
- [Issue 1]
```
### Detailed Style
```markdown
# Patch [Version] — [Title]
*[Date]*
## Highlights
[1-2 sentence summary of the most exciting changes]
## New Content
### [Feature Name]
[2-3 sentences describing the feature and why players should be excited]
## Gameplay Changes
### Balance
| Change | Before | After | Reason |
| ---- | ---- | ---- | ---- |
| [Item/ability] | [old value] | [new value] | [brief rationale] |
### Mechanics
- **[Change]**: [explanation of what changed and why]
## Quality of Life
- [Improvement with context]
## Bug Fixes
### Combat
- Fixed [description of what players experienced]
### UI
- Fixed [description]
### Networking
- Fixed [description]
## Performance
- [Improvement players will notice]
## Known Issues
- [Issue and workaround if available]
```
### Full Style
Includes everything from Detailed, plus:
```markdown
## Developer Commentary
### [Topic]
> [Developer insight into a major change — why it was made, what was considered,
> what the team learned. Written in first-person team voice.]
```
6. **Review the output** for:
- No internal jargon (replace technical terms with player-friendly language)
- No references to internal systems, tickets, or sprint numbers
- Balance changes include before/after values
- Bug fixes describe the player experience, not the technical cause
- Tone matches the game's voice (adjust formality based on game style)
7. **Save the patch notes** to `production/releases/[version]/patch-notes.md`,
creating the directory if needed.
8. **Output to the user**: the complete patch notes, the file path, a count of
changes by category, and any internal changes that were excluded (for review).

93
.claude/skills/perf-profile/SKILL.md Normal file
View File

@@ -0,0 +1,93 @@
---
name: perf-profile
description: "Structured performance profiling workflow. Identifies bottlenecks, measures against budgets, and generates optimization recommendations with priority rankings."
argument-hint: "[system-name or 'full']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash
---
When this skill is invoked:
1. **Determine scope** from the argument:
- If a system name: focus profiling on that specific system
- If `full`: run a comprehensive profile across all systems
2. **Read performance budgets** — Check for existing performance targets in design docs or CLAUDE.md:
- Target FPS (e.g., 60fps = 16.67ms frame budget)
- Memory budget (total and per-system)
- Load time targets
- Draw call budgets
- Network bandwidth limits (if multiplayer)
3. **Analyze the codebase** for common performance issues:
**CPU Profiling Targets**:
- `_process()` / `Update()` / `Tick()` functions — list all and estimate cost
- Nested loops over large collections
- String operations in hot paths
- Allocation patterns in per-frame code
- Unoptimized search/sort over game entities
- Expensive physics queries (raycasts, overlaps) every frame
**Memory Profiling Targets**:
- Large data structures and their growth patterns
- Texture/asset memory footprint estimates
- Object pool vs instantiate/destroy patterns
- Leaked references (objects that should be freed but aren't)
- Cache sizes and eviction policies
**Rendering Targets** (if applicable):
- Draw call estimates
- Overdraw from overlapping transparent objects
- Shader complexity
- Unoptimized particle systems
- Missing LODs or occlusion culling
**I/O Targets**:
- Save/load performance
- Asset loading patterns (sync vs async)
- Network message frequency and size
4. **Generate the profiling report**:
```markdown
## Performance Profile: [System or Full]
Generated: [Date]
### Performance Budgets
| Metric | Budget | Estimated Current | Status |
|--------|--------|-------------------|--------|
| Frame time | [16.67ms] | [estimate] | [OK/WARNING/OVER] |
| Memory | [target] | [estimate] | [OK/WARNING/OVER] |
| Load time | [target] | [estimate] | [OK/WARNING/OVER] |
| Draw calls | [target] | [estimate] | [OK/WARNING/OVER] |
### Hotspots Identified
| # | Location | Issue | Estimated Impact | Fix Effort |
|---|----------|-------|------------------|------------|
| 1 | [file:line] | [description] | [High/Med/Low] | [S/M/L] |
| 2 | [file:line] | [description] | [High/Med/Low] | [S/M/L] |
### Optimization Recommendations (Priority Order)
1. **[Title]** — [Description of the optimization]
- Location: [file:line]
- Expected gain: [estimate]
- Risk: [Low/Med/High]
- Approach: [How to implement]
### Quick Wins (< 1 hour each)
- [Simple optimization 1]
- [Simple optimization 2]
### Requires Investigation
- [Area that needs actual runtime profiling to determine impact]
```
5. **Output the report** with a summary: top 3 hotspots, estimated headroom vs budget, and recommended next action.
### Rules
- Never optimize without measuring first — gut feelings about performance are unreliable
- Recommendations must include estimated impact — "make it faster" is not actionable
- Profile on target hardware, not just development machines
- Distinguish between CPU-bound, GPU-bound, and I/O-bound bottlenecks
- Consider worst-case scenarios (maximum entities, lowest spec hardware, worst network conditions)
- Static analysis (this skill) identifies candidates; runtime profiling confirms

77
.claude/skills/playtest-report/SKILL.md Normal file
View File

@@ -0,0 +1,77 @@
---
name: playtest-report
description: "Generates a structured playtest report template or analyzes existing playtest notes into a structured format. Use this to standardize playtest feedback collection and analysis."
argument-hint: "[new|analyze path-to-notes]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When invoked with `new`, generate this template:
```markdown
# Playtest Report
## Session Info
- **Date**: [Date]
- **Build**: [Version/Commit]
- **Duration**: [Time played]
- **Tester**: [Name/ID]
- **Platform**: [PC/Console/Mobile]
- **Input Method**: [KB+M / Gamepad / Touch]
- **Session Type**: [First time / Returning / Targeted test]
## Test Focus
[What specific features or flows were being tested]
## First Impressions (First 5 minutes)
- **Understood the goal?** [Yes/No/Partially]
- **Understood the controls?** [Yes/No/Partially]
- **Emotional response**: [Engaged/Confused/Bored/Frustrated/Excited]
- **Notes**: [Observations]
## Gameplay Flow
### What worked well
- [Observation 1]
- [Observation 2]
### Pain points
- [Issue 1 -- Severity: High/Medium/Low]
- [Issue 2 -- Severity: High/Medium/Low]
### Confusion points
- [Where the player was confused and why]
### Moments of delight
- [What surprised or pleased the player]
## Bugs Encountered
| # | Description | Severity | Reproducible |
|---|-------------|----------|-------------|
## Feature-Specific Feedback
### [Feature 1]
- **Understood purpose?** [Yes/No]
- **Found engaging?** [Yes/No]
- **Suggestions**: [Tester suggestions]
## Quantitative Data (if available)
- **Deaths**: [Count and locations]
- **Time per area**: [Breakdown]
- **Items used**: [What and when]
- **Features discovered vs missed**: [List]
## Overall Assessment
- **Would play again?** [Yes/No/Maybe]
- **Difficulty**: [Too Easy / Just Right / Too Hard]
- **Pacing**: [Too Slow / Good / Too Fast]
- **Session length preference**: [Shorter / Good / Longer]
## Top 3 Priorities from this session
1. [Most important finding]
2. [Second priority]
3. [Third priority]
```
When invoked with `analyze`, read the raw notes, cross-reference with existing
design documents, and fill in the template above with structured findings.
Flag any playtest observations that conflict with design intent.

184
.claude/skills/project-stage-detect/SKILL.md Normal file
View File

@@ -0,0 +1,184 @@
---
name: project-stage-detect
description: "Automatically analyze project state, detect stage, identify gaps, and recommend next steps based on existing artifacts."
argument-hint: "[optional: role filter like 'programmer' or 'designer']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash
---
# Project Stage Detection
This skill scans your project to determine its current development stage, completeness
of artifacts, and gaps that need attention. It's especially useful when:
- Starting with an existing project
- Onboarding to a codebase
- Checking what's missing before a milestone
- Understanding "where are we?"
---
## Workflow
### 1. Scan Key Directories
Analyze project structure and content:
**Design Documentation** (`design/`):
- Count GDD files in `design/gdd/*.md`
- Check for game-concept.md, game-pillars.md
- Analyze completeness (Overview, Detailed Design, Edge Cases, etc.)
- Count narrative docs in `design/narrative/`
- Count level designs in `design/levels/`
**Source Code** (`src/`):
- Count source files (language-agnostic)
- Identify major systems (directories with 5+ files)
- Check for core/, gameplay/, ai/, networking/, ui/ directories
- Estimate lines of code (rough scale)
**Production Artifacts** (`production/`):
- Check for active sprint plans
- Look for milestone definitions
- Find roadmap documents
**Prototypes** (`prototypes/`):
- Count prototype directories
- Check for READMEs (documented vs undocumented)
- Assess if prototypes are archived or active
**Architecture Docs** (`docs/architecture/`):
- Count ADRs (Architecture Decision Records)
- Check for overview/index documents
**Tests** (`tests/`):
- Count test files
- Estimate test coverage (rough heuristic)
### 2. Classify Project Stage
Based on scanned artifacts, determine stage:
| Stage | Indicators |
|-------|-----------|
| **Concept** | No code or minimal prototype, maybe idea docs |
| **Pre-production** | Design docs started, prototypes, no main src/ |
| **Production** | Active src/, sprint plans, growing systems |
| **Post-Launch** | Released, production/ has release history, maintenance focus |
### 3. Collaborative Gap Identification
**DO NOT** just list missing files. Instead, **ask clarifying questions**:
- "I see combat code (`src/gameplay/combat/`) but no `design/gdd/combat-system.md`. Was this prototyped first, or should we reverse-document?"
- "You have 15 ADRs but no architecture overview. Should I create one to help new contributors?"
- "No sprint plans in `production/`. Are you tracking work elsewhere (Jira, Trello, etc.)?"
- "Prototypes directory has 3 projects with no READMEs. Were these experiments, or do they need documentation?"
### 4. Generate Stage Report
Use template: `docs/templates/project-stage-report.md`
**Report structure**:
```markdown
# Project Stage Analysis
**Date**: [date]
**Stage**: [Concept/Pre-production/Production/Post-Launch]
## Completeness Overview
- Design: [X%] ([N] docs, [gaps])
- Code: [X%] ([N] files, [systems])
- Architecture: [X%] ([N] ADRs, [gaps])
- Production: [X%] ([status])
- Tests: [X%] ([coverage estimate])
## Gaps Identified
1. [Gap description + clarifying question]
2. [Gap description + clarifying question]
## Recommended Next Steps
[Priority-ordered list based on stage and role]
```
### 5. Role-Filtered Recommendations (Optional)
If user provided a role argument (e.g., `/project-stage-detect programmer`):
**Programmer**:
- Focus on architecture docs, test coverage, missing ADRs
- Code-to-docs gaps
**Designer**:
- Focus on GDD completeness, missing design sections
- Prototype documentation
**Producer**:
- Focus on sprint plans, milestone tracking, roadmap
- Cross-team coordination docs
**General** (no role):
- Holistic view of all gaps
- Highest-priority items across domains
### 6. Request Approval Before Writing
**Collaborative protocol**:
```
I've analyzed your project. Here's what I found:
[Show summary]
Gaps identified:
1. [Gap 1 + question]
2. [Gap 2 + question]
Recommended next steps:
- [Priority 1]
- [Priority 2]
- [Priority 3]
May I write the full stage analysis to docs/project-stage-report.md?
```
Wait for user approval before creating the file.
---
## Example Usage
```bash
# General project analysis
/project-stage-detect
# Programmer-focused analysis
/project-stage-detect programmer
# Designer-focused analysis
/project-stage-detect designer
```
---
## Follow-Up Actions
After generating the report, suggest relevant next steps:
- **Missing design docs?** → `/reverse-document design src/[system]`
- **Missing architecture docs?** → `/architecture-decision` or `/reverse-document architecture`
- **Prototypes need documentation?** → `/reverse-document concept prototypes/[name]`
- **No sprint plan?** → `/sprint-plan`
- **Approaching milestone?** → `/milestone-review`
---
## Collaborative Protocol
This skill follows the collaborative design principle:
1. **Question First**: Ask about gaps, don't assume
2. **Present Options**: "Should I create X, or is it tracked elsewhere?"
3. **User Decides**: Wait for direction
4. **Show Draft**: Display report summary
5. **Get Approval**: "May I write to docs/project-stage-report.md?"
**Never** silently write files. **Always** show findings and ask before creating artifacts.

99
.claude/skills/prototype/SKILL.md Normal file
View File

@@ -0,0 +1,99 @@
---
name: prototype
description: "Rapid prototyping workflow. Skips normal standards to quickly validate a game concept or mechanic. Produces throwaway code and a structured prototype report."
argument-hint: "[concept-description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
---
When this skill is invoked:
1. **Read the concept description** from the argument. Identify the core
question this prototype must answer. If the concept is vague, state the
question explicitly before proceeding.
2. **Read CLAUDE.md** for project context and the current tech stack. Understand
what engine, language, and frameworks are in use so the prototype is built
with compatible tooling.
3. **Create a prototype plan**: Define in 3-5 bullet points what the minimum
viable prototype looks like. What is the core question? What is the absolute
minimum code needed to answer it? What can be skipped?
4. **Create the prototype directory**: `prototypes/[concept-name]/` where
`[concept-name]` is a short, kebab-case identifier derived from the concept.
5. **Implement the prototype** in the isolated directory. Every file must begin
with:
```
// PROTOTYPE - NOT FOR PRODUCTION
// Question: [Core question being tested]
// Date: [Current date]
```
Standards are intentionally relaxed:
- Hardcode values freely
- Use placeholder assets
- Skip error handling
- Use the simplest approach that works
- Copy code rather than importing from production
6. **Test the concept**: Run the prototype. Observe behavior. Collect any
measurable data (frame times, interaction counts, feel assessments).
7. **Generate the Prototype Report** and save it to
`prototypes/[concept-name]/REPORT.md`:
```markdown
## Prototype Report: [Concept Name]
### Hypothesis
[What we expected to be true -- the question we set out to answer]
### Approach
[What we built, how long it took, what shortcuts we took]
### Result
[What actually happened -- specific observations, not opinions]
### Metrics
[Any measurable data collected during testing]
- Frame time: [if relevant]
- Feel assessment: [subjective but specific -- "response felt sluggish at
200ms delay" not "felt bad"]
- Player action counts: [if relevant]
- Iteration count: [how many attempts to get it working]
### Recommendation: [PROCEED / PIVOT / KILL]
[One paragraph explaining the recommendation with evidence]
### If Proceeding
[What needs to change for a production-quality implementation]
- Architecture requirements
- Performance targets
- Scope adjustments from the original design
- Estimated production effort
### If Pivoting
[What alternative direction the results suggest]
### If Killing
[Why this concept does not work and what we should do instead]
### Lessons Learned
[Discoveries that affect other systems or future work]
```
8. **Output a summary** to the user with: the core question, the result, and
the recommendation. Link to the full report at
`prototypes/[concept-name]/REPORT.md`.
### Important Constraints
- Prototype code must NEVER import from production source files
- Production code must NEVER import from prototype directories
- If the recommendation is PROCEED, the production implementation must be
written from scratch -- prototype code is not refactored into production
- Total prototype effort should be timeboxed to 1-3 days equivalent of work
- If the prototype scope starts growing, stop and reassess whether the
question can be simplified

166
.claude/skills/release-checklist/SKILL.md Normal file
View File

@@ -0,0 +1,166 @@
---
name: release-checklist
description: "Generates a comprehensive pre-release validation checklist covering build verification, certification requirements, store metadata, and launch readiness."
argument-hint: "[platform: pc|console|mobile|all]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When this skill is invoked:
> **Explicit invocation only**: This skill should only run when the user explicitly requests it with `/release-checklist`. Do not auto-invoke based on context matching.
1. **Read the argument** for the target platform (`pc`, `console`, `mobile`,
or `all`). If no platform is specified, default to `all`.
2. **Read CLAUDE.md** for project context, version information, and platform
targets.
3. **Read the current milestone** from `production/milestones/` to understand
what features and content should be included in this release.
4. **Scan the codebase** for outstanding issues:
- Count `TODO` comments
- Count `FIXME` comments
- Count `HACK` comments
- Note their locations and severity
5. **Check for test results** in any test output directories or CI logs if
available.
6. **Generate the release checklist**:
```markdown
## Release Checklist: [Version] -- [Platform]
Generated: [Date]
### Codebase Health
- TODO count: [N] ([list top 5 if many])
- FIXME count: [N] ([list all -- these are potential blockers])
- HACK count: [N] ([list all -- these need review])
### Build Verification
- [ ] Clean build succeeds on all target platforms
- [ ] No compiler warnings (zero-warning policy)
- [ ] All assets included and loading correctly
- [ ] Build size within budget ([target size])
- [ ] Build version number correctly set ([version])
- [ ] Build is reproducible from tagged commit
### Quality Gates
- [ ] Zero S1 (Critical) bugs
- [ ] Zero S2 (Major) bugs -- or documented exceptions with producer approval
- [ ] All critical path features tested and signed off by QA
- [ ] Performance within budgets:
- [ ] Target FPS met on minimum spec hardware
- [ ] Memory usage within budget
- [ ] Load times within budget
- [ ] No memory leaks over extended play sessions
- [ ] No regression from previous build
- [ ] Soak test passed (4+ hours continuous play)
### Content Complete
- [ ] All placeholder assets replaced with final versions
- [ ] All TODO/FIXME in content files resolved or documented
- [ ] All player-facing text proofread
- [ ] All text localization-ready (no hardcoded strings)
- [ ] Audio mix finalized and approved
- [ ] Credits complete and accurate
```
7. **Add platform-specific sections** based on the argument:
For `pc`:
```markdown
### Platform Requirements: PC
- [ ] Minimum and recommended specs verified and documented
- [ ] Keyboard+mouse controls fully functional
- [ ] Controller support tested (Xbox, PlayStation, generic)
- [ ] Resolution scaling tested (1080p, 1440p, 4K, ultrawide)
- [ ] Windowed, borderless, and fullscreen modes working
- [ ] Graphics settings save and load correctly
- [ ] Steam/Epic/GOG SDK integrated and tested
- [ ] Achievements functional
- [ ] Cloud saves functional
- [ ] Steam Deck compatibility verified (if targeting)
```
For `console`:
```markdown
### Platform Requirements: Console
- [ ] TRC/TCR/Lotcheck requirements checklist complete
- [ ] Platform-specific controller prompts display correctly
- [ ] Suspend/resume works correctly
- [ ] User switching handled properly
- [ ] Network connectivity loss handled gracefully
- [ ] Storage full scenario handled
- [ ] Parental controls respected
- [ ] Platform-specific achievement/trophy integration tested
- [ ] First-party certification submission prepared
```
For `mobile`:
```markdown
### Platform Requirements: Mobile
- [ ] App store guidelines compliance verified
- [ ] All required device permissions justified and documented
- [ ] Privacy policy linked and accurate
- [ ] Data safety/nutrition labels completed
- [ ] Touch controls tested on multiple screen sizes
- [ ] Battery usage within acceptable range
- [ ] Background behavior correct (pause, resume, terminate)
- [ ] Push notification permissions handled correctly
- [ ] In-app purchase flow tested (if applicable)
- [ ] App size within store limits
```
8. **Add store and launch sections**:
```markdown
### Store / Distribution
- [ ] Store page metadata complete and proofread
- [ ] Short description
- [ ] Long description
- [ ] Feature list
- [ ] System requirements (PC)
- [ ] Screenshots up to date and per-platform resolution requirements met
- [ ] Trailers up to date
- [ ] Key art and capsule images current
- [ ] Age rating obtained and configured:
- [ ] ESRB
- [ ] PEGI
- [ ] Other regional ratings as required
- [ ] Legal notices, EULA, and privacy policy in place
- [ ] Third-party license attributions complete
- [ ] Pricing configured for all regions
### Launch Readiness
- [ ] Analytics / telemetry verified and receiving data
- [ ] Crash reporting configured and dashboard accessible
- [ ] Day-one patch prepared and tested (if needed)
- [ ] On-call team schedule set for first 72 hours
- [ ] Community launch announcements drafted
- [ ] Press/influencer keys prepared for distribution
- [ ] Support team briefed on known issues and FAQ
- [ ] Rollback plan documented (if critical issues found post-launch)
### Go / No-Go: [READY / NOT READY]
**Rationale:**
[Summary of readiness assessment. List any blocking items that must be
resolved before launch. If NOT READY, list the specific items that need
resolution and estimated time to address them.]
**Sign-offs Required:**
- [ ] QA Lead
- [ ] Technical Director
- [ ] Producer
- [ ] Creative Director
```
9. **Save the checklist** to
`production/releases/release-checklist-[version].md`, creating the
directory if it does not exist.
10. **Output a summary** to the user with: total checklist items, number of
known blockers (FIXME/HACK counts, known bugs), and the file path.

158
.claude/skills/retrospective/SKILL.md Normal file
View File

@@ -0,0 +1,158 @@
---
name: retrospective
description: "Generates a sprint or milestone retrospective by analyzing completed work, velocity, blockers, and patterns. Produces actionable insights for the next iteration."
argument-hint: "[sprint-N|milestone-name]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
context: |
!git log --oneline --since="2 weeks ago" 2>/dev/null
---
When this skill is invoked:
1. **Read the argument** to determine whether this is a sprint retrospective
(`sprint-N`) or a milestone retrospective (`milestone-name`).
2. **Read the sprint or milestone plan** from the appropriate location:
- Sprint plans: `production/sprints/`
- Milestone definitions: `production/milestones/`
Extract: planned tasks, estimated effort, owners, and goals.
3. **Read the git log** for the period covered by the sprint or milestone to
understand what was actually committed and when.
4. **Scan for completed and incomplete tasks** by comparing the plan against
actual deliverables. Check for:
- Tasks completed as planned
- Tasks completed but modified from the plan
- Tasks carried over (not completed)
- Tasks added mid-sprint (unplanned work)
- Tasks removed or descoped
5. **Scan the codebase for TODO/FIXME trends**:
- Count current TODO/FIXME/HACK comments
- Compare to previous sprint counts if available (check previous
retrospectives)
- Note whether technical debt is growing or shrinking
6. **Read previous retrospectives** (if any) from `production/sprints/` or
`production/milestones/` to check:
- Were previous action items addressed?
- Are the same problems recurring?
- How has velocity trended?
7. **Generate the retrospective**:
```markdown
## Retrospective: [Sprint N / Milestone Name]
Period: [Start Date] -- [End Date]
Generated: [Date]
### Metrics
| Metric | Planned | Actual | Delta |
|--------|---------|--------|-------|
| Tasks | [X] | [Y] | [+/- Z] |
| Completion Rate | -- | [Z%] | -- |
| Story Points / Effort Days | [X] | [Y] | [+/- Z] |
| Bugs Found | -- | [N] | -- |
| Bugs Fixed | -- | [N] | -- |
| Unplanned Tasks Added | -- | [N] | -- |
| Commits | -- | [N] | -- |
### Velocity Trend
| Sprint | Planned | Completed | Rate |
|--------|---------|-----------|------|
| [N-2] | [X] | [Y] | [Z%] |
| [N-1] | [X] | [Y] | [Z%] |
| [N] (current) | [X] | [Y] | [Z%] |
**Trend**: [Increasing / Stable / Decreasing]
[One sentence explaining the trend]
### What Went Well
- [Observation backed by specific data or examples]
- [Another positive observation]
- [Recognize specific contributions or decisions that paid off]
### What Went Poorly
- [Specific issue with measurable impact -- e.g., "Feature X took 5 days
instead of estimated 2, blocking tasks Y and Z"]
- [Another issue with impact]
- [Do not assign blame -- focus on systemic causes]
### Blockers Encountered
| Blocker | Duration | Resolution | Prevention |
|---------|----------|------------|------------|
| [What blocked progress] | [How long] | [How it was resolved] | [How to prevent recurrence] |
### Estimation Accuracy
| Task | Estimated | Actual | Variance | Likely Cause |
|------|-----------|--------|----------|--------------|
| [Most overestimated task] | [X] | [Y] | [+Z] | [Why] |
| [Most underestimated task] | [X] | [Y] | [-Z] | [Why] |
**Overall estimation accuracy**: [X%] of tasks within +/- 20% of estimate
[Analysis: Are we consistently over- or under-estimating? For which types of
tasks? What adjustment should we apply?]
### Carryover Analysis
| Task | Original Sprint | Times Carried | Reason | Action |
|------|----------------|---------------|--------|--------|
| [Task that was not completed] | [Sprint N-X] | [N] | [Why] | [Complete / Descope / Redesign] |
### Technical Debt Status
- Current TODO count: [N] (previous: [N])
- Current FIXME count: [N] (previous: [N])
- Current HACK count: [N] (previous: [N])
- Trend: [Growing / Stable / Shrinking]
- [Note any areas of concern]
### Previous Action Items Follow-Up
| Action Item (from Sprint N-1) | Status | Notes |
|-------------------------------|--------|-------|
| [Previous action] | [Done / In Progress / Not Started] | [Context] |
### Action Items for Next Iteration
| # | Action | Owner | Priority | Deadline |
|---|--------|-------|----------|----------|
| 1 | [Specific, measurable action] | [Who] | [High/Med/Low] | [When] |
| 2 | [Another action] | [Who] | [Priority] | [When] |
### Process Improvements
- [Specific change to how we work, with expected benefit]
- [Another improvement -- keep it to 2-3 actionable items, not a wish list]
### Summary
[2-3 sentence overall assessment: Was this a good sprint/milestone? What is
the single most important thing to change going forward?]
```
8. **Save the retrospective** to the appropriate location:
- Sprint: `production/sprints/sprint-[N]-retrospective.md`
- Milestone: `production/milestones/[milestone-name]-retrospective.md`
Create the directory if it does not exist.
9. **Output a summary** to the user with: completion rate, velocity trend
direction, top blocker, and the most important action item.
### Guidelines
- Be honest and specific. Vague retrospectives ("communication could be
better") produce vague improvements. Use data and examples.
- Focus on systemic issues, not individual blame.
- Limit action items to 3-5. More than that dilutes focus.
- Every action item must have an owner and a deadline.
- Check whether previous action items were completed. Recurring unaddressed
items are a process smell.
- If this is a milestone retrospective, also evaluate whether the milestone
goals were achieved and what that means for the overall project timeline.

262
.claude/skills/reverse-document/SKILL.md Normal file
View File

@@ -0,0 +1,262 @@
---
name: reverse-document
description: "Generate design or architecture documents from existing implementation. Works backwards from code/prototypes to create missing planning docs."
argument-hint: "<type> <path> (e.g., 'design src/gameplay/combat' or 'architecture src/core')"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
---
# Reverse Documentation
This skill analyzes existing implementation (code, prototypes, systems) and generates
appropriate design or architecture documentation. Use this when:
- You built a feature without writing a design doc first
- You inherited a codebase without documentation
- You prototyped a mechanic and need to formalize it
- You need to document "why" behind existing code
---
## Workflow
### 1. Parse Arguments
**Format**: `/reverse-document <type> <path>`
**Type options**:
- `design` → Generate a game design document (GDD section)
- `architecture` → Generate an Architecture Decision Record (ADR)
- `concept` → Generate a concept document from prototype
**Path**: Directory or file to analyze
- `src/gameplay/combat/` → All combat-related code
- `src/core/event-system.cpp` → Specific file
- `prototypes/stealth-mech/` → Prototype directory
**Examples**:
```bash
/reverse-document design src/gameplay/magic-system
/reverse-document architecture src/core/entity-component
/reverse-document concept prototypes/vehicle-combat
```
### 2. Analyze Implementation
**Read and understand the code/prototype**:
**For design docs (GDD):**
- Identify mechanics, rules, formulas
- Extract gameplay values (damage, cooldowns, ranges)
- Find state machines, ability systems, progression
- Detect edge cases handled in code
- Map dependencies (what systems interact?)
**For architecture docs (ADR):**
- Identify patterns (ECS, singleton, observer, etc.)
- Understand technical decisions (threading, serialization, etc.)
- Map dependencies and coupling
- Assess performance characteristics
- Find constraints and trade-offs
**For concept docs (prototype analysis):**
- Identify core mechanic
- Extract emergent gameplay patterns
- Note what worked vs what didn't
- Find technical feasibility insights
- Document player fantasy / feel
### 3. Ask Clarifying Questions (Collaborative Protocol)
**DO NOT** just describe the code. **ASK** about intent:
**Design questions**:
- "I see a stamina system that depletes during combat. Was this for:
- Pacing (prevent spam)?
- Resource management (strategic depth)?
- Or something else?"
- "The stagger mechanic seems central. Is this a core pillar, or supporting feature?"
- "Damage scales exponentially with level. Intentional power fantasy, or needs rebalancing?"
**Architecture questions**:
- "You're using a service locator pattern. Was this chosen for:
- Testability (mock dependencies)?
- Decoupling (reduce hard references)?
- Or inherited from existing code?"
- "I see manual memory management instead of smart pointers. Performance requirement, or legacy?"
**Concept questions**:
- "The prototype emphasizes stealth over combat. Is that the intended pillar?"
- "Players seem to exploit the grappling hook for speed. Feature or bug?"
### 4. Present Findings
Before drafting, show what you discovered:
```
I've analyzed src/gameplay/combat/. Here's what I found:
MECHANICS IMPLEMENTED:
- 3-hit combo system with timing windows
- Guard-break mechanic (heavy attack vs blocking enemy)
- Stamina system (depletes on attack/dodge, regens when idle)
- Stagger system (builds up, triggers vulnerable state)
FORMULAS DISCOVERED:
- Damage = Base * (1 + StrengthScaling * Level)
- Stagger buildup = AttackStaggerValue / (Enemy.Poise * 0.5)
- Stamina cost = BaseStaminaCost * (1 - EfficiencyBonus)
UNCLEAR INTENT AREAS:
1. Stamina system — pacing or resource management?
2. Stagger — core pillar or supporting feature?
3. Damage scaling — power fantasy or needs tuning?
Before I draft the design doc, could you clarify these points?
```
Wait for user to clarify intent before drafting.
### 5. Draft Document Using Template
Based on type, use appropriate template:
| Type | Template | Output Path |
|------|----------|-------------|
| `design` | `templates/design-doc-from-implementation.md` | `design/gdd/[system-name].md` |
| `architecture` | `templates/architecture-doc-from-code.md` | `docs/architecture/[decision-name].md` |
| `concept` | `templates/concept-doc-from-prototype.md` | `prototypes/[name]/CONCEPT.md` or `design/concepts/[name].md` |
**Draft structure**:
- Capture **what exists** (mechanics, patterns, implementation)
- Document **why it exists** (intent clarified with user)
- Identify **what's missing** (edge cases not handled, gaps in design)
- Flag **follow-up work** (balance tuning, missing features)
### 6. Show Draft and Request Approval
**Collaborative protocol**:
```
I've drafted the combat system design doc based on your code and clarifications.
[Show key sections: Overview, Mechanics, Formulas, Design Intent]
ADDITIONS I MADE:
- Documented stamina as "pacing mechanic" per your clarification
- Added edge cases not in code (what if stamina hits 0 mid-combo?)
- Flagged balance concern: exponential damage scaling at high levels
SECTIONS MARKED AS INCOMPLETE:
- "Enemy AI interaction with stagger" (not fully implemented yet)
- "Weapon variety and scaling" (only sword implemented so far)
May I write this to design/gdd/combat-system.md?
```
Wait for approval. User may request changes before writing.
### 7. Write Document with Metadata
When approved, write the file with special markers:
```markdown
---
status: reverse-documented
source: src/gameplay/combat/
date: 2026-02-13
verified-by: [User name]
---
# Combat System Design
> **Note**: This document was reverse-engineered from the existing implementation.
> It captures current behavior and clarified design intent. Some sections may be
> incomplete where implementation is partial or intent was unclear.
[Rest of document...]
```
### 8. Flag Follow-Up Work
After writing, suggest next steps:
```
✅ Written to design/gdd/combat-system.md
FOLLOW-UP RECOMMENDED:
1. Run /balance-check on combat formulas (exponential scaling concern)
2. Create ADR for stamina system architecture decision
3. Implement missing edge cases:
- Stamina depletion mid-combo behavior
- Stagger state during dodge
4. Extend design doc when weapon variety is implemented
Would you like me to tackle any of these now?
```
---
## Template Selection Logic
| If analyzing... | Use template... | Because... |
|----------------|-----------------|------------|
| `src/gameplay/*` | design-doc-from-implementation.md | Gameplay mechanics → GDD |
| `src/core/*`, `src/ai/*` | architecture-doc-from-code.md | Core systems → ADR |
| `prototypes/*` | concept-doc-from-prototype.md | Experiments → concept doc |
| `src/networking/*` | architecture-doc-from-code.md | Technical systems → ADR |
| `src/ui/*` | design-doc-from-implementation.md | UI/UX → design spec |
---
## Example Session: Reverse-Document Combat Code
```
User: /reverse-document design src/gameplay/combat
Agent: I'll analyze your combat implementation to create a design doc.
[Reads code, discovers mechanics, formulas]
Agent: I've analyzed src/gameplay/combat/. Here's what I found:
[Shows mechanics, formulas, unclear areas]
Before drafting, could you clarify:
1. Stamina system intent?
2. Is stagger a core pillar?
3. Damage scaling — intentional or needs tuning?
User: 1. Stamina is for pacing, prevent button mashing
2. Stagger is core — I want deliberate combat
3. Yeah, exponential is too much, should be linear
Agent: Perfect, that clarifies the vision. Let me draft the design doc.
[Shows draft with clarified intent]
May I write this to design/gdd/combat-system.md?
User: Yes, write it.
Agent: ✅ Written to design/gdd/combat-system.md
✅ Marked as [REVERSE-DOCUMENTED]
✅ Flagged damage scaling for rebalancing
Next steps:
- Update damage formula to linear scaling
- Run /balance-check to validate progression curve
- Document stagger as core pillar in game-pillars.md
```
---
## Collaborative Protocol
This skill follows the collaborative design principle:
1. **Analyze First**: Read code, understand implementation
2. **Question Intent**: Ask about "why", not just "what"
3. **Present Findings**: Show discoveries, highlight unclear areas
4. **User Clarifies**: Separate intent from accidents
5. **Draft Document**: Create doc based on reality + intent
6. **Show Draft**: Display key sections, explain additions
7. **Get Approval**: "May I write to [filepath]?"
8. **Flag Follow-Up**: Suggest related work, don't auto-execute
**Never assume intent. Always ask before documenting "why".**

73
.claude/skills/scope-check/SKILL.md Normal file
View File

@@ -0,0 +1,73 @@
---
name: scope-check
description: "Analyze a feature or sprint for scope creep by comparing current scope against the original plan. Flags additions, quantifies bloat, and recommends cuts."
argument-hint: "[feature-name or sprint-N]"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: |
!git diff --stat HEAD~20 2>/dev/null
---
When this skill is invoked:
1. **Read the original plan** — Find the relevant document:
- If a feature name: read the design doc from `design/gdd/`
- If a sprint number: read the sprint plan from `production/sprints/`
- If a milestone: read the milestone definition from `production/milestones/`
2. **Read the current state** — Check what has actually been implemented or is in progress:
- Scan the codebase for files related to the feature/sprint
- Read git log for commits related to this work
- Check for TODO comments that indicate unfinished scope additions
3. **Compare original vs current scope**:
```markdown
## Scope Check: [Feature/Sprint Name]
Generated: [Date]
### Original Scope
[List of items from the original plan]
### Current Scope
[List of items currently implemented or in progress]
### Scope Additions (not in original plan)
| Addition | Who Added | When | Justified? | Effort |
|----------|-----------|------|------------|--------|
| [item] | [commit/person] | [date] | [Yes/No/Unclear] | [S/M/L] |
### Scope Removals (in original but dropped)
| Removed Item | Reason | Impact |
|-------------|--------|--------|
| [item] | [why removed] | [what's affected] |
### Bloat Score
- Original items: [N]
- Current items: [N]
- Items added: [N] (+[X]%)
- Items removed: [N]
- Net scope change: [+/-N] ([X]%)
### Risk Assessment
- **Schedule Risk**: [Low/Medium/High] — [explanation]
- **Quality Risk**: [Low/Medium/High] — [explanation]
- **Integration Risk**: [Low/Medium/High] — [explanation]
### Recommendations
1. **Cut**: [Items that should be removed to stay on schedule]
2. **Defer**: [Items that can move to a future sprint/version]
3. **Keep**: [Additions that are genuinely necessary]
4. **Flag**: [Items that need a decision from producer/creative-director]
```
4. **Output the scope check** with a clear verdict:
- **On Track**: Scope within 10% of original
- **Minor Creep**: 10-25% scope increase — manageable with adjustments
- **Significant Creep**: 25-50% scope increase — need to cut or extend timeline
- **Out of Control**: >50% scope increase — stop and re-plan
### Rules
- Scope creep is additions without corresponding cuts or timeline extensions
- Not all additions are bad — some are discovered requirements. But they must be acknowledged and accounted for.
- When recommending cuts, prioritize preserving the core player experience over nice-to-haves
- Always quantify scope changes — "it feels bigger" is not actionable, "+35% items" is

307
.claude/skills/setup-engine/SKILL.md Normal file
View File

@@ -0,0 +1,307 @@
---
name: setup-engine
description: "Configure the project's game engine and version. Pins the engine in CLAUDE.md, detects knowledge gaps, and populates engine reference docs via WebSearch when the version is beyond the LLM's training data."
argument-hint: "[engine version] or no args for guided selection"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, WebSearch, WebFetch, Task
---
When this skill is invoked:
## 1. Parse Arguments
Three modes:
- **Full spec**: `/setup-engine godot 4.6` — engine and version provided
- **Engine only**: `/setup-engine unity` — engine provided, version will be looked up
- **No args**: `/setup-engine` — fully guided mode (engine recommendation + version)
---
## 2. Guided Mode (No Arguments)
If no engine is specified, run an interactive engine selection process:
### Check for existing game concept
- Read `design/gdd/game-concept.md` if it exists — extract genre, scope, platform
targets, art style, team size, and any engine recommendation from `/brainstorm`
- If no concept exists, inform the user:
> "No game concept found. Consider running `/brainstorm` first to discover what
> you want to build — it will also recommend an engine. Or tell me about your
> game and I can help you pick."
### If the user wants to pick without a concept, ask:
1. **What kind of game?** (2D, 3D, or both?)
2. **What platforms?** (PC, mobile, console, web?)
3. **Team size and experience?** (solo beginner, solo experienced, small team?)
4. **Any strong language preferences?** (GDScript, C#, C++, visual scripting?)
5. **Budget for engine licensing?** (free only, or commercial licenses OK?)
### Produce a recommendation
Use this decision matrix:
| Factor | Godot 4 | Unity | Unreal Engine 5 |
|--------|---------|-------|-----------------|
| **Best for** | 2D games, small 3D, solo/small teams | Mobile, mid-scope 3D, cross-platform | AAA 3D, photorealism, large teams |
| **Language** | GDScript (+ C#, C++ via extensions) | C# | C++ / Blueprint |
| **Cost** | Free, MIT license | Free under revenue threshold | Free under revenue threshold, 5% royalty |
| **Learning curve** | Gentle | Moderate | Steep |
| **2D support** | Excellent (native) | Good (but 3D-first engine) | Possible but not ideal |
| **3D quality ceiling** | Good (improving rapidly) | Very good | Best-in-class |
| **Web export** | Yes (native) | Yes (limited) | No |
| **Console export** | Via third-party | Yes (with license) | Yes |
| **Open source** | Yes | No | Source available |
Present the top 1-2 recommendations with reasoning tied to the user's answers.
Let the user choose — never force a recommendation.
---
## 3. Look Up Current Version
Once the engine is chosen:
- If version was provided, use it
- If no version provided, use WebSearch to find the latest stable release:
- Search: `"[engine] latest stable version [current year]"`
- Confirm with the user: "The latest stable [engine] is [version]. Use this?"
---
## 4. Update CLAUDE.md Technology Stack
Read `CLAUDE.md` and update the Technology Stack section. Replace the
`[CHOOSE]` placeholders with the actual values:
**For Godot:**
```markdown
- **Engine**: Godot [version]
- **Language**: GDScript (primary), C++ via GDExtension (performance-critical)
- **Build System**: SCons (engine), Godot Export Templates
- **Asset Pipeline**: Godot Import System + custom resource pipeline
```
**For Unity:**
```markdown
- **Engine**: Unity [version]
- **Language**: C#
- **Build System**: Unity Build Pipeline
- **Asset Pipeline**: Unity Asset Import Pipeline + Addressables
```
**For Unreal:**
```markdown
- **Engine**: Unreal Engine [version]
- **Language**: C++ (primary), Blueprint (gameplay prototyping)
- **Build System**: Unreal Build Tool (UBT)
- **Asset Pipeline**: Unreal Content Pipeline
```
---
## 5. Populate Technical Preferences
After updating CLAUDE.md, create or update `.claude/docs/technical-preferences.md` with
engine-appropriate defaults. Read the existing template first, then fill in:
### Engine & Language Section
- Fill from the engine choice made in step 4
### Naming Conventions (engine defaults)
**For Godot (GDScript):**
- Classes: PascalCase (e.g., `PlayerController`)
- Variables/functions: snake_case (e.g., `move_speed`)
- Signals: snake_case past tense (e.g., `health_changed`)
- Files: snake_case matching class (e.g., `player_controller.gd`)
- Scenes: PascalCase matching root node (e.g., `PlayerController.tscn`)
- Constants: UPPER_SNAKE_CASE (e.g., `MAX_HEALTH`)
**For Unity (C#):**
- Classes: PascalCase (e.g., `PlayerController`)
- Public fields/properties: PascalCase (e.g., `MoveSpeed`)
- Private fields: _camelCase (e.g., `_moveSpeed`)
- Methods: PascalCase (e.g., `TakeDamage()`)
- Files: PascalCase matching class (e.g., `PlayerController.cs`)
- Constants: PascalCase or UPPER_SNAKE_CASE
**For Unreal (C++):**
- Classes: Prefixed PascalCase (`A` for Actor, `U` for UObject, `F` for struct)
- Variables: PascalCase (e.g., `MoveSpeed`)
- Functions: PascalCase (e.g., `TakeDamage()`)
- Booleans: `b` prefix (e.g., `bIsAlive`)
- Files: Match class without prefix (e.g., `PlayerController.h`)
### Remaining Sections
- Performance Budgets: Leave as `[TO BE CONFIGURED]` with a suggestion:
> "Typical targets: 60fps / 16.6ms frame budget. Want to set these now?"
- Testing: Suggest engine-appropriate framework (GUT for Godot, NUnit for Unity, etc.)
- Forbidden Patterns / Allowed Libraries: Leave as placeholder
### Collaborative Step
Present the filled-in preferences to the user:
> "Here are the default technical preferences for [engine]. Want to customize
> any of these, or shall I save the defaults?"
Wait for approval before writing the file.
---
## 6. Determine Knowledge Gap
Check whether the engine version is likely beyond the LLM's training data.
**Known approximate coverage** (update this as models change):
- LLM knowledge cutoff: **May 2025**
- Godot: training data likely covers up to ~4.3
- Unity: training data likely covers up to ~2023.x / early 6000.x
- Unreal: training data likely covers up to ~5.3 / early 5.4
Compare the user's chosen version against these baselines:
- **Within training data** → `LOW RISK` — reference docs optional but recommended
- **Near the edge** → `MEDIUM RISK` — reference docs recommended
- **Beyond training data** → `HIGH RISK` — reference docs required
Inform the user which category they're in and why.
---
## 7. Populate Engine Reference Docs
### If WITHIN training data (LOW RISK):
Create a minimal `docs/engine-reference/<engine>/VERSION.md`:
```markdown
# [Engine] — Version Reference
| Field | Value |
|-------|-------|
| **Engine Version** | [version] |
| **Project Pinned** | [today's date] |
| **LLM Knowledge Cutoff** | May 2025 |
| **Risk Level** | LOW — version is within LLM training data |
## Note
This engine version is within the LLM's training data. Engine reference
docs are optional but can be added later if agents suggest incorrect APIs.
Run `/setup-engine refresh` to populate full reference docs at any time.
```
Do NOT create breaking-changes.md, deprecated-apis.md, etc. — they would
add context cost with minimal value.
### If BEYOND training data (MEDIUM or HIGH RISK):
Create the full reference doc set by searching the web:
1. **Search for the official migration/upgrade guide**:
- `"[engine] [old version] to [new version] migration guide"`
- `"[engine] [version] breaking changes"`
- `"[engine] [version] changelog"`
- `"[engine] [version] deprecated API"`
2. **Fetch and extract** from official documentation:
- Breaking changes between each version from the training cutoff to current
- Deprecated APIs with replacements
- New features and best practices
3. **Create the full reference directory**:
```
docs/engine-reference/<engine>/
├── VERSION.md # Version pin + knowledge gap analysis
├── breaking-changes.md # Version-by-version breaking changes
├── deprecated-apis.md # "Don't use X → Use Y" tables
├── current-best-practices.md # New practices since training cutoff
└── modules/ # Per-subsystem references (create as needed)
```
4. **Populate each file** using real data from the web searches, following
the format established in existing reference docs. Every file must have
a "Last verified: [date]" header.
5. **For module files**: Only create modules for subsystems where significant
changes occurred. Don't create empty or minimal module files.
---
## 8. Update CLAUDE.md Import
Update the `@` import under "Engine Version Reference" to point to the
correct engine:
```markdown
## Engine Version Reference
@docs/engine-reference/<engine>/VERSION.md
```
If the previous import pointed to a different engine (e.g., switching from
Godot to Unity), update it.
---
## 9. Update Agent Instructions
For the chosen engine's specialist agents, verify they have a
"Version Awareness" section. If not, add one following the pattern in
the existing Godot specialist agents.
The section should instruct the agent to:
1. Read `docs/engine-reference/<engine>/VERSION.md`
2. Check deprecated APIs before suggesting code
3. Check breaking changes for relevant version transitions
4. Use WebSearch to verify uncertain APIs
---
## 10. Refresh Subcommand
If invoked as `/setup-engine refresh`:
1. Read the existing `docs/engine-reference/<engine>/VERSION.md` to get
the current engine and version
2. Use WebSearch to check for:
- New engine releases since last verification
- Updated migration guides
- Newly deprecated APIs
3. Update all reference docs with new findings
4. Update "Last verified" dates on all modified files
5. Report what changed
---
## 11. Output Summary
After setup is complete, output:
```
Engine Setup Complete
=====================
Engine: [name] [version]
Knowledge Risk: [LOW/MEDIUM/HIGH]
Reference Docs: [created/skipped]
CLAUDE.md: [updated]
Tech Prefs: [created/updated]
Agent Config: [verified]
Next Steps:
1. Review docs/engine-reference/<engine>/VERSION.md
2. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop
3. [If fresh start] Run /brainstorm to discover your game concept
4. Create your first milestone: /sprint-plan new
```
---
## Guardrails
- NEVER guess an engine version — always verify via WebSearch or user confirmation
- NEVER overwrite existing reference docs without asking — append or update
- If reference docs already exist for a different engine, ask before replacing
- Always show the user what you're about to change before making CLAUDE.md edits
- If WebSearch returns ambiguous results, show the user and let them decide

108
.claude/skills/sprint-plan/SKILL.md Normal file
View File

@@ -0,0 +1,108 @@
---
name: sprint-plan
description: "Generates a new sprint plan or updates an existing one based on the current milestone, completed work, and available capacity. Pulls context from production documents and design backlogs."
argument-hint: "[new|update|status]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit
context: |
!ls production/sprints/ 2>/dev/null
---
When this skill is invoked:
1. **Read the current milestone** from `production/milestones/`.
2. **Read the previous sprint** (if any) from `production/sprints/` to
understand velocity and carryover.
3. **Scan design documents** in `design/gdd/` for features tagged as ready
for implementation.
4. **Check the risk register** at `production/risk-register/`.
For `new`:
5. **Generate a sprint plan** following this format:
```markdown
# Sprint [N] -- [Start Date] to [End Date]
## Sprint Goal
[One sentence describing what this sprint achieves toward the milestone]
## Capacity
- Total days: [X]
- Buffer (20%): [Y days reserved for unplanned work]
- Available: [Z days]
## Tasks
### Must Have (Critical Path)
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
|----|------|-------------|-----------|-------------|-------------------|
### Should Have
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
|----|------|-------------|-----------|-------------|-------------------|
### Nice to Have
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
|----|------|-------------|-----------|-------------|-------------------|
## Carryover from Previous Sprint
| Task | Reason | New Estimate |
|------|--------|-------------|
## Risks
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
## Dependencies on External Factors
- [List any external dependencies]
## Definition of Done for this Sprint
- [ ] All Must Have tasks completed
- [ ] All tasks pass acceptance criteria
- [ ] No S1 or S2 bugs in delivered features
- [ ] Design documents updated for any deviations
- [ ] Code reviewed and merged
```
For `status`:
5. **Generate a status report**:
```markdown
# Sprint [N] Status -- [Date]
## Progress: [X/Y tasks complete] ([Z%])
### Completed
| Task | Completed By | Notes |
|------|-------------|-------|
### In Progress
| Task | Owner | % Done | Blockers |
|------|-------|--------|----------|
### Not Started
| Task | Owner | At Risk? | Notes |
|------|-------|----------|-------|
### Blocked
| Task | Blocker | Owner of Blocker | ETA |
|------|---------|-----------------|-----|
## Burndown Assessment
[On track / Behind / Ahead]
[If behind: What is being cut or deferred]
## Emerging Risks
- [Any new risks identified this sprint]
```
### Agent Consultation
For comprehensive sprint planning, consider consulting:
- `producer` agent for capacity planning, risk assessment, and cross-department coordination
- `game-designer` agent for feature prioritization and design readiness assessment

69
.claude/skills/team-audio/SKILL.md Normal file
View File

@@ -0,0 +1,69 @@
---
name: team-audio
description: "Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer for full audio pipeline from direction to implementation."
argument-hint: "[feature or area to design audio for]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
---
When this skill is invoked:
1. **Read the argument** for the target feature or area (e.g., `combat`,
`main menu`, `forest biome`, `boss encounter`).
2. **Gather context**:
- Read relevant design docs in `design/gdd/` for the feature
- Read the sound bible at `design/gdd/sound-bible.md` if it exists
- Read existing audio asset lists in `assets/audio/`
- Read any existing sound design docs for this area
## How to Delegate
Use the Task tool to spawn each team member as a subagent:
- `subagent_type: audio-director` — Sonic identity, emotional tone, audio palette
- `subagent_type: sound-designer` — SFX specifications, audio events, mixing groups
- `subagent_type: technical-artist` — Audio middleware, bus structure, memory budgets
- `subagent_type: gameplay-programmer` — Audio manager, gameplay triggers, adaptive music
Always provide full context in each agent's prompt (feature description, existing audio assets, design doc references).
3. **Orchestrate the audio team** in sequence:
### Step 1: Audio Direction (audio-director)
Spawn the `audio-director` agent to:
- Define the sonic identity for this feature/area
- Specify the emotional tone and audio palette
- Set music direction (adaptive layers, stems, transitions)
- Define audio priorities and mix targets
- Establish any adaptive audio rules (combat intensity, exploration, tension)
### Step 2: Sound Design (sound-designer)
Spawn the `sound-designer` agent to:
- Create detailed SFX specifications for every audio event
- Define sound categories (ambient, UI, gameplay, music, dialogue)
- Specify per-sound parameters (volume range, pitch variation, attenuation)
- Plan audio event list with trigger conditions
- Define mixing groups and ducking rules
### Step 3: Technical Implementation (technical-artist)
Spawn the `technical-artist` agent to:
- Design the audio middleware integration (Wwise/FMOD/native)
- Define audio bus structure and routing
- Specify memory budgets for audio assets per platform
- Plan streaming vs preloaded asset strategy
- Design any audio-reactive visual effects
### Step 4: Code Integration (gameplay-programmer)
Spawn the `gameplay-programmer` agent to:
- Implement audio manager system or review existing
- Wire up audio events to gameplay triggers
- Implement adaptive music system (if specified)
- Set up audio occlusion/reverb zones
- Write unit tests for audio event triggers
4. **Compile the audio design document** combining all team outputs.
5. **Save to** `design/gdd/audio-[feature].md`.
6. **Output a summary** with: audio event count, estimated asset count,
implementation tasks, and any open questions between team members.

69
.claude/skills/team-combat/SKILL.md Normal file
View File

@@ -0,0 +1,69 @@
---
name: team-combat
description: "Orchestrate the combat team: coordinates game-designer, gameplay-programmer, ai-programmer, technical-artist, sound-designer, and qa-tester to design, implement, and validate a combat feature end-to-end."
argument-hint: "[combat feature description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
---
When this skill is invoked, orchestrate the combat team through a structured pipeline.
## Team Composition
- **game-designer** — Design the mechanic, define formulas and edge cases
- **gameplay-programmer** — Implement the core gameplay code
- **ai-programmer** — Implement NPC/enemy AI behavior for the feature
- **technical-artist** — Create VFX, shader effects, and visual feedback
- **sound-designer** — Define audio events, impact sounds, and ambient combat audio
- **qa-tester** — Write test cases and validate the implementation
## How to Delegate
Use the Task tool to spawn each team member as a subagent:
- `subagent_type: game-designer` — Design the mechanic, define formulas and edge cases
- `subagent_type: gameplay-programmer` — Implement the core gameplay code
- `subagent_type: ai-programmer` — Implement NPC/enemy AI behavior
- `subagent_type: technical-artist` — Create VFX, shader effects, visual feedback
- `subagent_type: sound-designer` — Define audio events, impact sounds, ambient audio
- `subagent_type: qa-tester` — Write test cases and validate implementation
Always provide full context in each agent's prompt (design doc path, relevant code files, constraints). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 3 agents can run simultaneously).
## Pipeline
### Phase 1: Design
Delegate to **game-designer**:
- Create or update the design document in `design/gdd/` covering: mechanic overview, player fantasy, detailed rules, formulas with variable definitions, edge cases, dependencies, tuning knobs with safe ranges, and acceptance criteria
- Output: completed design document
### Phase 2: Architecture
Delegate to **gameplay-programmer** (with **ai-programmer** if AI is involved):
- Review the design document
- Design the code architecture: class structure, interfaces, data flow
- Identify integration points with existing systems
- Output: architecture sketch with file list and interface definitions
### Phase 3: Implementation (parallel where possible)
Delegate in parallel:
- **gameplay-programmer**: Implement core combat mechanic code
- **ai-programmer**: Implement AI behaviors (if the feature involves NPC reactions)
- **technical-artist**: Create VFX and shader effects
- **sound-designer**: Define audio event list and mixing notes
### Phase 4: Integration
- Wire together gameplay code, AI, VFX, and audio
- Ensure all tuning knobs are exposed and data-driven
- Verify the feature works with existing combat systems
### Phase 5: Validation
Delegate to **qa-tester**:
- Write test cases from the acceptance criteria
- Test all edge cases documented in the design
- Verify performance impact is within budget
- File bug reports for any issues found
### Phase 6: Sign-off
- Collect results from all team members
- Report feature status: COMPLETE / NEEDS WORK / BLOCKED
- List any outstanding issues and their assigned owners
## Output
A summary report covering: design completion status, implementation status per team member, test results, and any open issues.

84
.claude/skills/team-level/SKILL.md Normal file
View File

@@ -0,0 +1,84 @@
---
name: team-level
description: "Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation."
argument-hint: "[level name or area to design]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
---
When this skill is invoked:
1. **Read the argument** for the target level or area (e.g., `tutorial`,
`forest dungeon`, `hub town`, `final boss arena`).
2. **Gather context**:
- Read the game concept at `design/gdd/game-concept.md`
- Read game pillars at `design/gdd/game-pillars.md`
- Read existing level docs in `design/levels/`
- Read relevant narrative docs in `design/narrative/`
- Read world-building docs for the area's region/faction
## How to Delegate
Use the Task tool to spawn each team member as a subagent:
- `subagent_type: narrative-director` — Narrative purpose, characters, emotional arc
- `subagent_type: world-builder` — Lore context, environmental storytelling, world rules
- `subagent_type: level-designer` — Spatial layout, pacing, encounters, navigation
- `subagent_type: systems-designer` — Enemy compositions, loot tables, difficulty balance
- `subagent_type: art-director` — Visual theme, color palette, lighting, asset requirements
- `subagent_type: qa-tester` — Test cases, boundary testing, playtest checklist
Always provide full context in each agent's prompt (game concept, pillars, existing level docs, narrative docs).
3. **Orchestrate the level design team** in sequence:
### Step 1: Narrative Context (narrative-director + world-builder)
Spawn the `narrative-director` agent to:
- Define the narrative purpose of this area (what story beats happen here?)
- Identify key characters, dialogue triggers, and lore elements
- Specify emotional arc (how should the player feel entering, during, leaving?)
Spawn the `world-builder` agent to:
- Provide lore context for the area (history, faction presence, ecology)
- Define environmental storytelling opportunities
- Specify any world rules that affect gameplay in this area
### Step 2: Layout and Encounter Design (level-designer)
Spawn the `level-designer` agent to:
- Design the spatial layout (critical path, optional paths, secrets)
- Define pacing curve (tension peaks, rest areas, exploration zones)
- Place encounters with difficulty progression
- Design environmental puzzles or navigation challenges
- Define points of interest and landmarks for wayfinding
- Specify entry/exit points and connections to adjacent areas
### Step 3: Systems Integration (systems-designer)
Spawn the `systems-designer` agent to:
- Specify enemy compositions and encounter formulas
- Define loot tables and reward placement
- Balance difficulty relative to expected player level/gear
- Design any area-specific mechanics or environmental hazards
- Specify resource distribution (health pickups, save points, shops)
### Step 4: Visual Direction (art-director)
Spawn the `art-director` agent to:
- Define the visual theme and color palette for the area
- Specify lighting mood and time-of-day settings
- List required art assets (environment props, unique assets)
- Define visual landmarks and sight lines
- Specify any special VFX needs (weather, particles, fog)
### Step 5: QA Planning (qa-tester)
Spawn the `qa-tester` agent to:
- Write test cases for the critical path
- Identify boundary and edge cases (sequence breaks, softlocks)
- Create a playtest checklist for the area
- Define acceptance criteria for level completion
4. **Compile the level design document** combining all team outputs into the
level design template format.
5. **Save to** `design/levels/[level-name].md`.
6. **Output a summary** with: area overview, encounter count, estimated asset
list, narrative beats, and any cross-team dependencies or open questions.

62
.claude/skills/team-narrative/SKILL.md Normal file
View File

@@ -0,0 +1,62 @@
---
name: team-narrative
description: "Orchestrate the narrative team: coordinates narrative-director, writer, world-builder, and level-designer to create cohesive story content, world lore, and narrative-driven level design."
argument-hint: "[narrative content description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Task
---
When this skill is invoked, orchestrate the narrative team through a structured pipeline.
## Team Composition
- **narrative-director** — Story arcs, character design, dialogue strategy, narrative vision
- **writer** — Dialogue writing, lore entries, item descriptions, in-game text
- **world-builder** — World rules, faction design, history, geography, environmental storytelling
- **level-designer** — Level layouts that serve the narrative, pacing, environmental storytelling beats
## How to Delegate
Use the Task tool to spawn each team member as a subagent:
- `subagent_type: narrative-director` — Story arcs, character design, narrative vision
- `subagent_type: writer` — Dialogue writing, lore entries, in-game text
- `subagent_type: world-builder` — World rules, faction design, history, geography
- `subagent_type: level-designer` — Level layouts that serve the narrative, pacing
Always provide full context in each agent's prompt (narrative brief, lore dependencies, character profiles). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 2 agents can run simultaneously).
## Pipeline
### Phase 1: Narrative Direction
Delegate to **narrative-director**:
- Define the narrative purpose of this content: what story beat does it serve?
- Identify characters involved, their motivations, and how this fits the overall arc
- Set the emotional tone and pacing targets
- Specify any lore dependencies or new lore this introduces
- Output: narrative brief with story requirements
### Phase 2: World Foundation (parallel)
Delegate in parallel:
- **world-builder**: Create or update lore entries for factions, locations, and history relevant to this content. Cross-reference against existing lore for contradictions. Set canon level for new entries.
- **writer**: Draft character dialogue using voice profiles. Ensure all lines are under 120 characters, use named placeholders for variables, and are localization-ready.
### Phase 3: Level Narrative Integration
Delegate to **level-designer**:
- Review the narrative brief and lore foundation
- Design environmental storytelling elements in the level
- Place narrative triggers, dialogue zones, and discovery points
- Ensure pacing serves both gameplay and story
### Phase 4: Review and Consistency
Delegate to **narrative-director**:
- Review all dialogue against character voice profiles
- Verify lore consistency across new and existing entries
- Confirm narrative pacing aligns with level design
- Check that all mysteries have documented "true answers"
### Phase 5: Polish
- Writer reviews all text for localization readiness
- Verify no line exceeds dialogue box constraints
- Confirm all text uses string keys (localization pipeline ready)
- World-builder finalizes canon levels for all new lore
## Output
A summary report covering: narrative brief status, lore entries created/updated, dialogue lines written, level narrative integration points, consistency review results, and any unresolved contradictions.

76
.claude/skills/team-polish/SKILL.md Normal file
View File

@@ -0,0 +1,76 @@
---
name: team-polish
description: "Orchestrate the polish team: coordinates performance-analyst, technical-artist, sound-designer, and qa-tester to optimize, polish, and harden a feature or area for release quality."
argument-hint: "[feature or area to polish]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
---
When this skill is invoked, orchestrate the polish team through a structured pipeline.
## Team Composition
- **performance-analyst** — Profiling, optimization, memory analysis, frame budget
- **technical-artist** — VFX polish, shader optimization, visual quality
- **sound-designer** — Audio polish, mixing, ambient layers, feedback sounds
- **qa-tester** — Edge case testing, regression testing, soak testing
## How to Delegate
Use the Task tool to spawn each team member as a subagent:
- `subagent_type: performance-analyst` — Profiling, optimization, memory analysis
- `subagent_type: technical-artist` — VFX polish, shader optimization, visual quality
- `subagent_type: sound-designer` — Audio polish, mixing, ambient layers
- `subagent_type: qa-tester` — Edge case testing, regression testing, soak testing
Always provide full context in each agent's prompt (target feature/area, performance budgets, known issues). Launch independent agents in parallel where the pipeline allows it (e.g., Phases 3 and 4 can run simultaneously).
## Pipeline
### Phase 1: Assessment
Delegate to **performance-analyst**:
- Profile the target feature/area using `/perf-profile`
- Identify performance bottlenecks and frame budget violations
- Measure memory usage and check for leaks
- Benchmark against target hardware specs
- Output: performance report with prioritized optimization list
### Phase 2: Optimization
Delegate to **performance-analyst** (with relevant programmers as needed):
- Fix performance hotspots identified in Phase 1
- Optimize draw calls, reduce overdraw
- Fix memory leaks and reduce allocation pressure
- Verify optimizations don't change gameplay behavior
- Output: optimized code with before/after metrics
### Phase 3: Visual Polish (parallel with Phase 2)
Delegate to **technical-artist**:
- Review VFX for quality and consistency with art bible
- Optimize particle systems and shader effects
- Add screen shake, camera effects, and visual juice where appropriate
- Ensure effects degrade gracefully on lower settings
- Output: polished visual effects
### Phase 4: Audio Polish (parallel with Phase 2)
Delegate to **sound-designer**:
- Review audio events for completeness (are any actions missing sound feedback?)
- Check audio mix levels — nothing too loud or too quiet relative to the mix
- Add ambient audio layers for atmosphere
- Verify audio plays correctly with spatial positioning
- Output: audio polish list and mixing notes
### Phase 5: Hardening
Delegate to **qa-tester**:
- Test all edge cases: boundary conditions, rapid inputs, unusual sequences
- Soak test: run the feature for extended periods checking for degradation
- Stress test: maximum entities, worst-case scenarios
- Regression test: verify polish changes haven't broken existing functionality
- Test on minimum spec hardware (if available)
- Output: test results with any remaining issues
### Phase 6: Sign-off
- Collect results from all team members
- Compare performance metrics against budgets
- Report: READY FOR RELEASE / NEEDS MORE WORK
- List any remaining issues with severity and recommendations
## Output
A summary report covering: performance before/after metrics, visual polish changes, audio polish changes, test results, and release readiness assessment.

76
.claude/skills/team-release/SKILL.md Normal file
View File

@@ -0,0 +1,76 @@
---
name: team-release
description: "Orchestrate the release team: coordinates release-manager, qa-lead, devops-engineer, and producer to execute a release from candidate to deployment."
argument-hint: "[version number or 'next']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
---
When this skill is invoked, orchestrate the release team through a structured pipeline.
## Team Composition
- **release-manager** — Release branch, versioning, changelog, deployment
- **qa-lead** — Test sign-off, regression suite, release quality gate
- **devops-engineer** — Build pipeline, artifacts, deployment automation
- **producer** — Go/no-go decision, stakeholder communication, scheduling
## How to Delegate
Use the Task tool to spawn each team member as a subagent:
- `subagent_type: release-manager` — Release branch, versioning, changelog, deployment
- `subagent_type: qa-lead` — Test sign-off, regression suite, release quality gate
- `subagent_type: devops-engineer` — Build pipeline, artifacts, deployment automation
- `subagent_type: producer` — Go/no-go decision, stakeholder communication
Always provide full context in each agent's prompt (version number, milestone status, known issues). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 3 agents can run simultaneously).
## Pipeline
### Phase 1: Release Planning
Delegate to **producer**:
- Confirm all milestone acceptance criteria are met
- Identify any scope items deferred from this release
- Set the target release date and communicate to team
- Output: release authorization with scope confirmation
### Phase 2: Release Candidate
Delegate to **release-manager**:
- Cut release branch from the agreed commit
- Bump version numbers in all relevant files
- Generate the release checklist using `/release-checklist`
- Freeze the branch — no feature changes, bug fixes only
- Output: release branch name and checklist
### Phase 3: Quality Gate (parallel)
Delegate in parallel:
- **qa-lead**: Execute full regression test suite. Test all critical paths. Verify no S1/S2 bugs. Sign off on quality.
- **devops-engineer**: Build release artifacts for all target platforms. Verify builds are clean and reproducible. Run automated tests in CI.
### Phase 4: Localization and Performance
Delegate (can run in parallel with Phase 3 if resources available):
- Verify all strings are translated (delegate to localization-lead if available)
- Run performance benchmarks against targets (delegate to performance-analyst if available)
- Output: localization and performance sign-off
### Phase 5: Go/No-Go
Delegate to **producer**:
- Collect sign-off from: qa-lead, release-manager, devops-engineer, technical-director
- Evaluate any open issues — are they blocking or can they ship?
- Make the go/no-go call
- Output: release decision with rationale
### Phase 6: Deployment (if GO)
Delegate to **release-manager** + **devops-engineer**:
- Tag the release in version control
- Generate changelog using `/changelog`
- Deploy to staging for final smoke test
- Deploy to production
- Monitor for 48 hours post-release
### Phase 7: Post-Release
- **release-manager**: Generate release report (what shipped, what was deferred, metrics)
- **producer**: Update milestone tracking, communicate to stakeholders
- **qa-lead**: Monitor incoming bug reports for regressions
- Schedule post-release retrospective if issues occurred
## Output
A summary report covering: release version, scope, quality gate results, go/no-go decision, deployment status, and monitoring plan.

65
.claude/skills/team-ui/SKILL.md Normal file
View File

@@ -0,0 +1,65 @@
---
name: team-ui
description: "Orchestrate the UI team: coordinates ux-designer, ui-programmer, and art-director to design, implement, and polish a user interface feature from wireframe to final."
argument-hint: "[UI feature description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
---
When this skill is invoked, orchestrate the UI team through a structured pipeline.
## Team Composition
- **ux-designer** — User flows, wireframes, accessibility, input handling
- **ui-programmer** — UI framework, screens, widgets, data binding, implementation
- **art-director** — Visual style, layout polish, consistency with art bible
## How to Delegate
Use the Task tool to spawn each team member as a subagent:
- `subagent_type: ux-designer` — User flows, wireframes, accessibility, input handling
- `subagent_type: ui-programmer` — UI framework, screens, widgets, data binding
- `subagent_type: art-director` — Visual style, layout polish, art bible consistency
Always provide full context in each agent's prompt (feature requirements, existing UI patterns, platform targets). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 4 review agents can run simultaneously).
## Pipeline
### Phase 1: UX Design
Delegate to **ux-designer**:
- Define the user flow for this feature (entry points, states, exit points)
- Create wireframes for each screen/state
- Specify interaction patterns: how does keyboard/mouse AND gamepad navigate this?
- Define accessibility requirements: text sizes, contrast, colorblind safety
- Identify data the UI needs to display (what game state does it read?)
- Output: UX spec with wireframes and interaction map
### Phase 2: Visual Design
Delegate to **art-director**:
- Review wireframes against the art bible
- Define visual treatment: colors, typography, spacing, animations
- Specify asset requirements (icons, backgrounds, decorative elements)
- Ensure consistency with existing UI screens
- Output: visual design spec with style notes
### Phase 3: Implementation
Delegate to **ui-programmer**:
- Implement the UI following the UX spec and visual design
- Ensure UI NEVER owns or modifies game state — display only, events for actions
- All text through localization system — no hardcoded strings
- Support both input methods (keyboard/mouse + gamepad)
- Implement accessibility features (text scaling, colorblind mode support)
- Wire up data binding to game state
- Output: implemented UI feature
### Phase 4: Review (parallel)
Delegate in parallel:
- **ux-designer**: Verify implementation matches wireframes and interaction spec. Test keyboard-only and gamepad-only navigation. Check accessibility.
- **art-director**: Verify visual consistency with art bible. Check at minimum and maximum supported resolutions.
### Phase 5: Polish
- Address review feedback
- Verify animations are skippable and respect motion preferences
- Confirm UI sounds trigger through audio event system
- Test at all supported resolutions and aspect ratios
## Output
A summary report covering: UX spec status, visual design status, implementation status, accessibility compliance, input method support, and any outstanding issues.

70
.claude/skills/tech-debt/SKILL.md Normal file
View File

@@ -0,0 +1,70 @@
---
name: tech-debt
description: "Track, categorize, and prioritize technical debt across the codebase. Scans for debt indicators, maintains a debt register, and recommends repayment scheduling."
argument-hint: "[scan|add|prioritize|report]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
---
When this skill is invoked:
1. **Parse the subcommand** from the argument:
- `scan` — Scan the codebase for tech debt indicators
- `add` — Add a new tech debt entry manually
- `prioritize` — Re-prioritize the existing debt register
- `report` — Generate a summary report of current debt status
2. **For `scan`**:
- Search the codebase for debt indicators:
- `TODO` comments (count and categorize)
- `FIXME` comments (these are bugs disguised as debt)
- `HACK` comments (workarounds that need proper solutions)
- `@deprecated` markers
- Duplicated code blocks (similar patterns in multiple files)
- Files over 500 lines (potential god objects)
- Functions over 50 lines (potential complexity)
- Categorize each finding:
- **Architecture Debt**: Wrong abstractions, missing patterns, coupling issues
- **Code Quality Debt**: Duplication, complexity, naming, missing types
- **Test Debt**: Missing tests, flaky tests, untested edge cases
- **Documentation Debt**: Missing docs, outdated docs, undocumented APIs
- **Dependency Debt**: Outdated packages, deprecated APIs, version conflicts
- **Performance Debt**: Known slow paths, unoptimized queries, memory issues
- Update the debt register at `docs/tech-debt-register.md`
3. **For `add`**:
- Prompt for: description, category, affected files, estimated fix effort, impact if left unfixed
- Append to the debt register
4. **For `prioritize`**:
- Read the debt register
- Score each item by: `(impact_if_unfixed * frequency_of_encounter) / fix_effort`
- Re-sort the register by priority score
- Recommend which items to include in the next sprint
5. **For `report`**:
- Read the debt register
- Generate summary statistics:
- Total items by category
- Total estimated fix effort
- Items added vs resolved since last report
- Trending direction (growing / stable / shrinking)
- Flag any items that have been in the register for more than 3 sprints
- Output the report
### Debt Register Format
```markdown
## Technical Debt Register
Last updated: [Date]
Total items: [N] | Estimated total effort: [T-shirt sizes summed]
| ID | Category | Description | Files | Effort | Impact | Priority | Added | Sprint |
|----|----------|-------------|-------|--------|--------|----------|-------|--------|
| TD-001 | [Cat] | [Description] | [files] | [S/M/L/XL] | [Low/Med/High/Critical] | [Score] | [Date] | [Sprint to fix or "Backlog"] |
```
### Rules
- Tech debt is not inherently bad — it is a tool. The register tracks conscious decisions.
- Every debt entry must explain WHY it was accepted (deadline, prototype, missing info)
- "Scan" should run at least once per sprint to catch new debt
- Items older than 3 sprints without action should either be fixed or consciously accepted with a documented reason