sdd-pipeline 1.0.2 → 1.2.0

package/README.md

@@ -1,95 +1,376 @@
-# XDM Method — SDD Pipeline for Claude Code
-
-Spec-Driven Development pipeline that transforms raw feature requests into validated, shipped code through a self-correcting converge loop.
-
-## Quick Start
-
-```powershell
-# 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
-```
-
-## Unified Command
-
-Use `/sdd` in Claude Code for the full pipeline:
-
-```powershell
-claude "/sdd init"
-claude "/sdd bmad landing page for my SaaS"
-claude "/sdd spec"
-claude "/sdd tasks"
-claude "/sdd converge"
-claude "/sdd status"
-```
-
-## 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 |
-
-Individual commands also available: `/sdd-bmad`, `/sdd-spec`, `/sdd-tasks`, `/sdd-converge`.
-
-## Key Features
-
-- **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`
-
-## Status
-
-```powershell
-sdd status           # Quick status (npm package)
-pwsh commands/sdd-status.ps1 --Verify  # Full verification
-```
-
-## Architecture
-
-```
-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
-```
-
-## Files
-
-| 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
-
-Enable via `.sdd/config.json` `project.domain`:
-- `api` — OpenAPI spec, endpoint validation
-- `frontend` — design system, Lighthouse targets
-- `backend` — data models, security requirements
-
-## Requirements
-
-- Windows 11 + PowerShell (primary), Bash (fallback)
-- Git, Node.js, npm
-- Claude Code CLI
-
-See [docs/spec-pipeline-synthesis.md](docs/spec-pipeline-synthesis.md) for full pipeline specification.
+# 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 |

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 }