@abdullah-alnahas/claude-sdd 0.5.0 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "claude-sdd",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Spec-Driven Development discipline system — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops"
 }

package/README.md

@@ -41,6 +41,9 @@ Red → Green → Refactor enforcement. Test traceability from behavior spec to
 ### Iterative Execution
 Disciplined delivery loops: implement with TDD → verify against spec → fix gaps → repeat. TDD is the inner discipline (how you write code), iterative execution is the outer cycle (how you deliver features).
 
+### Performance Optimization
+Profile-first discipline for performance work. Defends against convenience bias (shallow, input-specific hacks), bottleneck mis-targeting, and correctness regressions during optimization.
+
 ## Commands
 
 | Command | Purpose |
@@ -61,6 +64,7 @@ Disciplined delivery loops: implement with TDD → verify against spec → fix g
 | **simplifier** | Complexity reducer — proposes simpler alternatives |
 | **spec-compliance** | Spec adherence checker — verifies traceability (spec → test → code) |
 | **security-reviewer** | Security analysis — OWASP Top 10, input validation, auth review |
+| **performance-reviewer** | Performance optimization reviewer — validates patches for bottleneck targeting, convenience bias, measured improvement |
 
 ## Configuration
 
@@ -107,9 +111,9 @@ whitelist:
 ## Self-Test
 
 ```bash
-bash sdd/scripts/verify-hooks.sh
-bash sdd/scripts/verify-skills.sh
-bash sdd/scripts/verify-commands.sh
+bash scripts/verify-hooks.sh
+bash scripts/verify-skills.sh
+bash scripts/verify-commands.sh
 ```
 
 ## Development Phases

package/agents/critic.md

@@ -70,8 +70,4 @@ You are an adversarial reviewer. Your job is to find what's wrong, not confirm w
 
 ## Performance Patch Review
 
-When reviewing performance optimization patches, additionally check:
-- **Bottleneck targeting**: Does the patch address the actual bottleneck, or a convenient but less impactful location?
-- **Convenience bias**: Is this a structural improvement (algorithm, data structure) or a shallow, input-specific hack that's fragile and hard to maintain?
-- **Measured improvement**: Is the speedup quantified with before/after evidence, or just assumed?
-- **Correctness preservation**: Do all existing tests still pass after the optimization?
+When a patch includes performance changes, check for correctness regressions and logical errors as usual. For dedicated performance analysis (bottleneck targeting, convenience bias, measured speedup), defer to the **performance-reviewer** agent.

package/commands/sdd-adopt.md

@@ -1,7 +1,6 @@
 ---
 name: sdd-adopt
 description: Adopt an existing project into the SDD discipline system
-argument-hint: ""
 allowed-tools:
   - Read
   - Write

package/commands/sdd-autopilot.md

@@ -54,28 +54,41 @@ When invoked, execute the following phases in order. Announce each phase transit
 
 **Input**: Behavior spec + roadmap from previous phases.
 **Actions**:
-1. Work through roadmap items in priority order
+1. Work through roadmap items in priority order, in **batches of 3**
 2. For each item, use TDD:
    - Write failing test(s) that cover the relevant acceptance criteria
    - Write minimal code to pass
    - Refactor
-3. After each roadmap item, run available verification (test suite, linters, type checks)
+3. After each batch of 3 items:
+   - Run available verification (test suite, linters, type checks)
+   - Report progress with verification evidence (actual test output)
+   - Pause for user feedback before continuing
 4. If tests fail, fix using TDD (understand failure → write targeted fix → verify)
 5. Continue until all roadmap items complete
 
 Use the iterative execution outer loop: implement → verify → fix gaps → repeat (max 10 iterations per roadmap item).
 
-**Transition**: "Implement phase complete — N of M roadmap items done. Entering Verify phase."
+**Transition** (only when all items are complete): "Implement phase complete — all M roadmap items done. Entering Verify phase."
 
 ### Phase 4: Verify
 
 **Input**: Implementation from Phase 3.
 **Actions**:
+Use the two-stage review process (see `/sdd-review`):
+
+**Stage 1 — Spec Compliance:**
 1. Run full test suite
 2. Invoke **spec-compliance agent** — compare implementation against behavior-spec.md
