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/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.