specweave 1.0.203 → 1.0.205

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- SW:META template="claude" version="1.0.202" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.203" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
 
 <!-- SW:SECTION:hook-priority version="1.0.171" -->
 ## ⛔ Hook Instructions Override Everything
@@ -143,11 +143,27 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.202" -->
-## Meta-Rule: Think-Before-Act
+<!-- SW:SECTION:metarule version="1.0.203" -->
+## Workflow Orchestration
 
-**Satisfy dependencies BEFORE dependent operations.**
+### 1. Plan Mode Default
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
+- If something goes sideways, **STOP and re-plan** - don't keep pushing
+- Write detailed specs upfront to reduce ambiguity
+
+### 2. Subagent Strategy
+- Use subagents liberally to keep main context clean
+- Offload research, exploration, and parallel analysis to subagents
+- One task per subagent for focused execution
+- Append "use subagents" to requests for safe parallelization
 
+### 3. Verification Before Done
+- Never mark a task complete without proving it works
+- Ask yourself: **"Would a staff engineer approve this?"**
+- Run tests, check logs, demonstrate correctness
+
+### 4. Think-Before-Act (Dependencies)
+**Satisfy dependencies BEFORE dependent operations.**
 ```
 ❌ node script.js → Error → npm run build
 ✅ npm run build → node script.js → Success
@@ -159,7 +175,10 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 
 1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
 2. **Update immediately**: `Edit("tasks.md", "[ ] pending", "[x] completed")` + `Edit("spec.md", "[ ] AC-", "[x] AC-")`
-3. **Unique IDs**: Check `ls .specweave/increments/ | grep "^[0-9]" | tail -5`
+3. **Unique IDs**: Check ALL folders (active, archive, abandoned):
+   ```bash
+   find .specweave/increments -maxdepth 2 -type d -name "[0-9]*" | grep -oE '[0-9]{4}E?' | sort -u | tail -5
+   ```
 4. **Emergency**: "emergency mode" → 1 edit, 50 lines max, no agents
 5. **⛔ Initialization guard**: `.specweave/` folders MUST ONLY exist where `specweave init` was run
 6. **⛔ Marketplace refresh**: Use `specweave refresh-marketplace` CLI (not `scripts/refresh-marketplace.sh`)
@@ -232,14 +251,8 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 - **2026-02-02**: Enable interview process during increment creation for SpecWeave projects
 
 ### General
-- **2026-02-02**: User wants comprehensive codebase analysis to identify unused/obsolete commands and skills using multiple parallel agents (up to 40 subagents)
-- **2026-02-02**: User prefers detailed investigation and leaderboard reporting on command/skill usage patterns and deletion candidates
-- **2026-02-02**: "Use subagents" phrase triggers safe parallelization - documented in CLAUDE.md with full guidance
-- **2026-02-02**: User prefers comprehensive codebase analysis with multiple parallel agents (up to 40 subagents) for identifying unused/obsolete skills and commands
-- **2026-02-02**: User wants leaderboard-style output showing least-used commands/skills as candidates for deletion or removal
-- **2026-02-02**: User wants comprehensive codebase analysis to identify least-used commands/skills as candidates for deletion/removal - prefers large-scale investigation work with multiple parallel agents
-- **2026-02-02**: User wants comprehensive codebase analysis using multiple parallel agents (up to 40) to identify obsolete or least-used commands and skills for removal
-- **2026-02-02**: User expects detailed investigation work and leaderboard-style ranking of command/skill usage patterns
+- **2026-02-02**: Use subagents liberally for codebase analysis - up to 10+ concurrent for large-scale exploration
+- **2026-02-02**: Prefer leaderboard-style reporting when analyzing usage patterns or identifying deletion candidates
 
 <!-- SW:SECTION:context version="1.0.202" -->
 ## Context
@@ -385,7 +398,7 @@ Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.202" -->
+<!-- SW:SECTION:troubleshooting version="1.0.203" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -393,13 +406,9 @@ Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 | Skills/commands missing | Restart Claude Code |
 | Plugins outdated | `specweave refresh-marketplace` |
 | Out of sync | `/sw:sync-tasks` |
-| Find increment | `/sw:status` |
-| Root polluted | Move to `.specweave/increments/####/reports/` |
 | Duplicate IDs | `/sw:fix-duplicates` |
-| GitHub sync issues | Check config: `sync.github.enabled`, `canUpdateExternalItems` |
 | Edits blocked | Add `"additionalDirectories":["repositories"]` to `.claude/settings.json` |
-| Marketplace shows 0 | Normal with auto-load; `/plugin list` shows actual |
-| Docs folder collisions | Check: `ls docs/ \| grep -E '^[0-9]{2}-' \| cut -d'-' -f1 \| sort \| uniq -d` |
+| Session stuck | Kill + `rm -f .specweave/state/*.lock` + restart |
 <!-- SW:END:troubleshooting -->
 
 <!-- SW:SECTION:lazyloading version="1.0.202" -->
@@ -416,13 +425,20 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 **Token savings**: Core ~3-5K tokens vs all plugins ~60K+
 <!-- SW:END:lazyloading -->
 
-<!-- SW:SECTION:principles version="1.0.202" -->
+<!-- SW:SECTION:principles version="1.0.203" -->
 ## Principles
 
+### SpecWeave Principles
 1. **Spec-first**: `/sw:increment` before coding
 2. **Docs = truth**: Specs guide implementation
 3. **Incremental**: Small, validated increments
 4. **Traceable**: All work → specs → ACs