-3. Invoke **critic agent** — find logical errors, assumption issues
-4. Invoke **security-reviewer agent** — check for vulnerabilities
-5. Collect all findings
+3. DO NOT trust the implementation report. Read actual code and test output independently.
+4. For each acceptance criterion: PASS / FAIL / PARTIAL with evidence
+5. Stage 1 must pass before proceeding to Stage 2
+
+**Stage 2 — Code Quality:**
+6. Invoke **critic agent** — find logical errors, assumption issues
+7. Invoke **simplifier agent** — find unnecessary complexity
+8. Invoke **security-reviewer agent** — check for vulnerabilities
+9. If performance optimization was part of the spec, invoke **performance-reviewer agent**
+10. Collect all findings
 
 **Transition**: "Verify phase complete — N findings (X critical, Y high, Z medium). Entering Review phase."
 

package/commands/sdd-execute.md

@@ -73,9 +73,27 @@ No critical issues from critic agent.
 Completion is genuine — verified against spec.
 ```
 
+## Batch Execution
+
+When working on multiple criteria or tasks, group them into batches of 3:
+
+1. Implement batch (3 criteria/tasks) using TDD
+2. Verify the batch — run tests, check spec compliance
+3. Report progress with verification evidence (test output, not claims)
+4. Pause for user feedback before continuing to the next batch
+
+This prevents long unverified runs and gives the user control over direction.
+
+## Verification
+
+After each batch, use the two-stage review process:
+- **Stage 1**: Spec compliance — verify each criterion with evidence (see `/sdd-review`)
+- **Stage 2**: Code quality — only after Stage 1 passes
+
 ## Principles
 
 - TDD is the inner discipline: every piece of new code starts with a failing test
 - The outer loop verifies against the spec, not just test results
 - Honest reporting: never claim done when criteria are unsatisfied
 - Bounded: max iterations prevent infinite loops
+- Batch execution: groups of 3 with checkpoint reports

package/commands/sdd-phase.md

@@ -45,7 +45,7 @@ Phase state is stored in `.sdd-phase` in the project root. This file contains a
    - `design` → architecture-aware skill
    - `implement` → TDD discipline + iterative execution skills
    - `verify` → iterative execution (verification step)
-   - `review` → all agents (critic, simplifier, spec-compliance, security-reviewer)
+   - `review` → all agents (critic, simplifier, spec-compliance, security-reviewer, performance-reviewer)
 
 ## Output Format
 
@@ -54,6 +54,14 @@ SDD Phase: implement
 ─────────────────────
 Focus: TDD cycles within iterative execution — write tests first, then minimal code to pass
 
-Available skills: tdd-discipline, iterative-execution, guardrails
-Available agents: critic, simplifier, spec-compliance, security-reviewer
+Available skills: tdd-discipline, iterative-execution, guardrails, performance-optimization
+Recommended agents: critic, spec-compliance
+All agents: critic, simplifier, spec-compliance, security-reviewer, performance-reviewer
 ```
+
+Phase-specific agent recommendations:
+- **specify**: spec-compliance (verify spec completeness)
+- **design**: critic (architectural review), simplifier
+- **implement**: spec-compliance (traceability), critic (logic review)
+- **verify**: critic, security-reviewer, performance-reviewer, spec-compliance
+- **review**: all agents

package/commands/sdd-review.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-review
-description: On-demand self-review using critic and simplifier agents with iterative fix cycles
+description: Two-stage review — spec compliance first, then code quality. Only proceeds to Stage 2 after Stage 1 passes.
 argument-hint: "[--max-iterations <n>]"
 allowed-tools:
   - Read
@@ -14,40 +14,70 @@ allowed-tools:
 
 # /sdd-review
 
-Trigger an on-demand review of recent work using the critic and simplifier agents. Runs iteratively — reviews, fixes, re-reviews until no critical issues remain.
+Trigger a two-stage review of recent work. Stage 1 verifies spec compliance. Stage 2 reviews code quality. Stage 2 only runs after Stage 1 passes.
 
 ## Usage
 
 - `/sdd-review` — Review recent changes
 - `/sdd-review --max-iterations <n>` — Set max review-fix cycles (default: 3)
 
-## Behavior
+## Stage 1: Spec Compliance
+
+**Goal**: Verify the implementation satisfies the behavior spec.
 
 1. Identify what was recently changed (git diff or session context)
