sdd-pipeline 1.0.1 → 1.1.0

package/README.md

@@ -1,95 +1,378 @@
-# XDM Method — SDD Pipeline for Claude Code
+# XDM Method — Spec-Driven Development Pipeline
 
-Spec-Driven Development pipeline that transforms raw feature requests into validated, shipped code through a self-correcting converge loop.
+**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
-# Install globally (once)
+# 1. Install globally (once)
 npm install -g sdd-pipeline
 
-# In any new project directory:
-sdd init              # Initialize pipeline
-sdd bmad "todo app" # Generate BMAD brief
-sdd status           # Check pipeline phases
+# 2. Navigate to your project
+cd my-project
+
+# 3. Initialize pipeline
+sdd init
+
+# 4. Start with a feature
+sdd bmad "landing page for my SaaS"
+
+# 5. Use Claude Code for full pipeline
+/sdd spec      # Generate SPEC.md
+/sdd tasks     # Generate tasks
+/ck:cook       # Implement tasks
+
+# 6. Validate
+pwsh run-converge.ps1 -Url 'http://localhost:3000' -Strict
 ```
 
-## Unified Command
+---
 
-Use `/sdd` in Claude Code for the full pipeline:
+## Output Directory Structure
+
+All generated artifacts are organized in the `sdd/` directory:
+
+```
+project/
+├── sdd/                         # All generated artifacts
+│   ├── brief.md                # Phase 0: BMAD brief
+│   ├── SPEC.md                 # Phase 2: Specification
+│   ├── 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
+- Legacy files auto-migrated on first use
+- Configurable via `.sdd/config.json`
+
+---
+
+## Pipeline Phases
+
+```
+Raw Idea
+    │
+    ├── /sdd bmad     → sdd/brief.md      (Phase 0)
+    ├── /sdd spec     → sdd/SPEC.md       (Phase 2)
+    ├── /sdd tasks    → sdd/tasks/        (Phase 3)
+    ├── /ck:cook      → Implementation     (Phase 4)
+    │
+    └── /sdd converge → sdd/converge/      (Phase 5)
+              │
+              ├── PASS → Merge / Deploy
+              └── FAIL → Fix → Re-enter
+```
+
+| Phase | Command | Output | Gate |
+|-------|---------|--------|------|
+| 0 | `/sdd bmad <desc>` | `sdd/brief.md` | None |
+| 2 | `/sdd spec` | `sdd/SPEC.md` | Requires `sdd/brief.md` + confidence ≥20 |
+| 3 | `/sdd tasks` | `sdd/tasks/task-*/` | Requires `sdd/SPEC.md` |
+| 4 | `/ck:cook` | Code | Requires task files |
+| 5 | `pwsh run-converge.ps1` | `sdd/converge/` | All phases |
+
+---
+
+## Commands Reference
+
+### Core Pipeline Commands
+
+| Command | Phase | Output | Description |
+|---------|-------|--------|-------------|
+| `/sdd init` | — | `.sdd/`, `templates/`, `sdd/` | Initialize SDD pipeline. Creates directory structure. Run once per project. |
+| `/sdd bmad <desc>` | 0 | `sdd/brief.md` | Interactive brainstorm. Asks 9 discovery questions, generates confidence-scored brief. |
+| `/sdd spec` | 2 | `sdd/SPEC.md` | Generate SPEC.md from brief. Validates confidence ≥20/100 + expiry check. |
+| `/sdd tasks` | 3 | `sdd/tasks/task-*/` | Break SPEC.md into tasks (≤2 hours each). Creates MASTER-TASKS.md + T-XXX-*.md files. |
+| `/sdd cook` | 4 | — | Execute tasks sequentially. Args: `[--all \| --task T-XXX]`. |
+| `/sdd converge` | 5 | `sdd/converge/` | Validate implementation. Self-correcting loop. Args: `[--task <task-id>]`. |
+
+### 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
-claude "/sdd init"
-claude "/sdd bmad landing page for my SaaS"
+sdd init               # Same as /sdd init
+sdd bmad <desc>        # Same as /sdd bmad
+sdd status             # Same as /sdd status
+sdd help               # Show help
+
+# Full pipeline requires Claude Code
 claude "/sdd spec"
 claude "/sdd tasks"
