@abdullah-alnahas/claude-sdd 0.6.0 → 0.8.0

package/hooks/hooks.json

@@ -7,7 +7,8 @@
           {
             "type": "command",
             "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/session-init.sh\"",
-            "timeout": 10
+            "timeout": 10,
+            "additionalContext": true
           }
         ]
       }
@@ -18,7 +19,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "If this message is a trivial acknowledgment (e.g. 'yes', 'no', 'thanks', 'ok', 'continue'), skip and respond normally. Otherwise, apply the SDD pre-implementation checkpoint from the guardrails skill (enumerate assumptions, flag ambiguity, surface alternatives, push back on bad ideas, define scope, check for spec, plan TDD approach) before proceeding. If GUARDRAILS_DISABLED=true, skip."
+            "prompt": "If this message is a trivial acknowledgment (e.g. 'yes', 'no', 'thanks', 'ok', 'continue'), skip and respond normally. If SDD_MODE=review or SDD_MODE=research, skip. Otherwise, apply the SDD pre-implementation checkpoint from the guardrails skill (enumerate assumptions, flag ambiguity, surface alternatives, push back on bad ideas, define scope, check for spec, plan TDD approach) before proceeding. If GUARDRAILS_DISABLED=true, skip."
           }
         ]
       }
@@ -33,6 +34,16 @@
             "timeout": 15
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/compaction-counter.sh\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "Stop": [
@@ -41,7 +52,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Before finalizing, perform the SDD completion review from the guardrails skill (spec adherence, test coverage, complexity audit, dead code check, scope creep check, conceptual error scan). Report findings concisely. If GUARDRAILS_DISABLED=true, skip."
+            "prompt": "Before finalizing, perform the SDD completion review from the guardrails skill (spec adherence, test coverage, complexity audit, dead code check, scope creep check, conceptual error scan). Report findings concisely. If GUARDRAILS_DISABLED=true or SDD_MODE=research, skip."
           }
         ]
       }

package/hooks/scripts/compaction-counter.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# SDD Strategic Compaction Counter
+# Counts tool invocations per session and suggests compaction at threshold.
+# Runs as PostToolUse hook — must be fast and silent on stdout.
+
+set -euo pipefail
+
+THRESHOLD="${SDD_COMPACTION_THRESHOLD:-50}"
+COUNTER_FILE="/tmp/sdd-compaction-$$"
+
+# Use parent PID to scope counter to the Claude session
+if [ -n "${PPID:-}" ]; then
+  COUNTER_FILE="/tmp/sdd-compaction-$PPID"
+fi
+
+# Increment counter
+COUNT=0
+if [ -f "$COUNTER_FILE" ]; then
+  COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+fi
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Check threshold
+if [ "$COUNT" -ge "$THRESHOLD" ]; then
+  echo "SDD: $COUNT tool invocations since last compaction suggestion. Consider running /compact to free context window space. Key information to preserve: current task, spec criteria, files modified, test status." >&2
+  # Reset counter after suggesting
+  echo "0" > "$COUNTER_FILE"
+fi
+
+exit 0

package/hooks/scripts/post-edit-review.sh

@@ -4,15 +4,20 @@
 
 set -euo pipefail
 
-# Skip if guardrails disabled
+# Skip if guardrails disabled or in research mode
 if [ "${GUARDRAILS_DISABLED:-false}" = "true" ]; then
   exit 0
 fi
+if [ "${SDD_MODE:-dev}" = "research" ]; then
+  exit 0
+fi
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-# Resolve to absolute path to avoid relative vs absolute mismatch
+# Resolve to absolute path (POSIX-compatible fallback when realpath unavailable)
 if command -v realpath &>/dev/null; then
   PROJECT_DIR=$(realpath "$PROJECT_DIR" 2>/dev/null || echo "$PROJECT_DIR")
+else
+  PROJECT_DIR=$(cd "$PROJECT_DIR" 2>/dev/null && pwd || echo "$PROJECT_DIR")
 fi
 
 # Read tool input from stdin (JSON with file_path)
@@ -20,8 +25,8 @@ INPUT=$(cat)
 
 # Use jq if available, fall back to sed
 if command -v jq &>/dev/null; then
