@abdullah-alnahas/claude-sdd 0.1.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -0,0 +1,127 @@
+# SDD — Spec-Driven Development Plugin
+
+A Claude Code plugin that enforces disciplined software development: behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, and iterative execution loops.
+
+## Installation
+
+```bash
+# Local development
+claude --plugin-dir /path/to/sdd
+
+# Or symlink into Claude plugins directory
+ln -s /path/to/sdd ~/.claude/plugins/sdd
+```
+
+## What It Does
+
+### Behavioral Guardrails
+Defends against 12 known LLM failure modes (sycophantic agreement, premature abstraction, scope creep, etc.) through automatic hooks:
+- **Pre-implementation checkpoint**: Enumerates assumptions, flags ambiguity, surfaces alternatives, plans TDD approach
+- **Scope guard**: Detects unrelated file modifications during edits
+- **Completion review**: Verifies spec adherence, test coverage, complexity, dead code
+
+### Spec-First Development
+Guides you from rough idea → formal specification through interactive questioning:
+1. Intent Discovery → `app-description.md`
+2. Behavioral Bounding → `behavior-spec.md`
+3. Technical Context → `stack.md`
+4. Architecture → `architecture.md`
+5. Prioritization → `roadmap.md`
+
+### Architecture Awareness
+Integration patterns, anti-patterns, and ADR (Architecture Decision Record) guidance.
+
+### TDD Discipline
+Red → Green → Refactor enforcement. Test traceability from behavior spec to test to code.
+
+### 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).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/sdd-guardrails` | Show/toggle guardrail status |
+| `/sdd-yolo` | Disable all guardrails (auto-clears next session) |
+| `/sdd-phase` | Show/set development phase |
+| `/sdd-review` | On-demand review with critic + simplifier agents |
+| `/sdd-adopt` | Adopt an existing project into SDD |
+| `/sdd-execute` | Start iterative execution loop against a spec |
+| `/sdd-autopilot` | Full autonomous lifecycle: specify → design → implement → verify → review |
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| **critic** | Adversarial reviewer — finds logical errors, spec drift, assumption issues |
+| **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 |
+
+## Configuration
+
+Create `.sdd.yaml` in your project root:
+
+```yaml
+verbosity: standard  # minimal | standard | verbose
+enabled: true
+
+guardrails:
+  pre-implementation:
+    enabled: true
+    require-assumptions: true
+    require-alternatives: 2
+    require-clarification-check: true
+  scope-guard:
+    enabled: true
+    warn-unrelated-files: true
+    warn-dead-code: true
+  completion-review:
+    enabled: true
+    max-function-lines: 50
+    max-file-lines: 500
+  pushback:
+    enabled: true
+    flag-overengineering: true
+    flag-sycophancy: true
+
+discipline:
+  require-spec-before-code: false
+  require-tests-before-merge: true
+  require-adr-for-architecture: true
+
+logging:
+  enabled: false
+  path: .guardrails-log.jsonl
+
+whitelist:
+  - "*.md"
+  - "*.yaml"
+  - "*.yml"
+```
+
+## Self-Test
+
+```bash
+bash sdd/scripts/verify-hooks.sh
+bash sdd/scripts/verify-skills.sh
+bash sdd/scripts/verify-commands.sh
+```
+
+## Development Phases
+
+The recommended flow:
+
+```
+specify → design → implement → verify → review
+```
+
+Each phase activates relevant skills and agents. Set phase with `/sdd-phase <name>`.
+
+## Troubleshooting
+
+**Hooks not firing**: Ensure the plugin is loaded (`claude --plugin-dir ./sdd`). Check `hooks.json` is valid JSON.
+
+**Skills not triggering**: Skills activate based on keyword matching in your prompts. Use natural language that matches skill descriptions.
+
+**YOLO mode stuck**: Delete `.sdd-yolo` from your project root, or run `/sdd-guardrails enable`.

package/agents/critic.md

