@abdullah-alnahas/claude-sdd 0.3.0 → 0.5.0

package/.claude-plugin/plugin.json

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

package/agents/critic.md

@@ -32,7 +32,7 @@ allowed-tools:
 
 # Critic Agent
 
-You are an adversarial reviewer. Your job is to find what's wrong, not confirm what's right.
+You are an adversarial reviewer. Your job is to find what's wrong, not confirm what's right. Report findings only — do not modify code directly.
 
 ## Review Process
 
@@ -67,3 +67,11 @@ 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 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?

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/agents/security-reviewer.md

@@ -41,7 +41,7 @@ You review code through a security lens. Focus on high-impact issues, not theore
 3. **Check auth/authz**: Are protected resources properly gated?
 4. **Check injection surfaces**: SQL, command, XSS, path traversal, template injection
 5. **Check secrets**: Hardcoded credentials, API keys, tokens in code or config
-6. **Check dependencies**: Known vulnerable versions (if dependency info available)
+6. **Check dependencies**: Known vulnerable versions — run available audit tools (`npm audit`, `pip-audit`, `cargo audit`) when dependency files are present
 
 ## Priority Order
 

package/agents/simplifier.md

@@ -32,7 +32,7 @@ allowed-tools:
 
 # Simplifier Agent
 
-You ask one question: "Could this be done with less?" Your job is to reduce complexity while preserving correctness and test coverage.
+You ask one question: "Could this be done with less?" Your job is to identify complexity and propose simpler alternatives. Report findings only — do not modify code directly.
 
 ## Review Process
 

package/commands/sdd-guardrails.md

@@ -26,12 +26,28 @@ Show the current state of all SDD guardrails and optionally toggle them.
 | `scope-guard` | PostToolUse (Write/Edit) | Detect unrelated file modifications |
 | `completion-review` | Stop | Spec adherence, test coverage, complexity audit, dead code check |
 
+## Persistence
+
+Guardrail state is stored in `.sdd.yaml` under the `guardrails` key. Each guardrail has an `enabled` boolean:
+
+```yaml
+guardrails:
+  pre-implementation:
+    enabled: true
+  scope-guard:
+    enabled: true
+  completion-review:
+    enabled: true
+```
+
+When toggling a guardrail, read `.sdd.yaml`, update the relevant `enabled` value, and write it back. If `.sdd.yaml` does not exist, create it with defaults (all enabled).
+
 ## Behavior
 
 1. Check if `.sdd.yaml` exists in project root — if so, read guardrail config from it
 2. Check if `GUARDRAILS_DISABLED=true` (set by `/sdd-yolo`) — if so, report all disabled
 3. Display each guardrail with its enabled/disabled status
-4. If an argument is provided, toggle the specified guardrail
+4. If an argument is provided, toggle the specified guardrail in `.sdd.yaml`
 
 ## Output Format
 

package/commands/sdd-phase.md

@@ -27,10 +27,18 @@ Display or change the current SDD development phase. Phases provide context that
 | **verify** | Verification | Running full verification suite, spec-compliance checks, security review |
 | **review** | Review | Critic + simplifier agents, retrospective |
 
+## Persistence
+
+Phase state is stored in `.sdd-phase` in the project root. This file contains a single word (the phase name). If the file does not exist, phase is "none".
+
+- **Set phase**: Write the phase name to `.sdd-phase`
+- **Show phase**: Read `.sdd-phase` (or report "none" if missing)
+- **Clear phase**: Delete `.sdd-phase`
+
 ## Behavior
 
-1. Display the current phase (or "none" if not set)
-2. If a phase name is provided, set it
+1. Read `.sdd-phase` to display the current phase (or "none" if not found)
+2. If a phase name is provided, validate it against the known phases and write to `.sdd-phase`
 3. Phase context is available to subsequent prompts and skills
 4. Phase affects which skills are most relevant:
    - `specify` → spec-first skill

package/hooks/hooks.json

@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "If this message is a trivial acknowledgment (e.g. 'yes', 'no', 'thanks', 'ok', 'continue'), skip the checkpoint and respond normally.\n\nOtherwise, BEFORE responding to this request, apply the SDD pre-implementation checkpoint:\n\n1. **Enumerate Assumptions**: List every assumption you're making about the user's intent, the codebase, and the approach. Flag any that are uncertain.\n\n2. **Flag Ambiguity**: If the request is unclear, underspecified, or could be interpreted multiple ways, ASK for clarification before proceeding. Do not guess.\n\n3. **Surface Alternatives**: Identify at least 2 alternative approaches. Briefly note trade-offs. If the user's suggested approach has significant downsides, say so.\n\n4. **Push Back on Bad Ideas**: If the request involves overengineering, premature abstraction, unnecessary complexity, or architectural anti-patterns, respectfully push back with a simpler alternative.\n\n5. **Define Scope**: State explicitly what you WILL and WILL NOT change. Any file not directly related to the request is out of scope.\n\n6. **Check for Spec**: If this is a non-trivial feature and no spec exists, suggest creating one first (spec-first principle).\n\n7. **Plan TDD Approach**: Identify what tests should be written first. Implementation follows tests, not the reverse.\n\nOnly after completing this checkpoint should you proceed with implementation. If GUARDRAILS_DISABLED=true is set, skip this checkpoint."
+            "prompt": "If this message is a trivial acknowledgment (e.g. 'yes', 'no', 'thanks', 'ok', 'continue'), skip and respond normally. Otherwise, apply the SDD pre-implementation checkpoint from the guardrails skill (enumerate assumptions, flag ambiguity, surface alternatives, push back on bad ideas, define scope, check for spec, plan TDD approach) before proceeding. If GUARDRAILS_DISABLED=true, skip."
           }
         ]
       }
