mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-06-27 04:51:46 +00:00
Release v0.3.0: /design-system, /map-systems, status line, UPGRADING guide (#2)
* Add UPGRADING.md migration guide and link from README Covers v0.1→v0.2 upgrade with three strategies (git merge, cherry-pick, manual copy), file safety categories, and post-upgrade verification steps. Structured to support future version sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Rename /design-systems to /map-systems + /design-system and fix all references Split the monolithic /design-systems skill into two focused skills: - /map-systems: systems decomposition and index creation - /design-system: guided section-by-section GDD authoring Updated all cross-references across 14 files: README, UPGRADING, WORKFLOW-GUIDE, quick-start, skills-reference, game-concept template, systems-index template, brainstorm, design-review, gate-check, project-stage-detect, setup-engine, and start skills. Fixed skill counts from 36 to 37 everywhere. Added /map-systems and /design-system to quick-start Paths A and B workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix cross-reference gaps, broken hooks, and stale workflow chains - Fix log-agent.sh parsing agent_type instead of agent_name (always logged "unknown") - Fix GDD status lifecycle: design-system now writes Approved/Designed/In Review - Clean up settings.local.json vestigial Bash grants from development - Delete orphaned docs marked for removal in UPGRADING.md - Add /design-system to next-steps in /start, /brainstorm, /setup-engine - Fix WORKFLOW-GUIDE: add /map-systems + /design-system to Appendix C Workflow 1 - Fix invalid /map-systems map argument in WORKFLOW-GUIDE Step 2.1 - Update map-systems frontmatter to document [system-name] argument - Update commit hook to validate all 8 required GDD sections (was 5) - Update README template count 28 → 29, add 5 missing templates to quick-start Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add custom status line with 7-stage production pipeline Introduces a status line showing context %, model name, and production stage at a glance. Aligns gate-check and project-stage-detect to a unified 7-stage model (Concept → Systems Design → Technical Setup → Pre-Production → Production → Polish → Release). Stage is determined by explicit override (production/stage.txt) or auto-detected from project artifacts. Epic/Feature/Task breadcrumb appears conditionally in Production+ stages via a structured STATUS block in active.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add v0.2→v0.3 upgrade guide and PR validation test suite - UPGRADING.md: add v0.2.0→v0.3.0 section documenting breaking rename of /design-systems→/map-systems, new /design-system skill, statusline.sh, gate-check stage advancement, and safe-to-overwrite file list Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
@@ -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
|
||||
<!-- STATUS -->
|
||||
Epic: Combat System
|
||||
Feature: Melee Combat
|
||||
Task: Implement hitbox detection
|
||||
<!-- /STATUS -->
|
||||
```
|
||||
|
||||
- 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
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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 |
|
||||
|
||||
2
.claude/docs/templates/game-concept.md
vendored
2
.claude/docs/templates/game-concept.md
vendored
@@ -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`)
|
||||
|
||||
@@ -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]
|
||||
|
||||
---
|
||||
|
||||
2
.claude/docs/templates/systems-index.md
vendored
2
.claude/docs/templates/systems-index.md
vendored
@@ -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]`)
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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*)",
|
||||
|
||||
@@ -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`"
|
||||
|
||||
@@ -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.
|
||||
|
||||
496
.claude/skills/design-system/SKILL.md
Normal file
496
.claude/skills/design-system/SKILL.md
Normal file
@@ -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: "<system-name> (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 <system-name>` — 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).
|
||||
@@ -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`
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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]`
|
||||
|
||||
@@ -291,10 +291,11 @@ Agent Config: [verified]
|
||||
|
||||
Next Steps:
|
||||
1. Review docs/engine-reference/<engine>/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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
113
.claude/statusline.sh
Normal file
113
.claude/statusline.sh
Normal file
@@ -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
|
||||
*"<!-- STATUS -->"*) in_block=true; continue ;;
|
||||
*"<!-- /STATUS -->"*) 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}"
|
||||
21
README.md
21
README.md
@@ -3,14 +3,14 @@
|
||||
<p align="center">
|
||||
Turn a single Claude Code session into a full game development studio.
|
||||
<br />
|
||||
48 agents. 36 workflows. One coordinated AI team.
|
||||
48 agents. 37 workflows. One coordinated AI team.
|
||||
</p>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
|
||||
<a href=".claude/agents"><img src="https://img.shields.io/badge/agents-48-blueviolet" alt="48 Agents"></a>
|
||||
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-36-green" alt="36 Skills"></a>
|
||||
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-37-green" alt="37 Skills"></a>
|
||||
<a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-8-orange" alt="8 Hooks"></a>
|
||||
<a href=".claude/rules"><img src="https://img.shields.io/badge/rules-11-red" alt="11 Rules"></a>
|
||||
<a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/built%20for-Claude%20Code-f5f5f5?logo=anthropic" alt="Built for Claude Code"></a>
|
||||
@@ -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/
|
||||
|
||||
384
UPGRADING.md
Normal file
384
UPGRADING.md
Normal file
@@ -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-sha>
|
||||
```
|
||||
|
||||
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 `<!-- STATUS -->` 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.*
|
||||
@@ -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"
|
||||
|
||||
Reference in New Issue
Block a user