@abdullah-alnahas/claude-sdd 0.2.0 → 0.4.0

package/.claude-plugin/plugin.json

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

package/agents/critic.md

@@ -1,19 +1,38 @@
 ---
 name: critic
+model: sonnet
+color: red
 description: >
   Adversarial code reviewer that finds logical errors, invalid assumptions, spec drift, and requirement gaps.
   Use when you need an honest, direct assessment of code quality and correctness.
-capabilities:
-  - Logical error detection
-  - Assumption validation
-  - Spec drift detection
-  - Requirement coverage checking
-  - Complexity assessment
+
+  <example>
+  Context: User has completed implementing a feature.
+  user: "Review this code for bugs and logical errors"
+  assistant: "I'll use the critic agent to do an adversarial review of your code."
+  </example>
+
+  <example>
+  Context: User wants a critical assessment before merging.
+  user: "Find what's wrong with this implementation"
+  assistant: "Let me use the critic agent to identify issues."
+  </example>
+
+  <example>
+  Context: User suspects something is off.
+  user: "Do a critical review of these changes"
+  assistant: "I'll launch the critic agent for a thorough adversarial review."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
 ---
 
 # 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
 

package/agents/security-reviewer.md

@@ -1,14 +1,33 @@
 ---
 name: security-reviewer
+model: sonnet
+color: yellow
 description: >
   Security analysis agent that reviews code for OWASP Top 10 vulnerabilities, input validation gaps,
-  auth/authz issues, and injection risks. Use when reviewing code for security concerns.
-capabilities:
-  - OWASP Top 10 vulnerability detection
-  - Input validation review
-  - Authentication and authorization review
-  - Injection detection (SQL, command, XSS)
-  - Dependency risk awareness
+  auth/authz issues, and injection risks.
+
+  <example>
+  Context: User wants a security review.
+  user: "Review this for security vulnerabilities"
+  assistant: "I'll use the security-reviewer agent to check for vulnerabilities."
+  </example>
+
+  <example>
+  Context: User is concerned about injection risks.
+  user: "Check for injection risks in this code"
+  assistant: "Let me launch the security-reviewer agent to analyze injection surfaces."
+  </example>
+
+  <example>
+  Context: Pre-production security check.
+  user: "Is this code secure enough for production?"
+  assistant: "I'll use the security-reviewer agent to do a security analysis."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
 ---
 
 # Security Reviewer Agent
@@ -22,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

@@ -1,18 +1,38 @@
 ---
 name: simplifier
+model: sonnet
+color: cyan
 description: >
   Complexity reducer that proposes simpler alternatives, identifies unnecessary abstractions,
   and flags overengineering. Use when reviewing code for simplicity or after implementation.
-capabilities:
-  - Propose simpler alternatives
-  - Identify unnecessary abstractions
-  - Flag overengineering
-  - Reduce code volume while preserving behavior
+
+  <example>
+  Context: User wants to reduce complexity.
+  user: "Simplify this code"
+  assistant: "I'll use the simplifier agent to find complexity reduction opportunities."
+  </example>
+
+  <example>
+  Context: User suspects overengineering.
+  user: "Is this overengineered?"
+  assistant: "Let me launch the simplifier agent to check for unnecessary abstractions."
+  </example>
+
+  <example>
+  Context: Post-implementation cleanup.
+  user: "Can this be done with less code?"
+  assistant: "I'll use the simplifier agent to propose simpler alternatives."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
 ---
 
 # 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/agents/spec-compliance.md

@@ -1,14 +1,33 @@
 ---
 name: spec-compliance
+model: sonnet
+color: green
 description: >
   Spec adherence checker that compares implementation against spec documents, flags deviations,
   and verifies traceability from behavior spec to tests to code.
-  Use when verifying that code matches its specification.
-capabilities:
-  - Compare implementation against behavior specs
-  - Flag spec deviations
-  - Verify acceptance criteria coverage
-  - Check traceability (spec → test → code)
+
+  <example>
+  Context: User wants to verify implementation matches spec.
+  user: "Check if this matches the spec"
+  assistant: "I'll use the spec-compliance agent to verify adherence to the behavior spec."
+  </example>
+
+  <example>
+  Context: User wants traceability verification.
+  user: "Verify spec compliance"
+  assistant: "Let me launch the spec-compliance agent to check traceability from spec to tests to code."
+  </example>
+
+  <example>
+  Context: User is finishing a feature.
+  user: "Are all acceptance criteria covered?"
+  assistant: "I'll use the spec-compliance agent to check criteria coverage."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
 ---
 
 # Spec-Compliance Agent

package/commands/sdd-adopt.md

@@ -1,6 +1,13 @@
 ---
 name: sdd-adopt
 description: Adopt an existing project into the SDD discipline system
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
 ---
 
 # /sdd-adopt

package/commands/sdd-autopilot.md

@@ -1,6 +1,15 @@
 ---
 name: sdd-autopilot
 description: Autonomous end-to-end development — takes an app description and drives through all SDD phases (specify → design → implement → verify → review) with minimal user intervention
