@abdullah-alnahas/claude-sdd 0.6.0 → 0.8.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -51,7 +51,10 @@ Profile-first discipline for performance work. Defends against convenience bias
 | `/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-mode` | Switch context mode (dev/review/research) |
+| `/sdd-review` | Two-stage review — spec compliance then code quality |
+| `/sdd-verify` | Automated checks — build, types, lint, tests, security scans |
+| `/sdd-orchestrate` | Agent pipelines — feature, bugfix, refactor, security, or custom |
 | `/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 |
@@ -65,6 +68,23 @@ Profile-first discipline for performance work. Defends against convenience bias
 | **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 |
+| **planner** | Implementation planner — reads specs/architecture and produces ordered steps |
+
+## Context Modes
+
+SDD supports three context modes that adjust which guardrails are active:
+
+| Mode | Focus | Pre-Implementation | Completion Review | Scope Guard |
+|------|-------|-------------------|-------------------|-------------|
+| **dev** (default) | Build correctly | Active | Active | Strict |
+| **review** | Verify and critique | Skipped | Active | Normal |
+| **research** | Explore freely | Skipped | Skipped | Relaxed |
+
+Set mode with `/sdd-mode <mode>` or set a default in `.sdd.yaml`:
+
+```yaml
+mode: dev  # dev | review | research
+```
 
 ## Configuration
 
@@ -73,6 +93,8 @@ Create `.sdd.yaml` in your project root:
 ```yaml
 verbosity: standard  # minimal | standard | verbose
 enabled: true
+mode: dev  # dev | review | research
+compaction_threshold: 50  # tool invocations before suggesting /compact
 
 guardrails:
   pre-implementation:

package/agents/planner.md

@@ -0,0 +1,78 @@
+---
+name: planner
+model: sonnet
+color: blue
+description: >
+  Reads specs, architecture docs, and codebase structure to produce ordered implementation steps.
+  Use when starting a feature, breaking down a task, or needing an implementation roadmap.
+
+  <example>
+  Context: User has a spec and wants to know what to implement first.
+  user: "Break down this feature into implementation steps"
+  assistant: "I'll use the planner agent to analyze the spec and produce an ordered implementation plan."
+  </example>
+
+  <example>
+  Context: User is starting a new feature from a behavior spec.
+  user: "Plan the implementation for this spec"
+  assistant: "Let me launch the planner agent to create an implementation roadmap."
+  </example>
+
+  <example>
+  Context: User needs to understand implementation order and dependencies.
+  user: "What should I build first?"
+  assistant: "I'll use the planner agent to analyze dependencies and suggest an implementation order."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Planner Agent
+
+You analyze specs, architecture, and codebase structure to produce ordered implementation steps. You plan — you do not implement.
+
+## Planning Process
+
+1. **Read the spec** — understand what needs to be built (behavior spec, acceptance criteria)
+2. **Read architecture docs** — understand the system structure (if available)
+3. **Scan the codebase** — identify existing patterns, conventions, relevant files
+4. **Identify dependencies** — what must exist before other things can be built
+5. **Produce ordered steps** — a sequence that respects dependencies and enables incremental testing
+
+## Output Format
+
+```
+## Implementation Plan
+
+### Prerequisites
+[What must be true before starting — dependencies, setup, existing code to understand]
+
+### Steps
+
+1. **Step title** — Brief description
+   - Files: `path/to/file.ts` (create | modify)
+   - Depends on: (none | step N)
+   - Test: How to verify this step works
+
+2. **Step title** — Brief description
+   - Files: `path/to/file.ts` (create | modify)
+   - Depends on: Step 1
+   - Test: How to verify this step works
+
+### Risks
+[Potential issues, ambiguities in the spec, architectural concerns]
+
+### Suggested Order
+[If steps can be parallelized, note which can run concurrently]
+```
+
+## Planning Standards
+
+- **Respect existing patterns** — don't suggest new conventions when the codebase has established ones
+- **Small steps** — each step should be independently testable
+- **Dependencies are explicit** — never assume step order is obvious
+- **Tests at every step** — every step includes how to verify it
+- **Be honest about unknowns** — flag ambiguities, don't paper over them

package/commands/sdd-autopilot.md

@@ -54,29 +54,41 @@ When invoked, execute the following phases in order. Announce each phase transit
 
 **Input**: Behavior spec + roadmap from previous phases.
 **Actions**:
-1. Work through roadmap items in priority order
+1. Work through roadmap items in priority order, in **batches of 3**
 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)
+3. After each batch of 3 items:
+   - Run available verification (test suite, linters, type checks)
+   - Report progress with verification evidence (actual test output)
+   - Pause for user feedback before continuing
 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."
+**Transition** (only when all items are complete): "Implement phase complete — all M roadmap items done. Entering Verify phase."
 
 ### Phase 4: Verify
 
 **Input**: Implementation from Phase 3.
 **Actions**:
+Use the two-stage review process (see `/sdd-review`):
+
+**Stage 1 — Spec Compliance:**
 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. If performance optimization was part of the spec, invoke **performance-reviewer agent**
-6. Collect all findings
+3. DO NOT trust the implementation report. Read actual code and test output independently.
+4. For each acceptance criterion: PASS / FAIL / PARTIAL with evidence
+5. Stage 1 must pass before proceeding to Stage 2
+
+**Stage 2 — Code Quality:**
+6. Invoke **critic agent** — find logical errors, assumption issues
+7. Invoke **simplifier agent** — find unnecessary complexity
+8. Invoke **security-reviewer agent** — check for vulnerabilities
+9. If performance optimization was part of the spec, invoke **performance-reviewer agent**
+10. Collect all findings
 
 **Transition**: "Verify phase complete — N findings (X critical, Y high, Z medium). Entering Review phase."
 

package/commands/sdd-execute.md

