XDM Method — Spec-Driven Development Pipeline

Spec-Driven Development pipeline for Claude Code CLI. Transforms raw feature requests into validated, shipped code through a self-correcting converge loop.

Quick Start

# 1. Install globally (once)
npm install -g sdd-pipeline

# 2. Navigate to your project
cd my-project

# 3. Initialize pipeline
sdd init

# 4. Start with a feature (interactive 9-question interview)
claude "/sdd-bmad landing page for my SaaS"

# 5. Use Claude Code for full pipeline
claude "/sdd-spec"      # Generate SPEC.md
claude "/sdd-tasks"     # Generate tasks
claude "/sdd-cook"      # Implement tasks

# 6. Validate
claude "/sdd-converge"

Important: Use claude "/sdd-<cmd>" format for interactive commands (BMAD interview, SPEC generation, TASKS, COOK, CONVERGE).

Output Directory Structure

All generated artifacts are organized in the sdd/ directory (v1.1.0+):

project/
├── sdd/                         # All generated artifacts
│   ├── brief.md                 # Phase 0: BMAD brief
│   ├── SPEC.md                  # Phase 2: Specification
│   ├── tasks/                   # Phase 3: Task directories
│   │   └── task-260830-1200-feature/
│   │       ├── MASTER-TASKS.md
│   │       └── T-001-*.md
│   └── converge/                # Phase 5: Validation reports
├── .sdd/config.json            # Pipeline state & config
├── skills/                      # Implementation skills (Phase 4)
├── templates/                   # SDD templates
└── .claude/commands/           # Claude Code commands

Key features:

• All artifacts in one place (sdd/)
• Skills directory for implementation guidance
• Easy cleanup: delete sdd/ to reset
• Configurable via .sdd/config.json

Pipeline Phases

Raw Idea
    │
    ├── sdd bmad "idea"        → sdd/brief.md      (Phase 0)
    ├── claude "/sdd-bmad"       → Interactive 9-Q interview
    │
    ├── claude "/sdd-spec"      → sdd/SPEC.md       (Phase 2)
    ├── claude "/sdd-tasks"     → sdd/tasks/        (Phase 3)
    ├── claude "/sdd-cook"       → Implementation     (Phase 4)
    │
    └── claude "/sdd-converge"  → sdd/converge/     (Phase 5)
              │
              ├── PASS → Merge / Deploy
              └── FAIL → Fix → Re-enter

| Phase | Command | Output | Gate | |-------|---------|--------|------| | 0 | sdd bmad "idea" | sdd/brief.md | None | | 0 | claude "/sdd-bmad" | sdd/brief.md (interactive) | None | | 0 | claude "/sdd-bmad --batch answers.json" | sdd/brief.md | None (CI/CD mode) | | 2 | claude "/sdd-spec" | sdd/SPEC.md | Requires sdd/brief.md + confidence ≥20 | | 3 | claude "/sdd-tasks" | sdd/tasks/task-*/ | Requires sdd/SPEC.md | | 4 | claude "/sdd-cook" | Code | Requires task files | | 5 | claude "/sdd-converge" | sdd/converge/ | All phases |

Commands Reference

Core Pipeline Commands

| Command | Phase | Output | Description | |---------|-------|--------|-------------| | sdd init | — | .sdd/, templates/, sdd/, skills/ | Initialize SDD pipeline. Run once per project. | | sdd bmad <desc> | 0 | sdd/brief.md | Fast mode brief (low confidence). | | claude "/sdd-bmad <desc>" | 0 | sdd/brief.md | Interactive 9-question brainstorm. Generates confidence-scored brief. | | claude "/sdd-bmad --batch answers.json <desc>" | 0 | sdd/brief.md | Batch mode for CI/CD. Pre-defined answers file. | | claude "/sdd-spec" | 2 | sdd/SPEC.md | Generate SPEC.md from brief. Validates confidence ≥20/100. | | claude "/sdd-tasks" | 3 | sdd/tasks/task-*/ | Break SPEC.md into tasks (≤2 hours each). | | claude "/sdd-cook [--all\|--task T-XXX]" | 4 | Code | Unified: execution plan + implementation guidance + status tracking. | | claude "/sdd-converge" | 5 | sdd/converge/ | Validate implementation. Self-correcting loop. |

Utility Commands

| Command | Description | |---------|-------------| | sdd status | Show pipeline phase status. | | claude "/sdd check <file>" | Real-time validation. Check file(s) against SPEC.md clauses. | | pwsh commands/sdd-task-status.ps1 -TaskId T-001 -Status completed | Mark task complete. Updates MASTER-TASKS.md and frontmatter. |

Shell CLI (npm global)

sdd init               # Initialize pipeline
sdd bmad <desc>      # Fast mode brief (low confidence)
sdd status            # Show pipeline status
sdd help              # Show help

Usage Examples

Example 1: Landing Page

cd my-saas-project

# Initialize
sdd init

# Start with feature description (interactive)
claude "/sdd-bmad landing page for my SaaS product"

# Generate SPEC.md
claude "/sdd-spec"

# Break into tasks
claude "/sdd-tasks"

# Implement all tasks (unified command)
claude "/sdd-cook --all"

# Or implement one by one
claude "/sdd-cook --task T-001"
claude "/sdd-cook --task T-002"