-2. Run the **critic agent** — find logical errors, spec drift, assumption issues
-3. Run the **simplifier agent** — find unnecessary complexity
-4. If spec documents exist, run the **spec-compliance agent**
-5. Present findings with severity levels
-6. Offer to auto-fix issues found
-7. If fixes are made (using TDD — write test for the fix first if applicable), re-review
-8. Repeat until no critical issues remain or max iterations reached
+2. Find the relevant behavior spec and acceptance criteria
+3. Run the **spec-compliance agent** with the Stage 1 prompt from `iterative-execution/references/review-prompts.md`
+4. **DO NOT trust the implementation report.** Read the actual code and test output independently.
+5. For each acceptance criterion: PASS / FAIL / PARTIAL with evidence
+6. If any criterion fails:
+   - Present findings
+   - Offer to fix (using TDD — write a test for the fix first)
+   - After fixing, re-run Stage 1
+   - Repeat until all criteria pass or max iterations reached
+
+**Stage 1 must pass before proceeding to Stage 2.**
+
+## Stage 2: Code Quality
+
+**Goal**: Find unnecessary complexity, dead code, scope creep.
+
+1. Run the **critic agent** — find logical errors, assumption issues
+2. Run the **simplifier agent** — find unnecessary complexity
+3. If the changes involve performance optimization, run the **performance-reviewer agent**
+4. Present findings with severity levels:
+   - [Critical] — must fix
+   - [Simplification] — should fix
+   - [Observation] — consider fixing
+5. Offer to auto-fix critical and simplification issues
+6. If fixes are made (using TDD), re-run Stage 2
+7. Repeat until no critical issues remain or max iterations reached
 
 ## Output Format
 
 ```
-SDD Review — Iteration 1/3
-──────────────────────────
+SDD Review — Stage 1: Spec Compliance
+──────────────────────────────────────
+
+Spec: specs/behavior-spec.md (5 criteria)
+
+  ✓ Criterion 1: User can log in — PASS (test_login passes)
+  ✓ Criterion 2: Invalid credentials show error — PASS (test_invalid_login passes)
+  ✗ Criterion 3: Session persists — FAIL (no test found for this criterion)
+
+Stage 1: 2/3 FAIL — must fix before proceeding to Stage 2.
+```
+
+```
+SDD Review — Stage 2: Code Quality
+───────────────────────────────────
 
 Critic Findings:
   [Critical] ...
-  [Warning] ...
 
 Simplifier Findings:
   [Simplification] ...
 
-Spec Compliance:
-  [X of Y criteria satisfied]
-
 Actions:
   - Fix critical issues? (y/n)
   - Apply simplifications? (y/n)
@@ -55,7 +85,12 @@ Actions:
 
 ## Principles
 
+- Stage 1 is the gate. No code quality review on non-compliant code.
 - Reviews are honest — findings are reported as-is, not softened
+- DO NOT trust the implementer's report. Verify independently.
 - Fixes follow TDD: if the fix changes behavior, write a test first
 - Max iterations prevent infinite loops
-- The review itself is part of the iterative execution cycle
+
+## References
+
+See: `iterative-execution/references/review-prompts.md` — Subagent prompt templates

package/commands/sdd-yolo.md

@@ -1,7 +1,6 @@
 ---
 name: sdd-yolo
 description: Temporarily disable all SDD guardrails for this session
-argument-hint: ""
 allowed-tools:
   - Write
   - Bash

package/hooks/hooks.json

@@ -6,8 +6,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/scripts/session-init.sh",
-            "timeout": 10
+            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/session-init.sh\"",
+            "timeout": 10,
+            "additionalContext": true
           }
         ]
       }
@@ -29,7 +30,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/scripts/post-edit-review.sh",
+            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/post-edit-review.sh\"",
             "timeout": 15
           }
         ]

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

@@ -10,24 +10,42 @@ if [ "${GUARDRAILS_DISABLED:-false}" = "true" ]; then
 fi
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# 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)
 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 || echo "")
+  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
 else
-  FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"\s*:\s*"\([^"]*\)".*/\1/p' | head -1)
+  FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[ \t]*:[ \t]*"\([^"]*\)".*/\1/p' | head -1)
   if [ -z "$FILE_PATH" ]; then
-    FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"filePath"\s*:\s*"\([^"]*\)".*/\1/p' | head -1)
+    FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"filePath"[ \t]*:[ \t]*"\([^"]*\)".*/\1/p' | head -1)
   fi
 fi
 
 if [ -z "$FILE_PATH" ]; then
+  echo "SDD: post-edit-review skipped — no file_path in hook input" >&2
   exit 0
 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
 case "$FILE_PATH" in
   "$PROJECT_DIR/"*|"$PROJECT_DIR") ;; # Inside project, OK
@@ -39,7 +57,7 @@ esac
 
 # Check git status for unrelated modifications
 if command -v git &>/dev/null && [ -d "$PROJECT_DIR/.git" ]; then
-  MODIFIED_COUNT=$(cd "$PROJECT_DIR" && git diff --name-only 2>/dev/null | wc -l)
+  MODIFIED_COUNT=$(cd "$PROJECT_DIR" && git diff --name-only 2>/dev/null | wc -l | tr -d ' ')
   if [ "$MODIFIED_COUNT" -gt 10 ]; then
     echo "SDD SCOPE WARNING: $MODIFIED_COUNT files modified — possible scope creep. Review changes with 'git diff --stat'" >&2
     exit 2

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"
@@ -13,7 +18,9 @@ YOLO_FLAG="$PROJECT_DIR/.sdd-yolo"
 if [ -f "$YOLO_FLAG" ]; then
   echo "SDD: Previous YOLO mode detected — clearing flag, guardrails disabled for this session" >&2
   # Remove yolo flag (auto-clears on session start)
-  rm -f "$YOLO_FLAG"
+  if ! rm -f "$YOLO_FLAG" 2>/dev/null; then
+    echo "SDD WARNING: Could not remove yolo flag at $YOLO_FLAG — guardrails may remain disabled next session" >&2
+  fi
   if [ -n "$ENV_FILE" ]; then
     echo "GUARDRAILS_DISABLED=true" >> "$ENV_FILE"
     echo "SDD_YOLO_CLEARED=true" >> "$ENV_FILE"
@@ -40,5 +47,14 @@ else
   fi
 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
+
 echo "SDD: Session initialized — guardrails active" >&2
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abdullah-alnahas/claude-sdd",
-  "version": "0.5.0",
+  "version": "0.7.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

@@ -9,11 +9,13 @@ FAIL=0
 check() {
   local desc="$1"
   shift
-  if "$@" >/dev/null 2>&1; then
+  local output
+  if output=$("$@" 2>&1); then
     echo "  ✓ $desc"
     PASS=$((PASS + 1))
   else
     echo "  ✗ $desc"
+    [ -n "$output" ] && echo "    $output"
     FAIL=$((FAIL + 1))
   fi
 }
@@ -29,7 +31,7 @@ for cmd in "${COMMANDS[@]}"; do
   CMD_FILE="$PLUGIN_DIR/commands/$cmd.md"
 
   check "File exists" test -f "$CMD_FILE"
-  check "Has frontmatter" grep -q "^---" "$CMD_FILE"
+  check "Has frontmatter" bash -c "sed -n '1p' \"$CMD_FILE\" | grep -q '^---'"
   check "Has name field" grep -q "^name:" "$CMD_FILE"
   check "Has description field" grep -q "^description:" "$CMD_FILE"
   check "Is non-empty (>100 chars)" test "$(wc -c < "$CMD_FILE")" -gt 100
@@ -45,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")
+AGENTS=("critic" "simplifier" "spec-compliance" "security-reviewer" "performance-reviewer")
 for agent in "${AGENTS[@]}"; do
   check "Agent: $agent.md exists" test -f "$PLUGIN_DIR/agents/$agent.md"
 done

package/scripts/verify-hooks.sh

@@ -9,11 +9,13 @@ FAIL=0
 check() {
   local desc="$1"
   shift
-  if "$@" >/dev/null 2>&1; then
+  local output
+  if output=$("$@" 2>&1); then
     echo "  ✓ $desc"
     PASS=$((PASS + 1))
   else
     echo "  ✗ $desc"
+    [ -n "$output" ] && echo "    $output"
     FAIL=$((FAIL + 1))
   fi
 }
@@ -21,36 +23,50 @@ 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; json.load(open('$PLUGIN_DIR/hooks/hooks.json'))"
-check "Has hooks wrapper" python3 -c "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+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'
-"
-check "Has SessionStart hook" python3 -c "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+" "$PLUGIN_DIR/hooks/hooks.json"
+  check "Has SessionStart hook" "$PYTHON" -c "
+import json, sys
+d = json.load(open(sys.argv[1]))
 assert 'SessionStart' in d['hooks']
-"
-check "Has UserPromptSubmit hook" python3 -c "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+" "$PLUGIN_DIR/hooks/hooks.json"
+  check "Has UserPromptSubmit hook" "$PYTHON" -c "
+import json, sys
+d = json.load(open(sys.argv[1]))
 assert 'UserPromptSubmit' in d['hooks']
-"
-check "Has PostToolUse hook" python3 -c "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+" "$PLUGIN_DIR/hooks/hooks.json"
+  check "Has PostToolUse hook" "$PYTHON" -c "
+import json, sys
+d = json.load(open(sys.argv[1]))
 assert 'PostToolUse' in d['hooks']
-"
-check "Has Stop hook" python3 -c "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+" "$PLUGIN_DIR/hooks/hooks.json"
+  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 ""
@@ -60,10 +76,16 @@ check "post-edit-review.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/post-edit-
 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"
 
-# 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

@@ -9,11 +9,13 @@ FAIL=0
 check() {
   local desc="$1"
   shift
-  if "$@" >/dev/null 2>&1; then
+  local output
+  if output=$("$@" 2>&1); then
     echo "  ✓ $desc"
     PASS=$((PASS + 1))
   else
     echo "  ✗ $desc"
+    [ -n "$output" ] && echo "    $output"
     FAIL=$((FAIL + 1))
   fi
 }
@@ -21,7 +23,7 @@ check() {
 echo "SDD Skill Verification"
 echo "──────────────────────"
 
-SKILLS=("guardrails" "spec-first" "architecture-aware" "tdd-discipline" "iterative-execution")
+SKILLS=("guardrails" "spec-first" "architecture-aware" "tdd-discipline" "iterative-execution" "performance-optimization" "using-sdd")
 
 for skill in "${SKILLS[@]}"; do
   echo ""
@@ -30,7 +32,7 @@ for skill in "${SKILLS[@]}"; do
 
   check "Directory exists" test -d "$SKILL_DIR"
   check "SKILL.md exists" test -f "$SKILL_DIR/SKILL.md"
-  check "SKILL.md has frontmatter" grep -q "^---" "$SKILL_DIR/SKILL.md"
+  check "SKILL.md has frontmatter" bash -c "sed -n '1p' \"$SKILL_DIR/SKILL.md\" | grep -q '^---'"
   check "SKILL.md has name field" grep -q "^name:" "$SKILL_DIR/SKILL.md"
   check "SKILL.md has description field" grep -q "^description:" "$SKILL_DIR/SKILL.md"
 

package/skills/architecture-aware/SKILL.md

@@ -1,10 +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?", or "should I split this into services?"
+  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
@@ -22,13 +21,13 @@ Every pattern has trade-offs. State the specific benefit for THIS codebase, not
 ### Record Significant Decisions
 If a decision is hard to reverse or affects multiple components, it deserves an ADR (Architecture Decision Record).
 
-## When to Engage
+## When an Architecture Question Arises
 
-- User asks "how should I structure this?"
-- Adding a new component to an existing system
-- Introducing a new technology or pattern
-- Changing how components communicate
-- Anything that touches 3+ modules/services
+1. **Survey existing patterns** — read the codebase to understand current conventions, patterns, and structure
+2. **Evaluate fit** — does the proposed approach align with or diverge from existing patterns? Divergence needs justification.
+3. **State trade-offs explicitly** — every option has costs and benefits. Name them concretely for this codebase.
+4. **Decide whether an ADR is warranted** — write one if the decision is hard to reverse or affects multiple components
+5. **Document if yes** — use the ADR template from `references/adr-guide.md`
 
 ## What to Check
 
@@ -37,6 +36,12 @@ If a decision is hard to reverse or affects multiple components, it deserves an
 3. **Coupling**: Are we creating tight coupling between components?
 4. **Consistency**: Does this follow or violate established conventions?
 
+## 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
 
 See: `references/integration-patterns.md`

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
 
@@ -51,14 +97,7 @@ Before writing ANY implementation code, you MUST:
 
 ## Performance Changes
 
-When the task is performance optimization:
-
-1. **Profile first** — identify the actual bottleneck with evidence (timing, profiler output). Never guess.
-2. **Verify correctness after every change** — run the full test suite. Any test regression invalidates the optimization.
-3. **Measure improvement quantitatively** — compare before/after timings. No "it should be faster" — prove it.
-4. **Prefer structural improvements** — algorithmic and data-structure changes over micro-optimizations or input-specific hacks.
-5. **Never sacrifice correctness for speed** — a faster but broken program is not an optimization, it's a defect.
-6. **Watch for convenience bias** — small, surface-level tweaks that are easy to produce but fragile and hard to maintain. Push for deeper fixes.
+For performance optimization tasks, follow the **performance-optimization** skill for the full workflow (profile-first discipline, convenience bias detection, measured improvement). The core rule: never sacrifice correctness for speed.
 
 ## Completion Review
 
@@ -67,7 +106,7 @@ Before claiming work is done:
 1. Re-read the original request
 2. Verify every requirement is met
 3. Check for dead code you introduced
-4. Check function/file length limits (50/500 lines)
+4. Check function/file length guidelines (aim for ~50/~500 lines — adapt to project conventions)
 5. Verify no unrelated files were modified
 6. Run available tests
 
@@ -75,5 +114,15 @@ Before claiming work is done:
 
 Consult the failure patterns reference for detailed detection and response guidance for all 12 failure modes.
 
+## Related Skills
+
+- **spec-first** — for the pre-implementation spec check (step 6 above)
+- **tdd-discipline** — for the TDD inner discipline during implementation
+- **iterative-execution** — for the implement-verify-fix outer cycle
+- **performance-optimization** — for performance-specific guardrails
+- **architecture-aware** — for architectural consistency checks
+
+## References
+
 See: `references/failure-patterns.md`
 See: `references/pushback-guide.md`

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:
@@ -54,11 +68,7 @@ Use whatever is available, in order of preference:
 
 ## Performance Optimization Tasks
 
-When the task is performance optimization, the verification step MUST include:
-1. **Timing comparison** — measure before vs after on the actual workload. Quantify the speedup.
-2. **Test suite pass** — correctness preserved. Any new test failure invalidates the optimization.
-3. **Profile comparison** — confirm the bottleneck was actually addressed, not just masked or shifted elsewhere.
-4. **Convenience bias check** — is this a structural improvement or a shallow, input-specific hack? If the latter, iterate.
+For performance optimization tasks, the verification step must additionally include timing comparison, profile comparison, and convenience bias checks. Follow the **performance-optimization** skill for the full workflow.
 
 ## Honesty Rules
 
@@ -67,7 +77,16 @@ When the task is performance optimization, the verification step MUST include:
 - **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."
 
+## 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`

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,
-  localization failure, 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
@@ -49,10 +48,18 @@ Performance optimization is investigative work. You must understand the problem
 ## Convenience Bias Checklist
 
 Before submitting a performance patch, verify it is NOT:
-- [ ] An input-specific hack that only helps one case
-- [ ] A micro-optimization with unmeasurable impact
-- [ ] A change that trades correctness risk for speed
-- [ ] A surface-level tweak when a deeper structural fix exists
+- An input-specific hack that only helps one case
+- A micro-optimization with unmeasurable impact
+- A change that trades correctness risk for speed
+- A surface-level tweak when a deeper structural fix exists
+
+## Related Skills
+
+- **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
 

package/skills/spec-first/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: Spec-First Development
 description: >
-  This skill guides interactive specification development, turning rough ideas into formal documents before
-  any code is written. It should be used when the user is starting a new project or feature, wants to create
-  specs or plans, is adopting an existing project, or says things like "I want to build something," "let's
-  plan this out," "write a spec for this," or "let's design this first."
+  Use when starting a new project or feature, creating specs or plans, adopting an existing project,
+  or when the user says "I want to build something," "let's plan this out," "write a spec," or
+  "let's design this first." Use before any non-trivial implementation that lacks a spec.
 ---
 
 # Spec-First Development
@@ -60,6 +59,13 @@ For existing projects, use the adoption flow instead of starting from scratch. S
 - **Documents are living**: Specs evolve. That's fine. But they must exist before code.
 - **Lean templates**: The templates are starting points, not forms to fill out
 