@@ -41,7 +41,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Before finalizing, perform the SDD completion review:\n\n1. **Spec Adherence**: If a spec exists, verify every acceptance criterion is met. List any gaps.\n\n2. **Test Coverage**: Were tests written before implementation (TDD)? Do they trace back to spec criteria? Any untested acceptance criteria?\n\n3. **Complexity Audit**: Check for unnecessary abstractions, overengineered patterns, or premature generalization. Every function should be under 50 lines. Every file should be under 500 lines.\n\n4. **Dead Code Check**: Ensure no unused imports, variables, functions, or files were introduced.\n\n5. **Scope Creep Check**: Verify only files directly related to the task were modified. Flag any unrelated changes.\n\n6. **Conceptual Error Scan**: Re-read the core logic. Does it actually solve the problem correctly? Are there off-by-one errors, race conditions, or logical gaps?\n\nReport findings concisely. If GUARDRAILS_DISABLED=true is set, skip this review."
+            "prompt": "Before finalizing, perform the SDD completion review from the guardrails skill (spec adherence, test coverage, complexity audit, dead code check, scope creep check, conceptual error scan). Report findings concisely. If GUARDRAILS_DISABLED=true, skip."
           }
         ]
       }

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

@@ -30,7 +30,7 @@ fi
 
 # Check if inside project directory
 case "$FILE_PATH" in
-  "$PROJECT_DIR"*) ;; # Inside project, OK
+  "$PROJECT_DIR/"*|"$PROJECT_DIR") ;; # Inside project, OK
   /*)
     echo "SDD SCOPE WARNING: Edit to file outside project directory: $FILE_PATH" >&2
     exit 2

package/hooks/scripts/session-init.sh

@@ -11,7 +11,7 @@ YOLO_FLAG="$PROJECT_DIR/.sdd-yolo"
 
 # Check for yolo mode
 if [ -f "$YOLO_FLAG" ]; then
-  echo "SDD: YOLO mode active — all guardrails disabled" >&2
+  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 [ -n "$ENV_FILE" ]; then
@@ -29,7 +29,7 @@ fi
 
 # Check for config file
 if [ -f "$CONFIG_FILE" ]; then
-  echo "SDD: Config loaded from $CONFIG_FILE" >&2
+  echo "SDD: Config file found at $CONFIG_FILE" >&2
   if [ -n "$ENV_FILE" ]; then
     echo "SDD_CONFIG_FOUND=true" >> "$ENV_FILE"
   fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abdullah-alnahas/claude-sdd",
-  "version": "0.3.0",
+  "version": "0.5.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/skills/guardrails/SKILL.md

@@ -41,14 +41,25 @@ Before writing ANY implementation code, you MUST:
 
 ## During Implementation
 
-- Follow TDD: write a failing test first, then the minimum code to pass it, then refactor
-- Use iterative execution: implement → verify against spec → fix gaps → repeat
+- Follow TDD: write a failing test first, then the minimum code to pass it, then refactor (see the tdd-discipline skill for detailed workflow)
+- Use iterative execution: implement → verify against spec → fix gaps → repeat (see the iterative-execution skill for the full cycle)
 - Do not refactor surrounding code unless asked
 - Do not add error handling for impossible scenarios
 - Do not add comments explaining obvious code
 - Do not create abstractions for single-use patterns
 - Track every file you modify — justify each one
 
+## 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.
+
 ## Completion Review
 
 Before claiming work is done:

package/skills/iterative-execution/SKILL.md

@@ -47,11 +47,18 @@ Good completion criteria are:
 
 Use whatever is available, in order of preference:
 1. **Automated tests** (test runners, linters, type checkers)
-2. **Plugin agents** (critic, spec-compliance, security-reviewer)
-3. **Plugin skills** (guardrails, architecture-aware)
-4. **External MCP servers** (if user has configured any)
-5. **External plugin agents/skills** (if other plugins are installed)
-6. **Manual inspection** (read the code, trace the logic)
+2. **Available review agents** (e.g., critic, spec-compliance, security-reviewer)
+3. **Available analysis skills** (e.g., guardrails, architecture-aware)
+4. **External tools** (MCP servers, other plugins the user has configured)
+5. **Manual inspection** (read the code, trace the logic)
+
+## 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.
 
 ## Honesty Rules
 

package/skills/performance-optimization/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: Performance Optimization
+description: >
+  This skill enforces disciplined performance optimization practices defending against convenience bias,
+  localization failure, and correctness regressions. It should be used when the user asks to optimize,
+  speed up, improve performance, reduce runtime, or make code faster — any task where the goal is better
+  performance without breaking correctness.
+---
+
+# 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
+
+## 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/tdd-discipline/SKILL.md

@@ -47,7 +47,7 @@ Test: test_submit_form_saves_data()
 Code: FormHandler.submit()
 ```
 
-This chain ensures nothing is built without a reason and nothing specified goes untested.
+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