# Validate
claude "/sdd-converge"

Example 2: API Feature

cd my-api-project
sdd init

# Set domain to API
# Edit .sdd/config.json: set project.domain = "api"

claude "/sdd-bmad user authentication with JWT tokens"
claude "/sdd-spec"
claude "/sdd-tasks"
claude "/sdd-cook --all"

Example 3: Real-Time Validation

# During implementation, check your work
claude "/sdd check src/components/Button.tsx"

# Result:
# ✅ SC-001: "Start Free Trial" found
# ✅ SC-COLOR-001: #22c55e found
# ❌ SC-002: "Get Started" NOT FOUND

# Fix the issue, then continue
claude "/sdd-cook --task T-002"

Phase Gates

Phase gates enforce deliberate progress:

| Command | Gate | If Missing | |---------|------|------------| | claude "/sdd-spec" | sdd/brief.md | ERROR: Run claude "/sdd-bmad" first. | | claude "/sdd-spec" | Confidence ≥20 | WARNING: Spec may be incomplete. | | claude "/sdd-tasks" | sdd/SPEC.md | ERROR: Run claude "/sdd-spec" first. | | claude "/sdd-converge" | All artifacts | ERROR: Run full pipeline first. |

BMAD Confidence Score

BMAD calculates a 0-100 confidence score:

| Score | Level | Action | |-------|-------|--------| | <20 | None | BLOCKED. Re-run BMAD with more detail. | | 20-49 | Weak | WARNING. Proceed with caution. | | 50-69 | Medium | Acceptable. | | ≥70 | Strong | Full confidence. |

Scoring factors:

• Input quality (0-30 pts) — more detail = higher
• Interview completion (0-30 pts) — more answers = higher
• Problem clarity (0-20 pts) — specific, measurable = higher
• Technical awareness (0-20 pts) — stack detail = higher

Task Format

Each task in MASTER-TASKS.md:

• Takes ≤2 hours
• Independently verifiable
• Has frontmatter with depends_on, spec_sections

task-260830-1200-feature/
├── MASTER-TASKS.md        # Task index, phases, status
├── T-001-*.md            # Individual task files
├── T-002-*.md
└── ...

Mark tasks complete:

pwsh commands/sdd-task-status.ps1 -TaskId T-001 -Status completed

Extension System

Domain-specific templates via .sdd/config.json:

{
  "project": {
    "domain": "frontend"
  }
}

| Domain | Adds | |--------|------| | general | Base pipeline | | api | OpenAPI spec, endpoint validation | | frontend | Design system prompts, UX checklist | | backend | Data models, security requirements |

Security

| Layer | Protection | |-------|-----------| | Input | Sanitize regex blocks prompt injection | | URL | SSRF prevention — blocks private IPs | | npm | --ignore-scripts on global installs | | GitHub Actions | Least-privilege permissions |

Architecture

Two Interfaces (same logic):

Shell CLI:          sdd bmad "feature"      → bin/sdd.cjs
Claude Code:        /sdd bmad "feature"     → .claude/commands/sdd.md

Project structure:
├── .sdd/config.json         # Phase tracking
├── templates/               # SDD templates (synced from bundle)
├── skills/                  # Implementation skills (synced from bundle)
├── .claude/commands/       # Claude Code slash commands (synced from bundle)
├── commands/               # Standalone PowerShell scripts (synced from bundle)
├── lib/
│   ├── bmad.js            # BMAD CLI wrapper
│   ├── bmad/              # BMAD modules
│   └── bundle/             # SOURCE OF TRUTH for npm package
├── scripts/
│   └── sync-bundle.ps1    # Sync bundle to working directories
└── extensions/             # Domain-specific (api/frontend/backend)

npm package (sdd-pipeline):
├── bin/sdd.cjs            # CLI entry
├── lib/bmad.js           # CLI wrapper
├── lib/bmad/              # BMAD orchestrator
└── lib/bundle/           # All pipeline files for distribution

Development Workflow

1. Edit files in lib/bundle/ (source of truth)
2. Run npm run sync to sync to working directories
3. Test with npm run pack --dry-run
4. Commit and publish

Important: After modifying lib/bundle/, always run npm run sync before testing!

Requirements

• Windows 11 + PowerShell (primary)
• Git 2.52+
• Node.js 18+ + npm 9+
• Claude Code CLI (npx @anthropic-ai/claude-code)

CI/CD

GitHub Actions workflow:

on: [push, pull_request]
jobs:
  converge:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - run: pwsh lib/bundle/run-converge.ps1 -Url '${{ env.DEV_URL }}' -Strict

npm Package

| Field | Value | |-------|-------| | Name | sdd-pipeline | | Version | 1.3.0 | | Registry | npmjs.com | | CLI command | sdd | | Claude Code command | /sdd | | Install | npm install -g sdd-pipeline |

Key Features

• Phase gates — Commands fail if prerequisites missing
• Confidence scoring — BMAD quantifies spec readiness
• Problem-first — Solution→problem inversion surfaces needs
• Unified Phase 4 — sdd-cook handles planning + implementation
• Domain extensions — API, frontend, backend via config
• SSRF protection — URL validation blocks private IPs
• GitHub Actions CI — Runs converge on push/PR