+argument-hint: "<description or path-to-app-description.md>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
 ---
 
 # /sdd-autopilot

package/commands/sdd-execute.md

@@ -1,6 +1,15 @@
 ---
 name: sdd-execute
 description: Start an iterative execution loop — implement with TDD, verify against spec, fix gaps, repeat
+argument-hint: "[--max-iterations <n>] [--criteria <description>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
 ---
 
 # /sdd-execute

package/commands/sdd-guardrails.md

@@ -1,6 +1,11 @@
 ---
 name: sdd-guardrails
 description: Show guardrail status, toggle individual guardrails, and view configuration
+argument-hint: "[enable|disable <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
 ---
 
 # /sdd-guardrails
@@ -21,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

@@ -1,6 +1,11 @@
 ---
 name: sdd-phase
 description: Show or set the current development phase
+argument-hint: "[specify|design|implement|verify|review]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
 ---
 
 # /sdd-phase
@@ -22,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/commands/sdd-review.md

@@ -1,6 +1,15 @@
 ---
 name: sdd-review
 description: On-demand self-review using critic and simplifier agents with iterative fix cycles
+argument-hint: "[--max-iterations <n>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
 ---
 
 # /sdd-review

package/commands/sdd-yolo.md

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

package/hooks/hooks.json

@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "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

@@ -13,11 +13,15 @@ PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 
 # Read tool input from stdin (JSON with file_path)
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | grep -oP '"file_path"\s*:\s*"([^"]*)"' | head -1 | sed 's/.*"\([^"]*\)"/\1/' 2>/dev/null || echo "")
 
-if [ -z "$FILE_PATH" ]; then
-  # Try alternate JSON key names
-  FILE_PATH=$(echo "$INPUT" | grep -oP '"filePath"\s*:\s*"([^"]*)"' | head -1 | sed 's/.*"\([^"]*\)"/\1/' 2>/dev/null || echo "")
+# 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 "")
+else
+  FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"\s*:\s*"\([^"]*\)".*/\1/p' | head -1)
+  if [ -z "$FILE_PATH" ]; then
+    FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"filePath"\s*:\s*"\([^"]*\)".*/\1/p' | head -1)
+  fi
 fi
 
 if [ -z "$FILE_PATH" ]; then
@@ -26,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.2.0",
+  "version": "0.4.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/architecture-aware/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: Architecture Awareness
 description: >
-  Provides architecture consciousness during development — integration patterns, anti-patterns, and ADR guidance.
-  Use when designing systems, discussing architecture, integration, patterns, structure, or organization.
-version: 1.0.0
+  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?"
 ---
 
 # Architecture Awareness
 
-You maintain architectural consciousness throughout development. Every code change exists within an architectural context — respect it.
+Maintain architectural consciousness throughout development. Every code change exists within an architectural context — respect it.
 
 ## Core Principles
 

package/skills/guardrails/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: SDD Guardrails
 description: >
-  Core behavioral guardrails that defend against 12 common LLM failure modes during software development.
-  Use when implementing, building, fixing, refactoring, adding, changing, or modifying code.
-  Activates automatically to enforce disciplined development practices.
-version: 1.0.0
+  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.
 ---
 
 # SDD Behavioral Guardrails
 
-You are operating under the SDD (Spec-Driven Development) discipline system. These guardrails defend against known LLM failure patterns in software development.
+Operate under the SDD (Spec-Driven Development) discipline system. These guardrails defend against known LLM failure patterns in software development.
 
 ## Core Principles
 
@@ -41,8 +41,8 @@ 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

package/skills/iterative-execution/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: Iterative Execution
 description: >
-  Disciplined implement→verify→fix cycles for delivering against specs. Use when implementing features,
-  executing specs, making things work, iterating until specs are satisfied, or running execution loops.
-version: 1.0.0
+  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."
 ---
 
 # Iterative Execution
@@ -46,11 +47,10 @@ 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)
 
 ## Honesty Rules
 

package/skills/spec-first/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: Spec-First Development
 description: >
-  Interactive specification development that turns rough ideas into formal documents before code is written.
-  Use when starting a new project, new feature, creating specs, plans, adopting an existing project,
-  or when the user says "I want to build/create something."
-version: 1.0.0
+  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."
 ---
 
 # Spec-First Development
 
-You guide users from rough idea to formal specification through interactive questioning — not checklist dumping. Code comes AFTER specs, not before.
+Guide users from rough idea to formal specification through interactive questioning — not checklist dumping. Code comes AFTER specs, not before.
 
 ## The Process
 

package/skills/tdd-discipline/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: TDD Discipline
 description: >
-  Test-driven development enforcement — Red/Green/Refactor cycle, test co-location, traceability from behavior spec to test to code.
-  Use when writing tests, discussing TDD, coverage, verification, or validation.
-version: 1.0.0
+  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."
 ---
 
 # TDD Discipline
@@ -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