Model routing, PostCompact hook, parallel spawning, error recovery

Model tier assignment:
- model: haiku → help, sprint-status, story-readiness, scope-check,
  project-stage-detect, changelog, patch-notes, onboard (read-only/format)
- model: opus → review-all-gdds, architecture-review, gate-check
  (multi-doc synthesis, high-stakes verdicts)

PostCompact hook:
- New .claude/hooks/post-compact.sh — fires after compaction, reminds
  Claude to re-read production/session-state/active.md to restore context
- Registered in settings.json between PreCompact and Stop

Parallel Task spawning:
- review-all-gdds: Phase 2 (consistency) and Phase 3 (design theory) now
  explicitly instructed to spawn as parallel Task agents simultaneously

Error Recovery Protocol:
- Standard BLOCKED-handling section added to: review-all-gdds,
  architecture-review, dev-story, team-combat, team-qa, team-narrative,
  team-level, team-ui, team-audio, team-release, team-polish
- Pattern: surface blocker → assess dependencies → offer 3 options via
  AskUserQuestion → always produce partial report

Coordination rules:
- Added Model Tier Assignment table with routing rationale
- Added Subagents vs Agent Teams section (experimental agent teams docs)
- Added Parallel Task Protocol (when/how to spawn parallel agents)

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

.claude/docs/coordination-rules.md

@@ -11,3 +11,63 @@
    `producer` agent coordinates the propagation.
 5. **No Unilateral Cross-Domain Changes**: An agent must never modify files
    outside its designated directories without explicit delegation.
+
+## Model Tier Assignment
+
+Skills and agents are assigned to model tiers based on task complexity:
+
+| Tier | Model | When to use |
+|------|-------|-------------|
+| **Haiku** | `claude-haiku-4-5-20251001` | Read-only status checks, formatting, simple lookups — no creative judgment needed |
+| **Sonnet** | `claude-sonnet-4-6` | Implementation, design authoring, analysis of individual systems — default for most work |
+| **Opus** | `claude-opus-4-6` | Multi-document synthesis, high-stakes phase gate verdicts, cross-system holistic review |
+
+Skills with `model: haiku`: `/help`, `/sprint-status`, `/story-readiness`, `/scope-check`,
+`/project-stage-detect`, `/changelog`, `/patch-notes`, `/onboard`
+
+Skills with `model: opus`: `/review-all-gdds`, `/architecture-review`, `/gate-check`
+
+All other skills default to Sonnet. When creating new skills, assign Haiku if the
+skill only reads and formats; assign Opus if it must synthesize 5+ documents with
+high-stakes output; otherwise leave unset (Sonnet).
+
+## Subagents vs Agent Teams
+
+This project uses two distinct multi-agent patterns:
+
+### Subagents (current, always active)
+Spawned via `Task` within a single Claude Code session. Used by all `team-*` skills
+and orchestration skills. Subagents share the session's permission context, run
+sequentially or in parallel within the session, and return results to the parent.
+
+**When to spawn in parallel**: If two subagents' inputs are independent (neither
+needs the other's output to begin), spawn both Task calls simultaneously rather
+than waiting. Example: `/review-all-gdds` Phase 1 (consistency) and Phase 2
+(design theory) are independent — spawn both at the same time.
+
+### Agent Teams (experimental — opt-in)
+Multiple independent Claude Code *sessions* running simultaneously, coordinated
+via a shared task list. Each session has its own context window and token budget.
+Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable.
+
+**Use agent teams when**:
+- Work spans multiple subsystems that will not touch the same files
+- Each workstream would take >30 minutes and benefits from true parallelism
+- A senior agent (technical-director, producer) needs to coordinate 3+ specialist
+  sessions working on different epics simultaneously
+
+**Do not use agent teams when**:
+- One session's output is required as input for another (use sequential subagents)
+- The task fits in a single session's context (use subagents instead)
+- Cost is a concern — each team member burns tokens independently
+
+**Current status**: Not yet used in this project. Document usage here when first adopted.
+
+## Parallel Task Protocol
+
+When an orchestration skill spawns multiple independent agents:
+
+1. Issue all independent Task calls before waiting for any result
+2. Collect all results before proceeding to dependent phases
+3. If any agent is BLOCKED, surface it immediately — do not silently skip
+4. Always produce a partial report if some agents complete and others block

