Elgato_dark/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios synced 2026-04-21 13:27:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Release v0.2.0: Context Resilience, AskUserQuestion, /design-systems

Browse source 
* Add context resilience: file-backed state, incremental writing, auto-recovery

Prevents "prompt too long" crashes from killing sessions by persisting work
to disk incrementally instead of relying on conversation memory.

Changes:
- pre-compact.sh: dumps session state before context compression
- session-start.sh: detects active.md for crash recovery
- session-stop.sh: archives and clears active.md on clean shutdown
- context-management.md: file-backed state as primary strategy
- 9 agents updated with incremental section writing protocol
  (game-designer, systems-designer, economy-designer, narrative-director,
   level-designer, world-builder, writer, art-director, audio-director)
- CLAUDE.md: trimmed redundant imports (10 → 5) to reduce token overhead
- design-docs.md rule: enforces incremental writing pattern
- .gitignore: excludes ephemeral session state files
- directory-structure.md: documents session-state/ and session-logs/
- COLLABORATIVE-DESIGN-PRINCIPLE.md: documents incremental writing pattern

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add AskUserQuestion integration across collaborative protocols

Explicitly reference the AskUserQuestion tool in all collaborative agent
definitions, protocol templates, team orchestrator skills, and the master
principle doc. Introduces the Explain-then-Capture pattern: agents write
full expert analysis in conversation, then call AskUserQuestion with
concise labels to capture decisions via structured UI.

26 files updated:
- 3 protocol templates (design, leadership, implementation)
- 14 agent definitions (10 design + 3 leadership + writer)
- 8 orchestrator skills (brainstorm + 7 team-*)
- 1 master principle doc (COLLABORATIVE-DESIGN-PRINCIPLE.md)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add /design-systems skill: concept-to-GDD decomposition workflow

Bridges the gap between game concept and per-system design documents.
Professional studios use systems enumeration + dependency sorting between
concept and feature docs — skipping this step is one of the most expensive
mistakes (systems discovered during production cost 5-10x more to add).

New files:
- .claude/skills/design-systems/SKILL.md — 7-phase orchestration skill
  (enumerate systems, map dependencies, assign priorities, write GDDs)
- .claude/docs/templates/systems-index.md — master tracking template

Flow integration (7 existing skills updated):
- brainstorm, start, setup-engine, design-review, gate-check,
  project-stage-detect, game-concept template all reference /design-systems
  at the appropriate workflow touchpoints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix cross-platform bugs, add missing tool permissions, and update docs for v0.2.0

Hooks: fix \s → [[:space:]] in grep -E fallbacks (3 files), fix detect-gaps.sh
empty-variable bug, fix log-agent.sh field name (agent_name → agent_type),
harden validate-push.sh with explicit $MATCHED_BRANCH, convert for-in loops
to while-read for space-safe iteration, add POSIX head -n syntax, increase
PreCompact timeout, widen session-stop log window.

Skills: add AskUserQuestion to 10 skills and TodoWrite to 8 multi-phase skills.
Fix project-stage-detect template/output paths, tech-artist → technical-artist.

Docs: add /design-systems to all references (README, quick-start, workflow guide,
skills-reference), update skill count 35 → 36, remove stale AI artifacts from
COLLABORATIVE-DESIGN-PRINCIPLE.md, add AskUserQuestion note to examples README.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos 2026-02-20 20:52:35 +11:00 committed by GitHub
parent 882b76f942
commit e289ce906f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
59 changed files with 1454 additions and 170 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
.claude/agents/art-director.md
View file

@ -31,14 +31,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -51,6 +56,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Art Bible Maintenance**: Create and maintain the art bible defining style,

31
.claude/agents/audio-director.md
View file

@ -31,14 +31,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -51,6 +56,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Sound Palette Definition**: Define the sonic palette for the game --

18
.claude/agents/creative-director.md
View file

@ -154,6 +154,24 @@ You: [Creates ADR, updates docs, notifies relevant agents]
- Once decided, commit fully — document and cascade the decision
- Set up success metrics — "we'll know this was right if..."
#### Structured Decision UI
Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full strategic analysis in conversation: options with
pillar alignment, downstream consequences, risk assessment, recommendation.
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
**Guidelines:**
- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
- Add "(Recommended)" to your preferred option's label
- For open-ended context gathering, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Vision Guardianship**: Maintain and communicate the game's core pillars,

31
.claude/agents/economy-designer.md
View file

@ -31,14 +31,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -51,6 +56,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Resource Flow Modeling**: Map all resource sources (faucets) and sinks in

31
.claude/agents/game-designer.md
View file

@ -33,14 +33,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -53,6 +58,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Core Loop Design**: Define and refine the moment-to-moment, session, and

31
.claude/agents/level-designer.md
View file

@ -31,14 +31,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -51,6 +56,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Level Layout Design**: Create top-down layout documents for each level/area

18
.claude/agents/live-ops-designer.md
View file

@ -48,6 +48,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
## Core Responsibilities
- Design seasonal content calendars and event cadences
- Plan battle passes, seasons, and time-limited content

31
.claude/agents/narrative-director.md
View file

@ -31,14 +31,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -51,6 +56,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Story Architecture**: Design the narrative structure -- act breaks, major

18
.claude/agents/producer.md
View file

@ -58,6 +58,24 @@ When the user asks you to make a decision or resolve a conflict:
- Once decided, commit fully — document and cascade the decision
- Set up success metrics — "we'll know this was right if..."
#### Structured Decision UI
Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full strategic analysis in conversation: options with
pillar alignment, downstream consequences, risk assessment, recommendation.
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
**Guidelines:**
- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
- Add "(Recommended)" to your preferred option's label
- For open-ended context gathering, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Sprint Planning**: Break milestones into 1-2 week sprints with clear,

31
.claude/agents/systems-designer.md
View file

@ -31,14 +31,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -51,6 +56,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Formula Design**: Create mathematical formulas for damage, healing, XP

18
.claude/agents/technical-director.md
View file

@ -57,6 +57,24 @@ When the user asks you to make a decision or resolve a conflict:
- Once decided, commit fully — document and cascade the decision
- Set up success metrics — "we'll know this was right if..."
#### Structured Decision UI
Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full strategic analysis in conversation: options with
pillar alignment, downstream consequences, risk assessment, recommendation.
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
**Guidelines:**
- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
- Add "(Recommended)" to your preferred option's label
- For open-ended context gathering, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Architecture Ownership**: Define and maintain the high-level system

18
.claude/agents/ux-designer.md
View file

@ -51,6 +51,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **User Flow Mapping**: Document every user flow in the game -- from boot to

31
.claude/agents/world-builder.md
View file

@ -31,14 +31,19 @@ Before proposing any design:
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Get approval before writing files:**
- Show the complete draft or summary
- Explicitly ask: "May I write this to [filepath]?"
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
@ -51,6 +56,24 @@ Before proposing any design:
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
examples, pillar alignment.
2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
short descriptions. User picks or types a custom answer.
**Guidelines:**
- Use at every decision point (options in step 2, clarifying questions in step 1)
- Batch up to 4 independent questions in one call
- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
- For open-ended questions or file-write confirmations, use conversation instead
- If running as a Task subagent, structure text so the orchestrator can present
options via `AskUserQuestion`
### Key Responsibilities
1. **Lore Consistency**: Maintain a lore database and cross-reference all new

34
.claude/agents/writer.md
View file

@ -30,22 +30,21 @@ Before writing any code:
- "The design doc doesn't specify [edge case]. What should happen when...?"
- "This will require changes to [other system]. Should I coordinate with that first?"
3. **Propose architecture before implementing:**
- Show class structure, file organization, data flow
- Explain WHY you're recommending this approach (patterns, engine conventions, maintainability)
- Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible"
- Ask: "Does this match your expectations? Any changes before I write the code?"
3. **Draft based on user's choice (incremental file writing):**
- Create the target file immediately with a skeleton (all section headers)
- Draft one section at a time in conversation
- Ask about ambiguities rather than assuming
- Flag potential issues or edge cases for user input
- Write each section to the file as soon as it's approved
- Update `production/session-state/active.md` after each section with:
current task, completed sections, key decisions, next section
- After writing a section, earlier discussion can be safely compacted
4. **Implement with transparency:**
- If you encounter spec ambiguities during implementation, STOP and ask
- If rules/hooks flag issues, fix them and explain what was wrong
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
5. **Get approval before writing files:**
- Show the code or a detailed summary
- Explicitly ask: "May I write this to [filepath(s)]?"
- For multi-file changes, list all affected files
4. **Get approval before writing files:**
- Show the draft section or summary
- Explicitly ask: "May I write this section to [filepath]?"
- Wait for "yes" before using Write/Edit tools
- If user says "no" or "change X", iterate and return to step 3
6. **Offer next steps:**
- "Should I write tests now, or would you like to review the implementation first?"
@ -61,6 +60,13 @@ Before writing any code:
- Rules are your friend — when they flag issues, they're usually right
- Tests prove it works — offer to write them proactively
#### Structured Decision UI
Use the `AskUserQuestion` tool for implementation choices and next-step decisions.
Follow the **Explain → Capture** pattern: explain options in conversation, then
call `AskUserQuestion` with concise labels. Batch up to 4 questions in one call.
For open-ended writing questions, use conversation instead.
### Key Responsibilities
1. **Dialogue Writing**: Write character dialogue following voice profiles

