diff --git a/.claude/docs/context-management.md b/.claude/docs/context-management.md index efa1c36..2734f3b 100644 --- a/.claude/docs/context-management.md +++ b/.claude/docs/context-management.md @@ -20,6 +20,24 @@ after each significant milestone: The state file should contain: current task, progress checklist, key decisions made, files being worked on, and open questions. +### Status Line Block (Production+ only) + +When the project is in Production, Polish, or Release stage, include a structured +status block in `active.md` that the status line script can parse: + +```markdown + +Epic: Combat System +Feature: Melee Combat +Task: Implement hitbox detection + +``` + +- All three fields (Epic, Feature, Task) are optional — include only what applies +- Update this block when switching focus areas +- The status line displays it as a breadcrumb: `Combat System > Melee Combat > Hitboxes` +- Remove or empty the block when no active work focus exists + After any disruption (compaction, crash, `/clear`), read the state file first. ### Incremental File Writing diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md index 3f5cbcd..0069f14 100644 --- a/.claude/docs/quick-start.md +++ b/.claude/docs/quick-start.md @@ -99,7 +99,8 @@ Ask yourself: "What department would handle this in a real studio?" | `/project-stage-detect` | Analyze project state, detect stage, identify gaps | | `/reverse-document` | Generate design/architecture docs from existing code | | `/setup-engine` | Configure engine + version, populate reference docs | -| `/design-systems` | Decompose concept into systems, map dependencies, guide per-system GDDs | +| `/map-systems` | Decompose concept into systems, map dependencies, guide per-system GDDs | +| `/design-system` | Guided, section-by-section GDD authoring for a single game system | | `/team-combat` | Orchestrate full combat team pipeline | | `/team-narrative` | Orchestrate full narrative team pipeline | | `/team-ui` | Orchestrate full UI team pipeline | @@ -136,6 +137,11 @@ Templates are in `.claude/docs/templates/`: - `pitch-document.md` -- for pitching the game to stakeholders - `economy-model.md` -- for virtual economy design (sink/faucet model) - `faction-design.md` -- for faction identity, lore, and gameplay role +- `systems-index.md` -- for systems decomposition and dependency mapping +- `project-stage-report.md` -- for project stage detection output +- `design-doc-from-implementation.md` -- for reverse-documenting existing code into GDDs +- `architecture-doc-from-code.md` -- for reverse-documenting code into architecture docs +- `concept-doc-from-prototype.md` -- for reverse-documenting prototypes into concept docs ### 5. Follow the Coordination Rules @@ -165,10 +171,13 @@ If you already know what you need, jump directly to the relevant path: - If the engine version is newer than the LLM's training data, it fetches current docs from the web so agents suggest correct APIs 3. **Validate the concept** — Run `/design-review design/gdd/game-concept.md` -4. **Test the core loop** — Run `/prototype [core-mechanic]` -5. **Playtest it** — Run `/playtest-report` to validate the hypothesis -6. **Plan the first sprint** — Run `/sprint-plan new` -7. Start building +4. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies +5. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`) + to write GDDs in dependency order +6. **Test the core loop** — Run `/prototype [core-mechanic]` +7. **Playtest it** — Run `/playtest-report` to validate the hypothesis +8. **Plan the first sprint** — Run `/sprint-plan new` +9. Start building ### Path B: "I know what I want to build" @@ -177,10 +186,12 @@ If you already have a game concept and engine choice: 1. **Set up the engine** — Run `/setup-engine [engine] [version]` (e.g., `/setup-engine godot 4.6`) — also creates technical preferences 2. **Write the Game Pillars** — delegate to `creative-director` -3. **Create the initial ADR** — Run `/architecture-decision` -4. **Create the first milestone** in `production/milestones/` -5. **Plan the first sprint** — Run `/sprint-plan new` -6. Start building +3. **Decompose into systems** — Run `/map-systems` to enumerate systems and dependencies +4. **Design each system** — Run `/design-system [system-name]` for GDDs in dependency order +5. **Create the initial ADR** — Run `/architecture-decision` +6. **Create the first milestone** in `production/milestones/` +7. **Plan the first sprint** — Run `/sprint-plan new` +8. Start building ### Path C: "I know the game but not the engine" @@ -208,7 +219,7 @@ CLAUDE.md -- Master config (read this first, ~60 lines) .claude/ settings.json -- Claude Code hooks and project settings agents/ -- 48 agent definitions (YAML frontmatter) - skills/ -- 36 slash command definitions (YAML frontmatter) + skills/ -- 37 slash command definitions (YAML frontmatter) hooks/ -- 8 hook scripts (.sh) wired by settings.json rules/ -- 11 path-specific rule files docs/ diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md index e1d03a4..89ac704 100644 --- a/.claude/docs/skills-reference.md +++ b/.claude/docs/skills-reference.md @@ -36,5 +36,6 @@ | `/patch-notes` | Generate player-facing patch notes from git history and internal data | | `/brainstorm` | Guided ideation using professional studio methods (MDA, SDT, Bartle, verb-first) | | `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/FAIL) | -| `/design-systems` | Decompose game concept into systems, map dependencies, prioritize design order, guide per-system GDDs | +| `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order, guide per-system GDDs | +| `/design-system` | Guided, section-by-section GDD authoring for a single game system with cross-referencing and incremental writing | | `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs | diff --git a/.claude/docs/templates/game-concept.md b/.claude/docs/templates/game-concept.md index 8030622..5d80cf7 100644 --- a/.claude/docs/templates/game-concept.md +++ b/.claude/docs/templates/game-concept.md @@ -309,7 +309,7 @@ the combat-crafting loop engaging for 30+ minute sessions"] - [ ] Get concept approval from creative-director - [ ] Fill in CLAUDE.md technology stack based on engine choice (`/setup-engine`) - [ ] Create game pillars document (`/design-review` to validate) -- [ ] Decompose concept into systems (`/design-systems` — maps dependencies, assigns priorities, guides per-system GDD writing) +- [ ] Decompose concept into systems (`/map-systems` — maps dependencies, assigns priorities, guides per-system GDD writing) - [ ] Create first architecture decision record (`/architecture-decision`) - [ ] Prototype core loop (`/prototype [core-mechanic]`) - [ ] Validate core loop with playtest (`/playtest-report`) diff --git a/.claude/docs/templates/project-stage-report.md b/.claude/docs/templates/project-stage-report.md index 6f812b0..c033dd6 100644 --- a/.claude/docs/templates/project-stage-report.md +++ b/.claude/docs/templates/project-stage-report.md @@ -1,7 +1,7 @@ # Project Stage Analysis Report **Generated**: [DATE] -**Stage**: [Concept | Pre-production | Production | Post-Launch] +**Stage**: [Concept | Systems Design | Technical Setup | Pre-Production | Production | Polish | Release] **Analysis Scope**: [Full project | Specific role: programmer/designer/producer] --- diff --git a/.claude/docs/templates/systems-index.md b/.claude/docs/templates/systems-index.md index 3af19fe..f6bce8c 100644 --- a/.claude/docs/templates/systems-index.md +++ b/.claude/docs/templates/systems-index.md @@ -140,7 +140,7 @@ These should be prototyped early regardless of priority tier.] ## Next Steps - [ ] Review and approve this systems enumeration -- [ ] Design MVP-tier systems first (use `/design-systems [system-name]`) +- [ ] Design MVP-tier systems first (use `/design-system [system-name]`) - [ ] Run `/design-review` on each completed GDD - [ ] Run `/gate-check pre-production` when MVP systems are designed - [ ] Prototype the highest-risk system early (`/prototype [system]`) diff --git a/.claude/hooks/log-agent.sh b/.claude/hooks/log-agent.sh index 0a22e68..a88830e 100644 --- a/.claude/hooks/log-agent.sh +++ b/.claude/hooks/log-agent.sh @@ -3,15 +3,15 @@ # Tracks which agents are being used and when # # Input schema (SubagentStart): -# { "agent_id": "agent-abc123", "agent_type": "game-designer", ... } +# { "agent_id": "agent-abc123", "agent_name": "game-designer", ... } INPUT=$(cat) -# Parse agent type -- use jq if available, fall back to grep +# Parse agent name -- use jq if available, fall back to grep if command -v jq >/dev/null 2>&1; then - AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_type // "unknown"' 2>/dev/null) + AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_name // "unknown"' 2>/dev/null) else - AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_type"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"agent_type"[[:space:]]*:[[:space:]]*"//;s/"$//') + AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_name"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"agent_name"[[:space:]]*:[[:space:]]*"//;s/"$//') [ -z "$AGENT_NAME" ] && AGENT_NAME="unknown" fi diff --git a/.claude/hooks/validate-commit.sh b/.claude/hooks/validate-commit.sh index f7e639e..530b433 100644 --- a/.claude/hooks/validate-commit.sh +++ b/.claude/hooks/validate-commit.sh @@ -33,7 +33,7 @@ DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/') if [ -n "$DESIGN_FILES" ]; then while IFS= read -r file; do if [[ "$file" == *.md ]] && [ -f "$file" ]; then - for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do + for section in "Overview" "Player Fantasy" "Detailed" "Formulas" "Edge Cases" "Dependencies" "Tuning Knobs" "Acceptance Criteria"; do if ! grep -qi "$section" "$file"; then WARNINGS="$WARNINGS\nDESIGN: $file missing required section: $section" fi diff --git a/.claude/settings.json b/.claude/settings.json index cf594c8..1c15e2d 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,5 +1,9 @@ { "$schema": "https://json.schemastore.org/claude-code-settings.json", + "statusLine": { + "type": "command", + "command": "bash .claude/statusline.sh" + }, "permissions": { "allow": [ "Bash(git status*)", diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index a910726..c75749a 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -200,7 +200,8 @@ Ground the concept in reality: - "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" - - "Decompose the concept into individual systems with `/design-systems` — maps dependencies, assigns priorities, and guides per-system GDD creation" + - "Decompose the concept into individual systems with `/map-systems` — maps dependencies, assigns priorities, and creates the systems index" + - "Author per-system GDDs with `/design-system` — guided, section-by-section GDD writing" - "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`" diff --git a/.claude/skills/design-review/SKILL.md b/.claude/skills/design-review/SKILL.md index 117a32c..1886f01 100644 --- a/.claude/skills/design-review/SKILL.md +++ b/.claude/skills/design-review/SKILL.md @@ -67,10 +67,14 @@ When this skill is invoked: - If the document being reviewed is `game-concept.md` or `game-pillars.md`: - Check if `design/gdd/systems-index.md` exists - If it does NOT exist, add to Recommendations: - > "This concept is ready for systems decomposition. Run `/design-systems` + > "This concept is ready for systems decomposition. Run `/map-systems` > to break it down into individual systems with dependencies and priorities, > then write per-system GDDs." - If the document is an individual system GDD: - Check if the systems index references this system - - If so, suggest updating its status: "Update the systems index status for - this system from 'In Design' to 'Designed'." + - If verdict is APPROVED: suggest "Update the systems index status for + this system to 'Approved'." + - If verdict is NEEDS REVISION or MAJOR REVISION NEEDED: suggest "Update + the systems index status for this system to 'In Review'." + - Note: This skill is read-only. The user (or `/design-system`) must + perform the actual status update in the systems index. diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md new file mode 100644 index 0000000..1f3b2af --- /dev/null +++ b/.claude/skills/design-system/SKILL.md @@ -0,0 +1,496 @@ +--- +name: design-system +description: "Guided, section-by-section GDD authoring for a single game system. Gathers context from existing docs, walks through each required section collaboratively, cross-references dependencies, and writes incrementally to file." +argument-hint: " (e.g., 'combat-system', 'inventory', 'dialogue')" +user-invocable: true +allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite +--- + +When this skill is invoked: + +## 1. Parse Arguments & Validate + +A system name argument is **required**. If missing, fail with: +> "Usage: `/design-system ` — e.g., `/design-system combat-system` +> Run `/map-systems` first to create the systems index, then use this skill +> to write individual system GDDs." + +Normalize the system name to kebab-case for the filename (e.g., "combat system" +becomes `combat-system`). + +--- + +## 2. Gather Context (Read Phase) + +Read all relevant context **before** asking the user anything. This is the skill's +primary advantage over ad-hoc design — it arrives informed. + +### 2a: Required Reads + +- **Game concept**: Read `design/gdd/game-concept.md` — fail if missing: + > "No game concept found. Run `/brainstorm` first." +- **Systems index**: Read `design/gdd/systems-index.md` — fail if missing: + > "No systems index found. Run `/map-systems` first to map your systems." +- **Target system**: Find the system in the index. If not listed, warn: + > "[system-name] is not in the systems index. Would you like to add it, or + > design it as an off-index system?" + +### 2b: Dependency Reads + +From the systems index, identify: +- **Upstream dependencies**: Systems this one depends on. Read their GDDs if they + exist (these contain decisions this system must respect). +- **Downstream dependents**: Systems that depend on this one. Read their GDDs if + they exist (these contain expectations this system must satisfy). + +For each dependency GDD that exists, extract and hold in context: +- Key interfaces (what data flows between the systems) +- Formulas that reference this system's outputs +- Edge cases that assume this system's behavior +- Tuning knobs that feed into this system + +### 2c: Optional Reads + +- **Game pillars**: Read `design/gdd/game-pillars.md` if it exists +- **Existing GDD**: Read `design/gdd/[system-name].md` if it exists (resume, don't + restart from scratch) +- **Related GDDs**: Glob `design/gdd/*.md` and read any that are thematically related + (e.g., if designing "status-effects", also read "combat-system" even if it's not + a direct dependency) + +### 2d: Present Context Summary + +Before starting design work, present a brief summary to the user: + +> **Designing: [System Name]** +> - Priority: [from index] | Layer: [from index] +> - Depends on: [list, noting which have GDDs vs. undesigned] +> - Depended on by: [list, noting which have GDDs vs. undesigned] +> - Existing decisions to respect: [key constraints from dependency GDDs] +> - Pillar alignment: [which pillar(s) this system primarily serves] + +If any upstream dependencies are undesigned, warn: +> "[dependency] doesn't have a GDD yet. We'll need to make assumptions about +> its interface. Consider designing it first, or we can define the expected +> contract and flag it as provisional." + +Use `AskUserQuestion`: +- "Ready to start designing [system-name]?" + - Options: "Yes, let's go", "Show me more context first", "Design a dependency first" + +--- + +## 3. Create File Skeleton + +Once the user confirms, **immediately** create the GDD file with empty section +headers. This ensures incremental writes have a target. + +Use the template structure from `.claude/docs/templates/game-design-document.md`: + +```markdown +# [System Name] + +> **Status**: In Design +> **Author**: [user + agents] +> **Last Updated**: [today's date] +> **Implements Pillar**: [from context] + +## Overview + +[To be designed] + +## Player Fantasy + +[To be designed] + +## Detailed Design + +### Core Rules + +[To be designed] + +### States and Transitions + +[To be designed] + +### Interactions with Other Systems + +[To be designed] + +## Formulas + +[To be designed] + +## Edge Cases + +[To be designed] + +## Dependencies + +[To be designed] + +## Tuning Knobs + +[To be designed] + +## Visual/Audio Requirements + +[To be designed] + +## UI Requirements + +[To be designed] + +## Acceptance Criteria + +[To be designed] + +## Open Questions + +[To be designed] +``` + +Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?" + +After writing, update `production/session-state/active.md` with: +- Task: Designing [system-name] GDD +- Current section: Starting (skeleton created) +- File: design/gdd/[system-name].md + +--- + +## 4. Section-by-Section Design + +Walk through each section in order. For **each section**, follow this cycle: + +### The Section Cycle + +``` +Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write +``` + +1. **Context**: State what this section needs to contain, and surface any relevant + decisions from dependency GDDs that constrain it. + +2. **Questions**: Ask clarifying questions specific to this section. Use + `AskUserQuestion` for constrained questions, conversational text for open-ended + exploration. + +3. **Options**: Where the section involves design choices (not just documentation), + present 2-4 approaches with pros/cons. Explain reasoning in conversation text, + then use `AskUserQuestion` to capture the decision. + +4. **Decision**: User picks an approach or provides custom direction. + +5. **Draft**: Write the section content in conversation text for review. Flag any + provisional assumptions about undesigned dependencies. + +6. **Approval**: Ask "Approve this section, or would you like changes?" + +7. **Write**: Use the Edit tool to replace the `[To be designed]` placeholder with + the approved content. Confirm the write. + +After writing each section, update `production/session-state/active.md` with the +completed section name. + +### Section-Specific Guidance + +Each section has unique design considerations and may benefit from specialist agents: + +--- + +### Section A: Overview + +**Goal**: One paragraph a stranger could read and understand. + +**Questions to ask**: +- What is this system in one sentence? +- How does a player interact with it? (active/passive/automatic) +- Why does this system exist — what would the game lose without it? + +**Cross-reference**: Check that the description aligns with how the systems index +describes it. Flag discrepancies. + +--- + +### Section B: Player Fantasy + +**Goal**: The emotional target — what the player should *feel*. + +**Questions to ask**: +- What emotion or power fantasy does this serve? +- What reference games nail this feeling? What specifically creates it? +- Is this a "system you love engaging with" or "infrastructure you don't notice"? + +**Cross-reference**: Must align with the game pillars. If the system serves a pillar, +quote the relevant pillar text. + +--- + +### Section C: Detailed Design (Core Rules, States, Interactions) + +**Goal**: Unambiguous specification a programmer could implement without questions. + +This is usually the largest section. Break it into sub-sections: + +1. **Core Rules**: The fundamental mechanics. Use numbered rules for sequential + processes, bullets for properties. +2. **States and Transitions**: If the system has states, map every state and + every valid transition. Use a table. +3. **Interactions with Other Systems**: For each dependency (upstream and downstream), + specify what data flows in, what flows out, and who owns the interface. + +**Questions to ask**: +- Walk me through a typical use of this system, step by step +- What are the decision points the player faces? +- What can the player NOT do? (Constraints are as important as capabilities) + +**Agent delegation**: For complex mechanics, use the Task tool to delegate to +`game-designer` for high-level design review, or `systems-designer` for detailed +mechanical modeling. Provide the full context gathered in Phase 2. + +**Cross-reference**: For each interaction listed, verify it matches what the +dependency GDD specifies. If the dependency says "damage is calculated as X" and +this system expects something different, flag the conflict. + +--- + +### Section D: Formulas + +**Goal**: Every mathematical formula, with variables defined, ranges specified, +and edge cases noted. + +**Questions to ask**: +- What are the core calculations this system performs? +- Should scaling be linear, logarithmic, or stepped? +- What should the output ranges be at early/mid/late game? + +**Agent delegation**: For formula-heavy systems (combat, economy, progression), +delegate to `systems-designer` via the Task tool. Provide: +- The Core Rules from Section C (already written to file) +- Tuning goals from the user +- Balance context from dependency GDDs + +The agent should return proposed formulas with variable tables and expected output +ranges. Present these to the user for review before approving. + +**Cross-reference**: If a dependency GDD defines a formula whose output feeds into +this system, reference it explicitly. Don't reinvent — connect. + +--- + +### Section E: Edge Cases + +**Goal**: Explicitly handle unusual situations so they don't become bugs. + +**Questions to ask**: +- What happens at zero? At maximum? At negative values? +- What happens when two effects trigger simultaneously? +- What happens if the player tries to exploit this? (Identify degenerate strategies) + +**Agent delegation**: For systems with complex interactions, delegate to +`systems-designer` to identify edge cases from the formula space. For narrative +systems, consult `narrative-director` for story-breaking edge cases. + +**Cross-reference**: Check edge cases against dependency GDDs. If combat says +"damage cannot go below 1" but this system can reduce damage to 0, that's a +conflict to resolve. + +--- + +### Section F: Dependencies + +**Goal**: Map every system connection with direction and nature. + +This section is partially pre-filled from the context gathering phase. Present the +known dependencies from the systems index and ask: +- Are there dependencies I'm missing? +- For each dependency, what's the specific data interface? +- Which dependencies are hard (system cannot function without it) vs. soft + (enhanced by it but works without it)? + +**Cross-reference**: This section must be bidirectionally consistent. If this system +lists "depends on Combat", then the Combat GDD should list "depended on by [this +system]". Flag any one-directional dependencies for correction. + +--- + +### Section G: Tuning Knobs + +**Goal**: Every designer-adjustable value, with safe ranges and extreme behaviors. + +**Questions to ask**: +- What values should designers be able to tweak without code changes? +- For each knob, what breaks if it's set too high? Too low? +- Which knobs interact with each other? (Changing A makes B irrelevant) + +**Agent delegation**: If formulas are complex, delegate to `systems-designer` +to derive tuning knobs from the formula variables. + +**Cross-reference**: If a dependency GDD lists tuning knobs that affect this system, +reference them here. Don't create duplicate knobs — point to the source of truth. + +--- + +### Section H: Acceptance Criteria + +**Goal**: Testable conditions that prove the system works as designed. + +**Questions to ask**: +- What's the minimum set of tests that prove this works? +- What performance budget does this system get? (frame time, memory) +- What would a QA tester check first? + +**Cross-reference**: Include criteria that verify cross-system interactions work, +not just this system in isolation. + +--- + +### Optional Sections: Visual/Audio, UI Requirements, Open Questions + +These sections are included in the template but aren't part of the 8 required +sections. Offer them after the required sections are done: + +Use `AskUserQuestion`: +- "The 8 required sections are complete. Do you want to also define Visual/Audio + requirements, UI requirements, or capture open questions?" + - Options: "Yes, all three", "Just open questions", "Skip — I'll add these later" + +For **Visual/Audio**: Coordinate with `art-director` and `audio-director` if detail +is needed. Often a brief note suffices at the GDD stage. + +For **UI Requirements**: Coordinate with `ux-designer` for complex UI systems. + +For **Open Questions**: Capture anything that came up during design that wasn't +fully resolved. Each question should have an owner and target resolution date. + +--- + +## 5. Post-Design Validation + +After all sections are written: + +### 5a: Self-Check + +Read back the complete GDD from file (not from conversation memory — the file is +the source of truth). Verify: +- All 8 required sections have real content (not placeholders) +- Formulas reference defined variables +- Edge cases have resolutions +- Dependencies are listed with interfaces +- Acceptance criteria are testable + +### 5b: Offer Design Review + +Present a completion summary: + +> **GDD Complete: [System Name]** +> - Sections written: [list] +> - Provisional assumptions: [list any assumptions about undesigned dependencies] +> - Cross-system conflicts found: [list or "none"] + +Use `AskUserQuestion`: +- "Run `/design-review` now to validate the GDD?" + - Options: "Yes, run review now", "I'll review it myself first", "Skip review" + +If yes, invoke the design-review skill on the completed file. + +### 5c: Update Systems Index + +After the GDD is complete (and optionally reviewed): + +- Read the systems index +- Update the target system's row: + - If design-review was run and verdict is APPROVED: Status → "Approved" + - If design-review was run and verdict is NEEDS REVISION: Status → "In Review" + - If design-review was skipped: Status → "Designed" (pending review) + - If the user chose "I'll review it myself first": Status → "Designed" + - Design Doc: link to `design/gdd/[system-name].md` +- Update the Progress Tracker counts + +Ask: "May I update the systems index at `design/gdd/systems-index.md`?" + +### 5d: Update Session State + +Update `production/session-state/active.md` with: +- Task: [system-name] GDD +- Status: Complete (or In Review if design-review was run) +- File: design/gdd/[system-name].md +- Sections: All 8 written +- Next: [suggest next system from design order] + +### 5e: Suggest Next Steps + +Use `AskUserQuestion`: +- "What's next?" + - Options: + - "Design next system ([next-in-order])" — if undesigned systems remain + - "Fix review findings" — if design-review flagged issues + - "Stop here for this session" + - "Run `/gate-check`" — if enough MVP systems are designed + +--- + +## 6. Specialist Agent Routing + +This skill delegates to specialist agents for domain expertise. The main session +orchestrates the overall flow; agents provide expert content. + +| System Category | Primary Agent | Supporting Agent(s) | +|----------------|---------------|---------------------| +| Combat, damage, health | `game-designer` | `systems-designer` (formulas), `ai-programmer` (enemy AI) | +| Economy, loot, crafting | `economy-designer` | `systems-designer` (curves), `game-designer` (loops) | +| Progression, XP, skills | `game-designer` | `systems-designer` (curves), `economy-designer` (sinks) | +| Dialogue, quests, lore | `game-designer` | `narrative-director` (story), `writer` (content) | +| UI systems (HUD, menus) | `game-designer` | `ux-designer` (flows), `ui-programmer` (feasibility) | +| Audio systems | `game-designer` | `audio-director` (direction), `sound-designer` (specs) | +| AI, pathfinding, behavior | `game-designer` | `ai-programmer` (implementation), `systems-designer` (scoring) | +| Level/world systems | `game-designer` | `level-designer` (spatial), `world-builder` (lore) | +| Camera, input, controls | `game-designer` | `ux-designer` (feel), `gameplay-programmer` (feasibility) | + +**When delegating via Task tool**: +- Provide: system name, game concept summary, dependency GDD excerpts, the specific + section being worked on, and what question needs expert input +- The agent returns analysis/proposals to the main session +- The main session presents the agent's output to the user via `AskUserQuestion` +- The user decides; the main session writes to file +- Agents do NOT write to files directly — the main session owns all file writes + +--- + +## 7. Recovery & Resume + +If the session is interrupted (compaction, crash, new session): + +1. Read `production/session-state/active.md` — it records the current system and + which sections are complete +2. Read `design/gdd/[system-name].md` — sections with real content are done; + sections with `[To be designed]` still need work +3. Resume from the next incomplete section — no need to re-discuss completed ones + +This is why incremental writing matters: every approved section survives any +disruption. + +--- + +## Collaborative Protocol + +This skill follows the collaborative design principle at every step: + +1. **Question -> Options -> Decision -> Draft -> Approval** for every section +2. **AskUserQuestion** at every decision point (Explain -> Capture pattern): + - Phase 2: "Ready to start, or need more context?" + - Phase 3: "May I create the skeleton?" + - Phase 4 (each section): Design questions, approach options, draft approval + - Phase 5: "Run design review? Update systems index? What's next?" +3. **"May I write to [filepath]?"** before the skeleton and before each section write +4. **Incremental writing**: Each section is written to file immediately after approval +5. **Session state updates**: After every section write +6. **Cross-referencing**: Every section checks existing GDDs for conflicts +7. **Specialist routing**: Complex sections get expert agent input, presented to + the user for decision — never written silently + +**Never** auto-generate the full GDD and present it as a fait accompli. +**Never** write a section without user approval. +**Never** contradict an existing approved GDD without flagging the conflict. +**Always** show where decisions come from (dependency GDDs, pillars, user choices). diff --git a/.claude/skills/gate-check/SKILL.md b/.claude/skills/gate-check/SKILL.md index 5629c0d..9d9d9a2 100644 --- a/.claude/skills/gate-check/SKILL.md +++ b/.claude/skills/gate-check/SKILL.md @@ -1,9 +1,9 @@ --- 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]" +argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release]" user-invocable: true -allowed-tools: Read, Glob, Grep, Bash +allowed-tools: Read, Glob, Grep, Bash, Write --- # Phase Gate Validation @@ -14,6 +14,21 @@ 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). +## Production Stages (7) + +The project progresses through these stages: + +1. **Concept** — Brainstorming, game concept document +2. **Systems Design** — Mapping systems, writing GDDs +3. **Technical Setup** — Engine config, architecture decisions +4. **Pre-Production** — Prototyping, vertical slice validation +5. **Production** — Feature development (Epic/Feature/Task tracking active) +6. **Polish** — Performance, playtesting, bug fixing +7. **Release** — Launch prep, certification + +**When a gate passes**, write the new stage name to `production/stage.txt` +(single line, e.g. `Production`). This updates the status line immediately. + --- ## 1. Parse Arguments @@ -26,13 +41,11 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict). ## 2. Phase Gate Definitions -### Gate: Concept → Pre-production +### Gate: Concept → Systems Design **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) @@ -41,25 +54,48 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict). --- -### Gate: Pre-production → Production +### Gate: Systems Design → Technical Setup **Required Artifacts:** - [ ] Systems index exists at `design/gdd/systems-index.md` with at least MVP systems enumerated - [ ] At least 1 GDD in `design/gdd/` (beyond game-concept.md and systems-index.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 +- [ ] System dependencies are mapped in the systems index +- [ ] MVP priority tier is defined + +--- + +### Gate: Technical Setup → Pre-Production + +**Required Artifacts:** +- [ ] Engine chosen (CLAUDE.md Technology Stack is not `[CHOOSE]`) +- [ ] Technical preferences configured (`.claude/docs/technical-preferences.md` populated) +- [ ] At least 1 Architecture Decision Record in `docs/architecture/` +- [ ] Engine reference docs exist in `docs/engine-reference/` + +**Quality Checks:** - [ ] Architecture decisions cover core systems (rendering, input, state management) - [ ] Technical preferences have naming conventions and performance budgets set --- -### Gate: Production → Alpha +### Gate: Pre-Production → Production + +**Required Artifacts:** +- [ ] At least 1 prototype in `prototypes/` with a README +- [ ] First sprint plan exists in `production/sprints/` +- [ ] All MVP-tier GDDs from systems index are complete + +**Quality Checks:** +- [ ] Prototype validates the core loop hypothesis +- [ ] Sprint plan references real work items from GDDs +- [ ] Vertical slice scope is defined + +--- + +### Gate: Production → Polish **Required Artifacts:** - [ ] `src/` has active code organized into subsystems @@ -76,7 +112,7 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict). --- -### Gate: Alpha → Beta +### Gate: Polish → Release **Required Artifacts:** - [ ] All features from milestone plan are implemented @@ -84,28 +120,16 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict). - [ ] 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` +- [ ] All tests passing - [ ] Performance targets met across all target platforms - [ ] No known critical, high, or medium-severity bugs +- [ ] Accessibility basics covered (remapping, text scaling if applicable) - [ ] Localization verified for all target languages - [ ] Legal requirements met (EULA, privacy policy, age ratings if applicable) - [ ] Build compiles and packages cleanly @@ -182,11 +206,28 @@ For items that can't be automatically verified, **ask the user**: --- -## 6. Follow-Up Actions +## 6. Update Stage on PASS + +When the verdict is **PASS** and the user confirms they want to advance: + +1. Write the new stage name to `production/stage.txt` (single line, no trailing newline) +2. This immediately updates the status line for all future sessions + +Example: if passing the "Pre-Production → Production" gate: +```bash +echo -n "Production" > production/stage.txt +``` + +**Always ask before writing**: "Gate passed. May I update `production/stage.txt` to 'Production'?" + +--- + +## 7. Follow-Up Actions Based on the verdict, suggest specific next steps: -- **No systems index?** → `/design-systems` to decompose the concept into systems +- **No game concept?** → `/brainstorm` to create one +- **No systems index?** → `/map-systems` to decompose the concept into systems - **Missing design docs?** → `/reverse-document` or delegate to `game-designer` - **Missing ADRs?** → `/architecture-decision` - **Tests failing?** → delegate to `lead-programmer` or `qa-tester` diff --git a/.claude/skills/design-systems/SKILL.md b/.claude/skills/map-systems/SKILL.md similarity index 71% rename from .claude/skills/design-systems/SKILL.md rename to .claude/skills/map-systems/SKILL.md index c44fe1c..d1e57e1 100644 --- a/.claude/skills/design-systems/SKILL.md +++ b/.claude/skills/map-systems/SKILL.md @@ -1,7 +1,7 @@ --- -name: design-systems -description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and guide creation of per-system GDDs." -argument-hint: "[optional: 'map' to create/update the systems index, system-name to design a specific system, or 'next' for the highest-priority undesigned system]" +name: map-systems +description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and create the systems index." +argument-hint: "[optional: 'next' to pick highest-priority undesigned system, or a system name to hand off to /design-system]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite --- @@ -10,14 +10,12 @@ When this skill is invoked: ## 1. Parse Arguments -Three modes: +Two modes: -- **No argument / `map`**: `/design-systems` or `/design-systems map` — Run the full - decomposition workflow (Phases 1-5) to create or update the systems index. -- **System name**: `/design-systems combat` — Jump directly to Phase 6 to design - a specific system's GDD. Requires the systems index to exist already. -- **`next`**: `/design-systems next` — Pick the highest-priority undesigned system - from the index and start designing it (Phase 6). +- **No argument**: `/map-systems` — Run the full decomposition workflow (Phases 1-5) + to create or update the systems index. +- **`next`**: `/map-systems next` — Pick the highest-priority undesigned system + from the index and hand off to `/design-system` (Phase 6). --- @@ -212,12 +210,12 @@ After writing, update `production/session-state/active.md` with: --- -## 7. Phase 6: Design Individual Systems (Optional, Iterative) +## 7. Phase 6: Design Individual Systems (Handoff to /design-system) This phase is entered when: - The user says "yes" to designing systems after creating the index -- The user invokes `/design-systems [system-name]` -- The user invokes `/design-systems next` +- The user invokes `/map-systems [system-name]` +- The user invokes `/map-systems next` ### Step 6a: Select the System @@ -230,70 +228,26 @@ This phase is entered when: Use `AskUserQuestion` for: "Start designing [system-name] now, pick a different system, or stop here?" -### Step 6b: Delegate to Agents +### Step 6b: Hand Off to /design-system -Use the Task tool to delegate GDD writing to the appropriate agent(s): +Once a system is selected, invoke the `/design-system [system-name]` skill. -**For most gameplay systems:** -Delegate to `game-designer` with this context in the Task prompt: -- The system name and description from the systems index -- The game concept summary (elevator pitch, pillars, core loop) -- The dependency list (what this system depends on, what depends on it) -- Any existing related GDDs (read and summarize for context) -- The GDD template to follow (`.claude/docs/templates/game-design-document.md`) -- The 8 required sections per coding standards -- Instruction to follow the collaborative protocol and use incremental file writing +The `/design-system` skill handles the full GDD authoring process: +- Gathers context from game concept, systems index, and dependency GDDs +- Creates a file skeleton immediately +- Walks through all 8 required sections one at a time (collaborative, incremental) +- Cross-references existing docs to prevent contradictions +- Routes to specialist agents for domain expertise +- Writes each section to file as soon as it's approved +- Runs `/design-review` when complete +- Updates the systems index -**For formula-heavy systems (combat, economy, progression):** -Also delegate to `systems-designer` for detailed mathematical modeling. The -`game-designer` handles the high-level design; the `systems-designer` fills in -formulas, interaction matrices, and tuning knobs. +**Do not duplicate the /design-system workflow here.** This skill owns the systems +*index*; `/design-system` owns individual system *GDDs*. -**For narrative systems (dialogue, quests, lore):** -Coordinate with `narrative-director` in addition to `game-designer`. +### Step 6c: Loop or Stop -**For UI systems:** -Coordinate with `ux-designer` in addition to `game-designer`. - -**For audio systems:** -Coordinate with `audio-director` and `sound-designer`. - -**For economy systems:** -Coordinate with `economy-designer`. - -Present the agent's output to the user for review and approval before writing. - -### Step 6c: Write the GDD - -After user approval, write the GDD to `design/gdd/[system-name].md`. -(The delegated agent handles this, following the collaborative protocol.) - -### Step 6d: Run Design Review - -After the GDD is written, run `/design-review design/gdd/[system-name].md` to -validate: -- All 8 required sections are present and complete -- Formulas are internally consistent -- Dependencies match what other GDDs expect -- Edge cases don't contradict other systems -- Rules are precise enough for a programmer to implement - -If the review finds issues: -- Present them to the user -- Fix the identified holes before proceeding to the next system -- Re-run the review after fixes to confirm resolution - -### Step 6e: Update the Systems Index - -After each GDD passes review: -- Update the system's Status in the enumeration table (Not Started -> Approved) -- Update the Design Doc path column -- Update the Progress Tracker counts -- Ask: "May I update the systems index at `design/gdd/systems-index.md`?" - -### Step 6f: Loop or Stop - -After each system, use `AskUserQuestion`: +After `/design-system` completes, use `AskUserQuestion`: - "Continue to the next system ([next system name])?" - "Pick a different system?" - "Stop here for this session?" @@ -307,13 +261,7 @@ If continuing, return to Step 6a. After the systems index is created (or after designing some systems), suggest the appropriate next actions: -- For each undesigned MVP system, recommend the right agent(s): - - Gameplay mechanics: `game-designer` + `systems-designer` - - UI systems: `game-designer` + `ux-designer` - - Audio systems: `audio-director` + `sound-designer` - - Narrative systems: `game-designer` + `narrative-director` - - Economy systems: `economy-designer` - - Level design: `level-designer` +- "Run `/design-system [system-name]` to write the next system's GDD" - "Run `/design-review [path]` on each completed GDD to validate quality" - "Run `/gate-check pre-production` to check if you're ready to start building" - "Prototype the highest-risk system with `/prototype [system]`" @@ -331,11 +279,11 @@ This skill follows the collaborative design principle at every phase: - Phase 3: "Dependency ordering correct?" - Phase 4: "Priority assignments match your vision?" - Phase 5: "May I write the systems index?" - - Phase 6: "Start designing, pick different, or stop?" + - Phase 6: "Start designing, pick different, or stop?" then hand off to `/design-system` 3. **"May I write to [filepath]?"** before every file write 4. **Incremental writing**: Update the systems index after each system is designed -5. **Design review loop**: Every completed GDD passes `/design-review` before the - next system starts — holes are caught early, not downstream +5. **Handoff**: Individual GDD authoring is owned by `/design-system`, which handles + incremental section writing, cross-referencing, design review, and index updates 6. **Session state updates**: Write to `production/session-state/active.md` after each milestone (index created, system designed, priorities changed) diff --git a/.claude/skills/project-stage-detect/SKILL.md b/.claude/skills/project-stage-detect/SKILL.md index 69676c7..dccaa3c 100644 --- a/.claude/skills/project-stage-detect/SKILL.md +++ b/.claude/skills/project-stage-detect/SKILL.md @@ -57,14 +57,19 @@ Analyze project structure and content: ### 2. Classify Project Stage -Based on scanned artifacts, determine stage: +Based on scanned artifacts, determine stage. Check `production/stage.txt` first — +if it exists, use its value (explicit override from `/gate-check`). Otherwise, +auto-detect using these heuristics (check from most-advanced backward): | 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 | +| **Concept** | No game concept doc, brainstorming phase | +| **Systems Design** | Game concept exists, systems index missing or incomplete | +| **Technical Setup** | Systems index exists, engine not configured | +| **Pre-Production** | Engine configured, `src/` has <10 source files | +| **Production** | `src/` has 10+ source files, active development | +| **Polish** | Explicit only (set by `/gate-check` Production → Polish gate) | +| **Release** | Explicit only (set by `/gate-check` Polish → Release gate) | ### 3. Collaborative Gap Identification @@ -73,7 +78,7 @@ Based on scanned artifacts, determine stage: - "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.)?" -- "I found a game concept but no systems index. Have you decomposed the concept into individual systems yet, or should we run `/design-systems`?" +- "I found a game concept but no systems index. Have you decomposed the concept into individual systems yet, or should we run `/map-systems`?" - "Prototypes directory has 3 projects with no READMEs. Were these experiments, or do they need documentation?" ### 4. Generate Stage Report @@ -85,7 +90,7 @@ Use template: `.claude/docs/templates/project-stage-report.md` # Project Stage Analysis **Date**: [date] -**Stage**: [Concept/Pre-production/Production/Post-Launch] +**Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release] ## Completeness Overview - Design: [X%] ([N] docs, [gaps]) @@ -165,7 +170,7 @@ Wait for user approval before creating the file. After generating the report, suggest relevant next steps: -- **Concept exists but no systems index?** → `/design-systems` to decompose into systems +- **Concept exists but no systems index?** → `/map-systems` to decompose into systems - **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]` diff --git a/.claude/skills/setup-engine/SKILL.md b/.claude/skills/setup-engine/SKILL.md index 559b79e..56eb5a9 100644 --- a/.claude/skills/setup-engine/SKILL.md +++ b/.claude/skills/setup-engine/SKILL.md @@ -291,10 +291,11 @@ Agent Config: [verified] Next Steps: 1. Review docs/engine-reference//VERSION.md -2. [If from /brainstorm] Run /design-systems to decompose your concept into individual systems -3. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop -4. [If fresh start] Run /brainstorm to discover your game concept -5. Create your first milestone: /sprint-plan new +2. [If from /brainstorm] Run /map-systems to decompose your concept into individual systems +3. [If from /brainstorm] Run /design-system to author per-system GDDs (guided, section-by-section) +4. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop +5. [If fresh start] Run /brainstorm to discover your game concept +6. Create your first milestone: /sprint-plan new ``` --- diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md index a284bae..58c92fb 100644 --- a/.claude/skills/start/SKILL.md +++ b/.claude/skills/start/SKILL.md @@ -77,7 +77,7 @@ technical setup — all of that comes later. 4. Show the recommended path: - `/brainstorm` — discover your game concept - `/setup-engine` — configure the engine (brainstorm will recommend one) - - `/design-systems` — decompose the concept into systems and plan GDD writing order + - `/map-systems` — decompose the concept into systems and plan GDD writing order - `/prototype` — test the core mechanic - `/sprint-plan` — plan the first sprint @@ -91,7 +91,7 @@ The user has a seed but needs help growing it into a concept. 4. Show the recommended path: - `/brainstorm [hint]` — develop the idea into a full concept - `/setup-engine` — configure the engine - - `/design-systems` — decompose the concept into systems and plan GDD writing order + - `/map-systems` — decompose the concept into systems and plan GDD writing order - `/prototype` — test the core mechanic - `/sprint-plan` — plan the first sprint @@ -111,7 +111,8 @@ The user knows what they want to make but hasn't documented it. 3. Show the recommended path (adapted to their choice): - `/brainstorm` or `/setup-engine` (their pick) - `/design-review` — validate the concept doc - - `/design-systems` — decompose the concept into individual systems with dependencies and priorities + - `/map-systems` — decompose the concept into individual systems with dependencies and priorities + - `/design-system` — author per-system GDDs (guided, section-by-section) - `/architecture-decision` — make first technical decisions - `/sprint-plan` — plan the first sprint @@ -127,6 +128,7 @@ The user has artifacts already. Figure out what exists and what's missing. 4. Show the recommended path: - `/project-stage-detect` — full gap analysis - `/setup-engine` — if not configured + - `/design-system` — if systems index exists but GDDs are incomplete - `/gate-check` — validate readiness for next phase - `/sprint-plan` — organize the work diff --git a/.claude/statusline.sh b/.claude/statusline.sh new file mode 100644 index 0000000..ef094fa --- /dev/null +++ b/.claude/statusline.sh @@ -0,0 +1,113 @@ +#!/usr/bin/env bash +# Claude Code Game Studios — Status Line +# Receives JSON on stdin, outputs a single-line status. +# +# Segments: ctx% | model | production stage [| Epic > Feature > Task] + +input=$(cat) + +# --- Parse JSON (jq with grep fallback) --- +if command -v jq &>/dev/null; then + model=$(echo "$input" | jq -r '.model.display_name // "Unknown"') + used_pct=$(echo "$input" | jq -r '.context_window.used_percentage // empty') + cwd=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // ""') +else + model=$(echo "$input" | grep -oE '"display_name"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"//') + used_pct=$(echo "$input" | grep -oE '"used_percentage"\s*:\s*[0-9]+' | head -1 | sed 's/.*: *//') + cwd=$(echo "$input" | grep -oE '"current_dir"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"//') + [ -z "$model" ] && model="Unknown" +fi + +# Normalize Windows paths +cwd=$(echo "$cwd" | sed 's|\\|/|g') +[ -z "$cwd" ] && cwd="." + +# --- Context usage --- +if [ -n "$used_pct" ]; then + ctx_label="ctx: ${used_pct}%" +else + ctx_label="ctx: --" +fi + +# --- Production stage --- +# Priority 1: Explicit stage from stage.txt +stage_file="$cwd/production/stage.txt" +stage="" +if [ -f "$stage_file" ]; then + stage=$(head -1 "$stage_file" | tr -d '\r\n') +fi + +# Priority 2: Auto-detect from artifacts +if [ -z "$stage" ]; then + concept_file="$cwd/design/gdd/game-concept.md" + systems_file="$cwd/design/gdd/systems-index.md" + tech_prefs="$cwd/.claude/docs/technical-preferences.md" + + has_concept=false + has_systems=false + engine_configured=false + src_count=0 + + [ -f "$concept_file" ] && has_concept=true + [ -f "$systems_file" ] && has_systems=true + + # Check if engine is configured (not placeholder) + if [ -f "$tech_prefs" ]; then + engine_line=$(grep -m1 '^\*\*Engine\*\*:' "$tech_prefs" 2>/dev/null || true) + if [ -n "$engine_line" ] && ! echo "$engine_line" | grep -q "TO BE CONFIGURED"; then + engine_configured=true + fi + fi + + # Count source files (language-agnostic) + if [ -d "$cwd/src" ]; then + src_count=$(find "$cwd/src" -type f \( -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.h" -o -name "*.py" -o -name "*.rs" -o -name "*.lua" -o -name "*.tscn" -o -name "*.tres" \) 2>/dev/null | wc -l | tr -d ' ') + fi + + # Determine stage (check from most-advanced backward) + if [ "$src_count" -ge 10 ] 2>/dev/null; then + stage="Production" + elif [ "$engine_configured" = true ]; then + stage="Pre-Production" + elif [ "$has_systems" = true ]; then + stage="Technical Setup" + elif [ "$has_concept" = true ]; then + stage="Systems Design" + else + stage="Concept" + fi +fi + +# --- Epic/Feature/Task breadcrumb (Production+ only) --- +breadcrumb="" +if [ "$stage" = "Production" ] || [ "$stage" = "Polish" ] || [ "$stage" = "Release" ]; then + state_file="$cwd/production/session-state/active.md" + if [ -f "$state_file" ]; then + # Parse structured STATUS block + in_block=false + epic="" feature="" task="" + while IFS= read -r line; do + case "$line" in + *""*) in_block=true; continue ;; + *""*) break ;; + esac + if [ "$in_block" = true ]; then + case "$line" in + Epic:*) epic=$(echo "$line" | sed 's/^Epic: *//') ;; + Feature:*) feature=$(echo "$line" | sed 's/^Feature: *//') ;; + Task:*) task=$(echo "$line" | sed 's/^Task: *//') ;; + esac + fi + done < "$state_file" + + # Build breadcrumb from whatever is set + parts="" + [ -n "$epic" ] && parts="$epic" + [ -n "$feature" ] && parts="${parts:+$parts > }$feature" + [ -n "$task" ] && parts="${parts:+$parts > }$task" + [ -n "$parts" ] && breadcrumb=" | $parts" + fi +fi + +# --- Assemble --- +printf "%s" "${ctx_label} | ${model} | ${stage}${breadcrumb}" diff --git a/README.md b/README.md index 8e9502e..a78c7f4 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@

