ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-06-27 13:01:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

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
59 changed files with 1454 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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]`)