@@ -73,9 +73,27 @@ No critical issues from critic agent.
 Completion is genuine — verified against spec.
 ```
 
+## Batch Execution
+
+When working on multiple criteria or tasks, group them into batches of 3:
+
+1. Implement batch (3 criteria/tasks) using TDD
+2. Verify the batch — run tests, check spec compliance
+3. Report progress with verification evidence (test output, not claims)
+4. Pause for user feedback before continuing to the next batch
+
+This prevents long unverified runs and gives the user control over direction.
+
+## Verification
+
+After each batch, use the two-stage review process:
+- **Stage 1**: Spec compliance — verify each criterion with evidence (see `/sdd-review`)
+- **Stage 2**: Code quality — only after Stage 1 passes
+
 ## 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
+- Batch execution: groups of 3 with checkpoint reports

package/commands/sdd-mode.md

@@ -0,0 +1,42 @@
+---
+name: sdd-mode
+description: Switch SDD context mode (dev/review/research). Controls which guardrails are active.
+argument-hint: "[dev|review|research]"
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# /sdd-mode
+
+Switch the active SDD context mode. Each mode adjusts which guardrails, hooks, and checks are active.
+
+## Usage
+
+- `/sdd-mode` — Show current mode
+- `/sdd-mode dev` — Full guardrails (default)
+- `/sdd-mode review` — Review/verification focus
+- `/sdd-mode research` — Exploration focus, relaxed guardrails
+
+## Modes
+
+| Mode | Pre-Implementation Checkpoint | Completion Review | Scope Guard | Focus |
+|------|------------------------------|-------------------|-------------|-------|
+| **dev** | Active | Active | Strict | Build correctly — TDD, spec compliance, full discipline |
+| **review** | Skipped | Active | Normal | Verify and critique — find issues, check quality |
+| **research** | Skipped | Skipped | Relaxed | Explore and understand — read code, trace flows, prototype |
+
+## Behavior
+
+When invoked with an argument:
+1. Write `SDD_MODE=<mode>` to `$CLAUDE_ENV_FILE`
+2. Read the corresponding context file from `contexts/<mode>.md`
+3. Report the mode switch and what changed
+
+When invoked without an argument:
+1. Read `$SDD_MODE` (default: `dev`)
+2. Report current mode and its settings
+
+## Context Files
+
+Each mode has a context file at `contexts/<mode>.md` that is loaded by the session init hook. These define the behavioral adjustments for that mode. See `.sdd.yaml` to set a default mode per project.

package/commands/sdd-orchestrate.md

@@ -0,0 +1,103 @@
+---
+name: sdd-orchestrate
+description: Run named agent pipelines with structured handoffs — feature, bugfix, refactor, security, or custom.
+argument-hint: "<pipeline> [agent1,agent2,...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+---
+
+# /sdd-orchestrate
+
+Run a named pipeline of agents with structured handoffs. Each agent receives the previous agent's findings and builds on them.
+
+## Usage
+
+- `/sdd-orchestrate feature` — Full feature review pipeline
+- `/sdd-orchestrate bugfix` — Bug-focused pipeline
+- `/sdd-orchestrate refactor` — Refactoring review pipeline
+- `/sdd-orchestrate security` — Security-focused pipeline
+- `/sdd-orchestrate custom agent1,agent2,...` — User-specified agent sequence
+
+## Named Pipelines
+
+| Pipeline | Agent Sequence | Focus |
+|----------|---------------|-------|
+| **feature** | spec-compliance → planner → critic → security-reviewer | Complete feature validation |
+| **bugfix** | critic → spec-compliance → simplifier | Find root cause, check spec, simplify fix |
+| **refactor** | simplifier → critic → spec-compliance | Simplify, verify correctness, check spec |
+| **security** | security-reviewer → critic → simplifier | Security first, then correctness, then cleanup |
+
+### custom
+
+Specify agents as a comma-separated list:
+```
+/sdd-orchestrate custom critic,simplifier,performance-reviewer
+```
+
+Available agents: `critic`, `simplifier`, `spec-compliance`, `security-reviewer`, `performance-reviewer`, `planner`
+
+## Handoff Format
+
+Each agent produces a structured handoff:
+
+```
+## Agent: <name>
+
+### Findings
+[Structured findings from this agent]
+
+### Handoff
+[Key information the next agent needs]
+
+### Status: PASS | FAIL | NEEDS-ATTENTION
+```
+
+## Pipeline Behavior
+
+1. Run each agent in sequence
+2. Pass previous agent's findings as context to the next agent
+3. **On FAIL**: Pause the pipeline and ask the user:
+   - Fix issues and re-run from the failed agent
+   - Continue to the next agent anyway
+   - Abort the pipeline
+4. After all agents complete, produce a summary
+
+## Summary Output
+
+```
+SDD Orchestrate — feature pipeline
+────────────────────────────────────
+
+  ✓ spec-compliance ............... PASS
+  ✓ planner ....................... PASS (spec-compliance findings applied)
+  ✗ critic ........................ FAIL (2 critical issues)
+  ⊘ security-reviewer ............ SKIPPED (pipeline paused)
+
+Pipeline: PAUSED at critic — 2 critical issues found
+Action required: Fix issues before continuing
+```
+
+## Agent Prompt Template
+
+When launching each agent, include:
+
+```
+You are running as part of an SDD orchestration pipeline.
+Pipeline: <pipeline-name>
+Your position: Agent <N> of <total>
+Previous findings:
+<handoff from previous agent, or "First agent — no prior findings">
+
+Your task: <agent's standard task>
+Output your findings in the structured handoff format.
+```
+
+## References
+
+See agent definitions in `agents/` for each agent's review standards and output format.

package/commands/sdd-phase.md

@@ -63,5 +63,5 @@ 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
+- **verify**: critic, security-reviewer, performance-reviewer, spec-compliance
 - **review**: all agents

package/commands/sdd-review.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-review
-description: On-demand self-review using critic and simplifier agents with iterative fix cycles
+description: Two-stage review — spec compliance first, then code quality. Only proceeds to Stage 2 after Stage 1 passes.
 argument-hint: "[--max-iterations <n>]"
 allowed-tools:
   - Read
@@ -14,41 +14,70 @@ allowed-tools:
 
 # /sdd-review
 
-Trigger an on-demand review of recent work using the critic and simplifier agents. Runs iteratively — reviews, fixes, re-reviews until no critical issues remain.
+Trigger a two-stage review of recent work. Stage 1 verifies spec compliance. Stage 2 reviews code quality. Stage 2 only runs after Stage 1 passes.
 
 ## Usage
 
 - `/sdd-review` — Review recent changes
 - `/sdd-review --max-iterations <n>` — Set max review-fix cycles (default: 3)
 
-## Behavior
+## Stage 1: Spec Compliance
+
+**Goal**: Verify the implementation satisfies the behavior spec.
 
 1. Identify what was recently changed (git diff or session context)
-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. 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
+2. Find the relevant behavior spec and acceptance criteria
+3. Run the **spec-compliance agent** with the Stage 1 prompt from `iterative-execution/references/review-prompts.md`
+4. **DO NOT trust the implementation report.** Read the actual code and test output independently.
+5. For each acceptance criterion: PASS / FAIL / PARTIAL with evidence
+6. If any criterion fails:
+   - Present findings
+   - Offer to fix (using TDD — write a test for the fix first)
+   - After fixing, re-run Stage 1
+   - Repeat until all criteria pass or max iterations reached
+
+**Stage 1 must pass before proceeding to Stage 2.**
+
+## Stage 2: Code Quality
+
+**Goal**: Find unnecessary complexity, dead code, scope creep.
+
+1. Run the **critic agent** — find logical errors, assumption issues
+2. Run the **simplifier agent** — find unnecessary complexity
+3. If the changes involve performance optimization, run the **performance-reviewer agent**
+4. Present findings with severity levels:
+   - [Critical] — must fix
+   - [Simplification] — should fix
+   - [Observation] — consider fixing
+5. Offer to auto-fix critical and simplification issues
+6. If fixes are made (using TDD), re-run Stage 2
+7. Repeat until no critical issues remain or max iterations reached
 
 ## Output Format
 
 ```
