oh-my-customcode 0.19.4 → 0.21.0

package/README.md

@@ -21,7 +21,7 @@ Like oh-my-zsh transformed shell customization, oh-my-customcode makes personali
 
 | Feature | Description |
 |---------|-------------|
-| **Batteries Included** | 41 agents, 55 skills, 22 guides, 18 rules, 2 hooks, 4 contexts, ontology graph - ready to use out of the box |
+| **Batteries Included** | 41 agents, 60 skills, 22 guides, 18 rules, 2 hooks, 4 contexts, ontology graph - ready to use out of the box |
 | **Sub-Agent Model** | Supports hierarchical agent orchestration with specialized roles |
 | **Dead Simple Customization** | Create a folder + markdown file = new agent or skill |
 | **Mix and Match** | Use built-in components, create your own, or combine both |
@@ -124,20 +124,20 @@ Claude Code selects the appropriate model and parallelizes independent tasks (up
 | **QA** | 3 | qa-planner, qa-writer, qa-engineer |
 | **Total** | **41** | |
 
-### Skills (56)
+### Skills (60)
 
 | Category | Count | Skills |
 |----------|-------|--------|
 | **Routing** | 4 | secretary-routing, dev-lead-routing, de-lead-routing, qa-lead-routing |
 | **Best Practices** | 18 | go-best-practices, python-best-practices, typescript-best-practices, kotlin-best-practices, rust-best-practices, react-best-practices, fastapi-best-practices, springboot-best-practices, go-backend-best-practices, docker-best-practices, aws-best-practices, postgres-best-practices, supabase-postgres-best-practices, redis-best-practices, airflow-best-practices, dbt-best-practices, kafka-best-practices, snowflake-best-practices |
-| **Development** | 5 | dev-review, dev-refactor, create-agent, intent-detection, web-design-guidelines |
+| **Development** | 6 | dev-review, dev-refactor, create-agent, intent-detection, web-design-guidelines, analysis |
 | **Data Engineering** | 2 | spark-best-practices, pipeline-architecture-patterns |
 | **Optimization** | 3 | optimize-analyze, optimize-bundle, optimize-report |
 | **Memory** | 3 | memory-save, memory-recall, memory-management |
 | **Package Management** | 3 | npm-publish, npm-version, npm-audit |
 | **Operations** | 7 | update-docs, update-external, audit-agents, fix-refs, sauron-watch, monitoring-setup, claude-code-bible |
 | **Utilities** | 5 | lists, help, status, result-aggregation, writing-clearly-and-concisely |
-| **Quality & Workflow** | 2 | multi-model-verification, structured-dev-cycle |
+| **Quality & Workflow** | 6 | multi-model-verification, structured-dev-cycle, model-escalation, stuck-recovery, dag-orchestration, task-decomposition |
 | **Deploy** | 2 | vercel-deploy, codex-exec |
 | **External** | 1 | skills-sh-search |
 
@@ -225,7 +225,7 @@ your-project/
     │   ├── be-fastapi-expert.md
     │   ├── mgr-creator.md
     │   └── ...
-    ├── skills/            # Skill modules (55 directories, each with SKILL.md)
+    ├── skills/            # Skill modules (60 directories, each with SKILL.md)
     │   ├── go-best-practices/
     │   ├── react-best-practices/
     │   ├── secretary-routing/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-customcode",
-  "version": "0.19.4",
+  "version": "0.21.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/hooks/hooks.json

@@ -76,6 +76,10 @@
           {
             "type": "command",
             "command": "bash .claude/hooks/scripts/agent-teams-advisor.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/model-escalation-advisor.sh"
           }
         ],
         "description": "HUD statusline + R010 git delegation guard + R018 Agent Teams advisor on Task spawn"
@@ -163,6 +167,26 @@
           }
         ],
         "description": "Type check Python files with ty after edits"