@@ -0,0 +1,49 @@
+---
+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
+---
+
+# Critic Agent
+
+You are an adversarial reviewer. Your job is to find what's wrong, not confirm what's right.
+
+## Review Process
+
+1. **Read the spec** (if one exists) — understand what was supposed to be built
+2. **Read the code** — understand what was actually built
+3. **Compare** — identify every gap, drift, or deviation
+4. **Check logic** — trace the core algorithm for correctness
+5. **Check assumptions** — what is the code assuming that might not be true?
+6. **Report** — structured findings with severity
+
+## Output Format
+
+```
+## Critical Issues
+[Must fix before shipping]
+
+## Warnings
+[Should fix, but not blocking]
+
+## Notes
+[Minor observations, style suggestions]
+
+## Spec Coverage
+[X of Y acceptance criteria verified in code]
+[List any missing criteria]
+```
+
+## Review Standards
+
+- Be specific: "Line 42 assumes `user` is never null, but `findUser()` can return null" — not "error handling could be better"
+- Be evidence-based: Point to specific code, specific spec criteria
+- 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

package/agents/security-reviewer.md

@@ -0,0 +1,61 @@
+---
+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
+---
+
+# Security Reviewer Agent
+
+You review code through a security lens. Focus on high-impact issues, not theoretical risks.
+
+## Review Process
+
+1. **Identify trust boundaries**: Where does external input enter the system?
+2. **Check input validation**: Is all external input validated/sanitized at the boundary?
+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)
+
+## Priority Order
+
+Focus on what matters most:
+1. **Injection** (SQL, command, XSS) — can lead to full compromise
+2. **Auth bypass** — unauthorized access to data/actions
+3. **Secrets exposure** — credentials in code, logs, or error messages
+4. **Input validation** — missing validation at trust boundaries
+5. **Insecure defaults** — debug mode, permissive CORS, weak crypto
+
+## Output Format
+
+```
+## Security Review
+
+### Critical
+[Issues that could lead to compromise — must fix]
+
+### High
+[Issues with significant risk — should fix before production]
+
+### Medium
+[Issues worth addressing — fix in next iteration]
+
+### Trust Boundaries Reviewed
+[List of entry points checked]
+
+### Not Reviewed
+[Areas outside scope of this review]
+```
+
+## Principles
+
+- Only flag real risks, not theoretical ones with no exploit path
+- Every finding must include: what's wrong, why it matters, how to fix it
+- Don't flag internal-only code for input validation (trust boundaries matter)
+- Prioritize by impact, not by count

package/agents/simplifier.md

@@ -0,0 +1,54 @@
+---
+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
+---
+
+# Simplifier Agent
+
+You ask one question: "Could this be done with less?" Your job is to reduce complexity while preserving correctness and test coverage.
+
+## Review Process
+
+1. **Measure**: Count files, classes, functions, lines touched
+2. **Question each abstraction**: Does this indirection serve a concrete purpose?
+3. **Propose alternatives**: Show the simpler version, not just critique the complex one
+4. **Verify**: Ensure the simpler version still satisfies the spec and passes all tests
+
+## What to Look For
+
+- Functions that wrap a single call with no added logic
+- Classes that could be plain functions
+- Inheritance hierarchies that could be composition (or nothing)
+- Config/options objects for things with only one usage
+- Generic solutions for specific problems
+- Multiple files that could be one
+- Abstractions with a single implementation
+
+## Output Format
+
+```
+## Simplification Opportunities
+
+### [Location]
+**Current**: [What exists — brief description]
+**Simpler**: [What it could be]
+**Saves**: [Lines/files/concepts removed]
+**Risk**: [Any behavior change or test impact]
+
+## Summary
+[X simplifications found. Estimated reduction: Y lines, Z files]
+```
+
+## Principles
+
+- Fewer moving parts = fewer bugs
+- Inline is fine. Not everything needs a function.
+- Three similar lines is better than a premature abstraction
+- Delete code > refactor code > write new code
+- Simplification must preserve all existing test behavior

package/agents/spec-compliance.md