+
+### Core Principles (Quality)
+- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
+- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
+- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.
+- **Demand Elegance**: For non-trivial changes, pause and ask "is there a more elegant way?" - but skip this for simple, obvious fixes (don't over-engineer).
 <!-- SW:END:principles -->
 
 <!-- SW:SECTION:linking version="1.0.202" -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.203",
+  "version": "1.0.205",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/hooks/log-decision.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# log-decision.sh - Structured Decision Logging Utility
+#
+# Shared utility for all SpecWeave hooks to log decisions in structured JSON format.
+# Inspired by Claude Code 2.1.27's "Added tool call failures and denials to debug logs"
+#
+# Usage:
+#   source log-decision.sh
+#   log_decision "hook_name" "decision" "reason_code" "reason" "context_json" duration_ms
+#
+# Output:
+#   - Appends JSON entry to .specweave/logs/decisions.jsonl
+#   - Debug output to stderr when SPECWEAVE_DEBUG_HOOKS=1
+#
+# Schema:
+#   {
+#     "timestamp": "ISO8601",
+#     "hook": "stop-auto|stop-reflect|user-prompt-submit",
+#     "decision": "approve|block",
+#     "reason": "Human-readable reason",
+#     "reasonCode": "machine_parseable_enum",
+#     "durationMs": 123,
+#     "context": { ... hook-specific context ... }
+#   }
+
+# Max log size before rotation (10MB)
+_LOG_MAX_SIZE=10485760
+
+# Debug logging to stderr (only when SPECWEAVE_DEBUG_HOOKS=1)
+_log_debug() {
+    if [ "${SPECWEAVE_DEBUG_HOOKS:-0}" = "1" ]; then
+        local color_reset="\033[0m"
+        local color_cyan="\033[36m"
+        local color_green="\033[32m"
+        local color_red="\033[31m"
+        local color_yellow="\033[33m"
+
+        local level="$1"
+        shift
+        local message="$*"
+
+        local color="$color_cyan"
+        case "$level" in
+            "DECISION") color="$color_green" ;;
+            "BLOCK") color="$color_red" ;;
+            "WARN") color="$color_yellow" ;;
+        esac
+
+        echo -e "${color}[DEBUG]${color_reset} $message" >&2
+    fi
+}
+
+# Rotate log file if it exceeds max size
+_rotate_log_if_needed() {
+    local log_file="$1"
+
+    if [ ! -f "$log_file" ]; then
+        return 0
+    fi
+
+    local file_size
+    # Cross-platform file size (macOS vs Linux)
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        file_size=$(stat -f%z "$log_file" 2>/dev/null || echo "0")
+    else
+        file_size=$(stat -c%s "$log_file" 2>/dev/null || echo "0")
+    fi
+
+    if [ "$file_size" -gt "$_LOG_MAX_SIZE" ]; then
+        _log_debug "WARN" "Log rotation triggered (${file_size} > ${_LOG_MAX_SIZE})"
+
+        # Keep last ~5MB by taking last N lines
+        # Estimate: average 500 bytes per line, so 5MB = ~10000 lines
+        local temp_file="${log_file}.tmp"
+        tail -n 10000 "$log_file" > "$temp_file" 2>/dev/null
+        mv "$temp_file" "$log_file" 2>/dev/null
+
+        _log_debug "INFO" "Log rotated, kept last 10000 entries"
+    fi
+}
+
+# Main logging function
+# Arguments:
+#   $1: hook_name - Name of the hook (stop-auto, stop-reflect, etc.)
+#   $2: decision - Decision made (approve, block)
+#   $3: reason_code - Machine-parseable reason code (session_inactive, work_remaining, etc.)
+#   $4: reason - Human-readable reason message
+#   $5: context_json - JSON string with hook-specific context (default: "{}")
+#   $6: duration_ms - Execution time in milliseconds (default: 0)
+log_decision() {
+    local hook_name="$1"
+    local decision="$2"
+    local reason_code="$3"
+    local reason="$4"
+    local context_json="${5:-"{}"}"
+    local duration_ms="${6:-0}"
+
+    # Compute paths based on current PROJECT_ROOT
+    local project_root="${PROJECT_ROOT:-$(pwd)}"
+    local log_dir="$project_root/.specweave/logs"
+    local log_file="$log_dir/decisions.jsonl"
+
+    # Validate required arguments
+    if [ -z "$hook_name" ] || [ -z "$decision" ] || [ -z "$reason_code" ]; then
+        _log_debug "WARN" "log_decision called with missing arguments"
+        return 1
+    fi
+
+    # Ensure logs directory exists
+    if [ ! -d "$log_dir" ]; then
+        mkdir -p "$log_dir" 2>/dev/null
+        _log_debug "INFO" "Created logs directory: $log_dir"
+    fi
+
+    # Check for log rotation
+    _rotate_log_if_needed "$log_file"
+
+    # Generate ISO 8601 timestamp
+    local timestamp
+    timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date +%Y-%m-%dT%H:%M:%SZ)
+
+    # Escape special characters in reason for JSON
+    local escaped_reason
+    escaped_reason=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g; s/	/\\t/g' | tr '\n' ' ')
+
+    # Build JSON entry using jq
+    local json_entry
+    json_entry=$(jq -n -c \
+        --arg timestamp "$timestamp" \
+        --arg hook "$hook_name" \
+        --arg decision "$decision" \
+        --arg reason "$escaped_reason" \
+        --arg reasonCode "$reason_code" \
+        --argjson durationMs "$duration_ms" \
+        --argjson context "$context_json" \
+        '{
+            timestamp: $timestamp,
+            hook: $hook,
+            decision: $decision,
+            reason: $reason,
+            reasonCode: $reasonCode,
+            durationMs: $durationMs,
+            context: $context
+        }' 2>/dev/null)
+
+    # Fallback if jq fails
+    if [ -z "$json_entry" ]; then
+        json_entry="{\"timestamp\":\"$timestamp\",\"hook\":\"$hook_name\",\"decision\":\"$decision\",\"reason\":\"$escaped_reason\",\"reasonCode\":\"$reason_code\",\"durationMs\":$duration_ms,\"context\":$context_json}"
+    fi
+
+    # Append to log file
+    printf '%s\n' "$json_entry" >> "$log_file" 2>/dev/null
+
+    # Debug output
+    if [ "$decision" = "block" ]; then
+        _log_debug "BLOCK" "$hook_name: $reason_code - $reason"
+    else
+        _log_debug "DECISION" "$hook_name: $decision ($reason_code)"
+    fi
+
+    return 0
+}

package/plugins/specweave/hooks/stop-auto.sh

@@ -27,10 +27,36 @@
 
 set +e  # Don't exit on errors
 
+# Capture start time for duration tracking (macOS doesn't support %N, fallback to seconds only)
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    _START_TIME_MS=$(($(date +%s) * 1000))
+else
+    _START_TIME_MS=$(($(date +%s) * 1000 + $(date +%N 2>/dev/null | cut -c1-3 || echo "0")))
+fi
+
 # Read stdin (Claude Code passes context here)
 INPUT=$(cat)
 PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
 
+# ============================================================================
+# SOURCE STRUCTURED DECISION LOGGING
+# ============================================================================
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$SCRIPT_DIR/log-decision.sh" ]; then
+    source "$SCRIPT_DIR/log-decision.sh"
+fi
+
+# Helper to calculate duration in ms (macOS-compatible)
+_get_duration_ms() {
+    local end_time_ms
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        end_time_ms=$(($(date +%s) * 1000))
+    else
+        end_time_ms=$(($(date +%s) * 1000 + $(date +%N 2>/dev/null | cut -c1-3 || echo "0")))
+    fi
+    echo $((end_time_ms - _START_TIME_MS))
+}
+
 # ============================================================================
 # LOGGING
 # ============================================================================
