@abdullah-alnahas/claude-sdd 0.1.0 → 0.3.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.3.0",
+  "description": "Spec-Driven Development discipline system — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops"
 }

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abdullah-alnahas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,11 +5,15 @@ A Claude Code plugin that enforces disciplined software development: behavioral
 ## Installation
 
 ```bash
-# Local development
-claude --plugin-dir /path/to/sdd
+# From npm (recommended)
+claude plugins add @abdullah-alnahas/claude-sdd
 
-# Or symlink into Claude plugins directory
-ln -s /path/to/sdd ~/.claude/plugins/sdd
+# From GitHub
+git clone https://github.com/abdullah-alnahas/claude-sdd.git
+claude plugins add ./claude-sdd
+
+# For local development
+claude plugins add /path/to/sdd
 ```
 
 ## What It Does

package/agents/critic.md

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

package/agents/security-reviewer.md

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

package/agents/simplifier.md

@@ -1,12 +1,33 @@
 ---
+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

package/agents/spec-compliance.md

@@ -1,13 +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
@@ -47,6 +67,13 @@ You methodically compare what was specified against what was built. Every accept
 [X of Y criteria satisfied. Z deviations found.]
 ```
 
+## No Spec Available
+
+If no behavior spec exists for the code under review:
+1. Report clearly: "No behavior spec found for this code."
+2. Suggest creating one: "Run `/sdd-phase specify` or use the spec-first skill to create a behavior spec before verifying compliance."
+3. Do NOT attempt to invent criteria — without a spec, compliance checking is not meaningful.
+
 ## Principles
 
 - The spec is the source of truth, not the implementation

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

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

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 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."
           }
         ]
       }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abdullah-alnahas/claude-sdd",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -14,7 +14,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/abdullah-alnahas/claude-sdd.git"
+    "url": "git+https://github.com/abdullah-alnahas/claude-sdd.git"
   },
   "author": "abdullah-alnahas"
 }

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
 

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

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