-SDD Review — Iteration 1/3
-──────────────────────────
+SDD Review — Stage 1: Spec Compliance
+──────────────────────────────────────
+
+Spec: specs/behavior-spec.md (5 criteria)
+
+  ✓ Criterion 1: User can log in — PASS (test_login passes)
+  ✓ Criterion 2: Invalid credentials show error — PASS (test_invalid_login passes)
+  ✗ Criterion 3: Session persists — FAIL (no test found for this criterion)
+
+Stage 1: 2/3 FAIL — must fix before proceeding to Stage 2.
+```
+
+```
+SDD Review — Stage 2: Code Quality
+───────────────────────────────────
 
 Critic Findings:
   [Critical] ...
-  [Warning] ...
 
 Simplifier Findings:
   [Simplification] ...
 
-Spec Compliance:
-  [X of Y criteria satisfied]
-
 Actions:
   - Fix critical issues? (y/n)
   - Apply simplifications? (y/n)
@@ -56,7 +85,12 @@ Actions:
 
 ## Principles
 
+- Stage 1 is the gate. No code quality review on non-compliant code.
 - Reviews are honest — findings are reported as-is, not softened
+- DO NOT trust the implementer's report. Verify independently.
 - Fixes follow TDD: if the fix changes behavior, write a test first
 - Max iterations prevent infinite loops
-- The review itself is part of the iterative execution cycle
+
+## References
+
+See: `iterative-execution/references/review-prompts.md` — Subagent prompt templates

package/commands/sdd-verify.md

@@ -0,0 +1,87 @@
+---
+name: sdd-verify
+description: Run automated verification checks — build, types, lint, tests, security scans. Distinct from /sdd-review (agent-based).
+argument-hint: "[quick|full|pre-commit|pre-pr]"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Task
+---
+
+# /sdd-verify
+
+Run automated verification checks against the codebase. This is the **automated checks** complement to `/sdd-review` (which uses agent-based analysis).
+
+## Usage
+
+- `/sdd-verify` — Run full verification (default)
+- `/sdd-verify quick` — Build + type check only
+- `/sdd-verify full` — Build + types + lint + test suite + coverage
+- `/sdd-verify pre-commit` — Quick + lint + debug statement scan + git status check
+- `/sdd-verify pre-pr` — Full + security-reviewer agent + diff review + TODO/secrets scan
+
+## Modes
+
+### quick
+Fast feedback loop during development.
+1. Build / compile check
+2. Type check (tsc, mypy, etc.)
+
+### full (default)
+Comprehensive automated verification.
+1. Build / compile check
+2. Type check
+3. Lint (eslint, ruff, etc.)
+4. Full test suite
+5. Coverage report (if configured)
+
+### pre-commit
+Everything needed before committing.
+1. All `quick` checks
+2. Lint
+3. Debug statement scan (`console.log`, `debugger`, `print(`, `TODO`, `FIXME`, `HACK`)
+4. Git status — ensure no unintended files staged
+
+### pre-pr
+Everything needed before opening a PR.
+1. All `full` checks
+2. Launch **security-reviewer** agent on changed files
+3. Diff review — scan for TODO, FIXME, secrets patterns, hardcoded values
+4. Generate summary
+
+## Output Format
+
+```
+SDD Verify — [mode]
+───────────────────
+
+  ✓ Build .......................... PASS
+  ✓ Type check .................... PASS
+  ✗ Lint .......................... FAIL (3 errors)
+  ✓ Tests ......................... PASS (42/42)
+  ✓ Coverage ...................... 87%
+  ✗ Debug statements .............. FAIL (2 found)
+  ✓ Secrets scan .................. PASS
+
+──────────────────────────────────
+Summary: 5/7 passed, 2 failed
+Ready for PR: NO
+```
+
+## How to Detect Project Tools
+
+1. Check `package.json` for scripts (build, test, lint, typecheck)
+2. Check for `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`
+3. Check for config files (`.eslintrc`, `tsconfig.json`, `ruff.toml`, `mypy.ini`)
+4. If no tools detected, report what's missing and skip those checks
+
+## Difference from /sdd-review
+
+| | /sdd-verify | /sdd-review |
+|---|---|---|
+| **Type** | Automated checks | Agent-based analysis |
+| **Speed** | Fast (runs tools) | Slower (launches agents) |
+| **Finds** | Build errors, type errors, lint issues, test failures | Logic errors, spec drift, unnecessary complexity |
+| **When** | During development, before commit/PR | After implementation, before merge |