2
.claude/docs/CLAUDE-local-template.md
View file

@ -34,4 +34,4 @@ This file is gitignored and will not be committed.
1. Copy this template to your project root: `cp .claude/docs/CLAUDE-local-template.md CLAUDE.local.md`
2. Edit to match your preferences
3. Verify `.claude/CLAUDE.local.md` or `CLAUDE.local.md` is in `.gitignore`
3. Verify `CLAUDE.local.md` is in `.gitignore` (Claude Code reads it from the project root)

85
.claude/docs/context-management.md
View file

@ -1,22 +1,71 @@
# Context Management
Context is the most critical resource in a Claude Code session. Manage it actively:
Context is the most critical resource in a Claude Code session. Manage it actively.
- **Compact proactively** at ~65-70% context usage, not reactively when at the limit
## File-Backed State (Primary Strategy)
**The file is the memory, not the conversation.** Conversations are ephemeral and
will be compacted or lost. Files on disk persist across compactions and session crashes.
### Session State File
Maintain `production/session-state/active.md` as a living checkpoint. Update it
after each significant milestone:
- Design section approved and written to file
- Architecture decision made
- Implementation milestone reached
- Test results obtained
The state file should contain: current task, progress checklist, key decisions
made, files being worked on, and open questions.
After any disruption (compaction, crash, `/clear`), read the state file first.
### Incremental File Writing
When creating multi-section documents (design docs, architecture docs, lore entries):
1. Create the file immediately with a skeleton (all section headers, empty bodies)
2. Discuss and draft one section at a time in conversation
3. Write each section to the file as soon as it's approved
4. Update the session state file after each section
5. After writing a section, previous discussion about that section can be safely
compacted — the decisions are in the file
This keeps the context window holding only the *current* section's discussion
(~3-5k tokens) instead of the entire document's conversation history (~30-50k tokens).
## Proactive Compaction
- **Compact proactively** at ~60-70% context usage, not reactively at the limit
- **Use `/clear`** between unrelated tasks, or after 2+ failed correction attempts
- **Context budgets by task type**:
- Light (read/review): ~3k tokens startup
- Medium (implement feature): ~8k tokens
- Heavy (multi-system refactor): ~15k tokens
- **Preserve during compaction**: modified file list, active sprint tasks, architectural
decisions made this session, agent invocation outcomes, test results, unresolved blockers
- When delegating to subagents, provide full context in the prompt -- subagents do not
inherit conversation history unless explicitly given it
- **Natural compaction points:** after writing a section to file, after committing,
after completing a task, before starting a new topic
- **Focused compaction:** `/compact Focus on [current task] — sections 1-3 are
written to file, working on section 4`
# Compaction Instructions
## Context Budgets by Task Type
- Light (read/review): ~3k tokens startup
- Medium (implement feature): ~8k tokens
- Heavy (multi-system refactor): ~15k tokens
## Subagent Delegation
Use subagents for research and exploration to keep the main session clean.
Subagents run in their own context window and return only summaries:
- **Use subagents** when investigating across multiple files, exploring unfamiliar code,
or doing research that would consume >5k tokens of file reads
- **Use direct reads** when you know exactly which 1-2 files to check
- Subagents do not inherit conversation history — provide full context in the prompt
## Compaction Instructions
When context is compacted, preserve the following in the summary:
- Reference to `production/session-state/active.md` (read it to recover state)
- List of files modified in this session and their purpose
- Any architectural decisions made and their rationale
- Active sprint tasks and their current status
@ -24,3 +73,17 @@ When context is compacted, preserve the following in the summary:
- Test results (pass/fail counts, specific failures)
- Unresolved blockers or questions awaiting user input
- The current task and what step we are on
- Which sections of the current document are written to file vs. still in progress
**After compaction:** Read `production/session-state/active.md` and any files being
actively worked on to recover full context. The files contain the decisions; the
conversation history is secondary.
## Recovery After Session Crash
If a session dies ("prompt too long") or you start a new session to continue work:
1. The `session-start.sh` hook will detect and preview `active.md` automatically
2. Read the full state file for context
3. Read the partially-completed file(s) listed in the state
4. Continue from the next incomplete section or task

2
.claude/docs/directory-structure.md
View file

@ -13,4 +13,6 @@
├── tools/ # Build and pipeline tools (ci, build, asset-pipeline)
├── prototypes/ # Throwaway prototypes (isolated from src/)
└── production/ # Production management (sprints, milestones, releases)
├── session-state/ # Ephemeral session state (active.md — gitignored)
└── session-logs/ # Session audit trail (gitignored)
```

4
.claude/docs/hooks-reference.md
View file

@ -7,9 +7,9 @@ Hooks are configured in `.claude/settings.json` and fire automatically:
| `validate-commit.sh` | PreToolUse (Bash) | `git commit` commands | Validates design doc sections, JSON data files, hardcoded values, TODO format |
| `validate-push.sh` | PreToolUse (Bash) | `git push` commands | Warns on pushes to protected branches (develop/main) |
| `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks naming conventions and JSON validity for files in `assets/` |
| `session-start.sh` | SessionStart | Session begins | Loads current sprint context, active milestone, recent git activity |
| `session-start.sh` | SessionStart | Session begins | Loads sprint context, milestone, git activity; detects and previews active session state file for recovery |
| `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect |
| `pre-compact.sh` | PreCompact | Context compression | Logs session progress notes before context window compression |
| `pre-compact.sh` | PreCompact | Context compression | Dumps session state (active.md, modified files, WIP design docs) into conversation before compaction so it survives summarization |
| `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log |
| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail of all subagent invocations with timestamps |

2
.claude/docs/hooks-reference/post-merge-asset-validation.md
View file

@ -31,7 +31,7 @@ for file in $MERGED_ASSETS; do
filename=$(basename "$file")
# Check naming convention (lowercase with underscores)
if echo "$filename" | grep -qP '[A-Z\s-]'; then
if echo "$filename" | grep -qE '[A-Z[:space:]-]'; then
WARNINGS="$WARNINGS\nNAMING: $file -- must be lowercase with underscores"
EXIT_CODE=1
fi

4
.claude/docs/hooks-reference/pre-commit-code-quality.md
View file