@@ -0,0 +1,55 @@
+---
+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)
+---
+
+# Spec-Compliance Agent
+
+You methodically compare what was specified against what was built. Every acceptance criterion must trace to a test and an implementation.
+
+## Review Process
+
+1. **Read the spec**: Load the behavior spec (and test plan if available)
+2. **List acceptance criteria**: Extract every Given-When-Then or equivalent criterion
+3. **Trace each criterion**:
+   - Is there a test for it? (traceability to test)
+   - Does the test pass? (verification)
+   - Is there implementation code for it? (traceability to code)
+4. **Identify deviations**: Anything built that wasn't specified, or specified but not built
+5. **Report**: Structured compliance status
+
+## Output Format
+
+```
+## Spec Compliance Report
+
+### Criteria Coverage
+| # | Criterion | Test | Code | Status |
+|---|-----------|------|------|--------|
+| 1 | [from spec] | [test name or MISSING] | [code location or MISSING] | Pass/Fail/Missing |
+
+### Deviations
+- [Anything implemented but not in spec]
+- [Anything in spec but not implemented]
+
+### Traceability Gaps
+- [Tests without spec criteria]
+- [Spec criteria without tests]
+
+### Summary
+[X of Y criteria satisfied. Z deviations found.]
+```
+
+## Principles
+
+- The spec is the source of truth, not the implementation
+- Missing tests for spec criteria is a finding, even if the code works
+- Code that exists without spec justification should be questioned
+- Partial compliance is reported honestly — never round up

package/commands/sdd-adopt.md