+## Related Skills
+
+- **architecture-aware** — for deeper architectural guidance during Stage 4
+- **tdd-discipline** — for test planning from behavior specs (use `references/templates/test-plan.md`)
+- **iterative-execution** — delivers features against the specs produced here
+- **guardrails** — enforces spec-first as a pre-implementation check
+
 ## References
 
 See: `references/interactive-spec-process.md` — Detailed questioning flow

package/skills/tdd-discipline/SKILL.md

@@ -1,15 +1,19 @@
 ---
 name: TDD Discipline
 description: >
-  This skill enforces test-driven development discipline with the Red/Green/Refactor cycle and traceability
-  from behavior spec to test to code. It should be used when the user asks to write tests, add test coverage,
-  discuss testing strategy, or says "how should I test this?", "add tests for this," or "write tests first."
+  Use when writing tests, adding test coverage, fixing bugs, debugging, or when any new code needs
+  to be written. Use when the user says "write tests," "add tests," "fix this bug," "debug this,"
+  or "how should I test this?"
 ---
 
 # TDD Discipline
 
 Tests are not an afterthought — they are the first expression of intent. Write the test that describes the behavior, watch it fail, then write the minimum code to make it pass.
 
+## Spirit vs. Letter
+
+The spirit of TDD is: **know what correct behavior looks like before writing the code.** The Red/Green/Refactor cycle is the mechanism, but the principle is that you define "done" before you start. If a situation genuinely doesn't benefit from a test-first approach (see "When TDD Is Overhead" below), skip the mechanism — but never skip the principle of defining expected behavior first.
+
 ## Red → Green → Refactor
 
 1. **Red**: Write a failing test that describes the desired behavior