-  FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .filePath // empty' 2>/dev/null)
-  if [ $? -ne 0 ] || [ -z "$FILE_PATH" ]; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .filePath // empty' 2>/dev/null || true)
+  if [ -z "$FILE_PATH" ]; then
     echo "SDD: post-edit-review skipped — could not parse file_path from hook input" >&2
     exit 0
   fi
@@ -40,6 +45,8 @@ fi
 # Resolve file path to absolute for consistent comparison
 if command -v realpath &>/dev/null; then
   FILE_PATH=$(realpath "$FILE_PATH" 2>/dev/null || echo "$FILE_PATH")
+elif [ -f "$FILE_PATH" ]; then
+  FILE_PATH=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && echo "$(pwd)/$(basename "$FILE_PATH")" || echo "$FILE_PATH")
 fi
 
 # Check if inside project directory

package/hooks/scripts/session-init.sh

@@ -1,9 +1,14 @@
 #!/bin/bash
 # SDD Session Initialization Hook
-# Loads .sdd.yaml config, sets environment variables, checks yolo flag
+# Loads .sdd.yaml config, sets environment variables, checks yolo flag, injects using-sdd skill
 
 set -euo pipefail
 
+# Validate plugin environment
+if [ -z "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  echo "SDD WARNING: CLAUDE_PLUGIN_ROOT is not set — hooks may not locate plugin resources" >&2
+fi
+
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 ENV_FILE="${CLAUDE_ENV_FILE:-}"
 CONFIG_FILE="$PROJECT_DIR/.sdd.yaml"
@@ -29,12 +34,24 @@ if [ -n "$ENV_FILE" ]; then
   echo "SDD_ACTIVE=true" >> "$ENV_FILE"
 fi
 
-# Check for config file
+# Check for config file and read settings
+SDD_DEFAULT_MODE="dev"
+SDD_COMPACTION_THRESHOLD="50"
 if [ -f "$CONFIG_FILE" ]; then
   echo "SDD: Config file found at $CONFIG_FILE" >&2
   if [ -n "$ENV_FILE" ]; then
     echo "SDD_CONFIG_FOUND=true" >> "$ENV_FILE"
   fi
+  # Read mode from config (grep-based, no yaml parser needed)
+  CONFIG_MODE=$(grep -E '^\s*mode\s*:' "$CONFIG_FILE" 2>/dev/null | head -1 | sed 's/.*:\s*//' | tr -d '[:space:]"'"'" || true)
+  if [ -n "$CONFIG_MODE" ] && echo "$CONFIG_MODE" | grep -qE '^(dev|review|research)$'; then
+    SDD_DEFAULT_MODE="$CONFIG_MODE"
+  fi
+  # Read compaction threshold from config
+  CONFIG_THRESHOLD=$(grep -E '^\s*compaction_threshold\s*:' "$CONFIG_FILE" 2>/dev/null | head -1 | sed 's/.*:\s*//' | tr -d '[:space:]"'"'" || true)
+  if [ -n "$CONFIG_THRESHOLD" ] && echo "$CONFIG_THRESHOLD" | grep -qE '^[0-9]+$'; then
+    SDD_COMPACTION_THRESHOLD="$CONFIG_THRESHOLD"
+  fi
 else
   echo "SDD: No .sdd.yaml found — using defaults" >&2
   if [ -n "$ENV_FILE" ]; then
@@ -42,5 +59,29 @@ else
   fi
 fi
 
-echo "SDD: Session initialized — guardrails active" >&2
+# Set mode and compaction threshold in env
+if [ -n "$ENV_FILE" ]; then
+  echo "SDD_MODE=$SDD_DEFAULT_MODE" >> "$ENV_FILE"
+  echo "SDD_COMPACTION_THRESHOLD=$SDD_COMPACTION_THRESHOLD" >> "$ENV_FILE"
+fi
+
+# Inject using-sdd skill as additionalContext
+USING_SDD_PATH="${CLAUDE_PLUGIN_ROOT:-}/skills/using-sdd/SKILL.md"
+if [ -f "$USING_SDD_PATH" ]; then
+  # Strip frontmatter and output as additionalContext
+  sed '1{/^---$/!q;};1,/^---$/d' "$USING_SDD_PATH"
+else
+  echo "SDD WARNING: using-sdd skill not found at $USING_SDD_PATH" >&2
+fi
+
+# Inject context mode file
+CONTEXT_PATH="${CLAUDE_PLUGIN_ROOT:-}/contexts/${SDD_DEFAULT_MODE}.md"
+if [ -f "$CONTEXT_PATH" ]; then
+  echo ""
+  cat "$CONTEXT_PATH"
+else
+  echo "SDD WARNING: context file not found at $CONTEXT_PATH" >&2
+fi
+
+echo "SDD: Session initialized — mode=$SDD_DEFAULT_MODE, guardrails active" >&2
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abdullah-alnahas/claude-sdd",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Spec-Driven Development discipline system for Claude Code — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops",
   "keywords": [
     "claude-code-plugin",

package/scripts/verify-commands.sh

@@ -23,7 +23,7 @@ check() {
 echo "SDD Command Verification"
 echo "────────────────────────"
 
-COMMANDS=("sdd-guardrails" "sdd-yolo" "sdd-phase" "sdd-review" "sdd-adopt" "sdd-execute" "sdd-autopilot")
+COMMANDS=("sdd-guardrails" "sdd-yolo" "sdd-phase" "sdd-review" "sdd-adopt" "sdd-execute" "sdd-autopilot" "sdd-mode" "sdd-verify" "sdd-orchestrate")
 
 for cmd in "${COMMANDS[@]}"; do
   echo ""
@@ -47,7 +47,7 @@ check "All command names are unique" test "$(echo "$NAMES" | wc -l)" -eq "$(echo
 # Check agents referenced by commands exist
 echo ""
 echo "Agent references:"
-AGENTS=("critic" "simplifier" "spec-compliance" "security-reviewer" "performance-reviewer")
+AGENTS=("critic" "simplifier" "spec-compliance" "security-reviewer" "performance-reviewer" "planner")
 for agent in "${AGENTS[@]}"; do
   check "Agent: $agent.md exists" test -f "$PLUGIN_DIR/agents/$agent.md"
 done

package/scripts/verify-hooks.sh

@@ -23,49 +23,71 @@ check() {
 echo "SDD Hook Verification"
 echo "─────────────────────"
 
+# Detect Python interpreter
+PYTHON=""
+for candidate in python3 python; do
+  if command -v "$candidate" &>/dev/null; then
+    PYTHON="$candidate"
+    break
+  fi
+done
+
 # Check hooks.json exists and is valid JSON
 echo ""
 echo "hooks.json:"
 check "File exists" test -f "$PLUGIN_DIR/hooks/hooks.json"
-check "Valid JSON" python3 -c "import json, sys; json.load(open(sys.argv[1]))" "$PLUGIN_DIR/hooks/hooks.json"
-check "Has hooks wrapper" python3 -c "
+if [ -n "$PYTHON" ]; then
+  check "Valid JSON" "$PYTHON" -c "import json, sys; json.load(open(sys.argv[1]))" "$PLUGIN_DIR/hooks/hooks.json"
+  check "Has hooks wrapper" "$PYTHON" -c "
 import json, sys
 d = json.load(open(sys.argv[1]))
 assert 'hooks' in d, 'Missing hooks key'
 " "$PLUGIN_DIR/hooks/hooks.json"
-check "Has SessionStart hook" python3 -c "
+  check "Has SessionStart hook" "$PYTHON" -c "
 import json, sys
 d = json.load(open(sys.argv[1]))
 assert 'SessionStart' in d['hooks']
 " "$PLUGIN_DIR/hooks/hooks.json"
-check "Has UserPromptSubmit hook" python3 -c "
+  check "Has UserPromptSubmit hook" "$PYTHON" -c "
 import json, sys
 d = json.load(open(sys.argv[1]))
 assert 'UserPromptSubmit' in d['hooks']
 " "$PLUGIN_DIR/hooks/hooks.json"
-check "Has PostToolUse hook" python3 -c "
+  check "Has PostToolUse hook" "$PYTHON" -c "
 import json, sys
 d = json.load(open(sys.argv[1]))
 assert 'PostToolUse' in d['hooks']
 " "$PLUGIN_DIR/hooks/hooks.json"
-check "Has Stop hook" python3 -c "
+  check "Has Stop hook" "$PYTHON" -c "
 import json, sys
 d = json.load(open(sys.argv[1]))
 assert 'Stop' in d['hooks']
 " "$PLUGIN_DIR/hooks/hooks.json"
+else
+  echo "  ⚠ Python not found — skipping JSON validation (install python3 or activate a venv)"
+  FAIL=$((FAIL + 1))
+fi
 
 # Check scripts exist and are executable
 echo ""
 echo "Hook scripts:"
 check "session-init.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/session-init.sh"
 check "post-edit-review.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/post-edit-review.sh"
+check "compaction-counter.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/compaction-counter.sh"
 check "session-init.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/session-init.sh"
 check "post-edit-review.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/post-edit-review.sh"
+check "compaction-counter.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/compaction-counter.sh"
 
-# Test session-init.sh runs without error
+# Test session-init.sh runs without error (in isolated temp dir to avoid side effects)
 echo ""
 echo "Script execution:"
-check "session-init.sh runs without error" bash "$PLUGIN_DIR/hooks/scripts/session-init.sh"
+check "session-init.sh runs without error" bash -c "
+  TMPDIR=\$(mktemp -d)
+  CLAUDE_PROJECT_DIR=\"\$TMPDIR\" CLAUDE_ENV_FILE=\"\" bash \"$PLUGIN_DIR/hooks/scripts/session-init.sh\" 2>/dev/null
+  rc=\$?
+  rm -rf \"\$TMPDIR\"
+  exit \$rc
+"
 
 echo ""
 echo "─────────────────────"

package/scripts/verify-skills.sh

@@ -23,7 +23,7 @@ check() {
 echo "SDD Skill Verification"
 echo "──────────────────────"
 
-SKILLS=("guardrails" "spec-first" "architecture-aware" "tdd-discipline" "iterative-execution" "performance-optimization")
+SKILLS=("guardrails" "spec-first" "architecture-aware" "tdd-discipline" "iterative-execution" "performance-optimization" "using-sdd")
 
 for skill in "${SKILLS[@]}"; do
   echo ""

package/skills/architecture-aware/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: Architecture Awareness
 description: >
-  This skill provides architecture consciousness during development, including integration patterns,
-  anti-patterns, and ADR guidance. It should be used when the user asks how to structure or organize code,
-  discusses architecture or design patterns, plans integrations between components, or asks
-  "how should I structure this?", "what pattern should I use?", "should I split this into services?",
-  "should I write an ADR?", or "document this decision."
+  Use when structuring or organizing code, discussing architecture or design patterns, planning
+  integrations between components, or when the user asks "how should I structure this?", "what
+  pattern should I use?", "should I split this into services?", or "document this decision."
 ---
 
 # Architecture Awareness
@@ -41,6 +39,7 @@ If a decision is hard to reverse or affects multiple components, it deserves an
 ## Related Skills
 
 - **spec-first** — architecture decisions emerge during Stage 4 (Architecture)
+- **iterative-execution** — architectural context guides integration during implementation
 - **guardrails** — enforces architectural consistency as part of scope discipline
 
 ## References

package/skills/guardrails/SKILL.md

@@ -1,16 +1,19 @@
 ---
 name: SDD Guardrails
 description: >
-  This skill enforces core behavioral guardrails defending against 12 common LLM failure modes during
-  software development. It should be used when the user asks to implement, build, write, fix, refactor,
-  add, change, or modify code — essentially any coding task. It enforces honesty over agreement, scope
-  discipline, simplicity, and verification before claiming completion.
+  Use when implementing, building, fixing, refactoring, adding, changing, or modifying code.
+  Use when reviewing code or claiming work is complete. Use when you notice yourself agreeing
+  without critical evaluation or adding code beyond what was requested.
 ---
 
 # SDD Behavioral Guardrails
 
 Operate under the SDD (Spec-Driven Development) discipline system. These guardrails defend against known LLM failure patterns in software development.
 
+## Spirit vs. Letter
+
+Follow the **spirit** of these guardrails, not just their checklists. The goal is disciplined development that produces correct, simple, spec-compliant code. If following a checklist item mechanically would produce worse results than thoughtful application of the principle behind it, follow the principle. But this is **never** an excuse to skip steps — it's a reason to apply them thoughtfully.
+
 ## Core Principles
 
 ### 1. Honesty Over Agreement
@@ -26,7 +29,50 @@ The right solution is the simplest one that works. Before writing any code, ask:
 Every assumption you make is a potential bug. Enumerate your assumptions explicitly. If you're uncertain about intent, ask. If you're uncertain about behavior, test. Never silently guess.
 
 ### 5. Verify Before Claiming
-Never say "done" until you've verified. Run the tests. Check the output. Read your own code critically. A completion claim without verification is a lie.
+Never say "done" until you've verified. This is a formal gate:
+
+1. **IDENTIFY** the command or check needed to verify
+2. **RUN** the command (test suite, linter, type checker)
+3. **READ** the output — actually read it, don't skim
+4. **VERIFY** the claim against the output — does the evidence support "done"?
+5. **THEN** claim completion, citing the evidence
+
+A completion claim without verification is a lie.
+
+**Common verification failures:**
+
+| Failure | What Actually Happened |
+|---------|----------------------|
+| "Tests pass" without running them | You guessed. Run them. |
+| Ran tests but didn't read output | A failure was buried in the output. Read it. |
+| Tests pass but don't cover the change | You tested the wrong thing. Check coverage. |
+| "Looks correct" from reading code | Reading is not testing. Execute it. |
+| Verified one case, claimed all cases | Edge cases exist. Test them. |
+
+## Rationalization Red Flags
+
+These thoughts mean STOP — you're about to violate a guardrail:
+
+| Thought | Reality |
+|---------|---------|
+| "This small fix doesn't need the full checkpoint" | Small fixes are where scope creep starts. |
+| "The user seems to want me to just do it" | Discipline is not optional based on tone. |
+| "I'll verify at the end" | Verify continuously. End-of-task verification catches less. |
+| "This is obviously correct" | Obvious code has bugs too. Test it. |
+| "Adding this extra thing will help" | That's scope creep. Mention it, don't do it. |
+| "I'm sure this test passes" | Run it. Being sure is not evidence. |
+| "The user won't notice this improvement" | Unasked changes are defects regardless. |
+| "This is a standard pattern, no need to verify" | Standard patterns fail in specific contexts. Verify. |
+
+## Escalation Rule
+
+After 3 failed attempts to fix the same issue, **STOP**. Do not attempt a 4th fix. Instead:
+
+1. State what you've tried and why each attempt failed
+2. Question whether the approach or architecture is wrong
+3. Suggest an alternative approach or ask the user for direction
+
+Repeated failures on the same issue usually indicate a wrong approach, not insufficient effort.
 
 ## Pre-Implementation Checkpoint
 

package/skills/guardrails/references/failure-patterns.md

@@ -61,3 +61,8 @@
 **Detection**: You've been coding for a while and haven't re-read the original requirement.
 **Response**: Periodically re-read the request. Check that your solution actually solves the stated problem, not a related but different one.
 **Example**: User asks to "sort by date" and you implement alphabetical sort because you started coding before fully reading.
+
+### 13. Fix Thrashing
+**Detection**: You've attempted 3+ fixes for the same issue and it's still broken. Each fix introduces a new problem or reverts to a previous failure.
+**Response**: Stop fixing. Step back and question the approach. State what you've tried, why each failed, and propose an alternative architecture or ask the user for direction.
+**Example**: A test keeps failing despite three different fixes to the handler. The real problem is the test assumes synchronous behavior but the handler is async. The fix isn't in the handler — it's in the test setup or the architectural approach.

package/skills/iterative-execution/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: Iterative Execution
 description: >
-  This skill provides disciplined implement-verify-fix cycles for delivering features against specifications.
-  It should be used when the user asks to implement a feature from a spec, when implementation needs iterating
-  to match requirements, or when the user says "make this work," "implement this spec," "keep going until all
-  tests pass," or "it's not matching the spec yet."
+  Use when implementing a feature from a spec, when implementation needs iterating to match
+  requirements, or when delivering any non-trivial change. Use when the user says "make this work,"
+  "implement this spec," "keep going until all tests pass," or "it's not matching the spec yet."
 ---
 
 # Iterative Execution
@@ -36,6 +35,21 @@ They are complementary, not competing. TDD governs how you write code. Iterative
 7. Report honest completion status
 ```
 
+## Rationalization Red Flags
+
+These thoughts mean STOP — you're about to skip verification:
+
+| Thought | Reality |
+|---------|---------|
+| "I'll verify everything at the end" | Verify after each change. End-of-task catches less. |
+| "The code looks right, no need to run tests" | Looking right is not evidence. Run the tests. |
+| "I fixed the issue, moving on" | Did you verify the fix? Run the test again. |
+| "Only one small thing changed" | Small changes cause big failures. Verify. |
+| "I already know this passes" | You knew the previous version passed. This is a new version. |
+| "Verification would take too long" | Shipping a bug takes longer. Verify. |
+| "The spec is satisfied, I can see it" | Seeing is not testing. Run the criteria checks. |
+| "I'll skip this iteration's verification" | Skipping once becomes skipping always. Never skip. |
+
 ## Completion Criteria
 
 Good completion criteria are:
@@ -63,16 +77,17 @@ For performance optimization tasks, the verification step must additionally incl
 - **Never weaken criteria to match output.** The spec defines done, not the implementation.
 - **Be honest about partial completion.** "3 of 5 criteria met, blocked on X" is better than a false "done."
 
-## References
-
 ## Related Skills
 
 - **tdd-discipline** — the inner discipline used within each implementation step
 - **spec-first** — produces the specs that define completion criteria
 - **guardrails** — the overarching discipline layer
+- **architecture-aware** — architectural context for integration decisions during implementation
 - **performance-optimization** — specialized verification for performance tasks
 
 ## References
 
 See: `references/loop-patterns.md`
 See: `references/completion-criteria.md`
+See: `references/review-prompts.md`
+See: `references/retrieval-pattern.md`

package/skills/iterative-execution/references/retrieval-pattern.md

@@ -0,0 +1,65 @@
+# Iterative Retrieval Pattern
+
+A disciplined approach for subagents gathering context before acting. Prevents both under-researching (acting on incomplete information) and over-researching (reading everything "just in case").
+
+## The Pattern: DISPATCH → EVALUATE → REFINE → LOOP
+
+```
+1. DISPATCH — Send a focused query (search, read, find_symbol)
+2. EVALUATE — Is this enough to act? Do I know what I need?
+3. REFINE — If not, narrow or broaden the query based on what I learned
+4. LOOP — Repeat until confident or max iterations reached
+```
+
+## When to Use
+
+- Subagents exploring unfamiliar code before making changes
+- Gathering context across multiple files for a review
+- Understanding how a feature works before extending it
+- Investigating a bug's root cause across layers
+
+## When NOT to Use
+
+- You already know the exact file and symbol
+- The task is a single-file edit with clear instructions
+- You're running automated checks (tests, lint) — just run them
+
+## Example: Finding Where Auth Is Handled
+
+```
+DISPATCH: Search for "authenticate" in src/
+EVALUATE: Found 3 files. middleware/auth.ts looks like the entry point.
+DISPATCH: Read auth.ts symbols overview
+EVALUATE: Has validateToken(), refreshSession(), authMiddleware(). Need to understand validateToken.
+DISPATCH: Read validateToken body
+EVALUATE: Now I know the auth flow. Sufficient to proceed.
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| **Shotgun read** — read every file in the directory | Wastes context window, buries signal in noise | Start narrow, broaden only if needed |
+| **Single-shot guess** — read one file and assume that's enough | Misses critical context, produces wrong fixes | Always EVALUATE before acting |
+| **Infinite refinement** — keep searching "just one more thing" | Never starts the actual work | Set max iterations (3-5 for context gathering) |
+| **Keyword tunnel vision** — only search for one term | Misses related code using different names | Try synonyms, check imports/references |
+| **Depth-first rabbit hole** — follow every reference chain to the bottom | Loses sight of the original task | Stay focused on what you need to know for THIS task |
+
+## Integration with Iterative Execution
+
+The retrieval pattern is the **information-gathering phase** that precedes the execution cycle. Use it to:
+1. Understand the current state before defining completion criteria
+2. Find the spec and acceptance criteria
+3. Map the code that needs to change
+4. Identify test files and patterns
+
+Then hand off to the main iterative execution cycle: implement → verify → fix gaps → repeat.
+
+## Bounded Retrieval
+
+Always set bounds:
+- **Max queries**: 5-8 for context gathering before acting
+- **Max depth**: 2-3 levels of reference following
+- **Sufficiency check**: After each query, ask "Can I act now?"
+
+The goal is **sufficient context**, not **complete context**. You will never know everything. Act when you know enough.

package/skills/iterative-execution/references/review-prompts.md

@@ -0,0 +1,69 @@
+# Review Prompt Templates
+
+Subagent prompt templates for the two-stage review process.
+
+## Stage 1: Spec Compliance Reviewer
+
+Use this prompt for the spec-compliance review subagent:
+
+```
+You are reviewing an implementation against its behavior specification.
+
+DO NOT trust the implementer's report of what was done. Read the actual code and actual test output.
+
+Your job:
+1. Read the behavior spec (acceptance criteria)
+2. Read the implementation code
+3. Run or read test results
+4. For EACH acceptance criterion, independently verify:
+   - Is there a test that covers this criterion?
+   - Does the test actually test what the criterion specifies?
+   - Does the test pass? (Read the output, don't trust claims)
+   - Does the implementation match the criterion's intent, not just its letter?
+
+Report format:
+- For each criterion: PASS / FAIL / PARTIAL with evidence
+- Overall: X of Y criteria satisfied
+- Blocking issues (must fix before proceeding)
+- Non-blocking observations
+
+DO NOT soften findings. DO NOT say "mostly works" when a criterion fails.
+A criterion either passes with evidence or it doesn't.
+```
+
+## Stage 2: Code Quality Reviewer
+
+Use this prompt for the code quality review subagent (only run after Stage 1 passes):
+
+```
+You are reviewing code quality after spec compliance has been verified.
+
+Review the implementation for:
+1. Unnecessary complexity (could this be simpler?)
+2. Dead code introduced by the changes
+3. Scope creep (changes beyond what the spec required)
+4. Missing error handling at system boundaries
+5. Naming clarity
+6. Function/file length (aim ~50/~500 lines)
+
+For each finding, classify:
+- [Critical] — must fix (bugs, security issues)
+- [Simplification] — should fix (unnecessary complexity)
+- [Observation] — consider fixing (style, minor improvements)
+
+DO NOT invent requirements. Only flag issues that make the code worse.
+DO NOT suggest adding features, abstractions, or patterns not needed by the spec.
+```
+
+## Implementer Self-Review Checklist
+
+Before requesting external review, the implementer should verify:
+
+1. [ ] Re-read the original request/spec
+2. [ ] Every acceptance criterion has a corresponding test
+3. [ ] All tests pass (actually ran them, read the output)
+4. [ ] No unrelated files were modified
+5. [ ] No dead code was introduced
+6. [ ] No abstractions for single-use patterns
+7. [ ] Function lengths are reasonable
+8. [ ] Changes are the minimum needed to satisfy the spec

package/skills/performance-optimization/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: Performance Optimization
 description: >
-  This skill enforces disciplined performance optimization practices defending against convenience bias,
-  bottleneck mis-targeting, and correctness regressions. It should be used when the user asks to optimize,
-  speed up, improve performance, reduce runtime, or make code faster — any task where the goal is better
-  performance without breaking correctness.
+  Use when optimizing, speeding up, profiling, reducing memory usage, or improving performance.
+  Use when the user says "profile this," "find the bottleneck," "speed up," or "optimize."
+  Use when any change targets performance without breaking correctness.
 ---
 
 # Performance Optimization Discipline
@@ -59,6 +58,8 @@ Before submitting a performance patch, verify it is NOT:
 - **guardrails** — enforces correctness-first and verify-before-claiming during optimization
 - **iterative-execution** — the outer verify-fix cycle for measuring and iterating on improvements
 - **tdd-discipline** — ensures test suite is maintained through optimization changes
+- **spec-first** — performance requirements originate in specs (stack.md, behavior-spec.md)
+- **architecture-aware** — structural optimizations require architectural context
 
 ## References