mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-06-27 04:51:46 +00:00
Release v0.2.0: Context Resilience, AskUserQuestion, /design-systems
* 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
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
```
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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"
|
||||
```
|
||||
|
||||
@@ -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
3
.claude/docs/templates/game-concept.md
vendored
@@ -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
146
.claude/docs/templates/systems-index.md
vendored
Normal 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]`)
|
||||
Reference in New Issue
Block a user