.claude/hooks/post-compact.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# post-compact.sh — fires after conversation compaction
+# Reminds Claude to restore session state from the file-backed checkpoint.
+
+ACTIVE="production/session-state/active.md"
+
+echo "=== Context Restored After Compaction ==="
+
+if [ -f "$ACTIVE" ]; then
+  SIZE=$(wc -l < "$ACTIVE" 2>/dev/null || echo "?")
+  echo "Session state file exists: $ACTIVE ($SIZE lines)"
+  echo "IMPORTANT: Read this file now to restore your working context."
+  echo "It contains: current task, decisions made, files in progress, open questions."
+else
+  echo "No session state file found at $ACTIVE"
+  echo "If you were mid-task, check production/session-logs/ for the last session audit."
+fi
+
+echo "========================================="

.claude/settings.json

@@ -95,6 +95,18 @@
         ]
       }
     ],
+    "PostCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/post-compact.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "",

.claude/skills/architecture-review/SKILL.md

@@ -6,6 +6,7 @@ user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Task
 context: fork
 agent: technical-director
+model: opus
 ---
 
 # Architecture Review
@@ -583,6 +584,20 @@ After completing the review:
 
 ---
 
+## Error Recovery Protocol
+
+If any spawned agent returns BLOCKED, errors, or fails to complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" before continuing
+2. **Assess dependencies**: If the blocked agent's output is required by a later phase, do not proceed past that phase without user input
+3. **Offer options** via AskUserQuestion with three choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope (fewer GDDs, single-system focus)
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed so work is not lost
+
+---
+
 ## Collaborative Protocol
 
 1. **Read silently** — do not narrate every file read

.claude/skills/changelog/SKILL.md

@@ -7,6 +7,7 @@ allowed-tools: Read, Glob, Grep, Bash
 context: |
   !git log --oneline -30 2>/dev/null
   !git tag --list --sort=-v:refname 2>/dev/null | head -5
+model: haiku
 ---
 
 When this skill is invoked:

.claude/skills/dev-story/SKILL.md

@@ -231,6 +231,25 @@ Create `active.md` if it does not exist. Confirm: "Session state updated."
 
 ---
 
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess
+- Manifest version mismatch → show diff to user, ask whether to proceed with old rules or update story first
+
 ## Collaborative Protocol
 
 - **Load before implementing** — do not start coding until all context is loaded

