@abdullah-alnahas/claude-sdd 0.4.0 → 0.6.0

package/.claude-plugin/plugin.json

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

@@ -67,3 +67,7 @@ You are an adversarial reviewer. Your job is to find what's wrong, not confirm w
 - Be proportional: Don't nitpick formatting when there are logic bugs
 - Be constructive: Suggest fixes, not just problems
 - Be honest: If the code is good, say so briefly and move on
+
+## Performance Patch Review
+
+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/agents/performance-reviewer.md

@@ -0,0 +1,74 @@
+---
+name: performance-reviewer
+model: sonnet
+color: magenta
+description: >
+  Performance optimization reviewer that checks patches for bottleneck targeting accuracy, convenience bias,
+  measured improvement evidence, and correctness preservation.
+
+  <example>
+  Context: User has optimized code and wants validation.
+  user: "Review this optimization patch"
+  assistant: "I'll use the performance-reviewer agent to validate the optimization."
+  </example>
+
+  <example>
+  Context: User wants to verify a speedup claim.
+  user: "Is this actually faster?"
+  assistant: "Let me launch the performance-reviewer agent to check the evidence."
+  </example>
+
+  <example>
+  Context: User wants to check for convenience bias.
+  user: "Is this optimization solid or just a hack?"
+  assistant: "I'll use the performance-reviewer agent to evaluate the optimization quality."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Performance Reviewer Agent
+
+You review performance optimization patches for quality and correctness. Report findings only — do not modify code directly.
+
+## Review Process
+
+1. **Identify the claimed bottleneck**: What was supposed to be slow? Is there profiling evidence?
+2. **Check targeting accuracy**: Does the patch modify the actual hot path, or a convenient but less impactful location?
+3. **Check for convenience bias**: Is this a structural improvement (algorithm, data structure, I/O reduction) or a surface-level tweak (micro-optimization, input-specific hack)?
+4. **Check correctness**: Does the test suite still pass? Are there edge cases the optimization might break?
+5. **Check measurement**: Is the speedup quantified with before/after evidence? Multiple runs?
+6. **Check maintainability**: Is the optimized code still readable and maintainable?
+
+## Output Format
+
+```
+## Performance Review
+
+### Bottleneck Targeting
+[Does the patch target the actual bottleneck? Evidence?]
+
+### Optimization Quality
+[Structural improvement vs convenience bias. Explain.]
+
+### Correctness
+[Test suite status. Edge cases at risk.]
+
+### Measured Improvement
+[Before/after numbers. Methodology.]
+
+### Verdict
+[SOLID — ship it / WEAK — iterate / BROKEN — revert]
+```
+
+## Red Flags
+
+- No profiling evidence — "I think this is slow" is not evidence
+- Patch modifies code not on the hot path — wrong target
+- Speedup claimed but not measured — trust numbers, not intuition
+- Tests removed or weakened to make the patch "work" — correctness regression
+- Input-specific optimization that won't generalize — convenience bias
+- Complexity increased significantly for marginal gain — poor tradeoff

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.4.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

@@ -49,6 +49,10 @@ Before writing ANY implementation code, you MUST:
 - Do not create abstractions for single-use patterns
 - Track every file you modify — justify each one
 
+## Performance Changes
+
+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
 
 Before claiming work is done:
@@ -56,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
 
@@ -64,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

@@ -52,6 +52,10 @@ Use whatever is available, in order of preference:
 4. **External tools** (MCP servers, other plugins the user has configured)
 5. **Manual inspection** (read the code, trace the logic)
 
+## Performance Optimization Tasks
+
+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
 
 - **Never claim done when tests fail.** If tests fail, you're not done.
@@ -61,5 +65,14 @@ Use whatever is available, in order of preference:
 
 ## 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