@@ -46,7 +72,17 @@ log() {
 # SILENT APPROVE - Normal sessions get NO output
 # ============================================================================
 silent_approve() {
-    log "APPROVE: $1"
+    local reason="$1"
+    local reason_code="${2:-session_inactive}"
+    local context_json="${3:-"{}"}"
+
+    log "APPROVE: $reason"
+
+    # Log structured decision if log_decision function is available
+    if type log_decision &>/dev/null; then
+        log_decision "stop-auto" "approve" "$reason_code" "$reason" "$context_json" "$(_get_duration_ms)"
+    fi
+
     echo '{"decision":"approve"}'
     exit 0
 }
@@ -60,8 +96,8 @@ INCREMENTS_DIR="$SPECWEAVE_DIR/increments"
 CONFIG_FILE="$SPECWEAVE_DIR/config.json"
 
 # Not a SpecWeave project - silent approve
-[ ! -d "$SPECWEAVE_DIR" ] && silent_approve "Not a SpecWeave project"
-[ ! -d "$INCREMENTS_DIR" ] && silent_approve "No increments directory"
+[ ! -d "$SPECWEAVE_DIR" ] && silent_approve "Not a SpecWeave project" "not_specweave_project" "{}"
+[ ! -d "$INCREMENTS_DIR" ] && silent_approve "No increments directory" "no_increments_dir" "{}"
 
 # ============================================================================
 # STATE DIRECTORY (MUST be defined BEFORE AUTO_SESSION_FILE check)
@@ -101,7 +137,7 @@ if [ -f "$CONFIG_FILE" ]; then
 fi
 
 # Auto mode disabled in config - silent approve
-[ "$AUTO_ENABLED" != "true" ] && silent_approve "Auto mode disabled in config"
+[ "$AUTO_ENABLED" != "true" ] && silent_approve "Auto mode disabled in config" "auto_disabled" "{}"
 
 # ============================================================================
 # CHECK FOR AUTO MODE SESSION - Only block if explicitly activated
@@ -112,7 +148,7 @@ AUTO_SESSION_FILE="$STATE_DIR/auto-mode.json"
 
 # If no auto-mode.json exists, auto mode was never started this session
 if [ ! -f "$AUTO_SESSION_FILE" ]; then
-    silent_approve "Auto mode not activated (no session file)"
+    silent_approve "Auto mode not activated (no session file)" "session_inactive" '{"sessionActive":false}'
 fi
 
 # STALENESS CHECK: If session file is older than 30 minutes, it's stale
@@ -129,13 +165,13 @@ if [ "$SESSION_AGE" -gt "$MAX_SESSION_AGE" ]; then
     rm -f "$STATE_DIR/.stop-auto-dedup" 2>/dev/null
     rm -f "$STATE_DIR/.stop-auto-retry" 2>/dev/null
     rm -f "$STATE_DIR/.stop-auto-turns" 2>/dev/null  # Also clear turn counter
-    silent_approve "Stale auto-mode session cleared (inactive for ${SESSION_AGE}s)"
+    silent_approve "Stale auto-mode session cleared (inactive for ${SESSION_AGE}s)" "session_stale" "$(jq -n --argjson age "$SESSION_AGE" --argjson maxAge "$MAX_SESSION_AGE" '{sessionAge:$age,maxSessionAge:$maxAge}')"
 fi
 
 # Check if session is actually active
 AUTO_SESSION_ACTIVE=$(jq -r '.active // false' "$AUTO_SESSION_FILE" 2>/dev/null || echo "false")
 if [ "$AUTO_SESSION_ACTIVE" != "true" ]; then
-    silent_approve "Auto mode session not active"
+    silent_approve "Auto mode session not active" "session_inactive" '{"sessionActive":false}'
 fi
 
 # Update session file mtime to keep it fresh (touch it)
@@ -235,6 +271,20 @@ This is a safety mechanism to prevent runaway sessions.
    Current limit: $MAX_TURNS turns
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
+    # Log structured decision for turn limit
+    if type log_decision &>/dev/null; then
+        _turn_context=$(jq -n \
+            --argjson turnCurrent "$CURRENT_TURN" \
+            --argjson turnMax "$MAX_TURNS" \
+            --arg activeIncs "${ACTIVE_INCS:-none}" \
+            '{
+                sessionActive: true,
+                turn: {current: $turnCurrent, max: $turnMax},
+                increments: {active: ($activeIncs | split(", "))}
+            }')
+        log_decision "stop-auto" "approve" "turn_limit" "Turn limit reached: $CURRENT_TURN/$MAX_TURNS turns" "$_turn_context" "$(_get_duration_ms)"
+    fi
+
     jq -n \
         --arg decision "approve" \
         --arg reason "Turn limit reached: $CURRENT_TURN/$MAX_TURNS turns" \
@@ -255,7 +305,7 @@ if [ -f "$DEDUP_FILE" ]; then
     LAST_FIRE=$(cat "$DEDUP_FILE" 2>/dev/null || echo "0")
     ELAPSED=$((NOW - LAST_FIRE))
     [ "$ELAPSED" -gt 3600 ] && rm -f "$DEDUP_FILE" 2>/dev/null
-    [ "$ELAPSED" -lt "$DEDUP_WINDOW" ] && silent_approve "Deduplicated (${ELAPSED}s < ${DEDUP_WINDOW}s)"
+    [ "$ELAPSED" -lt "$DEDUP_WINDOW" ] && silent_approve "Deduplicated (${ELAPSED}s < ${DEDUP_WINDOW}s)" "deduplicated" "$(jq -n --argjson elapsed "$ELAPSED" --argjson window "$DEDUP_WINDOW" '{elapsed:$elapsed,dedupWindow:$window}')"
 fi
 
 mkdir -p "$STATE_DIR" 2>/dev/null
@@ -390,7 +440,10 @@ count_open_acs() {
     fi
 
     # Count unchecked ACs: - [ ] **AC-
-    grep -c '^- \[ \] \*\*AC-' "$spec_file" 2>/dev/null || echo "0"
+    # Note: grep -c returns exit code 1 when count is 0, so use a temp var
+    local count
+    count=$(grep -c '^- \[ \] \*\*AC-' "$spec_file" 2>/dev/null) || count=0
+    echo "$count"
 }
 
 # ============================================================================
@@ -738,11 +791,22 @@ if [ "$REMAINING_COUNT" -eq 0 ] && [ "$SKILL_VALIDATION_FAILED" != "true" ]; the
     clear_retry_counter
     clear_auto_session  # Clear session marker - work is done!
 
+    # Build context for logging
+    _complete_context=$(jq -n \
+        --argjson turnCurrent "$CURRENT_TURN" \
+        --argjson turnMax "$MAX_TURNS" \
+        --argjson closedCount "$CLOSED_COUNT" \
+        '{
+            sessionActive: false,
+            turn: {current: $turnCurrent, max: $turnMax},
+            closedIncrements: $closedCount
+        }')
+
     if [ "$CLOSED_COUNT" -gt 0 ]; then
         log "APPROVE: Auto-closed $CLOSED_COUNT increment(s), all work complete"
-        silent_approve "Auto-closed $CLOSED_COUNT increment(s)"
+        silent_approve "Auto-closed $CLOSED_COUNT increment(s)" "all_complete" "$_complete_context"
     else
-        silent_approve "No active increments"
+        silent_approve "No active increments" "all_complete" "$_complete_context"
     fi
 fi
 
@@ -762,6 +826,16 @@ if [ "$INCOMPLETE_COUNT" -eq 0 ] && [ "$SKILL_VALIDATION_FAILED" != "true" ]; th
 
     log "APPROVE: All tasks complete in active increments (manual close pending)"
 
+    # Log structured decision
+    if type log_decision &>/dev/null; then
+        _work_complete_context=$(jq -n \
+            --argjson turnCurrent "$CURRENT_TURN" \
+            --argjson turnMax "$MAX_TURNS" \
+            --arg readyToClose "$READY_TO_CLOSE" \
+            '{sessionActive: false, turn: {current: $turnCurrent, max: $turnMax}, increments: {active: [], readyToClose: ($readyToClose | split(" ") | map(select(length > 0)))}}')
+        log_decision "stop-auto" "approve" "work_complete" "All tasks complete - increments ready for manual close" "$_work_complete_context" "$(_get_duration_ms)"
+    fi
+
     # Show message about manual close needed
     CLOSE_MSG="
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -1010,6 +1084,18 @@ if [ "$CURRENT_RETRY" -ge "$MAX_RETRIES_BEFORE_ESCALATE" ]; then
     clear_retry_counter
     clear_auto_session  # End auto mode on circuit breaker
 
+    # Log structured decision
+    if type log_decision &>/dev/null; then
+        _circuit_context=$(jq -n \
+            --argjson turnCurrent "$CURRENT_TURN" \
+            --argjson turnMax "$MAX_TURNS" \
+            --argjson retryCurrent "$CURRENT_RETRY" \
+            --argjson retryMax "$MAX_RETRIES_BEFORE_ESCALATE" \
+            --arg activeIncs "$REMAINING_INCS" \
+            '{sessionActive: false, turn: {current: $turnCurrent, max: $turnMax}, retry: {current: $retryCurrent, max: $retryMax, stuck: true}, increments: {active: ($activeIncs | split(", ") | map(select(length > 0)))}}')
+        log_decision "stop-auto" "approve" "retry_limit" "Stuck session: $CURRENT_RETRY retries on same incomplete work" "$_circuit_context" "$(_get_duration_ms)"
+    fi
+
     jq -n \
         --arg decision "approve" \
         --arg reason "Stuck session: $CURRENT_RETRY retries on same incomplete work" \
@@ -1128,6 +1214,45 @@ Current status: $pending_count pending task(s), $open_acs open AC(s)
 Next command to run: $NEXT_COMMAND
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
+# Log structured decision before blocking
+if type log_decision &>/dev/null; then
+    # Get previous reasons from retry file
+    _prev_reasons_json="[]"
+    if [ -f "$RETRY_FILE" ] && [ -s "$RETRY_FILE" ]; then
+        _tmp_reasons=$(jq -c '.reasons // []' "$RETRY_FILE" 2>/dev/null)
+        [ -n "$_tmp_reasons" ] && _prev_reasons_json="$_tmp_reasons"
+    fi
+
+    # Build blocked increments array
+    _blocked_json="[]"
+    if [ -n "$FIRST_INC" ]; then
+        _blocked_json=$(jq -n \
+            --arg id "$FIRST_INC" \
+            --argjson tasksPending "$pending_count" \
+            --argjson acsOpen "$open_acs" \
+            --arg reason "$SUCCESS_CRITERIA" \
+            '[{id: $id, tasksPending: $tasksPending, acsOpen: $acsOpen, reason: $reason}]')
+    fi
+
+    # Pre-compute stuck value (avoid subshell in jq args)
+    _stuck_val="false"
+    [ "$CURRENT_RETRY" -ge "$MAX_RETRIES_BEFORE_ESCALATE" ] && _stuck_val="true"
+
+    # Build full context JSON
+    _block_context=$(jq -n \
+        --argjson turnCurrent "$CURRENT_TURN" \
+        --argjson turnMax "$MAX_TURNS" \
+        --argjson retryCurrent "$CURRENT_RETRY" \
+        --argjson retryMax "$MAX_RETRIES_BEFORE_ESCALATE" \
+        --argjson stuck "$_stuck_val" \
+        --arg activeIncs "$REMAINING_INCS" \
+        --argjson blocked "$_blocked_json" \
+        --argjson previousReasons "$_prev_reasons_json" \
+        '{sessionActive: true, turn: {current: $turnCurrent, max: $turnMax}, retry: {current: $retryCurrent, max: $retryMax, stuck: $stuck}, increments: {active: ($activeIncs | split(", ") | map(select(length > 0))), blocked: $blocked}, previousReasons: $previousReasons}')
+
+    log_decision "stop-auto" "block" "work_remaining" "$SUCCESS_CRITERIA" "$_block_context" "$(_get_duration_ms)"
+fi
+
 jq -n \
     --arg decision "block" \
     --arg reason "$ACTIONABLE_REASON" \

package/plugins/specweave/skills/image-generation/SKILL.md

@@ -1,25 +1,426 @@
 ---
 name: image-generation
-description: AI image generation using Pollinations.ai - FREE with no API key required. Use when generating hero images, icons, logos, illustrations, mockups, or any visual assets for websites and apps. Covers product shots, avatars, placeholders, and social media images with professional quality.
+description: AI image generation using Pollinations.ai with Stable Horde fallback - FREE with no API key required. Use when generating hero images, icons, logos, illustrations, mockups, or any visual assets for websites and apps. Covers product shots, avatars, placeholders, and social media images with professional quality.
 allowed-tools:
   - Read
   - Write
   - WebFetch
+  - Bash
 context: fork
 model: opus
 ---
 
 # AI Image Generation Skill
 
-Expert in generating professional-quality images using Pollinations.ai - a FREE, open-source AI image generation platform requiring NO API keys.
+Expert in generating professional-quality images using multi-provider resilience: **Pollinations.ai** (primary) with **Stable Horde** (fallback) - both FREE, no API keys required.
+
+## ⚠️ CRITICAL: Health Check First (MANDATORY)
+
+**BEFORE generating any image, ALWAYS run this CONTENT-BASED health check:**
+
+⚠️ **WARNING**: HTTP 200 status is NOT sufficient! Pollinations may return 200 but with error text instead of image data. **ALWAYS verify the response is actually an image.**
+
+```bash
+# ROBUST health check - verifies actual image content (not just HTTP status)
+TEMP_FILE=$(mktemp)
+curl -s -L -o "$TEMP_FILE" --max-time 10 "https://image.pollinations.ai/prompt/blue%20square?width=64&height=64&nologo=true"
+CONTENT_TYPE=$(file -b "$TEMP_FILE" | head -c 10)
+
+if [[ "$CONTENT_TYPE" == "PNG image" ]] || [[ "$CONTENT_TYPE" == "JPEG image" ]]; then
+    echo "✅ HEALTHY - Use Pollinations"
+else
+    echo "❌ BROKEN - Use Stable Horde (got: $CONTENT_TYPE)"
+    cat "$TEMP_FILE"  # Show error message
+fi
+rm -f "$TEMP_FILE"
+```
+
+### Decision Tree Based on CONTENT (Not Just Status)
+
+| Content Check | Meaning | Action |
+|---------------|---------|--------|
+| `PNG image data` | ✅ Healthy | Use Pollinations.ai |
+| `JPEG image data` | ✅ Healthy | Use Pollinations.ai |
+| `ASCII text` | ❌ Service error (502/503 in body) | **→ Use Stable Horde** |
+| `HTML document` | ❌ Error page | **→ Use Stable Horde** |
+| Empty/timeout | ❌ Network error | **→ Use Stable Horde** |
+
+### Automated Provider Selection Script (ROBUST VERSION)
+
+```bash
+#!/bin/bash
+# save as: check-image-api.sh
+# IMPORTANT: This checks CONTENT, not just HTTP status!
+
+TEMP_FILE=$(mktemp)
+curl -s -L -o "$TEMP_FILE" --max-time 15 \
+  "https://image.pollinations.ai/prompt/test%20square?width=64&height=64&nologo=true" 2>/dev/null
+
+CONTENT_TYPE=$(file -b "$TEMP_FILE" 2>/dev/null | cut -d',' -f1)
+rm -f "$TEMP_FILE"
+
+if [[ "$CONTENT_TYPE" == "PNG image data" ]] || [[ "$CONTENT_TYPE" == "JPEG image data" ]]; then
+    echo "PROVIDER=pollinations"
+    echo "STATUS=healthy"
+else
+    echo "PROVIDER=stablehorde"
+    echo "REASON=Pollinations returned '$CONTENT_TYPE' instead of image"
+fi
+```
+
+### Why HTTP 200 Is Misleading
+
+Pollinations.ai uses Cloudflare CDN. When the origin server is down:
+- Cloudflare returns **HTTP 200** (edge responds)
+- But the BODY contains: `502 Bad Gateway - Unable to reach the origin service`
+- This is why **content-based checking is mandatory**
+
+---
+
+## 🚨 NEVER GET STUCK Protocol (Claude Code Behavior)
+
+**This section defines how Claude Code should behave to NEVER get stuck on image generation.**
+
+### Rule 1: Always Set Timeouts
+
+```bash
+# ALWAYS use --max-time flag (15-30 seconds max)
+curl --max-time 15 "https://image.pollinations.ai/prompt/..."
+
+# NEVER use curl without timeout (can hang forever)
+curl "https://image.pollinations.ai/prompt/..."  # ❌ WRONG - can hang
+```
+
+### Rule 2: Fail Fast, Switch Immediately
+
+If ANY of these occur, **immediately switch to Stable Horde**:
+- Timeout (>15 seconds)
+- Non-image response (ASCII text, HTML)
+- HTTP 4xx/5xx errors
+- API Error 400 "Could not process image"
+
+**DO NOT:**
+- ❌ Retry more than once
+- ❌ Wait indefinitely
+- ❌ Keep trying the same failing provider
+
+### Rule 3: Check Before Acting
+
+**ALWAYS run health check BEFORE attempting image generation:**
+
+```bash
+# Quick pre-flight check (5 second max)
+TEMP=$(mktemp)
+timeout 5 curl -s -o "$TEMP" "https://image.pollinations.ai/prompt/test?width=64&height=64" 2>/dev/null
+if file "$TEMP" | grep -q "image"; then
+    echo "Provider ready"
+else
+    echo "Provider down - use Stable Horde"
+fi
+rm -f "$TEMP"
+```
+
+### Rule 4: Structured Error Handling
+
+When image generation fails, follow this exact flow:
+
+```
+1. Try Pollinations (timeout: 15s)
+   ├── Success (image data) → Done ✅
+   └── Failure (any error) → Step 2
+
+2. Try Stable Horde (timeout: 120s for full job)
+   ├── Success → Done ✅
+   └── Failure → Step 3
+
+3. Report failure and STOP
+   └── Tell user: "Image generation unavailable. Both Pollinations.ai and Stable Horde are down."
+   └── DO NOT keep retrying
+```
+
+### Rule 5: Exit Conditions (MANDATORY)
+
+Claude Code MUST exit the image generation attempt when:
+
+| Condition | Action | Max Attempts |
+|-----------|--------|--------------|
+| Timeout | Switch provider | 1 |
+| HTTP 5xx | Switch provider | 1 |
+| "Could not process image" | Switch provider | 1 |
+| Non-image response | Switch provider | 1 |
+| Both providers fail | **STOP and report** | 0 |
+
+### Example: Non-Blocking Image Generation
+
+```typescript
+async function generateImageNonBlocking(prompt: string): Promise<string | null> {
+  const TIMEOUT_MS = 15000;
+
+  // Try Pollinations first
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    const response = await fetch(
+      `https://image.pollinations.ai/prompt/${encodeURIComponent(prompt)}?width=512&height=512`,
+      { signal: controller.signal }
+    );
+    clearTimeout(timeoutId);
+
+    const contentType = response.headers.get('content-type');
+    if (contentType?.startsWith('image/')) {
+      return await response.blob().then(b => URL.createObjectURL(b));
+    }
+    // Not an image - fall through to Stable Horde
+  } catch (e) {
+    console.log('Pollinations failed, trying Stable Horde');
+  }
+
+  // Try Stable Horde
+  try {
+    return await generateViaStableHorde(prompt);
+  } catch (e) {
+    console.error('Both providers failed');
+    return null; // STOP - don't keep retrying
+  }
+}
+```
+
+### Claude API "Could Not Process Image" Error
+
+When you see this error:
+```
+API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"Could not process image"}}
+```
+
+**This means Claude's vision API cannot process the image.** Solutions:
+1. The image file may be corrupted or incomplete (502 error in disguise)
+2. The image format is unsupported
+3. The image URL returned an error page, not actual image data
+
+**Action:** Do NOT retry with Claude's Read tool. Instead:
+1. Download the image with curl first
+2. Verify it's actually an image: `file downloaded.png`
+3. If not an image → use Stable Horde fallback
 
 ## Quick Reference
 
-**Generate any image instantly:**
+### Primary: Pollinations.ai (when healthy)
 ```
 https://image.pollinations.ai/prompt/YOUR_PROMPT_HERE
 ```
 
+### Fallback: Stable Horde (when Pollinations is down)
+```
+POST https://stablehorde.net/api/v2/generate/async
+Content-Type: application/json
+
+{"prompt": "YOUR_PROMPT_HERE", "params": {"width": 512, "height": 512}}
+```
+
+---
+
+## Stable Horde Fallback API (FREE, No API Key)
+
+When Pollinations.ai returns 5xx errors, use Stable Horde - a community-powered, 100% free alternative.
+
+### Why Stable Horde Works
+
+- ✅ No API key required (anonymous mode)
+- ✅ No rate limits for reasonable usage
+- ✅ High-quality Stable Diffusion models
+- ✅ Community-powered (crowdsourced GPUs)
+- ⏱️ Generation time: 30-120 seconds (varies by queue)
+
+### Step 1: Submit Generation Request
+
+```bash
+curl -X POST "https://stablehorde.net/api/v2/generate/async" \
+  -H "Content-Type: application/json" \
+  -H "apikey: 0000000000" \
+  -d '{
+    "prompt": "a majestic mountain landscape, professional photography, 8k, detailed",
+    "params": {
+      "width": 512,
+      "height": 512,
+      "steps": 30,
+      "cfg_scale": 7.5,
+      "sampler_name": "k_euler_a"
+    },
+    "nsfw": false,
+    "censor_nsfw": true,
+    "models": ["stable_diffusion"]
+  }'
+```
+
+**Response:**
+```json
+{
+  "id": "abc123-def456-ghi789",
+  "kudos": 10
+}
+```
+
+### Step 2: Poll for Completion
+
+```bash
+# Poll every 5 seconds until done
+curl -s "https://stablehorde.net/api/v2/generate/check/abc123-def456-ghi789"
+```
+
+**Response when processing:**
+```json
+{
+  "done": false,
+  "wait_time": 45,
+  "queue_position": 3,
+  "processing": 1
+}
+```
+
+**Response when complete:**
+```json
+{
+  "done": true,
+  "generations": [
+    {
+      "img": "base64_encoded_image_data...",
+      "seed": "12345",
+      "worker_id": "worker-abc",
+      "model": "stable_diffusion"
+    }
+  ]
+}
+```
+
+### Step 3: Save the Image
+
+```bash
+# Extract and save base64 image
+curl -s "https://stablehorde.net/api/v2/generate/status/abc123-def456-ghi789" | \
+  jq -r '.generations[0].img' | base64 -d > output.png
+```
+
+### Complete Node.js Example with Fallback
+
+```typescript
+import https from 'https';
+import fs from 'fs';
+
+interface ImageOptions {
+  prompt: string;
+  width?: number;
+  height?: number;
+  outputPath: string;
+}
+
+// Health check for Pollinations
+async function checkPollinationsHealth(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = https.get(
+      'https://image.pollinations.ai/prompt/health?width=64&height=64',
+      { timeout: 3000 },
+      (res) => resolve(res.statusCode === 200)
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}
+
+// Generate via Pollinations (primary)
+async function generatePollinations(options: ImageOptions): Promise<string> {
+  const { prompt, width = 1024, height = 1024, outputPath } = options;
+  const url = `https://image.pollinations.ai/prompt/${encodeURIComponent(prompt)}?width=${width}&height=${height}&nologo=true`;
+
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`Pollinations returned ${res.statusCode}`));
+        return;
+      }
+      const file = fs.createWriteStream(outputPath);
+      res.pipe(file);
+      file.on('finish', () => { file.close(); resolve(outputPath); });
+    }).on('error', reject);
+  });
+}
+
+// Generate via Stable Horde (fallback)
+async function generateStableHorde(options: ImageOptions): Promise<string> {
+  const { prompt, width = 512, height = 512, outputPath } = options;
+
+  // Step 1: Submit job
+  const jobId = await submitHordeJob(prompt, width, height);
+  console.log(`Stable Horde job submitted: ${jobId}`);
+
+  // Step 2: Poll until done
+  let done = false;
+  let imageData: string | null = null;
+
+  while (!done) {
+    await new Promise(r => setTimeout(r, 5000)); // Wait 5s
+    const status = await checkHordeStatus(jobId);
+    console.log(`Queue position: ${status.queue_position}, Wait: ${status.wait_time}s`);
+
+    if (status.done) {
+      done = true;
+      imageData = status.generations[0]?.img;
+    }
+  }
+
+  // Step 3: Save image
+  if (imageData) {
+    fs.writeFileSync(outputPath, Buffer.from(imageData, 'base64'));
+    return outputPath;
+  }
+  throw new Error('No image generated');
+}
+
+// Main function with automatic fallback
+async function generateImage(options: ImageOptions): Promise<string> {
+  console.log('Checking Pollinations.ai health...');
+  const pollinationsHealthy = await checkPollinationsHealth();
+
+  if (pollinationsHealthy) {
+    console.log('✅ Pollinations healthy, using primary provider');
+    try {
+      return await generatePollinations(options);
+    } catch (err) {
+      console.log('⚠️ Pollinations failed, falling back to Stable Horde');
+      return await generateStableHorde(options);
+    }
+  } else {
+    console.log('❌ Pollinations down (502/503), using Stable Horde fallback');
+    return await generateStableHorde(options);
+  }
+}
+
+// Usage
+generateImage({
+  prompt: 'a futuristic city at sunset, cyberpunk, neon lights, 8k',
+  width: 1024,
+  height: 1024,
+  outputPath: './generated-image.png'
+}).then(path => console.log(`Image saved to: ${path}`));
+```
+
+### Stable Horde Parameters Reference
+
+| Parameter | Values | Default | Description |
+|-----------|--------|---------|-------------|
+| `width` | 64-1024 (multiples of 64) | 512 | Image width |
+| `height` | 64-1024 (multiples of 64) | 512 | Image height |
+| `steps` | 1-150 | 30 | Diffusion steps |
+| `cfg_scale` | 1-30 | 7.5 | Prompt adherence |
+| `sampler_name` | k_euler_a, k_dpm_2, etc. | k_euler_a | Sampling method |
+| `models` | ["stable_diffusion", "SDXL 1.0"] | auto | Model selection |
+
+### Stable Horde Web UI Alternative
+
+If you prefer a visual interface: **[ArtBot](https://tinybots.net/artbot)** - free web UI for Stable Horde.
+
+---
+
 ## When This Skill Activates
 
 This skill auto-activates when you need images for:
@@ -343,15 +744,101 @@ async function getOrGenerateImage(prompt: string, options: ImageOptions) {
 
 ## Troubleshooting
 
+### HTTP Error Codes & Solutions
+
+| Error Code | Provider | Meaning | Solution |
+|------------|----------|---------|----------|
+| `200` | Both | ✅ Success | Image generated |
+| `400` | Both | Bad Request | Fix prompt (invalid characters, too long) |
+| `429` | Pollinations | Rate Limited | Wait 15s or switch to Stable Horde |
+| `500` | Both | Internal Error | Retry once, then switch provider |
+| `502` | Pollinations | **Bad Gateway** | **→ Use Stable Horde immediately** |
+| `503` | Both | Service Unavailable | **→ Use Stable Horde immediately** |
+| `504` | Pollinations | Gateway Timeout | **→ Use Stable Horde immediately** |
+| `000` | Both | Network/DNS Error | Check internet, try Stable Horde |
+
+### Common Issues & Fixes
+
 | Issue | Solution |
 |-------|----------|
-| Slow generation | Use `turbo` model for faster results |
+| **Claude Code stuck** | Run health check first, use fallback on 5xx |
+| Slow generation | Use `turbo` model (Pollinations) or reduce steps (Horde) |
 | Poor quality | Add quality modifiers, use `flux` or `flux-realism` |
 | Wrong style | Specify style explicitly: "photograph", "illustration" |
 | Watermark appears | Add `nologo=true` parameter |
 | Inconsistent results | Use same `seed` parameter |
-| Rate limited | Wait 15s between requests or register for higher limits |
+| Rate limited | Wait 15s or use Stable Horde (no rate limits) |
 | Image not loading | URL-encode the prompt properly |
+| Stable Horde slow | Normal: 30-120s queue time, be patient |
+| Base64 decode fails | Ensure you're getting the full `img` field |
+
+### Quick Diagnostic Script (Content-Based)
+
+```bash
+#!/bin/bash
+# diagnose-image-api.sh - Run this when image generation fails
+# IMPORTANT: Uses CONTENT checking, not just HTTP status!
+
+echo "=== Image API Diagnostics (Content-Based) ==="
+
+# Test Pollinations with actual image download
+echo -n "1. Pollinations.ai: "
+TEMP_FILE=$(mktemp)
+curl -s -L -o "$TEMP_FILE" --max-time 15 \
+  "https://image.pollinations.ai/prompt/diagnostic%20test?width=64&height=64&nologo=true" 2>/dev/null
+P_CONTENT=$(file -b "$TEMP_FILE" 2>/dev/null | cut -d',' -f1)
+
+if [[ "$P_CONTENT" == "PNG image data" ]] || [[ "$P_CONTENT" == "JPEG image data" ]]; then
+    echo "✅ HEALTHY (returns actual images)"
+    P_HEALTHY=true
+elif [[ "$P_CONTENT" == "ASCII text" ]]; then
+    echo "❌ BROKEN (returns error text: $(head -c 50 "$TEMP_FILE"))"
+    P_HEALTHY=false
+elif [[ -z "$P_CONTENT" ]]; then
+    echo "❌ TIMEOUT or empty response"
+    P_HEALTHY=false
+else
+    echo "⚠️ UNKNOWN ($P_CONTENT)"
+    P_HEALTHY=false
+fi
+rm -f "$TEMP_FILE"
+
+# Test Stable Horde API
+echo -n "2. Stable Horde: "
+H_STATUS=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 \
+  "https://stablehorde.net/api/v2/status/heartbeat" 2>/dev/null || echo "TIMEOUT")
+if [[ "$H_STATUS" == "200" ]]; then
+    echo "✅ HEALTHY (API responding)"
+    H_HEALTHY=true
+else
+    echo "❌ ISSUE ($H_STATUS)"
+    H_HEALTHY=false
+fi
+
+# Test internet
+echo -n "3. Internet: "
+I_STATUS=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 "https://google.com" 2>/dev/null || echo "TIMEOUT")
+if [[ "$I_STATUS" == "200" || "$I_STATUS" == "301" ]]; then
+    echo "✅ OK"
+else
+    echo "❌ NO INTERNET"
+fi
+
+echo ""
+echo "=== Recommendation ==="
+if [[ "$P_HEALTHY" == "true" ]]; then
+    echo "✅ Use: Pollinations.ai (primary) - working normally"
+elif [[ "$H_HEALTHY" == "true" ]]; then
+    echo "🔄 Use: Stable Horde (fallback) - Pollinations is currently down"
+    echo ""
+    echo "Stable Horde usage:"
+    echo "  1. POST to https://stablehorde.net/api/v2/generate/async"
+    echo "  2. Poll https://stablehorde.net/api/v2/generate/check/{id}"
+    echo "  3. Get result from https://stablehorde.net/api/v2/generate/status/{id}"
+else
+    echo "❌ Both services unavailable. Check internet connection."
+fi
+```
 
 ## Integration with Frontend Design
 

package/src/templates/AGENTS.md.template

@@ -23,6 +23,8 @@
 | Section | Search For | Purpose |
 |---------|------------|---------|
 | Rules | `#essential-rules` | Critical rules, file organization |
