@abdullah-alnahas/claude-sdd 0.5.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "claude-sdd",
-  "version": "0.5.0",
+  "version": "0.6.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

@@ -75,7 +75,8 @@ Use the iterative execution outer loop: implement → verify → fix gaps → re
 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
+5. If performance optimization was part of the spec, invoke **performance-reviewer agent**
+6. Collect all findings
 
 **Transition**: "Verify phase complete — N findings (X critical, Y high, Z medium). Entering Review phase."
 

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**: security-reviewer, performance-reviewer, spec-compliance
+- **review**: all agents

package/commands/sdd-review.md

@@ -27,10 +27,11 @@ Trigger an on-demand review of recent work using the critic and simplifier agent
 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
+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
 
 ## Output Format
 

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,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/scripts/session-init.sh",
+            "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/session-init.sh\"",
             "timeout": 10
           }
         ]
@@ -29,7 +29,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,38 @@ if [ "${GUARDRAILS_DISABLED:-false}" = "true" ]; then
 fi
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# Resolve to absolute path to avoid relative vs absolute mismatch
+if command -v realpath &>/dev/null; then
+  PROJECT_DIR=$(realpath "$PROJECT_DIR" 2>/dev/null || 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)
+  if [ $? -ne 0 ] || [ -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")
+fi
+
 # Check if inside project directory
 case "$FILE_PATH" in
   "$PROJECT_DIR/"*|"$PROJECT_DIR") ;; # Inside project, OK
@@ -39,7 +53,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

@@ -13,7 +13,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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abdullah-alnahas/claude-sdd",
-  "version": "0.5.0",
+  "version": "0.6.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
 }
@@ -25,32 +27,32 @@ echo "─────────────────────"
 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 "Valid JSON" python3 -c "import json, sys; json.load(open(sys.argv[1]))" "$PLUGIN_DIR/hooks/hooks.json"
 check "Has hooks wrapper" python3 -c "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+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 "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+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 "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+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 "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+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 "
-import json
-d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+import json, sys
+d = json.load(open(sys.argv[1]))
 assert 'Stop' in d['hooks']
-"
+" "$PLUGIN_DIR/hooks/hooks.json"
 
 # Check scripts exist and are executable
 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")
 
 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

@@ -4,7 +4,8 @@ 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?"
+  "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."
 ---
 
 # Architecture Awareness
@@ -22,13 +23,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 +38,11 @@ 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)
+- **guardrails** — enforces architectural consistency as part of scope discipline
+
 ## References
 
 See: `references/integration-patterns.md`

package/skills/guardrails/SKILL.md

@@ -51,14 +51,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 +60,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 +68,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/iterative-execution/SKILL.md

@@ -54,11 +54,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
 
@@ -69,5 +65,14 @@ When the task is performance optimization, the verification step MUST include:
 
 ## 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
+- **performance-optimization** — specialized verification for performance tasks
+
+## References
+
 See: `references/loop-patterns.md`
 See: `references/completion-criteria.md`

package/skills/performance-optimization/SKILL.md

@@ -2,7 +2,7 @@
 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,
+  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.
 ---
@@ -49,10 +49,16 @@ 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
 
 ## References
 

package/skills/spec-first/SKILL.md

@@ -60,6 +60,12 @@ 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`)
+- **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

@@ -3,7 +3,8 @@ 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."
+  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."
 ---
 
 # TDD Discipline
@@ -20,7 +21,7 @@ This cycle applies at every level: unit, integration, e2e.
 
 ## 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
 
@@ -51,5 +52,13 @@ This chain ensures nothing is built without a reason and nothing specified goes
 
 ## 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
+
+## References
+
 See: `references/test-strategies.md`
 See: `references/traceability.md`