Turn a single Claude Code session into a full game development studio.
- 48 agents. 36 workflows. One coordinated AI team. + 48 agents. 37 workflows. One coordinated AI team.

MIT License 48 Agents - 36 Skills + 37 Skills 8 Hooks 11 Rules Built for Claude Code @@ -35,6 +35,7 @@ The result: you still make every decision, but now you have a team that asks the - [Studio Hierarchy](#studio-hierarchy) - [Slash Commands](#slash-commands) - [Getting Started](#getting-started) +- [Upgrading](#upgrading) - [Project Structure](#project-structure) - [How It Works](#how-it-works) - [Design Philosophy](#design-philosophy) @@ -50,10 +51,10 @@ The result: you still make every decision, but now you have a team that asks the | Category | Count | Description | |----------|-------|-------------| | **Agents** | 48 | Specialized subagents across design, programming, art, audio, narrative, QA, and production | -| **Skills** | 36 | Slash commands for common workflows (`/start`, `/sprint-plan`, `/code-review`, `/brainstorm`, etc.) | +| **Skills** | 37 | Slash commands for common workflows (`/start`, `/sprint-plan`, `/code-review`, `/brainstorm`, etc.) | | **Hooks** | 8 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit, and gap detection | | **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more | -| **Templates** | 28 | Document templates for GDDs, ADRs, sprint plans, economy models, faction design, and more | +| **Templates** | 29 | Document templates for GDDs, ADRs, sprint plans, economy models, faction design, and more | ## Studio Hierarchy @@ -91,7 +92,7 @@ The template includes agent sets for all three major engines. Use the set that m ## Slash Commands -Type `/` in Claude Code to access all 36 skills: +Type `/` in Claude Code to access all 37 skills: **Reviews & Analysis** `/design-review` `/code-review` `/balance-check` `/asset-audit` `/scope-check` `/perf-profile` `/tech-debt` @@ -100,7 +101,7 @@ Type `/` in Claude Code to access all 36 skills: `/sprint-plan` `/milestone-review` `/estimate` `/retrospective` `/bug-report` **Project Management** -`/start` `/project-stage-detect` `/reverse-document` `/gate-check` `/design-systems` +`/start` `/project-stage-detect` `/reverse-document` `/gate-check` `/map-systems` `/design-system` **Release** `/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix` @@ -142,6 +143,12 @@ All hooks fail gracefully if optional tools are missing — nothing breaks, you - `/setup-engine godot 4.6` — configure your engine if you already know - `/project-stage-detect` — analyze an existing project +## Upgrading + +Already using an older version of this template? See [UPGRADING.md](UPGRADING.md) +for step-by-step migration instructions, a breakdown of what changed between +versions, and which files are safe to overwrite vs. which need a manual merge. + ## Project Structure ``` @@ -149,7 +156,7 @@ CLAUDE.md # Master configuration .claude/ settings.json # Hooks, permissions, safety rules agents/ # 48 agent definitions (markdown + YAML frontmatter) - skills/ # 36 slash commands (subdirectory per skill) + skills/ # 37 slash commands (subdirectory per skill) hooks/ # 8 hook scripts (bash, cross-platform) rules/ # 11 path-scoped coding standards docs/ diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 0000000..a2f1261 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,384 @@ +# Upgrading Claude Code Game Studios + +This guide covers upgrading your existing game project repo from one version +of the template to the next. + +**Find your current version** in your git log: +```bash +git log --oneline | grep -i "release\|setup" +``` +Or check `README.md` for the version badge. + +--- + +## Table of Contents + +- [Upgrade Strategies](#upgrade-strategies) +- [v0.2.0 → v0.3.0](#v020--v030) +- [v0.1.0 → v0.2.0](#v010--v020) + +--- + +## Upgrade Strategies + +There are three ways to pull in template updates. Choose based on how your +repo is set up. + +### Strategy A — Git Remote Merge (recommended) + +Best when: you cloned the template and have your own commits on top of it. + +```bash +# Add the template as a remote (one-time setup) +git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git + +# Fetch the new version +git fetch template main + +# Merge into your branch +git merge template/main --allow-unrelated-histories +``` + +Git will flag conflicts only in files that both the template *and* you have +changed. Resolve each one — your game content goes in, structural improvements +come along for the ride. Then commit the merge. + +**Tip:** The files most likely to conflict are `CLAUDE.md` and +`.claude/docs/technical-preferences.md`, because you've filled them in with +your engine and project settings. Keep your content; accept the structural changes. + +--- + +### Strategy B — Cherry-pick specific commits + +Best when: you only want one specific feature (e.g., just the new skill, not +the full update). + +```bash +git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git +git fetch template main + +# Cherry-pick the specific commit(s) you want +git cherry-pick +``` + +Commit SHAs for each version are listed in the version sections below. + +--- + +### Strategy C — Manual file copy + +Best when: you didn't use git to set up the template (just downloaded a zip). + +1. Download or clone the new version alongside your repo. +2. Copy the files listed under **"Safe to overwrite"** directly. +3. For files under **"Merge carefully"**, open both versions side-by-side + and manually merge the structural changes while keeping your content. + +--- + +## v0.2.0 → v0.3.0 + +**Released:** 2026-03-09 +**Commit range:** `e289ce9..HEAD` +**Key themes:** `/design-system` GDD authoring, `/map-systems` rename, custom status line + +### Breaking Changes + +#### `/design-systems` renamed to `/map-systems` + +The `/design-systems` skill was renamed to `/map-systems` for clarity +(decomposing = *mapping*, not *designing*). + +**Action required:** Update any documentation, notes, or scripts that invoke +`/design-systems`. The new invocation is `/map-systems`. + +### What Changed + +| Category | Changes | +|----------|---------| +| **New skills** | `/design-system` (guided GDD authoring, section-by-section) | +| **Renamed skills** | `/design-systems` → `/map-systems` (breaking rename) | +| **New files** | `.claude/statusline.sh`, `.claude/settings.json` statusline config | +| **Skill updates** | `/gate-check` — writes `production/stage.txt` on PASS, new phase definitions | +| **Skill updates** | `brainstorm`, `start`, `design-review`, `project-stage-detect`, `setup-engine` — cross-reference fixes | +| **Bug fixes** | `log-agent.sh`, `validate-commit.sh` — hook execution fixed | +| **Docs** | `UPGRADING.md` added, `README.md` updated, `WORKFLOW-GUIDE.md` updated | + +--- + +### Files: Safe to Overwrite + +**New files to add:** +``` +.claude/skills/design-system/SKILL.md +.claude/statusline.sh +``` + +**Existing files to overwrite (no user content):** +``` +.claude/skills/map-systems/SKILL.md ← was design-systems/SKILL.md +.claude/skills/gate-check/SKILL.md +.claude/skills/brainstorm/SKILL.md +.claude/skills/start/SKILL.md +.claude/skills/design-review/SKILL.md +.claude/skills/project-stage-detect/SKILL.md +.claude/skills/setup-engine/SKILL.md +.claude/hooks/log-agent.sh +.claude/hooks/validate-commit.sh +README.md +docs/WORKFLOW-GUIDE.md +UPGRADING.md +``` + +**Delete (replaced by rename):** +``` +.claude/skills/design-systems/ ← entire directory; replaced by map-systems/ +``` + +--- + +### Files: Merge Carefully + +#### `.claude/settings.json` + +The new version adds a `statusLine` configuration block pointing to +`.claude/statusline.sh`. If you haven't customized `settings.json`, overwriting +is safe. Otherwise, add this block manually: + +```json +"statusLine": { + "script": ".claude/statusline.sh" +} +``` + +--- + +### New Features + +#### Custom Status Line + +`.claude/statusline.sh` displays a 7-stage production pipeline breadcrumb in +the terminal status line: + +``` +ctx: 42% | claude-sonnet-4-6 | Systems Design +``` + +In Production/Polish/Release stages, it also shows the active Epic/Feature/Task +from `production/session-state/active.md` if a `` block is present: + +``` +ctx: 42% | claude-sonnet-4-6 | Production | Combat System > Melee Combat > Hitboxes +``` + +The current stage is auto-detected from project artifacts, or can be pinned by +writing a stage name to `production/stage.txt`. + +#### `/gate-check` Stage Advancement + +When a gate PASS verdict is confirmed, `/gate-check` now writes the new stage +name to `production/stage.txt`. This immediately updates the status line for all +future sessions without requiring manual file edits. + +--- + +### After Upgrading + +1. **Delete the old skill directory:** + ```bash + rm -rf .claude/skills/design-systems/ + ``` + +2. **Test the status line** by starting a Claude Code session — you should see + the stage breadcrumb in the terminal footer. + +3. **Verify hook execution** still works: + ```bash + bash .claude/hooks/log-agent.sh '{}' '{}' + bash .claude/hooks/validate-commit.sh '{}' '{}' + ``` + +--- + +## v0.1.0 → v0.2.0 + +**Released:** 2026-02-21 +**Commit range:** `ad540fe..e289ce9` +**Key themes:** Context Resilience, AskUserQuestion integration, `/map-systems` skill + +### What Changed + +| Category | Changes | +|----------|---------| +| **New skills** | `/start` (onboarding), `/map-systems` (systems decomposition), `/design-system` (guided GDD authoring) | +| **New hooks** | `session-start.sh` (recovery), `detect-gaps.sh` (gap detection) | +| **New templates** | `systems-index.md`, 3 collaborative-protocol templates | +| **Context management** | Major rewrite — file-backed state strategy added | +| **Agent updates** | 14 design/creative agents — AskUserQuestion integration | +| **Skill updates** | All 7 `team-*` skills + `brainstorm` — AskUserQuestion at phase transitions | +| **CLAUDE.md** | Slimmed from ~159 to ~60 lines; 5 doc imports instead of 10 | +| **Hook updates** | All 8 hooks — Windows compatibility fixes, new features | +| **Docs removed** | `docs/IMPROVEMENTS-PROPOSAL.md`, `docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md` | + +--- + +### Files: Safe to Overwrite + +These are pure infrastructure — you have not customized them. Copy the new +versions directly with no risk to your project content. + +**New files to add:** +``` +.claude/skills/start/SKILL.md +.claude/skills/map-systems/SKILL.md +.claude/skills/design-system/SKILL.md +.claude/docs/templates/systems-index.md +.claude/docs/templates/collaborative-protocols/design-agent-protocol.md +.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md +.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md +.claude/hooks/detect-gaps.sh +.claude/hooks/session-start.sh +production/session-state/.gitkeep +docs/examples/README.md +.github/ISSUE_TEMPLATE/bug_report.md +.github/ISSUE_TEMPLATE/feature_request.md +.github/PULL_REQUEST_TEMPLATE.md +``` + +**Existing files to overwrite (no user content):** +``` +.claude/skills/brainstorm/SKILL.md +.claude/skills/design-review/SKILL.md +.claude/skills/gate-check/SKILL.md +.claude/skills/project-stage-detect/SKILL.md +.claude/skills/setup-engine/SKILL.md +.claude/skills/team-audio/SKILL.md +.claude/skills/team-combat/SKILL.md +.claude/skills/team-level/SKILL.md +.claude/skills/team-narrative/SKILL.md +.claude/skills/team-polish/SKILL.md +.claude/skills/team-release/SKILL.md +.claude/skills/team-ui/SKILL.md +.claude/hooks/log-agent.sh +.claude/hooks/pre-compact.sh +.claude/hooks/session-stop.sh +.claude/hooks/validate-assets.sh +.claude/hooks/validate-commit.sh +.claude/hooks/validate-push.sh +.claude/rules/design-docs.md +.claude/docs/hooks-reference.md +.claude/docs/skills-reference.md +.claude/docs/quick-start.md +.claude/docs/directory-structure.md +.claude/docs/context-management.md +docs/COLLABORATIVE-DESIGN-PRINCIPLE.md +docs/WORKFLOW-GUIDE.md +README.md +``` + +**Agent files to overwrite** (if you haven't written custom prompts into them): +``` +.claude/agents/art-director.md +.claude/agents/audio-director.md +.claude/agents/creative-director.md +.claude/agents/economy-designer.md +.claude/agents/game-designer.md +.claude/agents/level-designer.md +.claude/agents/live-ops-designer.md +.claude/agents/narrative-director.md +.claude/agents/producer.md +.claude/agents/systems-designer.md +.claude/agents/technical-director.md +.claude/agents/ux-designer.md +.claude/agents/world-builder.md +.claude/agents/writer.md +``` + +If you *have* customized agent prompts, see "Merge carefully" below. + +--- + +### Files: Merge Carefully + +These files contain both template structure and your project-specific content. +Do **not** overwrite them — merge the changes manually. + +#### `CLAUDE.md` + +The template version was slimmed from ~159 lines to ~60 lines. The key +structural change: 5 doc imports were removed because they're auto-loaded +by Claude Code anyway (agent-roster, skills-reference, hooks-reference, +rules-reference, review-workflow). + +**What to keep from your version:** +- The `## Technology Stack` section (your engine/language choices) +- Any project-specific additions you made + +**What to adopt from the new version:** +- Slimmer imports list (drop the 5 redundant `@` imports if present) +- Updated collaboration protocol wording + +#### `.claude/docs/technical-preferences.md` + +If you ran `/setup-engine`, this file has your engine config, naming +conventions, and performance budgets. Keep all of it. The template version +is just the empty placeholder. + +#### `.claude/docs/templates/game-concept.md` + +Minor structural update — a `## Next Steps` section was added pointing to +`/map-systems`. Add that section to your copy if you want the updated +guidance, but it's not required. + +#### `.claude/settings.json` + +Check whether the new version adds any permission rules you want. The change +was minor (schema update). If you haven't customized your `settings.json`, +overwriting is safe. + +#### Customized agent files + +If you've added project-specific knowledge or custom behavior to any agent +`.md` file, do a diff and manually add the new AskUserQuestion integration +sections rather than overwriting. The change in each agent is a standardized +collaborative protocol block at the end of the system prompt. + +--- + +### Files: Delete + +These files were removed in v0.2.0. If present in your repo, you can safely +delete them — they're replaced by better-organized alternatives. + +``` +docs/IMPROVEMENTS-PROPOSAL.md → superseded by WORKFLOW-GUIDE.md +docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md → content merged into context-management.md +``` + +--- + +### After Upgrading + +1. **Run `/project-stage-detect`** to verify the system reads your project + correctly with the new detection logic. + +2. **Run `/start`** once if you haven't used it — it now correctly identifies + your stage and skips onboarding steps you've already done. + +3. **Check `production/session-state/`** exists and is gitignored: + ```bash + ls production/session-state/ + cat .gitignore | grep session-state + ``` + +4. **Test hook execution** — if you're on Windows, verify the new hooks run + without errors in Git Bash: + ```bash + bash .claude/hooks/detect-gaps.sh '{}' '{}' + bash .claude/hooks/session-start.sh '{}' '{}' + ``` + +--- + +*Each future version will have its own section in this file.* diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index 55927e9..85ca2ee 100644 --- a/docs/WORKFLOW-GUIDE.md +++ b/docs/WORKFLOW-GUIDE.md @@ -3,7 +3,7 @@ > **How to go from zero to a shipped game using the Agent Architecture.** > > This guide walks you through every phase of game development using the -> 48-agent system, 36 slash commands, and automated hooks. It assumes you +> 48-agent system, 37 slash commands, and automated hooks. It assumes you > have Claude Code installed and are working from the project root. --- @@ -257,7 +257,7 @@ gets coded yet -- this is pure design and architecture. Before writing individual GDDs, enumerate all the systems your game needs: ``` -/design-systems map +/map-systems ``` This creates `design/gdd/systems-index.md` — a master tracking document that: @@ -270,11 +270,18 @@ This creates `design/gdd/systems-index.md` — a master tracking document that: Then design each system in dependency order: ``` -/design-systems next +/map-systems next ``` -This picks the highest-priority undesigned system and guides you through creating -its GDD. Each completed GDD goes through `/design-review` before the next starts. +This picks the highest-priority undesigned system and hands off to `/design-system`, +which guides you through creating its GDD section by section. Each completed GDD +goes through `/design-review` before the next starts. + +You can also write a specific system's GDD directly: + +``` +/design-system combat-system +``` ### Step 2.2: Create the Game Design Document (GDD) @@ -1714,7 +1721,7 @@ conflicts go to `producer`. |-------|----------| | **Onboarding** | `/start` | | **Ideation** | `/brainstorm` | -| **Design** | `/design-systems`, `/design-review`, `/architecture-decision` | +| **Design** | `/map-systems`, `/design-system`, `/design-review`, `/architecture-decision` | | **Sprint** | `/sprint-plan`, `/estimate`, `/scope-check`, `/retrospective` | | **Implementation** | `/code-review`, `/prototype`, `/tech-debt` | | **Testing** | `/balance-check`, `/playtest-report`, `/perf-profile` | @@ -1736,7 +1743,8 @@ conflicts go to `producer`. 3. Create a game concept doc (templates/game-concept.md) 4. Define game pillars (templates/game-pillars.md) 5. /design-review on your concept doc -6. Start creating GDDs for each system +6. /map-systems to decompose concept into systems with dependencies and priorities +7. /design-system to author per-system GDDs (guided, section-by-section) ``` ### Workflow 2: "I have a design and want to start coding"