-claude "/sdd converge"
-claude "/sdd status"
+pwsh run-converge.ps1 -Strict
 ```
 
-## Pipeline Phases
+---
 
-| Phase | Command | Output |
-|-------|---------|--------|
-| 0: BMAD | `/sdd bmad` | BMAD-brief.md |
-| 2: Spec | `/sdd spec` | SPEC.md |
-| 3: Tasks | `/sdd tasks` | TASKS.md |
-| 5: Converge | `/sdd converge` | converge/validation.md |
+## Usage Examples
 
-Individual commands also available: `/sdd-bmad`, `/sdd-spec`, `/sdd-tasks`, `/sdd-converge`.
+### Example 1: Landing Page
 
-## Key Features
+```powershell
+cd my-saas-project
 
-- **Phase gates:** `/sdd spec` fails if BMAD-brief.md missing — no bypass
-- **Prompt injection protection:** All user input sanitized
-- **SSRF protection:** URL validation blocks private IPs, localhost
-- **Dev server health check:** 60s timeout before Lighthouse runs
-- **GitHub Actions CI:** Runs converge on push/PR, creates Issue on failure
-- **Domain extensions:** API, frontend, backend — set via `.sdd/config.json`
+# Initialize
+sdd init
 
-## Status
+# Start with feature description
+sdd bmad "landing page for my SaaS product"
+
+# Claude Code generates spec
+/sdd spec
+
+# Break into tasks
+/sdd tasks
+
+# Implement each task
+/sdd cook --task T-001
+/sdd cook --task T-002
+/sdd cook --task T-003
+
+# Validate (with dev server running)
+/sdd converge
+```
+
+### Example 2: API Feature
 
 ```powershell
-sdd status           # Quick status (npm package)
-pwsh commands/sdd-status.ps1 --Verify  # Full verification
+cd my-api-project
+sdd init
+
+# Set domain to API
+# Edit .sdd/config.json: set project.domain = "api"
+
+sdd bmad "user authentication with JWT tokens"
+
+# /sdd spec now includes OpenAPI validation sections
+/sdd spec
+/sdd tasks
+/ck:cook --all
 ```
 
-## Architecture
+### Example 3: Real-Time Validation
+
+```powershell
+# During implementation, check your work
+/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
+/sdd cook --task T-002
 ```
-Raw Idea -> /sdd bmad -> BMAD-brief.md
-  -> /sdd spec -> SPEC.md
-  -> /sdd tasks -> TASKS.md
-  -> Implement
-  -> /sdd converge
-  -> pwsh run-converge.ps1 -> converge/validation.md
-         |
-         +-- PASS: merge
-         +-- FAIL: fix -> re-enter
+
+---
+
+## Phase Gates
+
+Phase gates enforce deliberate progress. Commands fail if prerequisites are missing:
+
+| Command | Gate | If Missing |
+|---------|------|------------|
+| `/sdd spec` | BMAD-brief.md | ERROR: Phase 0 not complete. Run `/sdd bmad` first. |
+| `/sdd spec` | Confidence ≥20 | WARNING: Confidence is Weak. Spec may be incomplete. |
+| `/sdd tasks` | SPEC.md | ERROR: SPEC.md not found. Run `/sdd spec` first. |
+| `/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 | `/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
+└── ...
 ```
 
-## Files
+---
+
+## 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.
 
-| Path | Purpose |
-|------|---------|
-| `.sdd/config.json` | Pipeline state, template versions |
-| `templates/` | SDD artifact templates |
-| `.claude/commands/` | Claude Code slash commands |
-| `run-converge.ps1` | Converge validation script |
-| `.github/workflows/converge.yml` | CI/CD pipeline |
-| `extensions/` | Domain-specific extensions |
+---
 
-## Extensions
+## Security
 
-Enable via `.sdd/config.json` `project.domain`:
-- `api` — OpenAPI spec, endpoint validation
-- `frontend` — design system, Lighthouse targets
-- `backend` — data models, security requirements
+| 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, Node.js, npm
-- Claude Code CLI
+- 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.0.2` |
+| 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
 
-See [docs/spec-pipeline-synthesis.md](docs/spec-pipeline-synthesis.md) for full pipeline specification.
+| 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 |

package/bin/sdd.js

@@ -37,15 +37,23 @@ switch (cmd) {
     console.log(`
 sdd — Spec-Driven Development CLI
 
