sdd-pipeline 1.2.6 → 1.2.8

package/README.md

@@ -1,376 +1,343 @@
-# 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
-
-```powershell
-# 1. Install globally (once)
-npm install -g sdd-pipeline
-
-# 2. Navigate to your project
-cd my-project
-
-# 3. Initialize pipeline
-claude "/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
-pwsh run-converge.ps1 -Url 'http://localhost:3000' -Strict
-```
-
-> **Important:** Always use `claude "/sdd-<cmd>"` format for interactive commands.
-
----
-
-## 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
-│   ├── PLAN.md                 # Phase 3: Implementation plan
-│   ├── tasks/                  # Phase 3: Task directories
-│   │   └── task-260829-1700-feature/
-│   │       ├── MASTER-TASKS.md
-│   │       └── T-001-*.md
-│   └── converge/               # Phase 5: Validation reports
-│       ├── validation.md        # Full project converge
-│       └── task-T-001/
-│           └── report.md       # Per-task converge
-├── .sdd/config.json           # Pipeline state & config
-├── templates/                   # SDD templates
-└── .claude/commands/           # Claude Code commands
-```
-
-**Key features:**
-- All artifacts in one place (`sdd/`)
-- Easy cleanup: delete `sdd/` to reset
-- Configurable via `.sdd/config.json`
-
----
-
-## Pipeline Phases
-
-```
-Raw Idea
-    │
-    ├── claude "/sdd-bmad"     → sdd/brief.md      (Phase 0)
-    ├── 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 | `claude "/sdd-bmad <desc>"` | `sdd/brief.md` | None |
-| 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 | `pwsh run-converge.ps1` | `sdd/converge/` | All phases |
-
----
-
-## Commands Reference
-
-### Core Pipeline Commands
-
-| Command | Phase | Output | Description |
-|---------|-------|--------|-------------|
-| `claude "/sdd init"` | — | `.sdd/`, `templates/`, `sdd/` | Initialize SDD pipeline. Creates directory structure. Run once per project. |
-| `claude "/sdd-bmad <desc>"` | 0 | `sdd/brief.md` | Interactive brainstorm. Asks 9 discovery questions, generates confidence-scored brief. |
-| `claude "/sdd-spec"` | 2 | `sdd/SPEC.md` | Generate SPEC.md from brief. Validates confidence ≥20/100 + expiry check. |
-| `claude "/sdd-tasks"` | 3 | `sdd/tasks/task-*/` | Break SPEC.md into tasks (≤2 hours each). Creates MASTER-TASKS.md + T-XXX-*.md files. |
-| `claude "/sdd-cook"` | 4 | Code | Execute tasks. Args: `[--all \| --task T-XXX]`. |
-| `claude "/sdd-converge"` | 5 | `sdd/converge/` | Validate implementation. Self-correcting loop. |
-
-### Utility Commands
-
-| Command | Description |
-|---------|-------------|
-| `/sdd status` | Show pipeline phase status. Displays current phase, completed phases, next command. |
-| `/sdd check <file>` | Real-time validation. Check file(s) against SPEC.md clauses ([SC-xxx], [AC-xxx]). |
-| `/sdd task-status T-XXX <status>` | Update task status. Args: `pending \| in-progress \| completed`. |
-
-### Shell CLI (npm global)
-
-```powershell
-sdd init               # Initialize pipeline
-sdd bmad <desc>       # Non-interactive brief (low confidence)
-sdd status             # Show pipeline status
-sdd help               # Show help
-
-# For interactive commands, use Claude Code
-claude "/sdd bmad <desc>"    # Interactive 9-question interview
-```
-
----
-
-## Usage Examples
-
-### Example 1: Landing Page
-
-```powershell
-cd my-saas-project
-
-# Initialize
-claude "/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 tasks
-claude "/sdd-cook --task T-001"
-claude "/sdd-cook --task T-002"
-claude "/sdd-cook --task T-003"
-
-# Validate (with dev server running)
-claude "/sdd-converge"
-```
-
-### Example 2: API Feature
-
-```powershell
-cd my-api-project
-claude "/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
-
-```powershell
-# 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. Commands fail if prerequisites are missing:
-
-| Command | Gate | If Missing |
-|---------|------|------------|
-| `claude "/sdd-spec"` | sdd/brief.md | ERROR: Phase 0 not complete. Run `claude "/sdd-bmad"` first. |
-| `claude "/sdd-spec"` | Confidence ≥20 | WARNING: Confidence is Weak. Spec may be incomplete. |
-| `claude "/sdd-tasks"` | sdd/SPEC.md | ERROR: SPEC.md not found. Run `claude "/sdd-spec"` first. |
-| `claude "/sdd-converge"` | All artifacts | ERROR: Missing artifacts. Run full pipeline first. |
-
----
-
-## BMAD Confidence Score
-
-BMAD calculates a 0-100 confidence score before generating SPEC.md:
-
-| Score | Level | Action |
-|-------|-------|--------|
-| <20 | None | `claude "/sdd-spec"` BLOCKED. Re-run BMAD with more detail. |
-| 20-49 | Weak | WARNING. Proceed with caution — spec may need iteration. |
-| 50-69 | Medium | Acceptable. Answer more questions for better spec. |
-| ≥70 | Strong | Full confidence. Proceed to spec. |
-
-**Scoring factors:**
-- Input quality (0-30 pts) — more detail = higher score
-- Interview completion (0-30 pts) — more answers = higher score
-- Problem clarity (0-20 pts) — specific, measurable = higher score
-- Technical awareness (0-20 pts) — stack/integration detail = higher score
-
----
-
-## Task Format
-
-Each task in MASTER-TASKS.md:
-- Takes ≤2 hours
-- Independently verifiable
-- Has frontmatter with `depends_on`, `spec_sections`
-
-```
-task-260829-1657-landing-page/
-├── MASTER-TASKS.md        # Task index, phases, status
-├── T-001-html-structure.md
-├── T-002-mobile-css.md
-├── T-003-desktop-css.md
-└── ...
-```
-
----
-
-## Extension System
-
-Domain-specific templates activate via `.sdd/config.json`:
-
-```json
-{
-  "project": {
-    "domain": "frontend"
-  }
-}
-```
-
-| Domain | Adds |
-|--------|------|
-| `general` | Base pipeline only |
-| `api` | OpenAPI spec, endpoint validation, API checklist |
-| `frontend` | Design system prompts, Lighthouse targets, UX checklist |
-| `backend` | Data models, security requirements, backend checklist |
-
-Extensions are **additive** — base pipeline always works.
-
----
-
-## Security
-
-| Layer | Protection |
-|-------|-----------|
-| Input | Sanitize regex blocks prompt injection patterns |
-| URL | SSRF prevention — blocks private IPs, localhost |
-| npm | `--ignore-scripts` on global installs |
-| GitHub Actions | Least-privilege permissions block |
-
----
-
-## Architecture
-
-```
-Two Interfaces (same logic):
-
-Shell CLI:          sdd bmad "feature"      → bin/sdd.js
-Claude Code:        /sdd bmad "feature"     → .claude/commands/sdd.md
-
-Pipeline files:
-├── .sdd/config.json         # Phase tracking, template versions
-├── templates/               # SDD artifact templates
-├── .claude/commands/       # Claude Code slash commands
-├── commands/               # Standalone CLI scripts
-├── run-converge.ps1        # Converge automation
-└── extensions/             # Domain-specific (api/frontend/backend)
-
-npm package (sdd-pipeline):
-├── bin/sdd.js              # CLI entry
-├── lib/init.js             # Extract pipeline
-├── lib/bmad/               # BMAD orchestrator (8 modules)
-└── lib/bundle/             # 31 pipeline files for distribution
-```
-
----
-
-## Requirements
-
-- Windows 11 + PowerShell (primary), Bash (fallback)
-- Git 2.52+
-- Node.js 18+ + npm 9+
-- Claude Code CLI (`npx @anthropic-ai/claude-code`)
-
-## CI/CD
-
-GitHub Actions workflow runs converge on push/PR:
-
-```yaml
-on: [push, pull_request]
-jobs:
-  converge:
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: pwsh run-converge.ps1 -Url '${{ env.DEV_URL }}' -Strict
-```
-
-On failure: artifacts uploaded + GitHub Issue created with fix recommendations.
-
----
-
-## File Structure
-
-```
-project/
-├── .sdd/config.json         # Pipeline state
-├── BMAD-brief.md           # Phase 0 output
-├── SPEC.md                 # Phase 2 output
-├── task-*/                 # Phase 3 output
-│   ├── MASTER-TASKS.md
-│   └── T-XXX-*.md
-├── converge/               # Phase 5 output
-│   └── validation.md
-└── .claude/commands/       # SDD commands
-```
-
-## Status
-
-```powershell
-sdd status           # Quick status (npm package)
-pwsh commands/sdd-status.ps1 --Verify  # Full verification
-```
-
----
-
-## npm Package
-
-| Field | Value |
-|-------|-------|
-| Name | `sdd-pipeline` |
-| Version | `1.1.0` |
-| Registry | npmjs.com |
-| CLI command | `sdd` |
-| Claude Code command | `/sdd` |
-| Install | `npm install -g sdd-pipeline` |
-
----
-
-## Key Features
-
-- **Phase gates** — `/sdd spec` fails if BMAD-brief.md missing — no bypass
-- **Confidence scoring** — BMAD quantifies spec readiness before implementation
-- **Problem-first** — Solution→problem inversion surfaces actual user needs
-- **Self-correcting converge** — Loop back to appropriate phase on failure
-- **Domain extensions** — API, frontend, backend — set via config
-- **SSRF protection** — URL validation blocks private IPs, localhost
-- **GitHub Actions CI** — Runs converge on push/PR, creates Issue on failure
-
----
-
-## Documentation
-
-| Document | Purpose |
-|----------|---------|
-| `docs/project-overview-pdr.md` | Project overview, problem statement, solution |
-| `docs/system-architecture.md` | System architecture, component map, CI/CD flow |
-| `docs/spec-pipeline-synthesis.md` | Full pipeline specification (1,200+ lines) |
-| `docs/codebase-summary.md` | Codebase overview, file inventory, key contracts |
-| `docs/deployment-guide.md` | Deployment instructions |
-| `docs/project-roadmap.md` | Future plans |
+# 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
+
+```powershell
+# 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 |
+| 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-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)
+
+```powershell
+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
+
+```powershell
+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
+
+```powershell
+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
+
+```powershell
+# 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:**
+```powershell
+pwsh commands/sdd-task-status.ps1 -TaskId T-001 -Status completed
+```
+
+---
+
+## Extension System
+
+Domain-specific templates via `.sdd/config.json`:
+
+```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
+
+Pipeline files:
+├── .sdd/config.json         # Phase tracking
+├── templates/               # SDD templates
+├── skills/                  # Implementation skills (Phase 4)
+├── .claude/commands/       # Claude Code slash commands
+├── commands/               # Standalone PowerShell scripts
+├── run-converge.ps1        # Validation automation
+└── extensions/             # Domain-specific (api/frontend/backend)
+
+npm package (sdd-pipeline):
+├── bin/sdd.cjs            # CLI entry
+├── lib/init.js            # Extract pipeline
+├── lib/bmad/              # BMAD orchestrator
+└── lib/bundle/           # 70 pipeline files for distribution
+```
+
+---
+
+## 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:
+
+```yaml
+on: [push, pull_request]
+jobs:
+  converge:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pwsh run-converge.ps1 -Url '${{ env.DEV_URL }}' -Strict
+```
+
+---
+
+## npm Package
+
+| Field | Value |
+|-------|-------|
+| Name | `sdd-pipeline` |
+| Version | `1.2.7` |
+| 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