+| **Orchestration** | `#workflow-orchestration` | **Plan Mode, Subagents, Verification** |
+| **Principles** | `#core-principles` | **Quality: Simplicity, No Laziness** |
 | Commands | `#commands` | All SpecWeave commands |
 | **Hooks** | `#non-claude-tools` | **CRITICAL: Hook behavior to mimic** |
 | **User Story** | `#user-story-format` | **CRITICAL: Project/Board fields** |
@@ -100,6 +102,171 @@
 
 ---
 
+<!-- SECTION:orchestration required -->
+## Workflow Orchestration {#workflow-orchestration}
+
+**Claude Code has built-in orchestration features. Non-Claude tools must implement these manually.**
+
+### 1. Plan Mode Default
+
+**Claude Code**: Has `EnterPlanMode` tool that automatically enters planning state for complex tasks.
+
+**Non-Claude Tools - Manual Planning Protocol:**
+```
+BEFORE implementing ANY non-trivial task (3+ steps):
+
+1. STOP - Don't start coding immediately
+2. Create `.specweave/increments/XXXX-feature/plan.md`
+3. List all steps required
+4. Identify dependencies between steps
+5. Note architectural decisions needed
+6. GET USER APPROVAL before implementing
+
+If something goes sideways during implementation:
+→ STOP and re-plan (don't keep pushing)
+→ Update plan.md with revised approach
+→ Get approval again if scope changed
+```
+
+**Planning Template (plan.md):**
+```markdown
+# Plan: Feature Name
+
+## Approach
+[High-level approach description]
+
+## Steps
+1. [ ] Step one
+2. [ ] Step two (depends on: #1)
+3. [ ] Step three
+
+## Risks/Decisions
+- [ ] Decision: [question needing user input]
+- Risk: [potential issue and mitigation]
+
+## Approval
+- [ ] User approved this plan
+```
+
+### 2. Subagent Strategy (Parallel Execution)
+
+**Claude Code**: Can spawn subagents with `Task` tool for parallel work.
+
+**Non-Claude Tools - Manual Parallelization:**
+```
+For large exploration/analysis tasks:
+
+Option A: Sequential Breakdown
+1. Split work into independent chunks
+2. Process one chunk at a time
+3. Aggregate results
+
+Option B: Parallel Prompts (Cursor/Copilot)
+1. Open multiple chat sessions
+2. Give each session one focused task
+3. Combine outputs manually
+
+Best practices:
+- One task per "subagent" (focused execution)
+- Keep analysis/exploration separate from implementation
+- Use checklists to track parallel workstreams
+```
+
+**When to use parallel approach:**
+- Codebase exploration (search multiple areas)
+- Multi-file analysis (review patterns across modules)
+- Batch validation (check multiple files for issues)
+- Large-scale refactoring analysis
+
+### 3. Verification Before Done
+
+**Claude Code**: PostToolUse hooks validate completion automatically.
+
+**Non-Claude Tools - Manual Verification Checklist:**
+```
+⛔ NEVER mark a task complete without proving it works!
+
+Before marking ANY task as [x] completed:
+
+□ Code compiles/builds successfully
+□ Tests pass (run: npm test, pytest, etc.)
+□ Manual verification performed (if applicable)
+□ Acceptance criteria actually satisfied (re-read AC)
+□ No console errors in browser (for frontend)
+□ API returns expected responses (for backend)
+
+Ask yourself: "Would a staff engineer approve this?"
+
+If answer is NO → task is NOT complete
+```
+
+**Verification Commands by Stack:**
+```bash
+# JavaScript/TypeScript
+npm run build && npm test
+
+# Python
+pytest && mypy .
+
+# .NET
+dotnet build && dotnet test
+
+# General
+git diff  # Review what actually changed
+```
+
+### 4. Think-Before-Act (Dependencies)
+
+**Satisfy dependencies BEFORE dependent operations.**
+
+```
+❌ Wrong: node script.js → Error → npm run build
+✅ Correct: npm run build → node script.js → Success
+
+❌ Wrong: Import module → Error → Install package
+✅ Correct: npm install package → Import module → Success
+```
+
+**Dependency Detection Questions:**
+1. Does this require a build step first?
+2. Are all imports/packages installed?
+3. Does this depend on another file being created?
+4. Is there a database migration needed?
+5. Are environment variables configured?
+<!-- /SECTION -->
+
+---
+
+<!-- SECTION:principles required -->
+## Core Principles (Quality) {#core-principles}
+
+### Simplicity First
+- Write the simplest code that solves the problem
+- Avoid over-engineering and premature optimization
+- One function = one responsibility
+- If you can delete code and tests still pass, delete it
+
+### No Laziness
+- Don't leave TODO comments for "later"
+- Don't skip error handling because "it probably won't fail"
+- Don't copy-paste without understanding
+- Test edge cases, not just happy paths
+
+### Minimal Impact
+- Change only what's necessary for the task
+- Don't refactor adjacent code unless asked
+- Keep PRs focused and reviewable
+- Preserve existing patterns unless improving them is the task
+
+### Demand Elegance (Balanced)
+- Code should be readable by humans first
+- Names should reveal intent
+- BUT: Don't over-abstract for hypothetical futures
+- Pragmatic > Perfect
+<!-- /SECTION -->
+
+---
+
 <!-- SECTION:commands required -->
 ## Commands Reference {#commands}
 