+Output Structure:
+  sdd/                    # All generated artifacts
+    brief.md             # Phase 0: BMAD brief
+    SPEC.md              # Phase 2: Specification
+    tasks/              # Phase 3: Task directories
+    converge/           # Phase 5: Validation reports
+
 Usage:
-  sdd init               Initialize SDD pipeline in current directory
-  sdd bmad <description> Generate BMAD brief
-  sdd status             Show pipeline phase status
+  sdd init               Initialize SDD pipeline
+  sdd bmad <desc>       Phase 0: Interactive brainstorm
+  sdd status             Show pipeline status
   sdd help               Show this help
 
 Full pipeline (requires Claude Code):
-  claude "/sdd-spec"    Generate SPEC.md
-  claude "/sdd-tasks"   Generate TASKS.md
-  pwsh run-converge.ps1 Run converge validation
+  claude "/sdd-spec"    Phase 2: Generate SPEC.md
+  claude "/sdd-tasks"   Phase 3: Generate tasks
+  claude "/sdd-cook"    Phase 4: Execute tasks
+  pwsh run-converge.ps1 Phase 5: Validate
 `)
 }

package/lib/bmad/agents/architect.js

@@ -0,0 +1,96 @@
+/**
+ * BMAD Architect Agent — Technical Architect perspective
+ * Analyzes from a feasibility, risk, and technical constraints lens.
+ */
+
+/**
+ * @param {object} state - BMAD interview state
+ * @returns {{ section: string, confidence: string }}
+ */
+function analyze(state) {
+  const input = state.input || ''
+  const answers = state.answers || {}
+
+  // Architect key questions: q4, q5, q6
+  const q4 = answers.q4 || ''
+  const q5 = answers.q5 || ''
+  const q6 = answers.q6 || ''
+
+  const mvp = q4 || inferMvp(input)
+  const risks = parseRisks(q6)
+  const integrations = parseIntegrations(q5)
+
+  const section = `## Architect Perspective
+**Minimum viable approach:** ${mvp}
+
+**Required integrations:** ${integrations}
+
+**Technical risks:**
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+${risks}
+
+**Tech constraints:**
+- ${inferConstraints(input)}
+
+**Done criteria (technical):** ${inferDoneCriteria(input, mvp)}
+`
+
+  const confidence = inferConfidence(q4, q5, q6)
+  return { section, confidence }
+}
+
+function inferMvp(input) {
+  if (!input) return '[one paragraph — what is the simplest thing that works?]'
+  return `Deliver: ${input.trim()}. No optional features in v1.`
+}
+
+function parseRisks(q6) {
+  if (!q6 || q6.trim().length < 10) {
+    return '| [Risk 1] | [H/M/L] | [H/M/L] | [Mitigation] |\n| [Risk 2] | [H/M/L] | [H/M/L] | [Mitigation] |'
+  }
+  // Best-effort parse — user provides structured answer or free text
+  const lines = q6.split('\n').filter((l) => l.trim())
+  if (lines.length >= 2) {
+    return lines
+      .slice(0, 3)
+      .map((line) => {
+        const parts = line.split(/[,;]/).map((p) => p.trim())
+        return `| ${parts[0] || 'Risk'} | ${parts[1] || 'M'} | ${parts[2] || 'M'} | ${parts.slice(3).join(', ') || 'TBD'} |`
+      })
+      .join('\n')
+  }
+  const risk1 = q6.split(/[.,\n]/)[0].trim() || 'Risk'
+  return `| ${risk1} | M | M | [Provide mitigation] |\n| [Risk 2] | [H/M/L] | [H/M/L] | [Mitigation] |`
+}
+
+function parseIntegrations(q5) {
+  if (!q5 || q5.trim().length < 5) return '[from Q5 — list required integrations or "None for MVP"]'
+  return q5.split(/[,;\n]/).filter((i) => i.trim()).slice(0, 5).join(', ')
+}
+
+function inferConstraints(input) {
+  const lower = (input || '').toLowerCase()
+  if (lower.includes('frontend') || lower.includes('website') || lower.includes('landing page'))
+    return 'Performance budget: Lighthouse ≥90, mobile-first CSS, no layout shift'
+  if (lower.includes('api') || lower.includes('backend') || lower.includes('service'))
+    return 'API: REST preferred, versioned endpoints, error responses must be structured'
+  if (lower.includes('mobile') || lower.includes('ios') || lower.includes('android'))
+    return 'Native build targets: latest OS version, accessibility support required'
+  return 'Technology choices constrained by existing project stack — do not introduce new dependencies without approval'
+}
+
+function inferDoneCriteria(input, mvp) {
+  if (!mvp) return '[define what "done" looks like technically — measurable conditions]'
+  return `MVP (${mvp.slice(0, 50)}...) is functional, tested, and meets non-functional requirements`
+}
+
+function inferConfidence(q4, q5, q6) {
+  const filled = [q4, q5, q6].filter((a) => a.trim().length > 10).length
+  if (filled >= 3) return 'High'
+  if (filled >= 2) return 'Medium'
+  if (filled >= 1) return 'Low'
+  return 'None'
+}
+
+module.exports = { analyze }

package/lib/bmad/agents/pm.js

@@ -0,0 +1,67 @@
+/**
+ * BMAD PM Agent — Product Manager perspective
+ * Analyzes user input and interview answers from a PM lens.
+ */
+
+/**
+ * @param {object} state - BMAD interview state (input, answers, inversion)
+ * @returns {{ section: string, confidence: string }}
+ */
+function analyze(state) {
+  const input = state.input || ''
+  const answers = state.answers || {}
+  const inversion = state.inversion || {}
+
+  // PM key questions: q1, q2, q3
+  const q1 = answers.q1 || inversion.problem || ''
+  const q2 = answers.q2 || ''
+  const q3 = answers.q3 || ''
+
+  // Synthesize PM perspective
+  const targetUser = q2.split(/[,.\n]/)[0].trim() || '[from Q2 — who is the user?]'
+  const primaryAction = inferPrimaryAction(input, q1)
+  const topNeeds = extractNeeds(q1, q3)
+
+  const section = `## PM Perspective
+**Target user:** ${targetUser}
+**User needs:** ${topNeeds}
+**Primary conversion action:** ${primaryAction}
+**Success metric (90-day):** ${q3 || '[from Q3 — what measurable outcome?]'}
+
+**Problem framing:** ${q1 || '[from Q1 — the problem being solved]'}
+`
+
+  const confidence = inferConfidence(q1, q2, q3)
+  return { section, confidence }
+}
+
+function inferPrimaryAction(input, q1) {
+  const lower = (input + ' ' + q1).toLowerCase()
+  if (lower.includes('signup') || lower.includes('register') || lower.includes('sign up'))
+    return 'Sign up / create account'
+  if (lower.includes('purchase') || lower.includes('buy') || lower.includes('checkout'))
+    return 'Complete purchase'
+  if (lower.includes('download')) return 'Download content or file'
+  if (lower.includes('subscribe')) return 'Subscribe to plan'
+  if (lower.includes('contact') || lower.includes('demo')) return 'Request demo or contact'
+  if (lower.includes('share') || lower.includes('invite')) return 'Share or invite'
+  return '[to be determined — what does the user do that matters to business?]'
+}
+
+function extractNeeds(q1, q3) {
+  if (!q1) return '[List top 3 needs this feature addresses]'
+  // Extract first 3 sentences or items
+  const sentences = q1.split(/[.\n]/).filter((s) => s.trim().length > 5).slice(0, 3)
+  if (sentences.length === 0) return '[List top 3 needs this feature addresses]'
+  return sentences.map((s) => `• ${s.trim()}`).join('\n')
+}
+
+function inferConfidence(q1, q2, q3) {
+  const filled = [q1, q2, q3].filter((a) => a.trim().length > 10).length
+  if (filled >= 3) return 'High'
+  if (filled >= 2) return 'Medium'
+  if (filled >= 1) return 'Low'
+  return 'None'
+}
+
+module.exports = { analyze }