+      },
+      {
+        "matcher": "tool == \"Task\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/task-outcome-recorder.sh"
+          }
+        ],
+        "description": "Record task outcomes (success/failure) for model escalation decisions"
+      },
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"Bash\" || tool == \"Task\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/stuck-detector.sh"
+          }
+        ],
+        "description": "Detect repetitive failure loops and advise recovery strategies"
       }
     ],
     "Stop": [

package/templates/.claude/hooks/scripts/model-escalation-advisor.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+set -euo pipefail
+
+# Model Escalation Advisor Hook
+# Trigger: PreToolUse, tool == "Task"
+# Purpose: Advise model escalation when failure patterns detected
+# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+
+input=$(cat)
+
+# Extract current task info
+agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // "unknown"')
+current_model=$(echo "$input" | jq -r '.tool_input.model // "inherit"')
+
+# Session-scoped outcome log
+OUTCOME_FILE="/tmp/.claude-task-outcomes-${PPID}"
+
+# Skip if no history
+if [ ! -f "$OUTCOME_FILE" ]; then
+  echo "$input"
+  exit 0
+fi
+
+# Thresholds
+FAILURE_THRESHOLD=2
+CONSECUTIVE_THRESHOLD=3
+COOLDOWN=5
+
+# Count failures for this agent type
+agent_failures=0
+if [ -n "$agent_type" ] && [ "$agent_type" != "unknown" ]; then
+  agent_failures=$(grep -c "\"agent_type\":\"${agent_type}\".*\"outcome\":\"failure\"" "$OUTCOME_FILE" 2>/dev/null || echo "0")
+fi
+
+# Count consecutive failures (tail entries)
+consecutive_failures=$(tail -${CONSECUTIVE_THRESHOLD} "$OUTCOME_FILE" 2>/dev/null | grep -c '"outcome":"failure"' 2>/dev/null || echo "0")
+
+# Escalation path
+next_model=""
+cost_multiplier=""
+case "$current_model" in
+  haiku)
+    next_model="sonnet"
+    cost_multiplier="~3-5x"
+    ;;
+  sonnet)
+    next_model="opus"
+    cost_multiplier="~5-10x"
+    ;;
+  *)
+    next_model=""
+    ;;
+esac
+
+# Advise escalation
+if [ -n "$next_model" ]; then
+  should_advise=false
+  reason=""
+
+  if [ "$agent_failures" -ge "$FAILURE_THRESHOLD" ]; then
+    should_advise=true
+    reason="${agent_type} failed ${agent_failures}x with ${current_model}"
+  elif [ "$consecutive_failures" -ge "$CONSECUTIVE_THRESHOLD" ]; then
+    should_advise=true
+    reason="${consecutive_failures} consecutive failures"
+  fi
+
+  if [ "$should_advise" = true ]; then
+    echo "" >&2
+    echo "--- [Model Escalation Advisory] ---" >&2
+    echo "  Agent type: ${agent_type}" >&2
+    echo "  Current model: ${current_model}" >&2
+    echo "  ⚡ Recommended: Escalate to ${next_model}" >&2
+    echo "  Cost impact: ${cost_multiplier} per task" >&2
+    echo "  Reason: ${reason}" >&2
+    echo "------------------------------------" >&2
+  fi
+fi
+
+# De-escalation check
+if [ "$current_model" != "haiku" ] && [ "$current_model" != "inherit" ] && [ "$current_model" != "" ]; then
+  recent_successes=$(tail -${COOLDOWN} "$OUTCOME_FILE" 2>/dev/null | grep -c '"outcome":"success"' 2>/dev/null || echo "0")
+
+  if [ "$recent_successes" -ge "$COOLDOWN" ]; then
+    lower_model=""
+    case "$current_model" in
+      opus) lower_model="sonnet" ;;
+      sonnet) lower_model="haiku" ;;
+    esac
+
+    if [ -n "$lower_model" ]; then
+      echo "" >&2
+      echo "--- [Model De-escalation Advisory] ---" >&2
+      echo "  ↓ Consider: ${current_model} → ${lower_model}" >&2
+      echo "  ${recent_successes} consecutive successes" >&2
+      echo "--------------------------------------" >&2
+    fi
+  fi
+fi
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/stuck-detector.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+set -euo pipefail
+
+# Stuck Detector Hook
+# Trigger: PostToolUse, tool matches "Edit|Write|Bash|Task"
+# Purpose: Detect repetitive failure loops and advise recovery
+# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+
+input=$(cat)
+
+# Extract tool info
+tool_name=$(echo "$input" | jq -r '.tool_name // "unknown"')
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.command // ""' | head -c 120)
+is_error=$(echo "$input" | jq -r '.tool_output.is_error // false')
+output_preview=$(echo "$input" | jq -r '.tool_output.output // ""' | head -c 200)
+
+# Session-scoped history
+HISTORY_FILE="/tmp/.claude-tool-history-${PPID}"
+
+# Create entry
+timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Generate error hash for deduplication (first 50 chars of error)
+error_hash=""
+if [ "$is_error" = "true" ]; then
+  error_hash=$(echo "$output_preview" | head -c 50 | md5sum 2>/dev/null | cut -d' ' -f1 || echo "unknown")
+fi
+
+entry=$(jq -n \
+  --arg ts "$timestamp" \
+  --arg tool "$tool_name" \
+  --arg path "$file_path" \
+  --arg err "$is_error" \
+  --arg hash "$error_hash" \
+  --arg preview "$output_preview" \
+  '{timestamp: $ts, tool: $tool, path: $path, is_error: $err, error_hash: $hash, preview: $preview}')
+
+echo "$entry" >> "$HISTORY_FILE"
+
+# Ring buffer: keep last 100 entries
+if [ -f "$HISTORY_FILE" ]; then
+  line_count=$(wc -l < "$HISTORY_FILE")
+  if [ "$line_count" -gt 100 ]; then
+    tail -100 "$HISTORY_FILE" > "${HISTORY_FILE}.tmp"
+    mv "${HISTORY_FILE}.tmp" "$HISTORY_FILE"
+  fi
+fi
+
+# --- Detection Logic ---
+
+# Only check for patterns if we have enough history
+if [ ! -f "$HISTORY_FILE" ]; then
+  echo "$input"
+  exit 0
+fi
+
+recent_count=$(wc -l < "$HISTORY_FILE")
+if [ "$recent_count" -lt 3 ]; then
+  echo "$input"
+  exit 0
+fi
+
+stuck_detected=false
+signal_type=""
+pattern_desc=""
+occurrence_count=0
+threshold=0
+recovery=""
+
+# Signal 1: Repeated error (same error_hash 3+ times in last 10 entries)
+if [ "$is_error" = "true" ] && [ -n "$error_hash" ]; then
+  error_repeat=$(tail -10 "$HISTORY_FILE" | grep -c "\"error_hash\":\"${error_hash}\"" 2>/dev/null || echo "0")
+  if [ "$error_repeat" -ge 3 ]; then
+    stuck_detected=true
+    signal_type="Repeated error"
+    pattern_desc="Same error appeared ${error_repeat} times in last 10 tool calls"
+    occurrence_count=$error_repeat
+    threshold=3
+    recovery="Rephrase the task or try a different approach"
+  fi
+fi
+
+# Signal 2: Edit loop (same file edited 3+ times in last 8 entries)
+if [ "$stuck_detected" = false ] && { [ "$tool_name" = "Edit" ] || [ "$tool_name" = "Write" ]; }; then
+  if [ -n "$file_path" ]; then
+    escaped_path=$(echo "$file_path" | sed 's/[.[\*^$()+?{|]/\\&/g')
+    edit_repeat=$(tail -8 "$HISTORY_FILE" | grep -c "\"path\":\"${escaped_path}\"" 2>/dev/null || echo "0")
+    if [ "$edit_repeat" -ge 3 ]; then
+      stuck_detected=true
+      signal_type="Edit loop"
+      pattern_desc="$(basename "$file_path") edited ${edit_repeat} times in last 8 calls"
+      occurrence_count=$edit_repeat
+      threshold=3
+      recovery="Try a different file or approach instead of re-editing"
+    fi
+  fi
+fi
+
+# Signal 3: Tool spam (same tool 5+ times in last 8 entries)
+if [ "$stuck_detected" = false ]; then
+  tool_repeat=$(tail -8 "$HISTORY_FILE" | grep -c "\"tool\":\"${tool_name}\"" 2>/dev/null || echo "0")
+  if [ "$tool_repeat" -ge 5 ]; then
+    stuck_detected=true
+    signal_type="Tool loop"
+    pattern_desc="${tool_name} called ${tool_repeat} times in last 8 calls"
+    occurrence_count=$tool_repeat
+    threshold=5
+    recovery="Step back and reconsider the approach"
+  fi
+fi
+
+# Output advisory if stuck detected
+if [ "$stuck_detected" = true ]; then
+  echo "" >&2
+  echo "--- [Stuck Detection] Loop detected ---" >&2
+  echo "  Signal: ${signal_type}" >&2
+  echo "  Pattern: ${pattern_desc}" >&2
+  echo "  Occurrences: ${occurrence_count}/${threshold}" >&2
+  echo "  💡 Recovery: ${recovery}" >&2
+  echo "----------------------------------------" >&2
+fi
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/task-outcome-recorder.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+set -euo pipefail
+
+# Task Outcome Recorder Hook
+# Trigger: PostToolUse, tool == "Task"
+# Purpose: Record task outcomes for model escalation decisions
+# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+
+input=$(cat)
+
+# Extract task info
+agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // "unknown"')
+model=$(echo "$input" | jq -r '.tool_input.model // "inherit"')
+description=$(echo "$input" | jq -r '.tool_input.description // ""' | head -c 80)
+
+# Determine outcome
+is_error=$(echo "$input" | jq -r '.tool_output.is_error // false')
+
+if [ "$is_error" = "true" ]; then
+  outcome="failure"
+  error_summary=$(echo "$input" | jq -r '.tool_output.output // ""' | head -c 200)
+else
+  outcome="success"
+  error_summary=""
+fi
+
+# Session-scoped outcome log
+OUTCOME_FILE="/tmp/.claude-task-outcomes-${PPID}"
+
+# Append JSON line entry
+timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+entry=$(jq -n \
+  --arg ts "$timestamp" \
+  --arg agent "$agent_type" \
+  --arg model "$model" \
+  --arg outcome "$outcome" \
+  --arg desc "$description" \
+  --arg err "$error_summary" \
+  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, description: $desc, error_summary: $err}')
+
+echo "$entry" >> "$OUTCOME_FILE"
+
+# Ring buffer: keep last 50 entries
+if [ -f "$OUTCOME_FILE" ]; then
+  line_count=$(wc -l < "$OUTCOME_FILE")
+  if [ "$line_count" -gt 50 ]; then
+    tail -50 "$OUTCOME_FILE" > "${OUTCOME_FILE}.tmp"
+    mv "${OUTCOME_FILE}.tmp" "$OUTCOME_FILE"
+  fi
+fi
+
+# Report failures to stderr
+if [ "$outcome" = "failure" ]; then
+  echo "" >&2
+  echo "--- [Task Outcome] FAILURE: ${agent_type}:${model} ---" >&2
+  echo "  ${description}" >&2
+  echo "  Error: $(echo "$error_summary" | head -c 100)" >&2
+  echo "-----------------------------------------------" >&2
+fi
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/rules/MUST-agent-design.md