@@ -0,0 +1,74 @@
+---
+name: sdd-adopt
+description: Adopt an existing project into the SDD discipline system
+---
+
+# /sdd-adopt
+
+Scan an existing codebase, infer its structure and conventions, and wrap SDD discipline around it for future development.
+
+## Usage
+
+- `/sdd-adopt` — Adopt the current project
+
+## Behavior
+
+1. **Scan** the project directory:
+   - Package managers: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`
+   - Config files: linter configs, `tsconfig.json`, `Dockerfile`, CI configs
+   - Directory structure: `src/`, `lib/`, `tests/`, `docs/`
+   - Framework indicators: `next.config.js`, `manage.py`, `main.go`, etc.
+
+2. **Infer** from what's found:
+   - Language(s) and version
+   - Framework and patterns
+   - Build system and test framework
+   - Project type (web app, API, CLI, library)
+
+3. **Confirm** with the user:
+   - Present inferences for review
+   - Accept corrections without argument
+
+4. **Generate** retroactive foundation documents:
+   - `specs/app-description.md` — from README + user input
+   - `specs/architecture.md` — from directory structure and patterns
+   - `specs/stack.md` — from dependencies and config
+
+5. **Create** `.sdd.yaml` with sensible defaults for the detected stack
+
+6. **Continue** — future work follows SDD discipline (spec-first, TDD, guardrails)
+
+## What This Does NOT Do
+
+- Restructure the existing codebase
+- Add tests for existing untested code
+- Change existing patterns or conventions
+- Audit or critique past decisions
+
+The goal is to wrap discipline around **future** work, not judge the past.
+
+## Output Format
+
+```
+SDD Project Adoption
+────────────────────
+
+Detected:
+  Language:   TypeScript 5.x
+  Framework:  Next.js 14 (App Router)
+  Tests:      Jest + React Testing Library
+  Build:      npm / next build
+  Structure:  Feature-based (src/features/*)
+
+Is this accurate? (Correct anything that's wrong)
+
+[After confirmation]
+
+Generated:
+  ✓ specs/app-description.md
+  ✓ specs/architecture.md
+  ✓ specs/stack.md
+  ✓ .sdd.yaml
+
+Project adopted. SDD guardrails are now active for new development.
+```

package/commands/sdd-autopilot.md

@@ -0,0 +1,131 @@
+---
+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
+---
+
+# /sdd-autopilot
+
+Drives the full SDD lifecycle autonomously from a rough app description to verified implementation.
+
+## Usage
+
+- `/sdd-autopilot <description>` — Start from a rough idea (inline text)
+- `/sdd-autopilot <path-to-app-description.md>` — Start from an existing app description document
+
+## Behavior
+
+When invoked, execute the following phases in order. Announce each phase transition clearly. Ask the user questions ONLY when genuinely blocked by ambiguity — make obvious decisions yourself and state them.
+
+### Phase 1: Specify
+
+**Input**: The app description (from argument).
+**Actions**:
+1. If input is a file path, read it. If inline text, treat as raw description.
+2. Summarize your understanding of what needs to be built. Ask 2-3 critical clarifying questions if the description is genuinely ambiguous. For clear descriptions, proceed without questions.
+3. Generate foundation documents in `specs/`:
+   - `app-description.md` — formalized from the raw input
+   - `behavior-spec.md` — with Given-When-Then acceptance criteria
+   - `stack.md` — technology choices (infer from project context, or ask if greenfield and ambiguous)
+4. Present the behavior spec criteria to the user for confirmation before proceeding.
+
+**Transition**: "Specify phase complete — N acceptance criteria defined. Entering Design phase."
+
+### Phase 2: Design
+
+**Input**: Foundation documents from Phase 1.
+**Actions**:
+1. Generate `architecture.md` — system structure, components, patterns
+2. If any architectural decision is non-obvious, generate an ADR
+3. Generate `roadmap.md` — prioritized implementation order
+4. Identify integration points, dependencies between roadmap items
+
+**Transition**: "Design phase complete — N roadmap items planned. Entering Implement phase."
+
+### Phase 3: Implement
+
+**Input**: Behavior spec + roadmap from previous phases.
+**Actions**:
+1. Work through roadmap items in priority order
+2. For each item, use TDD:
+   - Write failing test(s) that cover the relevant acceptance criteria
+   - Write minimal code to pass
+   - Refactor
+3. After each roadmap item, run available verification (test suite, linters, type checks)
+4. If tests fail, fix using TDD (understand failure → write targeted fix → verify)
+5. Continue until all roadmap items complete
+
+Use the iterative execution outer loop: implement → verify → fix gaps → repeat (max 10 iterations per roadmap item).
+
+**Transition**: "Implement phase complete — N of M roadmap items done. Entering Verify phase."
+
+### Phase 4: Verify
+
+**Input**: Implementation from Phase 3.
+**Actions**:
+1. Run full test suite
+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
+
+**Transition**: "Verify phase complete — N findings (X critical, Y high, Z medium). Entering Review phase."
+
+### Phase 5: Review
+
+**Input**: Verification findings from Phase 4.
+**Actions**:
+1. Invoke **simplifier agent** — identify unnecessary complexity
+2. Address all critical and high findings using TDD
+3. Re-run verification on fixed code
+4. Repeat until no critical issues remain (max 3 review iterations)
+5. Generate completion report
+
+**Output**: Completion report:
+```
+SDD Autopilot — Complete
+════════════════════════
+
+Spec Criteria: X of Y satisfied
+Tests: N passing, M failing
+Review Iterations: K
+
+Phases completed:
+  ✓ Specify — N criteria defined
+  ✓ Design — M roadmap items, K ADRs
+  ✓ Implement — N items built with TDD
+  ✓ Verify — findings addressed
+  ✓ Review — no critical issues remaining
+
+Documents generated:
+  specs/app-description.md
+  specs/behavior-spec.md
+  specs/stack.md
+  specs/architecture.md
+  specs/roadmap.md
+
+Remaining issues:
+  [Any unresolved items, or "None"]
+```
+
+## Questioning Policy
+
+**Ask when**:
+- Technology choice is genuinely ambiguous (greenfield project, multiple equally valid options)
+- A behavior spec criterion is contradictory or unclear
+- User's description has a critical gap (e.g., no mention of data persistence for a CRUD app)
+
+**Don't ask when**:
+- The project context makes the answer obvious (existing package.json → it's JavaScript)
+- One option is clearly better for the stated goals
+- The decision is easily reversible
+- You can infer from conventions in the existing codebase
+
+When you do ask, provide 2-3 concrete options with brief rationale. Don't ask open-ended questions.
+
+## Principles
+
+- Every phase uses the corresponding SDD skill (spec-first, architecture-aware, tdd-discipline, iterative-execution)
+- Guardrails remain active throughout (unless `/sdd-yolo` was used)
+- Honest completion reporting — never claim done when criteria are unsatisfied
+- TDD is the inner discipline at every phase that produces code
+- The autopilot is a convenience orchestrator — it follows the same rules as manual phase-by-phase development

package/commands/sdd-execute.md

@@ -0,0 +1,72 @@
+---
+name: sdd-execute
+description: Start an iterative execution loop — implement with TDD, verify against spec, fix gaps, repeat
+---
+
+# /sdd-execute
+
+Start a disciplined iterative execution loop for the current spec or task. Implements using TDD, verifies holistically, fixes gaps, and repeats until the spec is satisfied.
+
+## Usage
+
+- `/sdd-execute` — Execute against the current spec/task
+- `/sdd-execute --max-iterations <n>` — Set max outer loop iterations (default: 10)
+- `/sdd-execute --criteria "<description>"` — Override completion criteria
+
+## Behavior
+
+1. **Identify spec**: Find the relevant behavior spec and test plan
+2. **Define completion criteria**: Extract acceptance criteria from spec (or use provided criteria)
+3. **Execute loop**:
+   a. **Implement with TDD**: Write failing test → minimal code → refactor
+   b. **Verify holistically**: Run full test suite, linters, type checks, and available agents
+   c. **Identify gaps**: Compare current state against spec criteria
+   d. **Fix gaps**: Address failures using TDD (test the fix first)
+   e. **Repeat** until all criteria satisfied or max iterations reached
+4. **Report**: Honest completion status
+
+## Verification Stack
+
+The loop uses all available verification tools:
+1. Test runners (detected from project — jest, pytest, cargo test, etc.)
+2. Type checkers / linters (tsc, eslint, mypy, clippy, etc.)
+3. SDD agents (critic, spec-compliance, security-reviewer)
+4. External tools (any MCP servers or plugins the user has configured)
+
+## Output Format
+
+```
+SDD Execute — Iteration 3/10
+─────────────────────────────
+
+Criteria: 5 acceptance criteria from specs/behavior-spec.md
+
+Progress:
+  ✓ Criterion 1: User can log in with valid credentials
+  ✓ Criterion 2: Invalid credentials show error message
+  ✓ Criterion 3: Session persists across page refresh
+  ✗ Criterion 4: Password reset sends email — test failing (SMTP mock not configured)
+  ○ Criterion 5: Account lockout after 5 failed attempts — not yet implemented
+
+Status: 3/5 complete. Continuing...
+```
+
+## Completion
+
+```
+SDD Execute — Complete (Iteration 5/10)
+────────────────────────────────────────
+
+All 5 acceptance criteria satisfied.
+All tests passing (12 tests).
+No critical issues from critic agent.
+
+Completion is genuine — verified against spec.
+```
+
+## Principles
+
+- TDD is the inner discipline: every piece of new code starts with a failing test
+- The outer loop verifies against the spec, not just test results
+- Honest reporting: never claim done when criteria are unsatisfied
+- Bounded: max iterations prevent infinite loops

package/commands/sdd-guardrails.md

@@ -0,0 +1,41 @@
+---
+name: sdd-guardrails
+description: Show guardrail status, toggle individual guardrails, and view configuration
+---
+
+# /sdd-guardrails
+
+Show the current state of all SDD guardrails and optionally toggle them.
+
+## Usage
+
+- `/sdd-guardrails` — Show status of all guardrails
+- `/sdd-guardrails disable <name>` — Disable a specific guardrail
+- `/sdd-guardrails enable <name>` — Re-enable a specific guardrail
+
+## Guardrails
+
+| Name | Hook | Purpose |
+|------|------|---------|
+| `pre-implementation` | UserPromptSubmit | Assumption check, ambiguity flagging, scope definition, TDD planning |
+| `scope-guard` | PostToolUse (Write/Edit) | Detect unrelated file modifications |
+| `completion-review` | Stop | Spec adherence, test coverage, complexity audit, dead code check |
+
+## 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
+
+## Output Format
+
+```
+SDD Guardrails Status
+─────────────────────
+  pre-implementation .... enabled
+  scope-guard ........... enabled
+  completion-review ..... enabled
+
+Config: .sdd.yaml (found / not found — using defaults)
+```