sdd-pipeline 1.0.0 → 1.0.2

package/README.md

@@ -5,57 +5,64 @@ Spec-Driven Development pipeline that transforms raw feature requests into valid
 ## Quick Start
 
 ```powershell
-# 1. Initialize (if new project)
-claude "/sdd-init"
+# Install globally (once)
+npm install -g sdd-pipeline
 
-# 2. Brainstorm — generate structured brief
-claude "/sdd-bmad <feature description>"
-
-# 3. Generate SPEC.md
-claude "/sdd-spec"
+# In any new project directory:
+sdd init              # Initialize pipeline
+sdd bmad "todo app" # Generate BMAD brief
+sdd status           # Check pipeline phases
+```
 
-# 4. Generate TASKS.md
-claude "/sdd-tasks"
+## Unified Command
 
-# 5. Implement tasks
+Use `/sdd` in Claude Code for the full pipeline:
 
-# 6. Validate (auto in CI, or manually)
-pwsh run-converge.ps1 -Url "http://localhost:3000" -Strict
+```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 |
+| 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 before LLM embedding
-- **SSRF protection:** URL validation blocks private IPs, localhost, cloud metadata endpoints
-- **Dev server health check:** 60s timeout with retry before Lighthouse runs
+- **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
-pwsh commands/sdd-status.ps1           # Quick status
-pwsh commands/sdd-status.ps1 --Verify # Full verification
+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
+Raw Idea -> /sdd bmad -> BMAD-brief.md
+  -> /sdd spec -> SPEC.md
+  -> /sdd tasks -> TASKS.md
   -> Implement
-  -> run-converge.ps1 -> converge/validation.md
+  -> /sdd converge
+  -> pwsh run-converge.ps1 -> converge/validation.md
          |
          +-- PASS: merge
          +-- FAIL: fix -> re-enter

package/lib/bmad.js

@@ -0,0 +1,60 @@
+const fs = require('fs')
+const path = require('path')
+const sanitize = require('./sanitize')
+
+function run(description) {
+  if (!description) {
+    console.error('Usage: sdd bmad <description>')
+    console.error('Example: sdd bmad "landing page for my SaaS product"')
+    process.exit(1)
+  }
+
+  const sanitized = sanitize.run(description)
+  const date = new Date().toISOString().split('T')[0]
+  const expiry = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]
+
+  const content = `# BMAD Brief — [Project Name]
+
+> Generated: ${date}. Expires: ${expiry}.
+
+## Input
+> ${sanitized}
+
+## PM Perspective
+**Target user:** [Who benefits most from this feature]
+**User needs:** [Top 3 needs this feature addresses]
+**Primary conversion action:** [What user does that matters to business]
+
+## Architect Perspective
+**Minimum viable approach:** [One paragraph]
+**Technical risks:**
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [Risk 1] | [H/M/L] | [H/M/L] | [Mitigation] |
+
+## UX Perspective
+**First impression goal:** [Description]
+**Microcopy needed:** [List]
+
+## Synthesis
+**What we're building:** [2-3 sentences describing the feature]
+
+**What we're NOT building:** [Explicit exclusions]
+1. [Exclusion]
+
+## Open Questions
+| # | Question | Impact |
+|---|----------|--------|
+| 1 | [Question] | [Blocking?] |
+
+## Prompt Injection Check
+- Input was sanitized before processing
+- No system prompt overrides accepted
+`
+
+  fs.writeFileSync('BMAD-brief.md', content, 'utf8')
+  console.log('[OK] BMAD-brief.md created.')
+  console.log('Next: claude "/sdd-spec" to generate SPEC.md')
+}
+
+module.exports = { run }

package/lib/bundle/.claude/commands/sdd.md

@@ -0,0 +1,261 @@
+---
+tool: Bash
+when: always
+args: optional
+---
+$ErrorActionPreference = "Stop"
+$args = $argsRaw.Trim()
+
+function Write-Help {
+    Write-Host @"
+
+sdd — Spec-Driven Development CLI
+
+Usage:
+  /sdd init               Initialize SDD pipeline in current directory
+  /sdd bmad <desc>        Generate BMAD brief
+  /sdd status             Show pipeline phase status
+  /sdd help               Show this help
+
+Full pipeline commands:
+  /sdd spec               Generate SPEC.md from BMAD-brief.md
+  /sdd tasks              Generate TASKS.md from SPEC.md
+  /sdd converge           Run converge validation
+
+"@
+}
+
+function Test-PromptInjection {
+    param([string]$Input)
+    $blocked = '(?i)(ignore previous|disregard|system:|</?script|ignore all previous)'
+    if ($Input -match $blocked) {
+        Write-Host "[WARN] Input sanitized — blocked pattern detected" -ForegroundColor Yellow
+        return $Input -replace $blocked, '[FILTERED]'
+    }
+    return $Input
+}
+
+if (-not $args) {
+    Write-Host "Usage: /sdd <command> [args]" -ForegroundColor Yellow
+    Write-Help
+    exit 0
+}
+
+$parts = $args -split '\s+', 2
+$cmd = $parts[0].ToLower()
+$rest = if ($parts.Length -gt 1) { Test-PromptInjection -Input $parts[1] } else { "" }
+
+switch ($cmd) {
+    "init" {
+        New-Item -ItemType Directory -Force -Path ".sdd","templates","converge",".claude/commands","commands","extensions",".github/workflows" | Out-Null
+
+        if (Test-Path ".sdd/config.json") {
+            Write-Host "[SKIP] SDD pipeline already initialized" -ForegroundColor Yellow
+        } else {
+            $config = @{
+                version = "1.0"
+                phases = @{
+                    current = 0
+                    phase0 = @{ status = "pending"; brief = "BMAD-brief.md" }
+                    phase1 = @{ status = "pending" }
+                    phase2 = @{ status = "pending"; specFile = "SPEC.md" }
+                    phase3 = @{ status = "pending"; tasksFile = "TASKS.md" }
+                    phase4 = @{ status = "pending" }
+                    phase5 = @{ status = "pending"; validationFile = "converge/validation.md" }
+                }
+                templateVersions = @{
+                    constitution = "1.0.0"; bmad = "1.0.0"
+                    spec = "1.0.0"; plan = "1.0.0"; tasks = "1.0.0"
+                }
+                project = @{ name = "TODO"; domain = "general" }
+                settings = @{ autoConverge = $false; strictMode = $true; maxTaskHours = 2 }
+            }
+            $config | ConvertTo-Json | Set-Content ".sdd/config.json" -Encoding UTF8
+            Write-Host "[OK] SDD pipeline initialized." -ForegroundColor Green
+        }
+        Write-Host ""
+        Write-Host "Next: /sdd bmad <feature description>"
+    }
+
+    "bmad" {
+        if (-not $rest) {
+            Write-Host "Usage: /sdd bmad <description>" -ForegroundColor Red
+            Write-Host "Example: /sdd bmad landing page for my SaaS"
+            exit 1
+        }
+
+        $date = Get-Date -Format "yyyy-MM-dd"
+        $expiry = (Get-Date).AddDays(30).ToString("yyyy-MM-dd")
+
+        $brief = @"
+# BMAD Brief — [Project Name]
+
+> Generated: ${date}. Expires: ${expiry}.
+
+## Input
+> ${rest}
+
+## PM Perspective
+**Target user:** [Who benefits most from this feature]
+**User needs:** [Top 3 needs this feature addresses]
+**Primary conversion action:** [What user does that matters to business]
+
+## Architect Perspective
+**Minimum viable approach:** [One paragraph]
+**Technical risks:**
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [Risk 1] | [H/M/L] | [H/M/L] | [Mitigation] |
+
+## UX Perspective
+**First impression goal:** [Description]
+**Microcopy needed:** [List]
+
+## Synthesis
+**What we're building:** [2-3 sentences describing the feature]
+**What we're NOT building:** [Explicit exclusions]
+1. [Exclusion]
+
+## Open Questions
+| # | Question | Impact |
+|---|----------|--------|
+| 1 | [Question] | [Blocking?] |
+
+## Prompt Injection Check
+- Input was sanitized before processing
+- No system prompt overrides accepted
+"@
+
+        if (Test-Path "BMAD-brief.md") {
+            Write-Host "[WARN] BMAD-brief.md already exists — overwriting" -ForegroundColor Yellow
+        }
+        $brief | Set-Content "BMAD-brief.md" -Encoding UTF8
+        Write-Host "[OK] BMAD-brief.md created." -ForegroundColor Green
+        Write-Host ""
+        Write-Host "Next: /sdd spec"
+    }
+
+    "spec" {
+        if (-not (Test-Path "BMAD-brief.md")) {
+            Write-Host "[ERROR] BMAD-brief.md not found" -ForegroundColor Red
+            Write-Host "Run: /sdd bmad <description> first"
+            exit 1
+        }
+        if (-not (Test-Path "templates/SPEC.template.md")) {
+            Write-Host "[ERROR] templates/SPEC.template.md not found" -ForegroundColor Red
+            Write-Host "Run: /sdd init first"
+            exit 1
+        }
+
+        if (Test-Path ".sdd/config.json") {
+            $config = Get-Content ".sdd/config.json" | ConvertFrom-Json
+            $config.phases.current = 2
+            $config.phases.phase0.status = "completed"
+            $config.phases.phase0.completedAt = (Get-Date -Format "yyyy-MM-dd")
+            $config.phases.phase2.status = "in-progress"
+            $config | ConvertTo-Json | Set-Content ".sdd/config.json" -Encoding UTF8
+        }
+
+        Write-Host "[OK] Phase 0 gate passed." -ForegroundColor Green
+        Write-Host "Generate SPEC.md by expanding templates/SPEC.template.md"
+        Write-Host "using content from BMAD-brief.md."
+        Write-Host ""
+        Write-Host "The following sections are required:"
+        Write-Host "  1. Overview"
+        Write-Host "  2. User Stories (Must Have / Nice to Have)"
+        Write-Host "  3. Functional Requirements"
+        Write-Host "  4. Non-Functional Requirements"
+        Write-Host "  5. Technical Constraints"
+        Write-Host "  6. Open Questions"
+        Write-Host "  7. Success Criteria"
+    }
+
+    "tasks" {
+        if (-not (Test-Path "SPEC.md")) {
+            Write-Host "[ERROR] SPEC.md not found" -ForegroundColor Red
+            Write-Host "Run: /sdd spec first"
+            exit 1
+        }
+        if (-not (Test-Path "templates/TASKS.template.md")) {
+            Write-Host "[ERROR] templates/TASKS.template.md not found" -ForegroundColor Red
+            Write-Host "Run: /sdd init first"
+            exit 1
+        }
+
+        if (Test-Path ".sdd/config.json") {
+            $config = Get-Content ".sdd/config.json" | ConvertFrom-Json
+            $config.phases.current = 3
+            $config.phases.phase2.status = "completed"
+            $config.phases.phase2.completedAt = (Get-Date -Format "yyyy-MM-dd")
+            $config.phases.phase3.status = "in-progress"
+            $config | ConvertTo-Json | Set-Content ".sdd/config.json" -Encoding UTF8
+        }
+
+        Write-Host "[OK] Phase 2 gate passed." -ForegroundColor Green
+        Write-Host "Break SPEC.md into discrete tasks (T-001, T-002, ...)."
+        Write-Host "Each task must:"
+        Write-Host "  - Take <= 2 hours"
+        Write-Host "  - Be independently verifiable"
+        Write-Host "  - Have output artifact specified"
+    }
+
+    "status" {
+        if (-not (Test-Path ".sdd/config.json")) {
+            Write-Host "[ERROR] .sdd/config.json not found" -ForegroundColor Red
+            Write-Host "Run: /sdd init first"
+            exit 1
+        }
+
+        $config = Get-Content ".sdd/config.json" | ConvertFrom-Json
+        Write-Host "=== SDD Pipeline Status ===" -ForegroundColor Cyan
+        Write-Host "Project: $($config.project.name)"
+        Write-Host "Phase:  $($config.phases.current)"
+        Write-Host "Domain: $($config.project.domain)"
+        Write-Host ""
+
+        $phases = @("phase0","phase1","phase2","phase3","phase4","phase5")
+        foreach ($p in $phases) {
+            $phaseData = $config.phases.$p
+            $status = if ($phaseData.status) { $phaseData.status } else { "unknown" }
+            $icon = switch ($status) { "completed" { "[V]" } "in-progress" { "[>]" } default { "[ ]" } }
+            $color = switch ($status) { "completed" { "Green" } "in-progress" { "Yellow" } default { "Gray" } }
+            Write-Host "$icon $p : $status" -ForegroundColor $color
+        }
+
+        Write-Host ""
+        $next = $config.phases.current
+        $nextCmd = switch ($next) {
+            0 { "/sdd bmad <description>" }
+            2 { "/sdd spec" }
+            3 { "/sdd tasks" }
+            default { "All phases complete" }
+        }
+        Write-Host "Next: $nextCmd"
+    }
+
+    "converge" {
+        $required = @("SPEC.md", "PLAN.md", "TASKS.md")
+        $missing = $required | Where-Object { -not (Test-Path $_) }
+        if ($missing) {
+            Write-Host "[ERROR] Missing artifacts: $($missing -join ', ')" -ForegroundColor Red
+            Write-Host "Run: /sdd init && /sdd bmad <desc> && /sdd spec && /sdd tasks"
+            exit 1
+        }
+
+        Write-Host "[OK] All artifacts present." -ForegroundColor Green
+        Write-Host "Running converge validation..."
+        Write-Host ""
+        Write-Host "Run: pwsh run-converge.ps1 -Url 'http://localhost:3000' -Strict"
+    }
+
+    "help" {
+        Write-Help
+    }
+
+    default {
+        Write-Host "Unknown command: $cmd" -ForegroundColor Red
+        Write-Host ""
+        Write-Help
+        exit 1
+    }
+}

package/lib/config.js

@@ -0,0 +1,35 @@
+const fs = require('fs')
+const path = require('path')
+
+function read() {
+  const configPath = path.join(process.cwd(), '.sdd/config.json')
+  if (!fs.existsSync(configPath)) {
+    return null
+  }
+  return JSON.parse(fs.readFileSync(configPath, 'utf8'))
+}
+
+function printStatus() {
+  const config = read()
+  if (!config) {
+    console.error('ERROR: .sdd/config.json not found. Run: sdd init')
+    process.exit(1)
+  }
+
+  const phases = ['phase0', 'phase1', 'phase2', 'phase3', 'phase4', 'phase5']
+  console.log('=== SDD Pipeline Status ===')
+  console.log(`Project: ${config.project.name}`)
+  console.log(`Phase:  ${config.phases.current}`)
+  console.log(`Domain: ${config.project.domain}`)
+  console.log('')
+
+  for (const p of phases) {
+    const phaseData = config.phases[p]
+    const status = phaseData?.status || 'unknown'
+    const icon = status === 'completed' ? '[V]' : status === 'in-progress' ? '[>]' : '[ ]'
+    const color = status === 'completed' ? '32' : status === 'in-progress' ? '33' : '90'
+    console.log(`  \x1b[${color}m${icon} ${p}: ${status}\x1b[0m`)
+  }
+}
+
+module.exports = { read, printStatus }

package/lib/init.js

@@ -0,0 +1,126 @@
+const path = require('path')
+const fs = require('fs')
+
+const BUNDLE_DIR = path.join(__dirname, 'bundle')
+
+const FILES = [
+  '.sdd/config.json',
+  '.sdd/smoke-test.ps1',
+  '.sdd/tool-versions.json',
+  'templates/CONSTITUTION.template.md',
+  'templates/SPEC.template.md',
+  'templates/PLAN.template.md',
+  'templates/TASKS.template.md',
+  'templates/BMAD-brief.template.md',
+  'templates/README.md',
+  'converge/validation.md',
+  'CLAUDE.md',
+  'run-converge.ps1',
+]
+
+const DIRS = ['.sdd', 'templates', 'converge', 'commands', 'extensions']
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+function copyFile(src, dest) {
+  ensureDir(path.dirname(dest))
+  if (fs.existsSync(dest)) {
+    console.log(`  [SKIP] ${dest} already exists`)
+    return
+  }
+  const content = fs.readFileSync(src, 'utf8')
+  fs.writeFileSync(dest, content, 'utf8')
+  console.log(`  [COPY] ${dest}`)
+}
+
+function run() {
+  console.log('Initializing SDD pipeline...')
+  console.log('')
+
+  if (!fs.existsSync(BUNDLE_DIR)) {
+    console.error('ERROR: Bundle directory not found. Is the package installed correctly?')
+    process.exit(1)
+  }
+
+  for (const dir of DIRS) {
+    ensureDir(dir)
+  }
+
+  for (const file of FILES) {
+    const src = path.join(BUNDLE_DIR, file)
+    const dest = path.join(process.cwd(), file)
+    if (fs.existsSync(src)) {
+      copyFile(src, dest)
+    } else {
+      console.log(`  [WARN] ${src} not found in bundle`)
+    }
+  }
+
+  // Create .claude/commands/ with the command files
+  ensureDir('.claude/commands')
+  const cmdFiles = ['sdd-bmad.md', 'sdd-spec.md', 'sdd-tasks.md', 'sdd-converge.md', 'sdd-init.md']
+  for (const cmd of cmdFiles) {
+    const src = path.join(BUNDLE_DIR, '.claude/commands', cmd)
+    const dest = path.join(process.cwd(), '.claude/commands', cmd)
+    if (fs.existsSync(src)) {
+      copyFile(src, dest)
+    }
+  }
+
+  // Create .github/workflows/
+  ensureDir('.github/workflows')
+  const workflowSrc = path.join(BUNDLE_DIR, '.github/workflows/converge.yml')
+  const workflowDest = path.join(process.cwd(), '.github/workflows/converge.yml')
+  if (fs.existsSync(workflowSrc)) {
+    copyFile(workflowSrc, workflowDest)
+  }
+
+  // Create commands/sdd-status.ps1
+  ensureDir('commands')
+  const statusSrc = path.join(BUNDLE_DIR, 'commands/sdd-status.ps1')
+  const statusDest = path.join(process.cwd(), 'commands/sdd-status.ps1')
+  if (fs.existsSync(statusSrc)) {
+    copyFile(statusSrc, statusDest)
+  }
+
+  // Create extensions/
+  for (const ext of ['sdd-api', 'sdd-frontend', 'sdd-backend']) {
+    const extDir = path.join(BUNDLE_DIR, 'extensions', ext)
+    if (fs.existsSync(extDir)) {
+      copyDirRecursive(extDir, path.join(process.cwd(), 'extensions', ext))
+    }
+  }
+
+  // Copy extensions README
+  const extReadmeSrc = path.join(BUNDLE_DIR, 'extensions/README.md')
+  const extReadmeDest = path.join(process.cwd(), 'extensions/README.md')
+  if (fs.existsSync(extReadmeSrc)) {
+    copyFile(extReadmeSrc, extReadmeDest)
+  }
+
+  console.log('')
+  console.log('[OK] SDD pipeline initialized.')
+  console.log('')
+  console.log('Next: sdd bmad <your feature idea>')
+  console.log('Or:   claude "/sdd-bmad <feature>"')
+}
+
+function copyDirRecursive(src, dest) {
+  ensureDir(dest)
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath)
+    } else {
+      copyFile(srcPath, destPath)
+    }
+  }
+}
+
+module.exports = { run }

package/lib/sanitize.js

@@ -0,0 +1,10 @@
+// Prompt injection protection — sanitize user input before LLM embedding
+function sanitize(input) {
+  if (!input) return ''
+  return input
+    .replace(/ignore previous|disregard|system:|<script|<\/script>/gi, '[FILTERED]')
+    .replace(/ignore all previous instructions/gi, '[FILTERED]')
+    .trim()
+}
+
+module.exports = { run: sanitize }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "sdd-pipeline",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Spec-Driven Development pipeline for Claude Code",
-  "main": "bin/sdd.js",
   "bin": {
-    "sdd": "./bin/sdd.js"
+    "sdd": "bin/sdd.js"
   },
   "files": [
     "bin",
+    "lib",
     "lib/bundle"
   ],
   "engines": {