@ -27,14 +27,14 @@ if [ -n "$CODE_FILES" ]; then
if [[ "$file" == src/gameplay/* ]]; then
# Look for numeric literals that are likely balance values
# Adjust the pattern for your language
if grep -nP '(?<![\w.])(?:damage|health|speed|rate|chance|cost|duration)\s*[:=]\s*\d+' "$file"; then
if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file"; then
echo "WARNING: $file may contain hardcoded gameplay values. Use data files."
# Warning only, not blocking
fi
fi
# Check for TODO/FIXME without assignee
if grep -nP '(TODO|FIXME|HACK)(?!\()' "$file"; then
if grep -nE '(TODO|FIXME|HACK)[^(]' "$file"; then
echo "WARNING: $file has TODO/FIXME without owner tag. Use TODO(name) format."
fi

10
.claude/docs/hooks-reference/pre-commit-design-check.md
View file

@ -43,7 +43,15 @@ fi
if [ -n "$DATA_FILES" ]; then
for file in $DATA_FILES; do
if [[ "$file" == *.json ]]; then
if ! python -m json.tool "$file" > /dev/null 2>&1; then
# Find a working Python command
PYTHON_CMD=""
for cmd in python python3 py; do
if command -v "$cmd" >/dev/null 2>&1; then
PYTHON_CMD="$cmd"
break
fi
done
if [ -n "$PYTHON_CMD" ] && ! "$PYTHON_CMD" -m json.tool "$file" > /dev/null 2>&1; then
echo "ERROR: $file is not valid JSON"
EXIT_CODE=1
fi

3
.claude/docs/quick-start.md
View file

@ -99,6 +99,7 @@ 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 |
| `/team-combat` | Orchestrate full combat team pipeline |
| `/team-narrative` | Orchestrate full narrative team pipeline |
| `/team-ui` | Orchestrate full UI team pipeline |
@ -207,7 +208,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/ -- 35 slash command definitions (YAML frontmatter)
skills/ -- 36 slash command definitions (YAML frontmatter)
hooks/ -- 8 hook scripts (.sh) wired by settings.json
rules/ -- 11 path-specific rule files
docs/

5
.claude/docs/skills-reference.md
View file

@ -25,15 +25,16 @@
| `/perf-profile` | Structured performance profiling with bottleneck identification and recommendations |
| `/project-stage-detect` | Automatically analyze project state, detect stage, identify gaps, and recommend next steps |
| `/reverse-document` | Generate design or architecture documents from existing implementation (works backwards from code) |
| `/team-combat` | Orchestrate combat team: game-designer + gameplay-programmer + ai-programmer + tech-artist + sound-designer + qa-tester |
| `/team-combat` | Orchestrate combat team: game-designer + gameplay-programmer + ai-programmer + technical-artist + sound-designer + qa-tester |
| `/team-narrative` | Orchestrate narrative team: narrative-director + writer + world-builder + level-designer |
| `/team-ui` | Orchestrate UI team: ux-designer + ui-programmer + art-director |
| `/team-release` | Orchestrate release team: release-manager + qa-lead + devops-engineer + producer |
| `/team-polish` | Orchestrate polish team: performance-analyst + tech-artist + sound-designer + qa-tester |
| `/team-polish` | Orchestrate polish team: performance-analyst + technical-artist + sound-designer + qa-tester |
| `/team-audio` | Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer |
| `/team-level` | Orchestrate level team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester |
| `/launch-checklist` | Complete launch readiness validation across all departments |
| `/patch-notes` | Generate player-facing patch notes from git history and internal data |
| `/brainstorm` | Guided ideation using professional studio methods (MDA, SDT, Bartle, verb-first) |
| `/gate-check` | Validate readiness to advance between development phases (PASS/CONCERNS/FAIL) |
| `/design-systems` | Decompose game concept into systems, map dependencies, prioritize design order, guide per-system GDDs |
| `/setup-engine` | Configure engine + version, detect knowledge gaps, populate version-aware reference docs |

52
.claude/docs/templates/collaborative-protocols/design-agent-protocol.md vendored
View file

@ -16,12 +16,14 @@ Before proposing any design:
- What are the constraints (scope, complexity, existing systems)?
- Any reference games or mechanics the user loves/hates?
- How does this connect to the game's pillars?
- *Use `AskUserQuestion` to batch up to 4 constrained questions at once*
2. **Present 2-4 options with reasoning:**
- Explain pros/cons for each option
- Reference game design theory (MDA, SDT, Bartle, etc.)
- Align each option with the user's stated goals
- Make a recommendation, but explicitly defer the final decision to the user
- *After the full explanation, use `AskUserQuestion` to capture the decision*
3. **Draft based on user's choice:**
- Create sections iteratively (show one section, get feedback, refine)
@ -102,4 +104,54 @@ You: [uses Write tool]
- Explain WHY you recommend something (theory, examples, pillar alignment)
- Iterate based on feedback without defensiveness
- Celebrate when the user's modifications improve your suggestion
#### Structured Decision UI
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
plain text. Follow the **Explain → Capture** pattern:
1. **Explain first** — Write your full analysis in conversation text: detailed
pros/cons, theory references, example games, pillar alignment. This is where
the expert reasoning lives — don't try to fit it into the tool.
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels
and short descriptions. The user picks from the UI or types a custom answer.
**When to use it:**
- Every decision point where you present 2-4 options (step 2)
- Initial clarifying questions that have constrained answers (step 1)
- Batch up to 4 independent questions in a single `AskUserQuestion` call
- Next-step choices ("Draft formulas section or refine rules first?")
**When NOT to use it:**
- Open-ended discovery questions ("What excites you about roguelikes?")
- Single yes/no confirmations ("May I write to file?")
- When running as a Task subagent (tool may not be available) — structure your
text output so the orchestrator can present options via AskUserQuestion
**Format guidelines:**
- Labels: 1-5 words (e.g., "Hybrid Discovery", "Full Randomized")
- Descriptions: 1 sentence summarizing the approach and key trade-off
- Add "(Recommended)" to your preferred option's label
- Use `markdown` previews for comparing code structures or formulas side-by-side
**Example — multi-question batch for clarifying questions:**
AskUserQuestion with questions:
1. question: "Should crafting recipes be discovered or learned?"
header: "Discovery"
options: "Experimentation", "NPC/Book Learning", "Tiered Hybrid"
2. question: "How punishing should failed crafts be?"
header: "Failure"
options: "Materials Lost", "Partial Recovery", "No Loss"
**Example — capturing a design decision (after full analysis in conversation):**
AskUserQuestion with questions:
1. question: "Which crafting approach fits your vision?"
header: "Approach"
options:
"Hybrid Discovery (Recommended)" — balances exploration and accessibility
"Full Discovery" — maximum mystery, risk of frustration
"Hint System" — accessible but less surprise
```

30
.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md vendored
View file

@ -21,6 +21,7 @@ Before writing any code:
- "Where should [data] live? (CharacterStats? Equipment class? Config file?)"
- "The design doc doesn't specify [edge case]. What should happen when...?"
- "This will require changes to [other system]. Should I coordinate with that first?"
- *Use `AskUserQuestion` to batch constrained architecture questions*
3. **Propose architecture before implementing:**
- Show class structure, file organization, data flow
@ -119,4 +120,33 @@ You: [creates tests/combat/test_damage_calculator.gd]
- Flag deviations from design docs explicitly — designer should know if implementation differs
- Rules are your friend — when they flag issues, they're usually right
- Tests prove it works — offer to write them proactively
#### Structured Decision UI
Use the `AskUserQuestion` tool for architecture decisions and next-step choices.
Follow the **Explain → Capture** pattern:
1. **Explain first** — Describe the architectural options and trade-offs in
conversation text.
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
**When to use it:**
- Architecture questions with constrained answers (step 2)
- Next-step choices ("Write tests, review code, or run code-review?")
- Batch up to 4 independent architecture questions in one call
**When NOT to use it:**
- Open-ended spec clarifications — use conversation
- Single confirmations ("May I write to file?")
- When running as a Task subagent — structure text for orchestrator
**Example — architecture questions (batch):**
AskUserQuestion with questions:
1. question: "Where should DamageCalculator live?"
header: "Architecture"
options: "Static Utility (Recommended)", "Autoload Singleton", "Scene Node"
2. question: "How should damage be rounded?"
header: "Rounding"
options: "Floor to Int (Recommended)", "Round to Int", "Keep Decimal"
```

37
.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md vendored
View file

@ -15,6 +15,7 @@ When the user asks you to make a decision or resolve a conflict:
- Ask questions to understand all perspectives
- Review relevant docs (pillars, constraints, prior decisions)
- Identify what's truly at stake (often deeper than the surface question)
- *Use `AskUserQuestion` to batch up to 4 constrained questions at once*
2. **Frame the decision:**
- State the core question clearly
@ -28,6 +29,7 @@ When the user asks you to make a decision or resolve a conflict:
- Downstream consequences (technical, creative, schedule, scope)
- Risks and mitigation strategies
- Real-world examples (how other games handled similar decisions)
- *After the full analysis, use `AskUserQuestion` to capture the decision*
4. **Make a clear recommendation:**
- "I recommend Option [X] because..."
@ -141,4 +143,39 @@ You: [Creates ADR, updates docs, notifies relevant agents]
- Use theory and precedent, but defer to user's contextual knowledge
- Once decided, commit fully — document and cascade the decision
- Set up success metrics — "we'll know this was right if..."
#### Structured Decision UI
Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
Follow the **Explain → Capture** pattern:
1. **Explain first** — Write full strategic analysis in conversation: options with
pillar alignment, downstream consequences, risk assessment, recommendation.
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
**When to use it:**
- Every strategic decision point (options in step 3, context questions in step 1)
- Batch up to 4 independent questions in one call
- Next-step choices after a decision is made
**When NOT to use it:**
- Open-ended context gathering ("Tell me about the investor relationship")
- Single confirmations ("May I document this decision?")
- When running as a Task subagent — structure text for orchestrator
**Format guidelines:**
- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
- Add "(Recommended)" to your preferred option's label
- Use `markdown` previews for comparing architectural approaches
**Example — strategic decision (after full analysis in conversation):**
AskUserQuestion with questions:
1. question: "How should we handle crafting scope for Alpha?"
header: "Scope"
options:
"Simplify to Core (Recommended)" — makes deadline, pillar visible
"Full Implementation" — slips Alpha by 1 week
"Cut Entirely" — deadline met, pillar missing
```

3
.claude/docs/templates/game-concept.md vendored
View file

@ -307,8 +307,9 @@ the combat-crafting loop engaging for 30+ minute sessions"]
## Next Steps
- [ ] Get concept approval from creative-director
- [ ] Fill in CLAUDE.md technology stack based on engine choice
- [ ] 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)
- [ ] Create first architecture decision record (`/architecture-decision`)
- [ ] Prototype core loop (`/prototype [core-mechanic]`)
- [ ] Validate core loop with playtest (`/playtest-report`)

146
.claude/docs/templates/systems-index.md vendored Normal file
View file

@ -0,0 +1,146 @@
# Systems Index: [Game Title]
> **Status**: [Draft / Under Review / Approved]
> **Created**: [Date]
> **Last Updated**: [Date]
> **Source Concept**: design/gdd/game-concept.md
---
## Overview
[One paragraph explaining the game's mechanical scope. What kind of systems does
this game need? Reference the core loop and game pillars. This should help any
team member understand the "big picture" of what needs to be designed and built.]
---
## Systems Enumeration
| # | System Name | Category | Priority | Status | Design Doc | Depends On |
|---|-------------|----------|----------|--------|------------|------------|
| 1 | [e.g., Player Controller] | Core | MVP | [Not Started / In Design / In Review / Approved / Implemented] | [design/gdd/player-controller.md or "—"] | [e.g., Input System, Physics] |
| 2 | [e.g., Camera System] | Core | MVP | Not Started | — | Player Controller |
[Add a row for every identified system. Use the categories and priority tiers
defined below. Mark systems that were inferred (not explicitly in the concept doc)
with "(inferred)" in the system name.]
---
## Categories
| Category | Description | Typical Systems |
|----------|-------------|-----------------|
| **Core** | Foundation systems everything depends on | Player controller, input, physics, camera, scene management, state machine |
| **Gameplay** | The systems that make the game fun | Combat, AI, stealth, movement abilities, interaction |
| **Progression** | How the player grows over time | XP/leveling, skill trees, unlocks, achievements, reputation |
| **Economy** | Resource creation and consumption | Currency, loot, crafting, shops, item database, drop tables |
| **Persistence** | Save state and continuity | Save/load, settings, cloud sync, profile management |
| **UI** | Player-facing information displays | HUD, menus, inventory screen, dialogue UI, map, notifications |
| **Audio** | Sound and music systems | Music manager, SFX bus, ambient audio, adaptive music, voice |
| **Narrative** | Story and dialogue delivery | Dialogue system, quest tracking, cutscenes, journal, lore entries |
| **Meta** | Systems outside the core game loop | Analytics, tutorials/onboarding, accessibility options, photo mode |
[Not every game needs every category. Remove categories that don't apply.
Add custom categories if needed.]
---
## Priority Tiers
| Tier | Definition | Target Milestone | Design Urgency |
|------|------------|------------------|----------------|
| **MVP** | Required for the core loop to function. Without these, you can't test "is this fun?" | First playable prototype | Design FIRST |
| **Vertical Slice** | Required for one complete, polished area. Demonstrates the full experience. | Vertical slice / demo | Design SECOND |
| **Alpha** | All features present in rough form. Complete mechanical scope, placeholder content OK. | Alpha milestone | Design THIRD |
| **Full Vision** | Polish, edge cases, nice-to-haves, and content-complete features. | Beta / Release | Design as needed |
---
## Dependency Map
[Systems sorted by dependency order — design and build from top to bottom.
Systems at the top are foundations; systems at the bottom are wrappers.]
### Foundation Layer (no dependencies)
1. [System] — [one-line rationale for why this is foundational]
### Core Layer (depends on foundation)
1. [System] — depends on: [list]
### Feature Layer (depends on core)
1. [System] — depends on: [list]
### Presentation Layer (depends on features)
1. [System] — depends on: [list]
### Polish Layer (depends on everything)
1. [System] — depends on: [list]
---
## Recommended Design Order
[Combining dependency sort and priority tiers. Design these systems in this
order. Each system's GDD should be completed and reviewed before starting the
next, though independent systems at the same layer can be designed in parallel.]
| Order | System | Priority | Layer | Agent(s) | Est. Effort |
|-------|--------|----------|-------|----------|-------------|
| 1 | [First system to design] | MVP | Foundation | game-designer | [S/M/L] |
| 2 | [Second system] | MVP | Foundation | game-designer | [S/M/L] |
[Effort estimates: S = 1 session, M = 2-3 sessions, L = 4+ sessions.
A "session" is one focused design conversation producing a complete GDD.]
---
## Circular Dependencies
[List any circular dependency chains found during analysis. These require
special architectural attention — either break the cycle with an interface,
or design the systems simultaneously.]
- [None found] OR
- [System A <-> System B: Description of the circular relationship and
proposed resolution]
---
## High-Risk Systems
[Systems that are technically unproven, design-uncertain, or scope-dangerous.
These should be prototyped early regardless of priority tier.]
| System | Risk Type | Risk Description | Mitigation |
|--------|-----------|-----------------|------------|
| [System] | [Technical / Design / Scope] | [What could go wrong] | [Prototype, research, or scope fallback] |
---
## Progress Tracker
| Metric | Count |
|--------|-------|
| Total systems identified | [N] |
| Design docs started | [N] |
| Design docs reviewed | [N] |
| Design docs approved | [N] |
| MVP systems designed | [N/total MVP] |
| Vertical Slice systems designed | [N/total VS] |
---
## Next Steps
- [ ] Review and approve this systems enumeration
- [ ] Design MVP-tier systems first (use `/design-systems [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]`)

4
.claude/hooks/detect-gaps.sh
View file

@ -15,7 +15,7 @@ FRESH_PROJECT=true
# Check if engine is configured
if [ -f ".claude/docs/technical-preferences.md" ]; then
ENGINE_LINE=$(grep -E "^\- \*\*Engine\*\*:" .claude/docs/technical-preferences.md 2>/dev/null)
if echo "$ENGINE_LINE" | grep -qv "TO BE CONFIGURED" 2>/dev/null; then
if [ -n "$ENGINE_LINE" ] && ! echo "$ENGINE_LINE" | grep -q "TO BE CONFIGURED" 2>/dev/null; then
FRESH_PROJECT=false
fi
fi
@ -151,3 +151,5 @@ fi
echo ""
echo "💡 To get a comprehensive project analysis, run: /project-stage-detect"
echo "==================================="
exit 0

8
.claude/hooks/log-agent.sh
View file

@ -3,15 +3,15 @@
# Tracks which agents are being used and when
#
# Input schema (SubagentStart):
# { "agent_name": "game-designer", "model": "sonnet", ... }
# { "agent_id": "agent-abc123", "agent_type": "game-designer", ... }
INPUT=$(cat)
# Parse agent name -- use jq if available, fall back to grep
# Parse agent type -- use jq if available, fall back to grep
if command -v jq >/dev/null 2>&1; then
AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_name // "unknown"' 2>/dev/null)
AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_type // "unknown"' 2>/dev/null)
else
AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_name"\s*:\s*"[^"]*"' | sed 's/"agent_name"\s*:\s*"//;s/"$//')
AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_type"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"agent_type"[[:space:]]*:[[:space:]]*"//;s/"$//')
[ -z "$AGENT_NAME" ] && AGENT_NAME="unknown"
fi

83
.claude/hooks/pre-compact.sh
View file

@ -1,15 +1,82 @@
#!/bin/bash
# Claude Code PreCompact hook: Save session state before context compression
# Ensures progress notes survive context window compression
# Claude Code PreCompact hook: Dump session state before context compression
# This output appears in the conversation right before compaction, ensuring
# critical state survives the summarization process.
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
echo "=== SESSION STATE BEFORE COMPACTION ==="
echo "Timestamp: $(date)"
# --- Active session state file ---
STATE_FILE="production/session-state/active.md"
if [ -f "$STATE_FILE" ]; then
echo ""
echo "## Active Session State (from $STATE_FILE)"
STATE_LINES=$(wc -l < "$STATE_FILE" 2>/dev/null | tr -d ' ')
if [ "$STATE_LINES" -gt 100 ] 2>/dev/null; then
head -n 100 "$STATE_FILE"
echo "... (truncated — $STATE_LINES total lines, showing first 100)"
else
cat "$STATE_FILE"
fi
else
echo ""
echo "## No active session state file found"
echo "Consider maintaining production/session-state/active.md for better recovery."
fi
# --- Files modified this session (unstaged + staged + untracked) ---
echo ""
echo "## Files Modified (git working tree)"
CHANGED=$(git diff --name-only 2>/dev/null)
STAGED=$(git diff --staged --name-only 2>/dev/null)
UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null)
if [ -n "$CHANGED" ]; then
echo "Unstaged changes:"
echo "$CHANGED" | while read -r f; do echo " - $f"; done
fi
if [ -n "$STAGED" ]; then
echo "Staged changes:"
echo "$STAGED" | while read -r f; do echo " - $f"; done
fi
if [ -n "$UNTRACKED" ]; then
echo "New untracked files:"
echo "$UNTRACKED" | while read -r f; do echo " - $f"; done
fi
if [ -z "$CHANGED" ] && [ -z "$STAGED" ] && [ -z "$UNTRACKED" ]; then
echo " (no uncommitted changes)"
fi
# --- Work-in-progress design docs ---
echo ""
echo "## Design Docs — Work In Progress"
WIP_FOUND=false
for f in design/gdd/*.md; do
[ -f "$f" ] || continue
INCOMPLETE=$(grep -n -E "TODO|WIP|PLACEHOLDER|\[TO BE|\[TBD\]" "$f" 2>/dev/null)
if [ -n "$INCOMPLETE" ]; then
WIP_FOUND=true
echo " $f:"
echo "$INCOMPLETE" | while read -r line; do echo " $line"; done
fi
done
if [ "$WIP_FOUND" = false ]; then
echo " (no WIP markers found in design docs)"
fi
# --- Log compaction event ---
SESSION_LOG_DIR="production/session-logs"
# Create session log directory if it doesn't exist
mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
# Save a marker file noting that compaction occurred
echo "Context compaction occurred at $(date). Session state may have been compressed." \
echo "Context compaction occurred at $(date)." \
>> "$SESSION_LOG_DIR/compaction-log.txt" 2>/dev/null
echo ""
echo "## Recovery Instructions"
echo "After compaction, read $STATE_FILE to recover full working context."
echo "Then read any files listed above that are being actively worked on."
echo "=== END SESSION STATE ==="
exit 0

17
.claude/hooks/session-start.sh
View file

@ -54,5 +54,22 @@ if [ -d "src" ]; then
fi
fi
# --- Active session state recovery ---
STATE_FILE="production/session-state/active.md"
if [ -f "$STATE_FILE" ]; then
echo ""
echo "=== ACTIVE SESSION STATE DETECTED ==="
echo "A previous session left state at: $STATE_FILE"
echo "Read this file to recover context and continue where you left off."
echo ""
echo "Quick summary:"
head -20 "$STATE_FILE" 2>/dev/null
TOTAL_LINES=$(wc -l < "$STATE_FILE" 2>/dev/null)
if [ "$TOTAL_LINES" -gt 20 ]; then
echo " ... ($TOTAL_LINES total lines — read the full file to continue)"
fi
echo "=== END SESSION STATE PREVIEW ==="
fi
echo "==================================="
exit 0

17
.claude/hooks/session-stop.sh
View file

@ -7,10 +7,23 @@ SESSION_LOG_DIR="production/session-logs"
mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
# Log recent git activity from this session
RECENT_COMMITS=$(git log --oneline --since="1 hour ago" 2>/dev/null)
# Log recent git activity from this session (check up to 8 hours for long sessions)
RECENT_COMMITS=$(git log --oneline --since="8 hours ago" 2>/dev/null)
MODIFIED_FILES=$(git diff --name-only 2>/dev/null)
# --- Clean up active session state on normal shutdown ---
STATE_FILE="production/session-state/active.md"
if [ -f "$STATE_FILE" ]; then
# Archive to session log before removing
{
echo "## Archived Session State: $TIMESTAMP"
cat "$STATE_FILE"
echo "---"
echo ""
} >> "$SESSION_LOG_DIR/session-log.md" 2>/dev/null
rm "$STATE_FILE" 2>/dev/null
fi
if [ -n "$RECENT_COMMITS" ] || [ -n "$MODIFIED_FILES" ]; then
{
echo "## Session End: $TIMESTAMP"

2
.claude/hooks/validate-assets.sh
View file

@ -12,7 +12,7 @@ INPUT=$(cat)
if command -v jq >/dev/null 2>&1; then
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
else
FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"\s*:\s*"[^"]*"' | sed 's/"file_path"\s*:\s*"//;s/"$//')
FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
fi
# Normalize path separators (Windows backslash to forward slash)

18
.claude/hooks/validate-commit.sh
View file

@ -12,7 +12,7 @@ INPUT=$(cat)
if command -v jq >/dev/null 2>&1; then
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
else
COMMAND=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | sed 's/"command"\s*:\s*"//;s/"$//')
COMMAND=$(echo "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
fi
# Only process git commit commands
@ -31,7 +31,7 @@ WARNINGS=""
# Check design documents for required sections
DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/')
if [ -n "$DESIGN_FILES" ]; then
for file in $DESIGN_FILES; do
while IFS= read -r file; do
if [[ "$file" == *.md ]] && [ -f "$file" ]; then
for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do
if ! grep -qi "$section" "$file"; then
@ -39,7 +39,7 @@ if [ -n "$DESIGN_FILES" ]; then
fi
done
fi
done
done <<< "$DESIGN_FILES"
fi
# Validate JSON data files -- block invalid JSON
@ -54,7 +54,7 @@ if [ -n "$DATA_FILES" ]; then
fi
done
for file in $DATA_FILES; do
while IFS= read -r file; do
if [ -f "$file" ]; then
if [ -n "$PYTHON_CMD" ]; then
if ! "$PYTHON_CMD" -m json.tool "$file" > /dev/null 2>&1; then
@ -65,32 +65,32 @@ if [ -n "$DATA_FILES" ]; then
echo "WARNING: Cannot validate JSON (python not found): $file" >&2
fi
fi
done
done <<< "$DATA_FILES"
fi
# Check for hardcoded gameplay values in gameplay code
# Uses grep -E (POSIX extended) instead of grep -P (Perl) for cross-platform compatibility
CODE_FILES=$(echo "$STAGED" | grep -E '^src/gameplay/')
if [ -n "$CODE_FILES" ]; then
for file in $CODE_FILES; do
while IFS= read -r file; do
if [ -f "$file" ]; then
if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file" 2>/dev/null; then
WARNINGS="$WARNINGS\nCODE: $file may contain hardcoded gameplay values. Use data files."
fi
fi
done
done <<< "$CODE_FILES"
fi
# Check for TODO/FIXME without assignee -- uses grep -E instead of grep -P
SRC_FILES=$(echo "$STAGED" | grep -E '^src/')
if [ -n "$SRC_FILES" ]; then
for file in $SRC_FILES; do
while IFS= read -r file; do
if [ -f "$file" ]; then
if grep -nE '(TODO|FIXME|HACK)[^(]' "$file" 2>/dev/null; then
WARNINGS="$WARNINGS\nSTYLE: $file has TODO/FIXME without owner tag. Use TODO(name) format."
fi
fi
done
done <<< "$SRC_FILES"
fi
# Print warnings (non-blocking) and allow commit

12
.claude/hooks/validate-push.sh
View file

@ -12,7 +12,7 @@ INPUT=$(cat)
if command -v jq >/dev/null 2>&1; then
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
else
COMMAND=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | sed 's/"command"\s*:\s*"//;s/"$//')
COMMAND=$(echo "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
fi
# Only process git push commands
@ -21,23 +21,23 @@ if ! echo "$COMMAND" | grep -qE '^git[[:space:]]+push'; then
fi
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
FULL_GATE=false
MATCHED_BRANCH=""
# Check if pushing to a protected branch
for branch in develop main master; do
if [ "$CURRENT_BRANCH" = "$branch" ]; then
FULL_GATE=true
MATCHED_BRANCH="$branch"
break
fi
# Also check if pushing to a protected branch explicitly (quote branch name for safety)
if echo "$COMMAND" | grep -qE "[[:space:]]${branch}([[:space:]]|$)"; then
FULL_GATE=true
MATCHED_BRANCH="$branch"
break
fi
done
if [ "$FULL_GATE" = true ]; then
echo "Push to protected branch '$CURRENT_BRANCH' detected." >&2
if [ -n "$MATCHED_BRANCH" ]; then
echo "Push to protected branch '$MATCHED_BRANCH' detected." >&2
echo "Reminder: Ensure build passes, unit tests pass, and no S1/S2 bugs exist." >&2
# Allow the push but warn -- uncomment below to block instead:
# echo "BLOCKED: Run tests before pushing to $CURRENT_BRANCH" >&2

3
.claude/rules/design-docs.md
View file

@ -13,3 +13,6 @@ paths:
- Acceptance criteria must be testable — a QA tester must be able to verify pass/fail
- No hand-waving: "the system should feel good" is not a valid specification
- Balance values must link to their source formula or rationale
- Design documents MUST be written incrementally: create skeleton first, then fill
each section one at a time with user approval between sections. Write each
approved section to the file immediately to persist decisions and manage context

2
.claude/settings.json
View file

@ -81,7 +81,7 @@
{
"type": "command",
"command": "bash .claude/hooks/pre-compact.sh",
"timeout": 5
"timeout": 10
}
]
}

11
.claude/skills/brainstorm/SKILL.md
View file

@ -3,7 +3,7 @@ name: brainstorm
description: "Guided game concept ideation — from zero idea to a structured game concept document. Uses professional studio ideation techniques, player psychology frameworks, and structured creative exploration."
argument-hint: "[genre or theme hint, or 'open' for fully open brainstorm]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, WebSearch
allowed-tools: Read, Glob, Grep, Write, WebSearch, AskUserQuestion
---
When this skill is invoked:
@ -21,6 +21,14 @@ When this skill is invoked:
exploration** where the AI acts as a creative facilitator, not a replacement
for the human's vision.
**Use `AskUserQuestion`** at key decision points throughout brainstorming:
- Constrained taste questions (genre preferences, scope, team size)
- Concept selection ("Which 2-3 concepts resonate?") after presenting options
- Direction choices ("Develop further, explore more, or prototype?")
- Pillar ranking after concepts are refined
Write full creative analysis in conversation text first, then use
`AskUserQuestion` to capture the decision with concise labels.
Professional studio brainstorming principles to follow:
- Withhold judgment — no idea is bad during exploration
- Encourage unusual ideas — outside-the-box thinking sparks better concepts
@ -192,6 +200,7 @@ 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"
- "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`"

12
.claude/skills/design-review/SKILL.md
View file

@ -62,3 +62,15 @@ When this skill is invoked:
### Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]
```
9. **Contextual next step recommendations**:
- 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`
> 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'."

344
.claude/skills/design-systems/SKILL.md Normal file
View file

@ -0,0 +1,344 @@
---
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]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite
---
When this skill is invoked:
## 1. Parse Arguments
Three 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).
---
## 2. Phase 1: Read Concept (Required Context)
Read the game concept and any existing design work. This provides the raw material
for systems decomposition.
**Required:**
- Read `design/gdd/game-concept.md` — **fail with a clear message if missing**:
> "No game concept found at `design/gdd/game-concept.md`. Run `/brainstorm` first
> to create one, then come back to decompose it into systems."
**Optional (read if they exist):**
- Read `design/gdd/game-pillars.md` — pillars constrain priority and scope
- Read `design/gdd/systems-index.md` — if exists, **resume** from where it left off
(update, don't recreate from scratch)
- Glob `design/gdd/*.md` — check which system GDDs already exist
**If the systems index already exists:**
- Read it and present current status to the user
- Use `AskUserQuestion` to ask:
"The systems index already exists with [N] systems ([M] designed, [K] not started).
What would you like to do?"
- Options: "Update the index with new systems", "Design the next undesigned system",
"Review and revise priorities"
---
## 3. Phase 2: Systems Enumeration (Collaborative)
Extract and identify all systems the game needs. This is the creative core of the
skill — it requires human judgment because concept docs rarely enumerate every
system explicitly.
### Step 2a: Extract Explicit Systems
Scan the game concept for directly mentioned systems and mechanics:
- Core Mechanics section (most explicit)
- Core Loop section (implies what systems drive each loop tier)
- Technical Considerations section (networking, procedural generation, etc.)
- MVP Definition section (required features = required systems)
### Step 2b: Identify Implicit Systems
For each explicit system, identify the **hidden systems** it implies. Games always
need more systems than the concept doc mentions. Use this inference pattern:
- "Inventory" implies: item database, equipment slots, weight/capacity rules,
inventory UI, item serialization for save/load
- "Combat" implies: damage calculation, health system, hit detection, status effects,
enemy AI, combat UI (health bars, damage numbers), death/respawn
- "Open world" implies: streaming/chunking, LOD system, fast travel, map/minimap,
point of interest tracking, world state persistence
- "Multiplayer" implies: networking layer, lobby/matchmaking, state synchronization,
anti-cheat, network UI (ping, player list)
- "Crafting" implies: recipe database, ingredient gathering, crafting UI,
success/failure mechanics, recipe discovery/learning
- "Dialogue" implies: dialogue tree system, dialogue UI, choice tracking, NPC
state management, localization hooks
- "Progression" implies: XP system, level-up mechanics, skill tree, unlock
tracking, progression UI, progression save data
Explain in conversation text why each implicit system is needed (with examples).
### Step 2c: User Review
Present the enumeration organized by category. For each system, show:
- Name
- Category
- Brief description (1 sentence)
- Whether it was explicit (from concept) or implicit (inferred)
Then use `AskUserQuestion` to capture feedback:
- "Are there systems missing from this list?"
- "Should any of these be combined or split?"
- "Are there systems listed that this game does NOT need?"
Iterate until the user approves the enumeration.
---
## 4. Phase 3: Dependency Mapping (Collaborative)
For each system, determine what it depends on. A system "depends on" another if
it cannot function without that other system existing first.
### Step 3a: Map Dependencies
For each system, list its dependencies. Use these dependency heuristics:
- **Input/output dependencies**: System A produces data System B needs
- **Structural dependencies**: System A provides the framework System B plugs into
- **UI dependencies**: Every gameplay system has a corresponding UI system that
depends on it (but UI is designed after the gameplay system)
### Step 3b: Sort by Dependency Order
Arrange systems into layers:
1. **Foundation**: Systems with zero dependencies (designed and built first)
2. **Core**: Systems depending only on Foundation systems
3. **Feature**: Systems depending on Core systems
4. **Presentation**: UI and feedback systems that wrap gameplay systems
5. **Polish**: Meta-systems, tutorials, analytics, accessibility
### Step 3c: Detect Circular Dependencies
Check for cycles in the dependency graph. If found:
- Highlight them to the user
- Propose resolutions (interface abstraction, simultaneous design, breaking the
cycle by defining a contract between the two systems)
### Step 3d: Present to User
Show the dependency map as a layered list. Highlight:
- Any circular dependencies
- Any "bottleneck" systems (many others depend on them — these are high-risk)
- Any systems with no dependents (leaf nodes — lower risk, can be designed late)
Use `AskUserQuestion` to ask: "Does this dependency ordering look right? Any
dependencies I'm missing or that should be removed?"
---
## 5. Phase 4: Priority Assignment (Collaborative)
Assign each system to a priority tier based on what milestone it's needed for.
### Step 4a: Auto-Assign Based on Concept
Use these heuristics for initial assignment:
- **MVP**: Systems mentioned in the concept's "Required for MVP" section, plus their
Foundation-layer dependencies
- **Vertical Slice**: Systems needed for a complete experience in one area
- **Alpha**: All remaining gameplay systems
- **Full Vision**: Polish, meta, and nice-to-have systems
### Step 4b: User Review
Present the priority assignments in a table. For each tier, explain why systems
were placed there.
Use `AskUserQuestion` to ask: "Do these priority assignments match your vision?
Which systems should be higher or lower priority?"
Explain reasoning in conversation: "I placed [system] in MVP because the core loop
requires it — without [system], the 30-second loop can't function."
### Step 4c: Determine Design Order
Combine dependency sort + priority tier to produce the final design order:
1. MVP Foundation systems first
2. MVP Core systems second
3. MVP Feature systems third
4. Vertical Slice Foundation/Core systems
5. ...and so on
This is the order the team should write GDDs in.
---
## 6. Phase 5: Create Systems Index (Write)
### Step 5a: Draft the Document
Using the template at `.claude/docs/templates/systems-index.md`, populate the
systems index with all data from Phases 2-4:
- Fill the enumeration table
- Fill the dependency map
- Fill the recommended design order
- Fill the high-risk systems
- Fill progress tracker (all systems "Not Started" initially, unless GDDs already exist)
### Step 5b: Approval
Present a summary of the document:
- Total systems count by category
- MVP system count
- First 3 systems in the design order
- Any high-risk items
Ask: "May I write the systems index to `design/gdd/systems-index.md`?"
Wait for approval. Write the file only after "yes."
### Step 5c: Update Session State
After writing, update `production/session-state/active.md` with:
- Task: Systems decomposition
- Status: Systems index created
- File: design/gdd/systems-index.md
- Next: Design individual system GDDs
---
## 7. Phase 6: Design Individual Systems (Optional, Iterative)
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`
### Step 6a: Select the System
- If a system name was provided, find it in the systems index
- If `next` was used, pick the highest-priority undesigned system (by design order)
- If the user just finished the index, ask:
"Would you like to start designing individual systems now? The first system in
the design order is [name]. Or would you prefer to stop here and come back later?"
Use `AskUserQuestion` for: "Start designing [system-name] now, pick a different
system, or stop here?"
### Step 6b: Delegate to Agents
Use the Task tool to delegate GDD writing to the appropriate agent(s):
**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
**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.
**For narrative systems (dialogue, quests, lore):**
Coordinate with `narrative-director` in addition to `game-designer`.
**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`:
- "Continue to the next system ([next system name])?"
- "Pick a different system?"
- "Stop here for this session?"
If continuing, return to Step 6a.
---
## 8. Phase 7: Suggest Next Steps
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-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]`"
- "Plan the first implementation sprint with `/sprint-plan new`"
---
## Collaborative Protocol
This skill follows the collaborative design principle at every phase:
1. **Question -> Options -> Decision -> Draft -> Approval** at every step
2. **AskUserQuestion** at every decision point (Explain -> Capture pattern):
- Phase 2: "Missing systems? Combine or split?"
- 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?"
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
6. **Session state updates**: Write to `production/session-state/active.md` after
each milestone (index created, system designed, priorities changed)
**Never** auto-generate the full systems list and write it without review.
**Never** start designing a system without user confirmation.
**Always** show the enumeration, dependencies, and priorities for user validation.

4
.claude/skills/gate-check/SKILL.md
View file

@ -44,7 +44,8 @@ This skill is prescriptive ("are we ready to advance?" with a formal verdict).
### Gate: Pre-production → Production
**Required Artifacts:**
- [ ] At least 1 GDD in `design/gdd/` (beyond game-concept.md)
- [ ] 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/`
@ -185,6 +186,7 @@ For items that can't be automatically verified, **ask the user**:
Based on the verdict, suggest specific next steps:
- **No systems index?** → `/design-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`

11
.claude/skills/project-stage-detect/SKILL.md
View file

@ -25,7 +25,8 @@ Analyze project structure and content:
**Design Documentation** (`design/`):
- Count GDD files in `design/gdd/*.md`
- Check for game-concept.md, game-pillars.md
- Check for game-concept.md, game-pillars.md, systems-index.md
- If systems-index.md exists, count total systems vs. designed systems
- Analyze completeness (Overview, Detailed Design, Edge Cases, etc.)
- Count narrative docs in `design/narrative/`
- Count level designs in `design/levels/`
@ -72,11 +73,12 @@ 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`?"
- "Prototypes directory has 3 projects with no READMEs. Were these experiments, or do they need documentation?"
### 4. Generate Stage Report
Use template: `docs/templates/project-stage-report.md`
Use template: `.claude/docs/templates/project-stage-report.md`
**Report structure**:
```markdown
@ -137,7 +139,7 @@ Recommended next steps:
- [Priority 2]
- [Priority 3]
May I write the full stage analysis to docs/project-stage-report.md?
May I write the full stage analysis to production/project-stage-report.md?
```
Wait for user approval before creating the file.
@ -163,6 +165,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
- **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]`
@ -179,6 +182,6 @@ This skill follows the collaborative design principle:
2. **Present Options**: "Should I create X, or is it tracked elsewhere?"
3. **User Decides**: Wait for direction
4. **Show Draft**: Display report summary
5. **Get Approval**: "May I write to docs/project-stage-report.md?"
5. **Get Approval**: "May I write to production/project-stage-report.md?"
**Never** silently write files. **Always** show findings and ask before creating artifacts.

7
.claude/skills/setup-engine/SKILL.md
View file

@ -291,9 +291,10 @@ Agent Config: [verified]
Next Steps:
1. Review docs/engine-reference/<engine>/VERSION.md
2. [If from /brainstorm] Run /prototype [core-mechanic] to test the core loop
3. [If fresh start] Run /brainstorm to discover your game concept
4. Create your first milestone: /sprint-plan new
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
```
---

5
.claude/skills/start/SKILL.md
View file

@ -3,7 +3,7 @@ name: start
description: "First-time onboarding — asks where you are, then guides you to the right workflow. No assumptions."
argument-hint: "[no arguments]"
user-invocable: true
allowed-tools: Read, Glob, Grep
allowed-tools: Read, Glob, Grep, AskUserQuestion
---
# Guided Onboarding
@ -77,6 +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
- `/prototype` — test the core mechanic
- `/sprint-plan` — plan the first sprint
@ -90,6 +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
- `/prototype` — test the core mechanic
- `/sprint-plan` — plan the first sprint
@ -109,6 +111,7 @@ 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
- `/architecture-decision` — make first technical decisions
- `/sprint-plan` — plan the first sprint

9
.claude/skills/team-audio/SKILL.md
View file

@ -3,10 +3,15 @@ name: team-audio
description: "Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer for full audio pipeline from direction to implementation."
argument-hint: "[feature or area to design audio for]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
---
When this skill is invoked:
When this skill is invoked, orchestrate the audio team through a structured pipeline.
**Decision Points:** At each step transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
The user must approve before moving to the next step.
1. **Read the argument** for the target feature or area (e.g., `combat`,
`main menu`, `forest biome`, `boss encounter`).

7
.claude/skills/team-combat/SKILL.md
View file

@ -3,10 +3,15 @@ name: team-combat
description: "Orchestrate the combat team: coordinates game-designer, gameplay-programmer, ai-programmer, technical-artist, sound-designer, and qa-tester to design, implement, and validate a combat feature end-to-end."
argument-hint: "[combat feature description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
---
When this skill is invoked, orchestrate the combat team through a structured pipeline.
**Decision Points:** At each phase transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
The user must approve before moving to the next phase.
## Team Composition
- **game-designer** — Design the mechanic, define formulas and edge cases
- **gameplay-programmer** — Implement the core gameplay code

7
.claude/skills/team-level/SKILL.md
View file

@ -3,11 +3,16 @@ name: team-level
description: "Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation."
argument-hint: "[level name or area to design]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
---
When this skill is invoked:
**Decision Points:** At each step transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
The user must approve before moving to the next step.
1. **Read the argument** for the target level or area (e.g., `tutorial`,
`forest dungeon`, `hub town`, `final boss arena`).

7
.claude/skills/team-narrative/SKILL.md
View file

@ -3,10 +3,15 @@ name: team-narrative
description: "Orchestrate the narrative team: coordinates narrative-director, writer, world-builder, and level-designer to create cohesive story content, world lore, and narrative-driven level design."
argument-hint: "[narrative content description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Task
allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite
---
When this skill is invoked, orchestrate the narrative team through a structured pipeline.
**Decision Points:** At each phase transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
The user must approve before moving to the next phase.
## Team Composition
- **narrative-director** — Story arcs, character design, dialogue strategy, narrative vision
- **writer** — Dialogue writing, lore entries, item descriptions, in-game text

7
.claude/skills/team-polish/SKILL.md
View file

@ -3,10 +3,15 @@ name: team-polish
description: "Orchestrate the polish team: coordinates performance-analyst, technical-artist, sound-designer, and qa-tester to optimize, polish, and harden a feature or area for release quality."
argument-hint: "[feature or area to polish]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
---
When this skill is invoked, orchestrate the polish team through a structured pipeline.
**Decision Points:** At each phase transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
The user must approve before moving to the next phase.
## Team Composition
- **performance-analyst** — Profiling, optimization, memory analysis, frame budget
- **technical-artist** — VFX polish, shader optimization, visual quality

7
.claude/skills/team-release/SKILL.md
View file

@ -3,10 +3,15 @@ name: team-release
description: "Orchestrate the release team: coordinates release-manager, qa-lead, devops-engineer, and producer to execute a release from candidate to deployment."
argument-hint: "[version number or 'next']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
---
When this skill is invoked, orchestrate the release team through a structured pipeline.
**Decision Points:** At each phase transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
The user must approve before moving to the next phase.
## Team Composition
- **release-manager** — Release branch, versioning, changelog, deployment
- **qa-lead** — Test sign-off, regression suite, release quality gate

7
.claude/skills/team-ui/SKILL.md
View file

@ -3,10 +3,15 @@ name: team-ui
description: "Orchestrate the UI team: coordinates ux-designer, ui-programmer, and art-director to design, implement, and polish a user interface feature from wireframe to final."
argument-hint: "[UI feature description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
---
When this skill is invoked, orchestrate the UI team through a structured pipeline.
**Decision Points:** At each phase transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
The user must approve before moving to the next phase.
## Team Composition
- **ux-designer** — User flows, wireframes, accessibility, input handling
- **ui-programmer** — UI framework, screens, widgets, data binding, implementation

2
.gitignore vendored
View file

@ -12,7 +12,9 @@ Desktop.ini
# === Claude Code Local ===
.claude/settings.local.json
.claude/docs/UPGRADE-PLAN.md
CLAUDE.local.md
production/session-logs/
production/session-state/*.md
# === Internal Planning (not for public) ===
docs/IMPROVEMENTS-PROPOSAL.md

20
CLAUDE.md
View file

@ -26,10 +26,6 @@ Each agent owns a specific domain, enforcing separation of concerns and quality.
@.claude/docs/technical-preferences.md
## Agent Roster
@.claude/docs/agent-roster.md
## Coordination Rules
@.claude/docs/coordination-rules.md
@ -49,24 +45,10 @@ See `docs/COLLABORATIVE-DESIGN-PRINCIPLE.md` for full protocol and examples.
> **First session?** If the project has no engine configured and no game concept,
> run `/start` to begin the guided onboarding flow.
## Coding Standards & Review
## Coding Standards
@.claude/docs/coding-standards.md
@.claude/docs/review-workflow.md
## Context Management
@.claude/docs/context-management.md
## Active Hooks
@.claude/docs/hooks-reference.md
## Available Skills (Slash Commands)
@.claude/docs/skills-reference.md
## Path-Specific Rules
@.claude/docs/rules-reference.md

12
README.md
View file

@ -3,14 +3,14 @@
<p align="center">
Turn a single Claude Code session into a full game development studio.
<br />
48 agents. 35 workflows. One coordinated AI team.
48 agents. 36 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-35-green" alt="35 Skills"></a>
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-36-green" alt="36 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>
@ -50,7 +50,7 @@ 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** | 35 | Slash commands for common workflows (`/start`, `/sprint-plan`, `/code-review`, `/brainstorm`, etc.) |
| **Skills** | 36 | 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 |
@ -91,7 +91,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 35 skills:
Type `/` in Claude Code to access all 36 skills:
**Reviews & Analysis**
`/design-review` `/code-review` `/balance-check` `/asset-audit` `/scope-check` `/perf-profile` `/tech-debt`
@ -100,7 +100,7 @@ Type `/` in Claude Code to access all 35 skills:
`/sprint-plan` `/milestone-review` `/estimate` `/retrospective` `/bug-report`
**Project Management**
`/start` `/project-stage-detect` `/reverse-document` `/gate-check`
`/start` `/project-stage-detect` `/reverse-document` `/gate-check` `/design-systems`
**Release**
`/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix`
@ -149,7 +149,7 @@ CLAUDE.md # Master configuration
.claude/
settings.json # Hooks, permissions, safety rules
agents/ # 48 agent definitions (markdown + YAML frontmatter)
skills/ # 35 slash commands (subdirectory per skill)
skills/ # 36 slash commands (subdirectory per skill)
hooks/ # 8 hook scripts (bash, cross-platform)
rules/ # 11 path-scoped coding standards
docs/

186
docs/COLLABORATIVE-DESIGN-PRINCIPLE.md
View file

@ -329,6 +329,127 @@ Skill: "Writing design/concept.md..."
---
## 🎛️ Structured Decision UI (AskUserQuestion)
Use the `AskUserQuestion` tool to present decisions as a **selectable UI** instead
of plain markdown text. This gives the user a clean interface to pick from options
(or type "Other" for a custom answer).
### The Explain → Capture Pattern
Detailed reasoning doesn't fit in the tool's short descriptions. So use a two-step
pattern:
1. **Explain first** — Write your full expert analysis in conversation text:
detailed pros/cons, theory references, example games, pillar alignment. This is
where the reasoning lives.
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels
and short descriptions. The user picks from the UI or types a custom answer.
### When to Use AskUserQuestion
✅ **Use it for:**
- Every decision point where you'd present 2-4 options
- Initial clarifying questions with constrained answers
- Batching up to 4 independent questions in one call
- Next-step choices ("Draft formulas or refine rules first?")
- Architecture decisions ("Static utility or singleton?")
- Strategic choices ("Simplify scope, slip deadline, or cut feature?")
❌ **Don't use it for:**
- Open-ended discovery questions ("What excites you about roguelikes?")
- Single yes/no confirmations ("May I write to file?")
- When running as a Task subagent (tool may not be available)
### Format Guidelines
- **Labels**: 1-5 words (e.g., "Hybrid Discovery", "Full Randomized")
- **Descriptions**: 1 sentence summarizing the approach and key trade-off
- **Recommended**: Add "(Recommended)" to your preferred option's label
- **Previews**: Use `markdown` field for comparing code structures or formulas
- **Multi-select**: Use `multiSelect: true` when choices aren't mutually exclusive
### Example — Multi-Question Batch (Clarifying Questions)
After introducing the topic in conversation, batch constrained questions:
```
AskUserQuestion:
questions:
- question: "Should crafting recipes be discovered or learned?"
header: "Discovery"
options:
- label: "Experimentation"
description: "Players discover by trying combinations — high mystery"
- label: "NPC/Book Learning"
description: "Recipes taught explicitly — accessible, lower mystery"
- label: "Tiered Hybrid"
description: "Basic recipes learned, advanced discovered — best of both"
- question: "How punishing should failed crafts be?"
header: "Failure"
options:
- label: "Materials Lost"
description: "All consumed on failure — high stakes, risk/reward"
- label: "Partial Recovery"
description: "50% returned — moderate risk"
- label: "No Loss"
description: "Materials returned, only time spent — forgiving"
```
### Example — Design Decision (After Full Analysis)
After writing the full pros/cons analysis in conversation text:
```
AskUserQuestion:
questions:
- question: "Which crafting approach fits your vision?"
header: "Approach"
options:
- label: "Hybrid Discovery (Recommended)"
description: "Discovery base with earned hints — balances exploration and accessibility"
- label: "Full Discovery"
description: "Pure experimentation — maximum mystery, risk of frustration"
- label: "Hint System"
description: "Progressive hints reveal recipes — accessible but less surprise"
```
### Example — Strategic Decision
After presenting the full strategic analysis with pillar alignment:
```
AskUserQuestion:
questions:
- question: "How should we handle crafting scope for Alpha?"
header: "Scope"
options:
- label: "Simplify to Core (Recommended)"
description: "Recipe discovery only, 10 recipes — makes deadline, pillar visible"
- label: "Full Implementation"
description: "Complete system, 30 recipes — slips Alpha by 1 week"
- label: "Cut Entirely"
description: "Drop crafting, focus on combat — deadline met, pillar missing"
```
### Team Skill Orchestration
In team skills, subagents return their analysis as text. The **orchestrator**
(main session) calls `AskUserQuestion` at each decision point between phases:
```
[game-designer returns 3 combat approaches with analysis]
Orchestrator uses AskUserQuestion:
question: "Which combat approach should we develop?"
options: [concise summaries of the 3 approaches]
[User picks → orchestrator passes decision to next phase]
```
---
## 📄 File Writing Protocol
### NEVER Write Files Without Explicit Approval
@ -352,6 +473,39 @@ Every file write must follow:
[Returns to step 1]
```
### Incremental Section Writing (Design Documents)
For multi-section documents (design docs, lore entries, architecture docs), write
each section to the file as it's approved instead of building the full document
in conversation. This prevents context overflow during long iterative sessions.
```
1. Agent creates file with skeleton (all section headers, empty bodies)
Agent: "May I create design/gdd/crafting-system.md with the section skeleton?"
User: "Yes"
2. For EACH section:
Agent: [Drafts section in conversation]
User: [Reviews, requests changes]
Agent: [Revises until approved]
Agent: "May I write this section to the file?"
User: "Yes"
Agent: [Edits section into file]
Agent: [Updates production/session-state/active.md with progress]
─── Context for this section can now be safely compacted ───
─── The decisions are IN THE FILE ───
3. If session crashes or compacts mid-document:
Agent: [Reads the file — completed sections are all there]
Agent: [Reads production/session-state/active.md — knows what's next]
Agent: "Sections 1-4 are complete. Ready to work on section 5?"
```
Why this matters: A full design doc session with 8 sections and 2-3 revision
cycles per section can accumulate 30-50k tokens of conversation. Incremental
writing keeps the live context at ~3-5k tokens (only the current section's
discussion), because completed sections are persisted to disk.
### Multi-File Writes
When a change affects multiple files:
@ -455,21 +609,6 @@ The orchestration is automated, but **decision points stay with the user**.
---
## 🔧 Updating All Documentation
This principle needs to be embedded in:
### Files to Update:
1. **CLAUDE.md** — Add "Collaboration Protocol" section
2. **WORKFLOW-GUIDE.md** — Rewrite all "What happens" sections
3. **Agent Roster** — Add "Questions to Ask" to each agent description
4. **.claude/agents/*.md** — Update system prompts to enforce this
5. **Skills** — Update all skills to ask before writing
6. **README.md** — Clarify this is collaborative, not autonomous
---
## ✅ Quick Validation: Is Your Session Collaborative?
After any agent interaction, check:
@ -537,14 +676,13 @@ WHEN implementing:
---
## 🚀 Next Steps
## Implementation Status
To fully implement this principle:
This principle has been fully embedded across the project:
1. **Update CLAUDE.md** with collaboration protocol
2. **Update agent definitions** to enforce question-asking
3. **Update WORKFLOW-GUIDE.md** to show collaborative examples
4. **Update all skills** to require approval before writing
5. **Add /collaborative-check skill** to audit if sessions are collaborative
Would you like me to implement these updates now?
- **CLAUDE.md** — Collaboration protocol section added
- **All 48 agent definitions** — Updated to enforce question-asking and approval
- **All skills** — Updated to require approval before writing
- **WORKFLOW-GUIDE.md** — Rewritten with collaborative examples
- **README.md** — Clarifies collaborative (not autonomous) design
- **AskUserQuestion tool** — Integrated into 10 skills for structured option UI

30
docs/WORKFLOW-GUIDE.md
View 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, 35 slash commands, and automated hooks. It assumes you
> 48-agent system, 36 slash commands, and automated hooks. It assumes you
> have Claude Code installed and are working from the project root.
---
@ -252,7 +252,31 @@ Also define **anti-pillars** -- things your game intentionally avoids:
You create all the design documents that define how your game works. Nothing
gets coded yet -- this is pure design and architecture.
### Step 2.1: Create the Game Design Document (GDD)
### Step 2.1: Decompose Your Concept Into Systems
Before writing individual GDDs, enumerate all the systems your game needs:
```
/design-systems map
```
This creates `design/gdd/systems-index.md` — a master tracking document that:
- Lists every system your game needs (combat, movement, UI, etc.)
- Maps dependencies between systems
- Assigns priority tiers (MVP, Vertical Slice, Alpha, Full Vision)
- Determines design order (Foundation → Core → Feature → Presentation → Polish)
Then design each system in dependency order:
```
/design-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.
### Step 2.2: Create the Game Design Document (GDD)
For each major system in your game, create a design document in `design/gdd/`.
Use the template:
@ -1690,7 +1714,7 @@ conflicts go to `producer`.
|-------|----------|
| **Onboarding** | `/start` |
| **Ideation** | `/brainstorm` |
| **Design** | `/design-review`, `/architecture-decision` |
| **Design** | `/design-systems`, `/design-review`, `/architecture-decision` |
| **Sprint** | `/sprint-plan`, `/estimate`, `/scope-check`, `/retrospective` |
| **Implementation** | `/code-review`, `/prototype`, `/tech-debt` |
| **Testing** | `/balance-check`, `/playtest-report`, `/perf-profile` |

6
docs/examples/README.md
View file

@ -91,6 +91,12 @@ All examples follow the **collaborative workflow pattern:**
Question → Options → Decision → Draft → Approval
```
> **Note:** These examples show the collaborative pattern as conversational text.
> In practice, agents now use the `AskUserQuestion` tool at decision points to
> present structured option pickers (with labels, descriptions, and multi-select).
> The pattern is **Explain → Capture**: agents explain their analysis in
> conversation first, then present a structured UI picker for the user's decision.
### ✅ **Collaborative Behaviors Shown:**
1. **Agents Ask Before Assuming**

0
production/session-state/.gitkeep Normal file
View file