package/contexts/dev.md

@@ -0,0 +1,25 @@
+# SDD Context: Dev Mode
+
+Full guardrails active. This is the default mode for implementation work.
+
+## Active Guardrails
+
+- **Pre-implementation checkpoint**: ON — enumerate assumptions, flag ambiguity, surface alternatives, push back on bad ideas, define scope, check for spec, plan TDD approach
+- **Completion review**: ON — spec adherence, test coverage, complexity audit, dead code check, scope creep check
+- **Scope guard**: STRICT — reject changes outside defined scope without explicit approval
+- **TDD enforcement**: ON — tests before implementation
+- **Post-edit review**: ON — review after each write/edit
+
+## When to Use
+
+- Implementing features from specs
+- Fixing bugs
+- Refactoring code
+- Any task where correctness and discipline matter
+
+## Principles
+
+- Every change starts with understanding the spec
+- Every implementation starts with a test
+- Every completion is verified against criteria
+- Scope is defended — no drive-by improvements

package/contexts/research.md

@@ -0,0 +1,26 @@
+# SDD Context: Research Mode
+
+Exploration focus. Guardrails are relaxed to allow free investigation without implementation ceremony.
+
+## Active Guardrails
+
+- **Pre-implementation checkpoint**: OFF — you're exploring, not committing to implementation
+- **Completion review**: OFF — research doesn't have a "done" in the spec-compliance sense
+- **Scope guard**: RELAXED — follow the investigation wherever it leads
+- **TDD enforcement**: OFF for prototypes — but ON if research produces code intended for production
+- **Post-edit review**: OFF — prototypes and experiments don't need review
+
+## When to Use
+
+- Understanding unfamiliar codebases
+- Investigating bugs (root cause analysis)
+- Prototyping and experimentation
+- Architecture exploration and spike work
+- Reading documentation and tracing flows
+
+## Principles
+
+- Follow curiosity — explore freely
+- Take notes — capture findings for later
+- Don't ship research code — if it becomes production code, switch to dev mode
+- Time-box — set a goal for what you want to learn

package/contexts/review.md

@@ -0,0 +1,25 @@
+# SDD Context: Review Mode
+
+Critic and verification focus. Pre-implementation checkpoint is skipped since you're reviewing, not building.
+
+## Active Guardrails
+
+- **Pre-implementation checkpoint**: OFF — you're reviewing existing code, not starting new work
+- **Completion review**: ON — ensure review findings are complete and actionable
+- **Scope guard**: NORMAL — stay focused on what you're reviewing
+- **TDD enforcement**: ON for any fixes — if review leads to fixes, tests come first
+- **Post-edit review**: ON — verify any fixes made during review
+
+## When to Use
+
+- Code review (PRs, post-implementation)
+- Auditing existing code for quality
+- Security reviews
+- Running `/sdd-review` or agent-based reviews
+
+## Principles
+
+- Find what's wrong, not confirm what's right
+- Be specific and evidence-based
+- Report findings honestly — don't soften
+- If fixing, follow TDD discipline