@@ -129,7 +296,21 @@
 <!-- SECTION:nonclaudetools required -->
 ## Non-Claude Tools (Cursor, Copilot, etc.) {#non-claude-tools}
 
-**CRITICAL**: Claude Code has automatic hooks. Other tools DO NOT.
+**CRITICAL**: Claude Code has automatic hooks and orchestration. Other tools DO NOT.
+
+> **See also**: [Workflow Orchestration](#workflow-orchestration) for Plan Mode, Subagent Strategy, and Verification protocols.
+
+### Built-in vs Manual - Complete Comparison
+
+| Capability | Claude Code | Non-Claude Tools |
+|------------|-------------|------------------|
+| **Plan Mode** | `EnterPlanMode` tool (automatic) | Manual: Create plan.md, get approval |
+| **Subagents** | `Task` tool spawns parallel agents | Manual: Split work, parallel prompts |
+| **Verification** | PostToolUse hooks validate | Manual: Run tests, check checklist |
+| **Hooks** | Auto-run on events | YOU must mimic (see below) |
+| **Task sync** | Automatic AC updates | Manual: Edit tasks.md + spec.md |
+| **Commands** | Slash syntax works | Read command .md, follow manually |
+| **Skills** | Auto-activate on keywords | Read SKILL.md, follow workflow |
 
 ### Latest Features
 

package/src/templates/CLAUDE.md.template

@@ -151,10 +151,26 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 <!-- /SECTION -->
 
 <!-- SECTION:metarule required -->
-## Meta-Rule: Think-Before-Act
+## Workflow Orchestration
 
-**Satisfy dependencies BEFORE dependent operations.**
+### 1. Plan Mode Default
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
+- If something goes sideways, **STOP and re-plan** - don't keep pushing
+- Write detailed specs upfront to reduce ambiguity
+
+### 2. Subagent Strategy
+- Use subagents liberally to keep main context clean
+- Offload research, exploration, and parallel analysis to subagents
+- One task per subagent for focused execution
+- Append "use subagents" to requests for safe parallelization
 
+### 3. Verification Before Done
+- Never mark a task complete without proving it works
+- Ask yourself: **"Would a staff engineer approve this?"**
+- Run tests, check logs, demonstrate correctness
+
+### 4. Think-Before-Act (Dependencies)
+**Satisfy dependencies BEFORE dependent operations.**
 ```
 ❌ node script.js → Error → npm run build
 ✅ npm run build → node script.js → Success
@@ -166,7 +182,10 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 
 1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
 2. **Update immediately**: `Edit("tasks.md", "[ ] pending", "[x] completed")` + `Edit("spec.md", "[ ] AC-", "[x] AC-")`
-3. **Unique IDs**: Check `ls .specweave/increments/ | grep "^[0-9]" | tail -5`
+3. **Unique IDs**: Check ALL folders (active, archive, abandoned):
+   ```bash
+   find .specweave/increments -maxdepth 2 -type d -name "[0-9]*" | grep -oE '[0-9]{4}E?' | sort -u | tail -5
+   ```
 4. **Emergency**: "emergency mode" → 1 edit, 50 lines max, no agents
 5. **⛔ Initialization guard**: `.specweave/` folders MUST ONLY exist where `specweave init` was run
 6. **⛔ Marketplace refresh**: Use `specweave refresh-marketplace` CLI (not `scripts/refresh-marketplace.sh`)
@@ -384,13 +403,9 @@ Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 | Skills/commands missing | Restart Claude Code |
 | Plugins outdated | `specweave refresh-marketplace` |
 | Out of sync | `/sw:sync-tasks` |
-| Find increment | `/sw:status` |
-| Root polluted | Move to `.specweave/increments/####/reports/` |
 | Duplicate IDs | `/sw:fix-duplicates` |
-| GitHub sync issues | Check config: `sync.github.enabled`, `canUpdateExternalItems` |
 | Edits blocked | Add `"additionalDirectories":["repositories"]` to `.claude/settings.json` |
-| Marketplace shows 0 | Normal with auto-load; `/plugin list` shows actual |
-| Docs folder collisions | Check: `ls docs/ \| grep -E '^[0-9]{2}-' \| cut -d'-' -f1 \| sort \| uniq -d` |
+| Session stuck | Kill + `rm -f .specweave/state/*.lock` + restart |
 <!-- /SECTION -->
 
 <!-- SECTION:lazyloading -->
@@ -410,10 +425,17 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 <!-- SECTION:principles -->
 ## Principles
 
+### SpecWeave Principles
 1. **Spec-first**: `/sw:increment` before coding
 2. **Docs = truth**: Specs guide implementation
 3. **Incremental**: Small, validated increments
 4. **Traceable**: All work → specs → ACs
+
+### Core Principles (Quality)
+- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
+- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
+- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.
+- **Demand Elegance**: For non-trivial changes, pause and ask "is there a more elegant way?" - but skip this for simple, obvious fixes (don't over-engineer).
 <!-- /SECTION -->
 
 <!-- SECTION:linking -->