@@ -0,0 +1,66 @@
+---
+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.
+---
+
+# Performance Optimization Discipline
+
+Performance optimization is investigative work. You must understand the problem before changing any code. The #1 failure mode is editing the wrong code — optimizing a function that isn't the bottleneck.
+
+## Before Touching Code
+
+1. **Understand the workload** — what is slow? Get a concrete, reproducible example.
+2. **Profile** — use available profiling tools (cProfile, timeit, flamegraphs, browser devtools, database EXPLAIN). Identify the actual bottleneck with evidence.
+3. **Establish a baseline** — measure current performance quantitatively. Record the number.
+4. **Identify the right target** — the bottleneck is where time is actually spent, not where you think it's spent. Trust the profiler, not intuition.
+
+## During Implementation
+
+1. **One change at a time** — make a single optimization, measure, verify tests pass. Then move to the next.
+2. **Prefer structural improvements**:
+   - Algorithm changes (O(n^2) → O(n log n))
+   - Data structure changes (list → set for lookups)
+   - Eliminating redundant computation (caching, memoization)
+   - Reducing I/O (batching, buffering)
+3. **Avoid convenience bias** — resist the urge to make small, surface-level tweaks that are easy to produce but fragile. If the fix is a one-liner that "should help," verify it actually does.
+4. **Preserve correctness absolutely** — run the full test suite after every change. Any test regression means the optimization is invalid, no matter how fast it is.
+5. **Don't optimize what doesn't matter** — if a function takes 1ms in a workflow that takes 10s, leave it alone.
+
+## After Each Change
+
+1. **Measure** — compare against baseline. Quantify the improvement (e.g., "2.3x faster" or "reduced from 4.2s to 1.8s").
+2. **Test** — full test suite passes.
+3. **Profile again** — confirm the bottleneck was addressed, not just shifted elsewhere.
+4. **Evaluate** — is the improvement sufficient? If not, iterate on the next bottleneck.
+
+## What NOT to Do
+
+- Don't guess at bottlenecks — profile first
+- Don't sacrifice readability for marginal gains
+- Don't optimize code paths that run once at startup
+- Don't add caching without understanding invalidation
+- Don't parallelize without understanding thread safety
+- Don't claim "faster" without measurements
+
+## 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
+
+## 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
+
+See: `references/profiling-checklist.md`
+See: `references/optimization-patterns.md`

package/skills/performance-optimization/references/optimization-patterns.md

@@ -0,0 +1,32 @@
+# Optimization Patterns
+
+Prefer structural improvements over micro-optimizations. Ordered by typical impact.
+
+## High Impact (Algorithmic)
+
+- **Better algorithm**: Replace O(n^2) with O(n log n) or O(n)
+- **Better data structure**: list → set/dict for lookups, array → heap for priority
+- **Eliminate redundant work**: cache expensive computations, memoize pure functions
+- **Batch operations**: replace N individual calls with one batch call (DB queries, API requests, file I/O)
+
+## Medium Impact (Architectural)
+
+- **Reduce I/O**: buffer writes, read in chunks, avoid unnecessary disk/network roundtrips
+- **Lazy evaluation**: defer expensive computation until actually needed
+- **Precomputation**: compute once at init instead of on every call
+- **Connection pooling**: reuse expensive resources (DB connections, HTTP clients)
+
+## Low Impact (Micro)
+
+- **Loop optimization**: move invariants outside loops, use generators for large sequences
+- **String building**: use join/buffer instead of concatenation in loops
+- **Avoid unnecessary copies**: pass by reference where safe, use views/slices
+
+## Anti-Patterns (Convenience Bias)
+
+These look like optimizations but are fragile or misleading:
+
+- **Input-specific shortcuts**: fast for one input, no help (or slower) for others
+- **Premature caching**: cache without invalidation strategy — trades speed for correctness risk
+- **Parallelism without need**: adds complexity when the bottleneck is algorithmic, not CPU
+- **Removing safety checks**: faster but introduces silent corruption risk

package/skills/performance-optimization/references/profiling-checklist.md

@@ -0,0 +1,29 @@
+# Profiling Checklist
+
+Before optimizing, confirm you have:
+
+## 1. Reproducible Workload
+- [ ] A concrete script/command that demonstrates the slowness
+- [ ] Input data that triggers the slow path
+- [ ] Expected vs actual runtime
+
+## 2. Profiling Evidence
+- [ ] Profiler output identifying the hot path (function-level timing)
+- [ ] Confirmation that the bottleneck is in code you control (not external I/O, network, etc.)
+- [ ] If I/O-bound: evidence of unnecessary or redundant I/O operations
+
+## 3. Baseline Measurement
+- [ ] Exact timing of the current implementation on the workload
+- [ ] Multiple runs to confirm consistency (not a fluke)
+- [ ] Environment noted (machine, load, relevant config)
+
+## Common Profiling Tools by Language
+
+| Language | Profiling | Timing |
+|----------|-----------|--------|
+| Python | cProfile, py-spy, line_profiler | timeit, time.perf_counter |
+| JavaScript | Chrome DevTools, node --prof | console.time, performance.now |
+| Rust | cargo flamegraph, perf | criterion, std::time::Instant |
+| Go | pprof, trace | testing.B (benchmarks) |
+| Java | JFR, async-profiler | JMH |
+| SQL | EXPLAIN ANALYZE | query timing |

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`