@abdullah-alnahas/claude-sdd 0.6.0 → 0.7.0

package/.claude-plugin/plugin.json

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

package/commands/sdd-autopilot.md

@@ -54,29 +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. If performance optimization was part of the spec, invoke **performance-reviewer agent**
-6. 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

@@ -63,5 +63,5 @@ Phase-specific agent recommendations:
 - **specify**: spec-compliance (verify spec completeness)
 - **design**: critic (architectural review), simplifier
 - **implement**: spec-compliance (traceability), critic (logic review)
-- **verify**: security-reviewer, performance-reviewer, spec-compliance
+- **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,41 +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. If the changes involve performance optimization, run the **performance-reviewer agent**
-6. Present findings with severity levels
-7. Offer to auto-fix issues found
-8. If fixes are made (using TDD — write a test for the fix first), re-review
-9. 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)
@@ -56,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/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
           }
         ]
       }

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

@@ -10,9 +10,11 @@ if [ "${GUARDRAILS_DISABLED:-false}" = "true" ]; then
 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 +22,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 +42,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"
@@ -42,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.6.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-hooks.sh

@@ -23,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, 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 ""
@@ -62,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

@@ -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,16 @@ 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`

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
 

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
@@ -64,6 +63,7 @@ For existing projects, use the adoption flow instead of starting from scratch. S
 
 - **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

package/skills/tdd-discipline/SKILL.md

@@ -1,16 +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, fix a bug, or says "how should I test this?", "add tests for this," "write tests first,"
-  "fix this bug," or "debug this."
+  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
@@ -19,6 +22,21 @@ 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. 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.
@@ -50,13 +68,12 @@ 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.
 
-## References
-
 ## 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
 

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