@@ -18,9 +22,24 @@ Tests are not an afterthought — they are the first expression of intent. Write
 
 This cycle applies at every level: unit, integration, e2e.
 
+## Rationalization Red Flags
+
+These thoughts mean STOP — you're about to skip TDD:
+
+| Thought | Reality |
+|---------|---------|
+| "I'll write tests after the code works" | That's test-after, not TDD. Write the test first. |
+| "This is too simple to need a test" | Simple code with no test becomes complex code with no test. |
+| "I know this works, I'll just verify manually" | Manual verification doesn't persist. Tests do. |
+| "The test is obvious, I'll skip to code" | If it's obvious, it takes 30 seconds to write. Do it. |
+| "I need to see the code structure first" | Write the test to discover the structure. That's the point. |
+| "This is just a refactor, tests already pass" | Run the tests. Confirm they pass. Then refactor. |
+| "Writing a test for this would be too complex" | If you can't test it, you can't verify it. Simplify the design. |
+| "I'll add tests in the next iteration" | Next iteration never comes. Write them now. |
+
 ## Relationship to Iterative Execution
 
-TDD is the **inner discipline** — how you write each piece of code. Iterative execution is the **outer cycle** — how you deliver a complete feature against a spec. Every "implement" step in the iterative execution cycle uses TDD internally. They are complementary: TDD ensures code correctness at the unit level; iterative execution ensures spec satisfaction at the feature level.
+TDD is the **inner discipline** — how you write each piece of code. Iterative execution is the **outer cycle** — how you deliver a complete feature against a spec. They are complementary: TDD ensures correctness at the unit level; iterative execution ensures spec satisfaction at the feature level. See the **iterative-execution** skill for the full outer cycle.
 
 ## When TDD Adds Value
 
