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}"
|
||||
Reference in New Issue
Block a user