.claude/skills/gate-check/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[target-phase: systems-design | technical-setup | pre-production
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write
 context: fork
+model: opus
 ---
 
 # Phase Gate Validation

.claude/skills/help/SKILL.md

@@ -6,6 +6,7 @@ user-invocable: true
 allowed-tools: Read, Glob, Grep
 context: |
   !echo "=== Live Project State ===" && echo "Stage: $(cat production/stage.txt 2>/dev/null | tr -d '[:space:]' || echo 'not set')" && echo "Latest sprint: $(ls -t production/sprints/*.md 2>/dev/null | head -1 || echo 'none')" && echo "Session state: $(head -5 production/session-state/active.md 2>/dev/null || echo 'none')"
+model: haiku
 ---
 
 # Studio Help — What Do I Do Next?

.claude/skills/onboard/SKILL.md

@@ -4,6 +4,7 @@ description: "Generates a contextual onboarding document for a new contributor o
 argument-hint: "[role|area]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write
+model: haiku
 ---
 
 When this skill is invoked:

.claude/skills/patch-notes/SKILL.md

@@ -4,6 +4,7 @@ description: "Generate player-facing patch notes from git history, sprint data,
 argument-hint: "[version] [--style brief|detailed|full]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Bash
+model: haiku
 agent: community-manager
 ---
 

.claude/skills/project-stage-detect/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[optional: role filter like 'programmer' or 'designer']"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash
 context: fork
+model: haiku
 agent: Explore
 ---
 

.claude/skills/review-all-gdds/SKILL.md

@@ -6,6 +6,7 @@ user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Bash
 context: fork
 agent: game-designer
+model: opus
 ---
 
 # Review All GDDs
@@ -81,6 +82,15 @@ If fewer than 2 system GDDs exist, stop:
 
 ---
 
+### Parallel Execution
+
+Phase 2 (Consistency) and Phase 3 (Design Theory) are independent — they read
+the same GDD inputs but produce separate reports. Spawn both as parallel Task
+agents simultaneously rather than waiting for Phase 2 to complete before
+starting Phase 3. Collect both results before writing the combined report.
+
+---
+
 ## Phase 2: Cross-GDD Consistency
 
 Work through every pair and group of GDDs to find contradictions and gaps.
@@ -568,6 +578,20 @@ verdict from this review before architecture work can begin.
 
 ---
 
+## Error Recovery Protocol
+
+If any spawned agent returns BLOCKED, errors, or fails to complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" before continuing
+2. **Assess dependencies**: If the blocked agent's output is required by a later phase, do not proceed past that phase without user input
+3. **Offer options** via AskUserQuestion with three choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope (fewer GDDs, single-system focus)
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed so work is not lost
+
+---
+
 ## Collaborative Protocol
 
 1. **Read silently** — load all GDDs before presenting anything

.claude/skills/scope-check/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[feature-name or sprint-N]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash
 context: fork
+model: haiku
 ---
 
 # Scope Check

.claude/skills/sprint-status/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[sprint-number or blank for current]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
 context: fork
+model: haiku
 ---
 
 # Sprint Status

.claude/skills/story-readiness/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[story-file-path or 'all' or 'sprint']"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
 context: fork
+model: haiku
 ---
 
 # Story Readiness

.claude/skills/team-audio/SKILL.md

@@ -88,3 +88,21 @@ Spawn the `gameplay-programmer` agent to:
 
 6. **Output a summary** with: audio event count, estimated asset count,
    implementation tasks, and any open questions between team members.
+
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess

.claude/skills/team-combat/SKILL.md

@@ -78,5 +78,23 @@ Delegate to **qa-tester**:
 - Report feature status: COMPLETE / NEEDS WORK / BLOCKED
 - List any outstanding issues and their assigned owners
 
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess
+
 ## Output
 A summary report covering: design completion status, implementation status per team member, test results, and any open issues.

.claude/skills/team-level/SKILL.md

@@ -95,3 +95,21 @@ Spawn the `qa-tester` agent to:
 
 6. **Output a summary** with: area overview, encounter count, estimated asset
    list, narrative beats, and any cross-team dependencies or open questions.
+
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess

.claude/skills/team-narrative/SKILL.md

@@ -64,5 +64,23 @@ Delegate in parallel:
 - **localization-lead**: Validate i18n compliance — check string key naming conventions, flag any strings with hardcoded formatting that won't survive translation, verify character limit headroom for languages that expand (German/Finnish typically +30%), confirm no cultural assumptions in text that would need locale-specific variants
 - **world-builder**: Finalize canon levels for all new lore entries
 
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess
+
 ## Output
 A summary report covering: narrative brief status, lore entries created/updated, dialogue lines written, level narrative integration points, consistency review results, and any unresolved contradictions.

.claude/skills/team-polish/SKILL.md

@@ -86,5 +86,23 @@ Delegate to **qa-tester**:
 - Report: READY FOR RELEASE / NEEDS MORE WORK
 - List any remaining issues with severity and recommendations
 
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess
+
 ## Output
 A summary report covering: performance before/after metrics, visual polish changes, audio polish changes, test results, and release readiness assessment.

.claude/skills/team-qa/SKILL.md

@@ -205,6 +205,24 @@ Ask: "May I write this QA sign-off report to `production/qa/qa-signoff-[sprint]-
 
 Write only after receiving approval.
 
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess
+
 ## Output
 
 A summary covering: stories in scope, smoke check result, manual QA results, bugs filed (with IDs and severities), and the final APPROVED / APPROVED WITH CONDITIONS / NOT APPROVED verdict.

.claude/skills/team-release/SKILL.md

@@ -95,5 +95,23 @@ Delegate to **community-manager** (in parallel with deployment):
 - **analytics-engineer**: Confirm live dashboards are healthy; alert if any critical events are missing
 - Schedule post-release retrospective if issues occurred
 
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess
+
 ## Output
 A summary report covering: release version, scope, quality gate results, go/no-go decision, deployment status, and monitoring plan.

.claude/skills/team-ui/SKILL.md

@@ -123,6 +123,24 @@ All three review streams must report before proceeding to Phase 5.
 - `/team-ui [feature]` — Full pipeline from concept through polish (calls `/ux-design` and `/ux-review` internally)
 - `/quick-design` — Small UI changes that don't need a full new UX spec
 
+## Error Recovery Protocol
+
+If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+
+1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
+2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
+3. **Offer options** via AskUserQuestion with choices:
+   - Skip this agent and note the gap in the final report
+   - Retry with narrower scope
+   - Stop here and resolve the blocker first
+4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+
+Common blockers:
+- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
+- ADR status is Proposed → do not implement; run `/architecture-decision` first
+- Scope too large → split into two stories via `/create-stories`
+- Conflicting instructions between ADR and story → surface the conflict, do not guess
+
 ## Output
 
 A summary report covering: UX spec status, UX review verdict, visual design status, implementation status, accessibility compliance, input method support, interaction pattern library update status, and any outstanding issues.