@@ -49,6 +68,13 @@ Code: FormHandler.submit()
 
 This chain ensures nothing is built without a reason and nothing specified goes untested. If a test has no spec criterion, either add the criterion to the spec or question whether the test is needed. If a spec criterion has no test, that is a finding — even if the code works.
 
+## Related Skills
+
+- **iterative-execution** — the outer delivery cycle that uses TDD internally
+- **spec-first** — produces behavior specs that drive test design (see `spec-first/references/templates/test-plan.md`)
+- **guardrails** — enforces TDD during implementation
+- **performance-optimization** — uses TDD to preserve correctness during optimization
+
 ## References
 
 See: `references/test-strategies.md`

package/skills/using-sdd/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: Using SDD
+description: >
+  Use at the start of every session and before every response to determine which SDD skills apply.
+  This is the meta-skill — it teaches skill discovery and invocation discipline.
+---
+
+# Using SDD Skills
+
+You have access to SDD (Spec-Driven Development) skills that enforce development discipline. **Check for applicable skills before every response.**
+
+## The Rule
+
+**Invoke relevant skills BEFORE any response or action.** Even a 1% chance a skill might apply means you should check. If it turns out to be wrong for the situation, you don't need to use it.
+
+## Available Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| **guardrails** | ANY coding task — implement, build, fix, refactor, add, change, modify |
+| **spec-first** | New project/feature, creating specs/plans, adopting a project |
+| **tdd-discipline** | Writing tests, adding coverage, fixing bugs, debugging |
+| **iterative-execution** | Implementing a feature from spec, iterating to match requirements |
+| **architecture-aware** | Structuring code, design patterns, component integration, ADRs |
+| **performance-optimization** | Optimizing, profiling, speeding up, reducing resource usage |
+
+## Skill Priority Order
+
+When multiple skills apply, use this order:
+
+1. **Guardrails first** — always active for any coding task. This is the discipline layer.
+2. **Process skills second** (spec-first, tdd-discipline, iterative-execution) — these determine HOW to approach the task.
+3. **Domain skills third** (architecture-aware, performance-optimization) — these provide specialized guidance.
+
+## Rationalization Red Flags
+
+These thoughts mean STOP — you're rationalizing skipping a skill:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions about code are tasks. Check guardrails. |
+| "I need more context first" | Skill check comes BEFORE exploration. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can just do this quickly" | Quick work is where discipline matters most. |
+| "This doesn't need a formal skill" | If a skill exists for this task type, use it. |
+| "I remember the skill" | Skills evolve. Read the current version. |
+| "This doesn't count as implementation" | If you're changing code, guardrails apply. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "The user said to skip guardrails" | Only `/sdd-yolo` disables guardrails. Verbal requests don't count. |
+| "I already know what to do" | Knowing the task ≠ following the discipline. |
+
+## Skill Classification
+
+**Rigid skills** (follow exactly, don't adapt away discipline):
+- guardrails
+- tdd-discipline
+
+**Flexible skills** (adapt principles to context):
+- spec-first
+- architecture-aware
+- iterative-execution
+- performance-optimization
+
+## Spirit vs. Letter
+
+Follow the **spirit** of each skill, not just its checklist. 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.
+
+## References
+
+See: `references/skill-creation-process.md`

package/skills/using-sdd/references/skill-creation-process.md

@@ -0,0 +1,54 @@
+# Skill Creation Process
+
+Creating new SDD skills follows a RED/GREEN/REFACTOR approach — the same TDD discipline applied to the skills themselves.
+
+## RED: Identify the Failure
+
+Before writing a skill, you need evidence of a failure pattern:
+
+1. **Observe the failure** — identify a specific, repeatable behavior problem (e.g., the agent skips verification, over-engineers, ignores specs)
+2. **Document the failure** — write down exactly what went wrong, with concrete examples
+3. **Pressure test** — verify this isn't a one-off. Does it happen across different tasks, projects, or prompts?
+
+If you can't reproduce the failure consistently, you don't need a skill yet. You need more data.
+
+## GREEN: Write the Minimal Skill
+
+Write the smallest skill that addresses the failure:
+
+1. **Frontmatter** — name + CSO-format description ("Use when..." with trigger conditions only)
+2. **One core principle** — the single behavioral change needed
+3. **Detection** — how the agent recognizes it's about to fail
+4. **Response** — what the agent should do instead
+5. **Rationalization table** — 4-8 entries mapping excuses to counters
+
+The skill should be under 500 words at this stage. If it's longer, you're solving too many problems at once.
+
+## REFACTOR: Plug Loopholes
+
+Deploy the minimal skill and observe:
+
+1. **Does the agent follow it?** If not, the trigger conditions in the description may be wrong — fix them.
+2. **Does the agent rationalize around it?** Add entries to the rationalization table for each observed excuse.
+3. **Does it create new problems?** If the skill causes over-correction (e.g., too rigid in cases where flexibility is needed), add "When This Skill Is Overhead" section.
+4. **Is it too broad?** Split into focused skills. One skill should address one failure pattern cluster.
+
+## Checklist
+
+Before shipping a new skill:
+
+- [ ] Failure pattern documented with 3+ examples
+- [ ] Description uses "Use when..." CSO format
+- [ ] Rationalization table has 4+ entries
+- [ ] Skill body under 3000 words
+- [ ] References directory exists (even if empty initially)
+- [ ] Added to `using-sdd` skill table
+- [ ] Added to `scripts/verify-skills.sh` SKILLS array
+- [ ] Rigid vs. flexible classification documented in `using-sdd`
+
+## Anti-Patterns
+
+- **Speculative skills**: Writing a skill for a problem you haven't observed yet
+- **Kitchen-sink skills**: Cramming multiple unrelated concerns into one skill
+- **Checklist-only skills**: Lists of rules without detection/response guidance
+- **Aspirational skills**: Describing ideal behavior without addressing the specific failure that motivated the skill