@@ -26,8 +26,22 @@ source:                    # For external agents
   origin: github | npm
   url: https://...
   version: 1.0.0
+escalation:              # Model escalation policy (optional)
+  enabled: true          # Enable auto-escalation advisory
+  path: haiku → sonnet → opus  # Escalation sequence
+  threshold: 2           # Failures before advisory
 ```
 
+### Escalation Policy
+
+When `escalation.enabled: true`, the model-escalation hooks will track outcomes for this agent type and advise escalation when failures exceed the threshold. This is advisory-only — the orchestrator decides whether to accept the recommendation.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | false | Enable escalation tracking for this agent |
+| `path` | haiku → sonnet → opus | Model upgrade sequence |
+| `threshold` | 2 | Failure count before escalation advisory |
+
 ## Memory Scopes
 
 | Scope | Location | Git Tracked |

package/templates/.claude/skills/dag-orchestration/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: dag-orchestration
+description: YAML-based DAG workflow engine with topological execution and failure strategies
+---
+
+# DAG Orchestration Skill
+
+Defines and executes directed acyclic graph (DAG) workflows. The orchestrator uses this skill to plan multi-step tasks with dependencies, execute them in topologically-sorted order, and handle failures.
+
+**Orchestrator-only** — only the main conversation uses this skill (R010). Subagents execute individual nodes.
+
+## Workflow Spec Format
+
+```yaml
+# .claude/workflows/<name>.yaml or inline in conversation
+workflow:
+  name: feature-implementation
+  description: Implement a new feature with tests and docs
+
+nodes:
+  - id: analyze
+    agent: Explore
+    model: haiku
+    prompt: "Analyze codebase for integration points"
+
+  - id: implement
+    agent: lang-typescript-expert
+    model: sonnet
+    prompt: "Implement the feature"
+    depends_on: [analyze]
+
+  - id: test
+    agent: qa-engineer
+    model: sonnet
+    prompt: "Write and run tests"
+    depends_on: [implement]
+
+  - id: review
+    agent: lang-typescript-expert
+    model: opus
+    prompt: "Code review"
+    depends_on: [implement]
+
+  - id: docs
+    agent: arch-documenter
+    model: sonnet
+    prompt: "Update documentation"
+    depends_on: [implement]
+
+  - id: commit
+    agent: mgr-gitnerd
+    model: sonnet
+    prompt: "Commit changes"
+    depends_on: [test, review, docs]
+
+config:
+  max_parallel: 4          # R009 limit
+  failure_strategy: stop   # stop | skip | retry
+  retry_count: 2           # Max retries per node (if strategy=retry)
+  timeout_per_node: 300    # Seconds per node (0 = no limit)
+```
+
+## Execution Algorithm — Kahn's Topological Sort
+
+```
+1. Parse workflow YAML
+2. Build adjacency list and in-degree map
+3. Validate: detect cycles (error if found)
+4. Initialize queue with nodes where in-degree = 0
+5. While queue is not empty:
+   a. Dequeue up to max_parallel nodes
+   b. Execute nodes in parallel via Task tool (R009)
+   c. On completion:
+      - Success → decrement in-degree of dependents
+      - Failure → apply failure_strategy
+   d. Enqueue newly-ready nodes (in-degree = 0)
+6. Verify all nodes executed (detect unreachable nodes)
+```
+
+## Execution Rules
+
+| Rule | Detail |
+|------|--------|
+| Max parallel | 4 concurrent nodes (R009) |
+| Agent Teams gate | 3+ parallel nodes → check R018 eligibility |
+| Orchestrator only | DAG scheduling runs in main conversation (R010) |
+| Node execution | Each node = one Task tool call to specified agent |
+| State tracking | `/tmp/.claude-dag-$PPID.json` |
+
+## Failure Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `stop` | Halt entire DAG on first failure (default) |
+| `skip` | Mark failed node as skipped, continue dependents with warning |
+| `retry` | Retry failed node up to `retry_count` times, then stop |
+
+## State File Format
+
+```json
+{
+  "workflow": "feature-implementation",
+  "started_at": "2026-03-07T10:00:00Z",
+  "status": "running",
+  "nodes": {
+    "analyze": {"status": "completed", "started": "...", "completed": "..."},
+    "implement": {"status": "running", "started": "..."},
+    "test": {"status": "pending"},
+    "review": {"status": "pending"},
+    "docs": {"status": "pending"},
+    "commit": {"status": "blocked", "blocked_by": ["test", "review", "docs"]}
+  },
+  "execution_order": [["analyze"], ["implement"], ["test", "review", "docs"], ["commit"]]
+}
+```
+
+## Display Format
+
+```
+[DAG] feature-implementation — 6 nodes
+[Layer 0] analyze ← running
+[Layer 1] implement ← pending (depends: analyze)
+[Layer 2] test, review, docs ← pending (parallel, depends: implement)
+[Layer 3] commit ← blocked (depends: test, review, docs)
+```
+
+Progress:
+```
+[DAG Progress] 3/6 nodes completed
+  ✓ analyze (12s)
+  ✓ implement (45s)
+  → test (running)
+  → review (running)
+  → docs (running)
+  ○ commit (blocked)
+```
+
+## Common Workflow Templates
+
+### Feature Implementation
+```yaml
+nodes: [analyze → implement → [test, review, docs] → commit]
+```
+
+### Code Review + Fix
+```yaml
+nodes: [review → fix → re-review → commit]
+failure_strategy: retry
+```
+
+### Multi-Language Project
+```yaml
+nodes: [
+  analyze → [impl-frontend, impl-backend, impl-db] → integration-test → commit
+]
+```
+
+### Refactoring
+```yaml
+nodes: [
+  analyze → plan → [refactor-1, refactor-2, refactor-3] → test → review → commit
+]
+```
+
+## Integration
+
+| Rule | Integration |
+|------|-------------|
+| R009 | Max 4 parallel nodes; independent nodes MUST parallelize |
+| R010 | DAG scheduler runs only in orchestrator |
+| R015 | Display DAG plan before execution |
+| R018 | 3+ parallel nodes → check Agent Teams eligibility |
+| model-escalation | Node failures feed into task-outcome-recorder |
+| stuck-recovery | Repeated node failures trigger stuck detection |
+
+## Inline DAG
+
+For ad-hoc workflows without a YAML file:
+
+```
+[DAG Plan]
+1. analyze (Explore:haiku)
+2. implement (lang-typescript-expert:sonnet) ← depends: 1
+3. test (qa-engineer:sonnet) ← depends: 2
+4. review (lang-typescript-expert:opus) ← depends: 2
+5. commit (mgr-gitnerd:sonnet) ← depends: 3, 4
+
+Execute? [Y/n]
+```
+
+The orchestrator builds the DAG from this inline format and executes using the same algorithm.
+
+## Limitations
+
+- No cycles allowed (DAG = acyclic)
+- Max 20 nodes per workflow (complexity guard)
+- Nested DAGs not supported (flatten instead)
+- Cross-workflow dependencies not supported

package/templates/.claude/skills/model-escalation/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: model-escalation
+description: Advisory model escalation based on task outcome tracking
+---
+
+# Model Escalation Skill
+
+Tracks task outcomes and advises model upgrades when failures are detected. **Advisory-only** — the orchestrator makes the final decision (R010).
+
+## Escalation Path
+
+```
+haiku → sonnet → opus
+```
+
+## Trigger Conditions
+
+| Condition | Action |
+|-----------|--------|
+| 2+ failures with same model for same agent type | Advise escalation |
+| 3+ consecutive failures across any agent type | Advise global escalation |
+| Sustained success after escalation | Advise de-escalation |
+
+## Thresholds
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `failure_threshold` | 2 | Failures before escalation advisory |
+| `consecutive_threshold` | 3 | Consecutive failures for global advisory |
+| `cooldown_tasks` | 5 | Successes before de-escalation advisory |
+
+## Cost Guard
+
+- Advisory includes estimated cost multiplier
+- De-escalation suggested after sustained success at higher tier
+- Cost tracked per session via PPID-scoped temp file
+
+## Architecture
+
+```
+PostToolUse (Task) → task-outcome-recorder.sh
+  Records: agent_type, model, success/failure, error_summary
+  Storage: /tmp/.claude-task-outcomes-$PPID (JSON lines, max 50)
+
+PreToolUse (Task) → model-escalation-advisor.sh
+  Reads outcomes → counts failures → advises escalation via stderr
+  Advisory only — never blocks, never modifies tool input
+```
+
+## Advisory Format
+
+```
+--- [Model Escalation Advisory] ---
+  Agent type: {agent_type}
+  Current model: {current_model}
+  Recent failures: {count}/{threshold}
+  ⚡ Recommended: Escalate to {next_model}
+  Cost impact: {multiplier} per task
+---
+```

package/templates/.claude/skills/stuck-recovery/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: stuck-recovery
+description: Detect stuck loops and advise recovery strategies
+---
+
+# Stuck Recovery Skill
+
+Detects when tasks are stuck in repetitive failure loops and advises recovery strategies. **Advisory-only** — the orchestrator decides the action (R010).
+
+## Detection Signals
+
+| Signal | Pattern | Threshold |
+|--------|---------|-----------|
+| Repeated error | Same error message appears 3+ times | 3 occurrences |
+| Edit loop | Same file edited 3+ times in sequence | 3 edits |
+| Agent retry | Same agent_type fails 3+ times consecutively | 3 failures |
+| Tool loop | Same tool called 5+ times with similar input | 5 calls |
+
+## Recovery Strategies
+
+| Strategy | When | Action |
+|----------|------|--------|
+| Fresh context | Repeated same error | Suggest rephrasing the task |
+| Model escalation | Agent retry loop | Trigger model-escalation advisory |
+| Alternative approach | Edit loop detected | Suggest different file/method |
+| Human intervention | All automated strategies exhausted | Ask user for guidance |
+
+## Architecture
+
+```
+PostToolUse (Edit, Write, Bash, Task) → stuck-detector.sh
+  Tracks: tool_name, file_path, error_hash, agent_type
+  Storage: /tmp/.claude-tool-history-$PPID (JSON lines, max 100)
+  Detection: sliding window pattern matching
+  Output: stderr advisory when loop detected
+```
+
+## Advisory Format
+
+```
+--- [Stuck Detection] Loop detected ---
+  Signal: {signal_type}
+  Pattern: {description}
+  Occurrences: {count}/{threshold}
+  💡 Recovery: {suggested_strategy}
+---
+```
+
+## Integration
+
+- Complements model-escalation skill (escalation is one recovery strategy)
+- Respects R010 (advisory only, orchestrator decides)
+- Uses same PPID-scoped temp file pattern as other hooks
+- Works with task-outcome-recorder.sh data when available

package/templates/.claude/skills/task-decomposition/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: task-decomposition
+description: Auto-decompose large tasks into DAG-compatible parallel subtasks
+---
+
+# Task Decomposition Skill
+
+Analyzes task complexity and decomposes large tasks into smaller, parallelizable subtasks compatible with the DAG orchestration skill. The orchestrator uses this as a planning frontend before execution.
+
+## Trigger Conditions
+
+Decomposition is **recommended** when any of these thresholds are met:
+
+| Trigger | Threshold | Rationale |
+|---------|-----------|-----------|
+| Estimated duration | > 30 minutes | Too long for single agent |
+| Files affected | > 3 files | Parallelizable across files |
+| Domains involved | > 2 domains | Requires multiple specialists |
+| Agent types needed | > 2 types | Cross-specialty coordination |
+
+## Decomposition Process
+
+```
+1. Analyze task scope
+   ├── Estimate duration, file count, domains
+   ├── Identify required agent types
+   └── Check trigger thresholds
+
+2. If thresholds met → decompose:
+   ├── Break into atomic subtasks (single agent, single concern)
+   ├── Identify dependencies between subtasks
+   ├── Map subtasks to agents (use routing skills)
+   └── Generate DAG workflow spec
+
+3. Present plan to user (R015 transparency)
+   ├── Show decomposed subtasks with agents
+   ├── Show dependency graph
+   ├── Show estimated parallel execution time
+   └── Request confirmation before execution
+
+4. Execute via dag-orchestration skill
+```
+
+## Decomposition Heuristics
+
+### By File Independence
+```
+Task: "Update auth module across 5 files"
+  ├── auth.ts → lang-typescript-expert
+  ├── middleware.ts → lang-typescript-expert
+  ├── config.ts → lang-typescript-expert (independent)
+  ├── auth.test.ts → qa-engineer (depends: auth.ts)
+  └── README.md → arch-documenter (depends: all above)
+
+DAG: [auth.ts, middleware.ts, config.ts] → auth.test.ts → README.md
+```
+
+### By Domain Separation
+```
+Task: "Add user profile feature with API and UI"
+  ├── API endpoint → be-express-expert
+  ├── Database schema → db-postgres-expert
+  ├── Frontend component → fe-vercel-agent
+  └── Integration test → qa-engineer
+
+DAG: [API, DB] → Frontend → Integration test
+     (API and DB are independent, Frontend needs both)
+```
+
+### By Layer
+```
+Task: "Implement order processing in Spring Boot"
+  ├── Domain model → lang-kotlin-expert
+  ├── Repository → be-springboot-expert (depends: domain)
+  ├── Service → be-springboot-expert (depends: domain, repository)
+  ├── Controller → be-springboot-expert (depends: service)
+  └── Tests → qa-engineer (depends: all)
+
+DAG: domain → [repository] → service → controller → tests
+```
+
+## Output Format
+
+### Decomposition Plan
+```
+[Task Decomposition]
+├── Original: "Add user authentication with JWT"
+├── Complexity: High (4 files, 3 domains, ~45 min)
+├── Decomposed into 5 subtasks:
+│
+│   [1] analyze (Explore:haiku)
+│       Scan codebase for existing auth patterns
+│
+│   [2] implement-auth (lang-typescript-expert:sonnet)
+│       Implement JWT signing and validation
+│       Depends: [1]
+│
+│   [3] implement-middleware (lang-typescript-expert:sonnet)
+│       Create auth middleware
+│       Depends: [1]
+│
+│   [4] write-tests (qa-engineer:sonnet)
+│       Write auth tests
+│       Depends: [2, 3]
+│
+│   [5] commit (mgr-gitnerd:sonnet)
+│       Commit all changes
+│       Depends: [4]
+│
+├── Parallel layers: 3 (max 2 concurrent in layer 2)
+├── Estimated time: ~20 min (vs ~45 min sequential)
+└── Proceed? [Y/n]
+```
+
+### Generated DAG Spec
+```yaml
+workflow:
+  name: auto-decomposed-auth
+  description: "Auto-decomposed: Add user authentication with JWT"
+
+nodes:
+  - id: analyze
+    agent: Explore
+    model: haiku
+    prompt: "Scan codebase for existing auth patterns"
+  - id: implement-auth
+    agent: lang-typescript-expert
+    model: sonnet
+    prompt: "Implement JWT signing and validation"
+    depends_on: [analyze]
+  - id: implement-middleware
+    agent: lang-typescript-expert
+    model: sonnet
+    prompt: "Create auth middleware"
+    depends_on: [analyze]
+  - id: write-tests
+    agent: qa-engineer
+    model: sonnet
+    prompt: "Write auth tests"
+    depends_on: [implement-auth, implement-middleware]
+  - id: commit
+    agent: mgr-gitnerd
+    model: sonnet
+    prompt: "Commit all changes"
+    depends_on: [write-tests]
+
+config:
+  max_parallel: 4
+  failure_strategy: stop
+```
+
+## Atomic Task Criteria
+
+A subtask is **atomic** when it meets ALL of:
+- Single agent can handle it
+- Single concern (one logical change)
+- Independently testable outcome
+- < 15 minutes estimated duration
+- < 3 files affected
+
+If a subtask is not atomic → decompose further (max 2 levels deep).
+
+## Skip Decomposition When
+
+| Condition | Reason |
+|-----------|--------|
+| Single file edit | Already atomic |
+| < 10 minutes estimated | Overhead not worth it |
+| User explicitly requests "just do it" | User override |
+| Single domain, single agent | No parallelization benefit |
+
+## Integration
+
+| Component | Integration |
+|-----------|-------------|
+| dag-orchestration | Generates DAG specs consumed by dag-orchestration |
+| Routing skills | Uses dev-lead/de-lead/qa-lead routing for agent mapping |
+| R009 | Maximizes parallelization within max-4 limit |
+| R010 | Decomposition happens in orchestrator only |
+| R015 | Plan displayed before execution for user approval |
+| R018 | 3+ agents in plan → check Agent Teams eligibility |

package/templates/manifest.json

@@ -18,7 +18,7 @@
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 56
+      "files": 60
     },
     {
       "name": "guides",