From e289ce906fe56de47d4f8561c4b9d9fe43fd660c Mon Sep 17 00:00:00 2001 From: Donchitos <150119193+Donchitos@users.noreply.github.com> Date: Fri, 20 Feb 2026 20:52:35 +1100 Subject: [PATCH] Release v0.2.0: Context Resilience, AskUserQuestion, /design-systems MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * 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 * 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 * 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 --------- Co-authored-by: Claude Opus 4.6 --- .claude/agents/art-director.md | 31 +- .claude/agents/audio-director.md | 31 +- .claude/agents/creative-director.md | 18 + .claude/agents/economy-designer.md | 31 +- .claude/agents/game-designer.md | 31 +- .claude/agents/level-designer.md | 31 +- .claude/agents/live-ops-designer.md | 18 + .claude/agents/narrative-director.md | 31 +- .claude/agents/producer.md | 18 + .claude/agents/systems-designer.md | 31 +- .claude/agents/technical-director.md | 18 + .claude/agents/ux-designer.md | 18 + .claude/agents/world-builder.md | 31 +- .claude/agents/writer.md | 34 +- .claude/docs/CLAUDE-local-template.md | 2 +- .claude/docs/context-management.md | 85 ++++- .claude/docs/directory-structure.md | 2 + .claude/docs/hooks-reference.md | 4 +- .../post-merge-asset-validation.md | 2 +- .../pre-commit-code-quality.md | 4 +- .../pre-commit-design-check.md | 10 +- .claude/docs/quick-start.md | 3 +- .claude/docs/skills-reference.md | 5 +- .../design-agent-protocol.md | 52 +++ .../implementation-agent-protocol.md | 30 ++ .../leadership-agent-protocol.md | 37 ++ .claude/docs/templates/game-concept.md | 3 +- .claude/docs/templates/systems-index.md | 146 ++++++++ .claude/hooks/detect-gaps.sh | 4 +- .claude/hooks/log-agent.sh | 8 +- .claude/hooks/pre-compact.sh | 83 ++++- .claude/hooks/session-start.sh | 17 + .claude/hooks/session-stop.sh | 17 +- .claude/hooks/validate-assets.sh | 2 +- .claude/hooks/validate-commit.sh | 18 +- .claude/hooks/validate-push.sh | 12 +- .claude/rules/design-docs.md | 3 + .claude/settings.json | 2 +- .claude/skills/brainstorm/SKILL.md | 11 +- .claude/skills/design-review/SKILL.md | 12 + .claude/skills/design-systems/SKILL.md | 344 ++++++++++++++++++ .claude/skills/gate-check/SKILL.md | 4 +- .claude/skills/project-stage-detect/SKILL.md | 11 +- .claude/skills/setup-engine/SKILL.md | 7 +- .claude/skills/start/SKILL.md | 5 +- .claude/skills/team-audio/SKILL.md | 9 +- .claude/skills/team-combat/SKILL.md | 7 +- .claude/skills/team-level/SKILL.md | 7 +- .claude/skills/team-narrative/SKILL.md | 7 +- .claude/skills/team-polish/SKILL.md | 7 +- .claude/skills/team-release/SKILL.md | 7 +- .claude/skills/team-ui/SKILL.md | 7 +- .gitignore | 2 + CLAUDE.md | 20 +- README.md | 12 +- docs/COLLABORATIVE-DESIGN-PRINCIPLE.md | 186 ++++++++-- docs/WORKFLOW-GUIDE.md | 30 +- docs/examples/README.md | 6 + production/session-state/.gitkeep | 0 59 files changed, 1454 insertions(+), 170 deletions(-) create mode 100644 .claude/docs/templates/systems-index.md create mode 100644 .claude/skills/design-systems/SKILL.md create mode 100644 production/session-state/.gitkeep diff --git a/.claude/agents/art-director.md b/.claude/agents/art-director.md index 9cc4b9b..17c5ae8 100644 --- a/.claude/agents/art-director.md +++ b/.claude/agents/art-director.md @@ -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, diff --git a/.claude/agents/audio-director.md b/.claude/agents/audio-director.md index 17e0975..a4de753 100644 --- a/.claude/agents/audio-director.md +++ b/.claude/agents/audio-director.md @@ -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 -- diff --git a/.claude/agents/creative-director.md b/.claude/agents/creative-director.md index 22acf8d..109f968 100644 --- a/.claude/agents/creative-director.md +++ b/.claude/agents/creative-director.md @@ -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, diff --git a/.claude/agents/economy-designer.md b/.claude/agents/economy-designer.md index 9b7a022..431850c 100644 --- a/.claude/agents/economy-designer.md +++ b/.claude/agents/economy-designer.md @@ -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 diff --git a/.claude/agents/game-designer.md b/.claude/agents/game-designer.md index 368841b..8696ba8 100644 --- a/.claude/agents/game-designer.md +++ b/.claude/agents/game-designer.md @@ -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 diff --git a/.claude/agents/level-designer.md b/.claude/agents/level-designer.md index e6c4a78..428c63f 100644 --- a/.claude/agents/level-designer.md +++ b/.claude/agents/level-designer.md @@ -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 diff --git a/.claude/agents/live-ops-designer.md b/.claude/agents/live-ops-designer.md index 0267121..32fd802 100644 --- a/.claude/agents/live-ops-designer.md +++ b/.claude/agents/live-ops-designer.md @@ -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 diff --git a/.claude/agents/narrative-director.md b/.claude/agents/narrative-director.md index c4eb3c6..06ce7c3 100644 --- a/.claude/agents/narrative-director.md +++ b/.claude/agents/narrative-director.md @@ -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 diff --git a/.claude/agents/producer.md b/.claude/agents/producer.md index 1abe187..9715ed2 100644 --- a/.claude/agents/producer.md +++ b/.claude/agents/producer.md @@ -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, diff --git a/.claude/agents/systems-designer.md b/.claude/agents/systems-designer.md index 926fbc5..f66d635 100644 --- a/.claude/agents/systems-designer.md +++ b/.claude/agents/systems-designer.md @@ -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 diff --git a/.claude/agents/technical-director.md b/.claude/agents/technical-director.md index f867ce8..82d53ac 100644 --- a/.claude/agents/technical-director.md +++ b/.claude/agents/technical-director.md @@ -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 diff --git a/.claude/agents/ux-designer.md b/.claude/agents/ux-designer.md index 45af2ba..5a7e24f 100644 --- a/.claude/agents/ux-designer.md +++ b/.claude/agents/ux-designer.md @@ -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 diff --git a/.claude/agents/world-builder.md b/.claude/agents/world-builder.md index ea1a59e..dbd494c 100644 --- a/.claude/agents/world-builder.md +++ b/.claude/agents/world-builder.md @@ -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 diff --git a/.claude/agents/writer.md b/.claude/agents/writer.md index 6234696..24f9920 100644 --- a/.claude/agents/writer.md +++ b/.claude/agents/writer.md @@ -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 diff --git a/.claude/docs/CLAUDE-local-template.md b/.claude/docs/CLAUDE-local-template.md index 7a53ba2..b3bebc2 100644 --- a/.claude/docs/CLAUDE-local-template.md +++ b/.claude/docs/CLAUDE-local-template.md @@ -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) diff --git a/.claude/docs/context-management.md b/.claude/docs/context-management.md index 3871f9a..efa1c36 100644 --- a/.claude/docs/context-management.md +++ b/.claude/docs/context-management.md @@ -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 diff --git a/.claude/docs/directory-structure.md b/.claude/docs/directory-structure.md index c260574..7e859f2 100644 --- a/.claude/docs/directory-structure.md +++ b/.claude/docs/directory-structure.md @@ -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) ``` diff --git a/.claude/docs/hooks-reference.md b/.claude/docs/hooks-reference.md index 46913a6..4f53c5d 100644 --- a/.claude/docs/hooks-reference.md +++ b/.claude/docs/hooks-reference.md @@ -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 | diff --git a/.claude/docs/hooks-reference/post-merge-asset-validation.md b/.claude/docs/hooks-reference/post-merge-asset-validation.md index 166d83f..5415769 100644 --- a/.claude/docs/hooks-reference/post-merge-asset-validation.md +++ b/.claude/docs/hooks-reference/post-merge-asset-validation.md @@ -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 diff --git a/.claude/docs/hooks-reference/pre-commit-code-quality.md b/.claude/docs/hooks-reference/pre-commit-code-quality.md index 310aca2..d562b9e 100644 --- a/.claude/docs/hooks-reference/pre-commit-code-quality.md +++ b/.claude/docs/hooks-reference/pre-commit-code-quality.md @@ -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 '(? /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 diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md index b3f4559..3f5cbcd 100644 --- a/.claude/docs/quick-start.md +++ b/.claude/docs/quick-start.md @@ -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/ diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md index 19f1aff..e1d03a4 100644 --- a/.claude/docs/skills-reference.md +++ b/.claude/docs/skills-reference.md @@ -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 | diff --git a/.claude/docs/templates/collaborative-protocols/design-agent-protocol.md b/.claude/docs/templates/collaborative-protocols/design-agent-protocol.md index c9fac2d..c9d7460 100644 --- a/.claude/docs/templates/collaborative-protocols/design-agent-protocol.md +++ b/.claude/docs/templates/collaborative-protocols/design-agent-protocol.md @@ -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 ``` diff --git a/.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md b/.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md index 0ed32e0..d257f63 100644 --- a/.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md +++ b/.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md @@ -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" ``` diff --git a/.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md b/.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md index 7fd3335..72e36c8 100644 --- a/.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md +++ b/.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md @@ -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 ``` diff --git a/.claude/docs/templates/game-concept.md b/.claude/docs/templates/game-concept.md index cd99fab..8030622 100644 --- a/.claude/docs/templates/game-concept.md +++ b/.claude/docs/templates/game-concept.md @@ -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`) diff --git a/.claude/docs/templates/systems-index.md b/.claude/docs/templates/systems-index.md new file mode 100644 index 0000000..3af19fe --- /dev/null +++ b/.claude/docs/templates/systems-index.md @@ -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]`) diff --git a/.claude/hooks/detect-gaps.sh b/.claude/hooks/detect-gaps.sh index c031f40..2a2c96d 100644 --- a/.claude/hooks/detect-gaps.sh +++ b/.claude/hooks/detect-gaps.sh @@ -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 diff --git a/.claude/hooks/log-agent.sh b/.claude/hooks/log-agent.sh index 9467df0..0a22e68 100644 --- a/.claude/hooks/log-agent.sh +++ b/.claude/hooks/log-agent.sh @@ -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 diff --git a/.claude/hooks/pre-compact.sh b/.claude/hooks/pre-compact.sh index 997a107..4d4842f 100644 --- a/.claude/hooks/pre-compact.sh +++ b/.claude/hooks/pre-compact.sh @@ -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 diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh index c57fe98..eba3e16 100644 --- a/.claude/hooks/session-start.sh +++ b/.claude/hooks/session-start.sh @@ -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 diff --git a/.claude/hooks/session-stop.sh b/.claude/hooks/session-stop.sh index 411db4a..ead7120 100644 --- a/.claude/hooks/session-stop.sh +++ b/.claude/hooks/session-stop.sh @@ -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" diff --git a/.claude/hooks/validate-assets.sh b/.claude/hooks/validate-assets.sh index d7be121..0497edf 100644 --- a/.claude/hooks/validate-assets.sh +++ b/.claude/hooks/validate-assets.sh @@ -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) diff --git a/.claude/hooks/validate-commit.sh b/.claude/hooks/validate-commit.sh index e8fde28..f7e639e 100644 --- a/.claude/hooks/validate-commit.sh +++ b/.claude/hooks/validate-commit.sh @@ -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 diff --git a/.claude/hooks/validate-push.sh b/.claude/hooks/validate-push.sh index e529d80..e9aff2e 100644 --- a/.claude/hooks/validate-push.sh +++ b/.claude/hooks/validate-push.sh @@ -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 diff --git a/.claude/rules/design-docs.md b/.claude/rules/design-docs.md index 0a83de7..33ea617 100644 --- a/.claude/rules/design-docs.md +++ b/.claude/rules/design-docs.md @@ -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 diff --git a/.claude/settings.json b/.claude/settings.json index 63b2d06..cf594c8 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -81,7 +81,7 @@ { "type": "command", "command": "bash .claude/hooks/pre-compact.sh", - "timeout": 5 + "timeout": 10 } ] } diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index bc59a0e..a910726 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -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`" diff --git a/.claude/skills/design-review/SKILL.md b/.claude/skills/design-review/SKILL.md index aeeb620..117a32c 100644 --- a/.claude/skills/design-review/SKILL.md +++ b/.claude/skills/design-review/SKILL.md @@ -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'." diff --git a/.claude/skills/design-systems/SKILL.md b/.claude/skills/design-systems/SKILL.md new file mode 100644 index 0000000..c44fe1c --- /dev/null +++ b/.claude/skills/design-systems/SKILL.md @@ -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. diff --git a/.claude/skills/gate-check/SKILL.md b/.claude/skills/gate-check/SKILL.md index 183e44b..5629c0d 100644 --- a/.claude/skills/gate-check/SKILL.md +++ b/.claude/skills/gate-check/SKILL.md @@ -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` diff --git a/.claude/skills/project-stage-detect/SKILL.md b/.claude/skills/project-stage-detect/SKILL.md index cf6ae2c..69676c7 100644 --- a/.claude/skills/project-stage-detect/SKILL.md +++ b/.claude/skills/project-stage-detect/SKILL.md @@ -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. diff --git a/.claude/skills/setup-engine/SKILL.md b/.claude/skills/setup-engine/SKILL.md index 9fc2a73..559b79e 100644 --- a/.claude/skills/setup-engine/SKILL.md +++ b/.claude/skills/setup-engine/SKILL.md @@ -291,9 +291,10 @@ Agent Config: [verified] Next Steps: 1. Review docs/engine-reference//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 ``` --- diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md index 316d498..a284bae 100644 --- a/.claude/skills/start/SKILL.md +++ b/.claude/skills/start/SKILL.md @@ -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 diff --git a/.claude/skills/team-audio/SKILL.md b/.claude/skills/team-audio/SKILL.md index 105e02e..5bb3553 100644 --- a/.claude/skills/team-audio/SKILL.md +++ b/.claude/skills/team-audio/SKILL.md @@ -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`). diff --git a/.claude/skills/team-combat/SKILL.md b/.claude/skills/team-combat/SKILL.md index 42a0f16..490be11 100644 --- a/.claude/skills/team-combat/SKILL.md +++ b/.claude/skills/team-combat/SKILL.md @@ -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 diff --git a/.claude/skills/team-level/SKILL.md b/.claude/skills/team-level/SKILL.md index 3e59dad..cbba7c1 100644 --- a/.claude/skills/team-level/SKILL.md +++ b/.claude/skills/team-level/SKILL.md @@ -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`). diff --git a/.claude/skills/team-narrative/SKILL.md b/.claude/skills/team-narrative/SKILL.md index a9f156a..2187f91 100644 --- a/.claude/skills/team-narrative/SKILL.md +++ b/.claude/skills/team-narrative/SKILL.md @@ -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 diff --git a/.claude/skills/team-polish/SKILL.md b/.claude/skills/team-polish/SKILL.md index 960c5ee..85f489d 100644 --- a/.claude/skills/team-polish/SKILL.md +++ b/.claude/skills/team-polish/SKILL.md @@ -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 diff --git a/.claude/skills/team-release/SKILL.md b/.claude/skills/team-release/SKILL.md index 04775b4..0a8b7e3 100644 --- a/.claude/skills/team-release/SKILL.md +++ b/.claude/skills/team-release/SKILL.md @@ -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 diff --git a/.claude/skills/team-ui/SKILL.md b/.claude/skills/team-ui/SKILL.md index eabb792..a8ff3ac 100644 --- a/.claude/skills/team-ui/SKILL.md +++ b/.claude/skills/team-ui/SKILL.md @@ -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 diff --git a/.gitignore b/.gitignore index 8bb1202..ea2e1bc 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index b6058ee..789b883 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/README.md b/README.md index 2b41fa4..8e9502e 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@

Turn a single Claude Code session into a full game development studio.
- 48 agents. 35 workflows. One coordinated AI team. + 48 agents. 36 workflows. One coordinated AI team.

MIT License 48 Agents - 35 Skills + 36 Skills 8 Hooks 11 Rules Built for Claude Code @@ -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/ diff --git a/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md b/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md index 57440b8..08be1f7 100644 --- a/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md +++ b/docs/COLLABORATIVE-DESIGN-PRINCIPLE.md @@ -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 diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index 48f1d93..55927e9 100644 --- a/docs/WORKFLOW-GUIDE.md +++ b/docs/WORKFLOW-GUIDE.md @@ -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` | diff --git a/docs/examples/README.md b/docs/examples/README.md index a4a2a76..5c31e04 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -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** diff --git a/production/session-state/.gitkeep b/production/session-state/.gitkeep new file mode 100644 index 0000000..e69de29