sdd-pipeline 1.0.2 → 1.2.0

package/lib/bmad/agents/ux.js

@@ -0,0 +1,103 @@
+/**
+ * BMAD UX Agent — UX Designer perspective
+ * Analyzes from a user experience, accessibility, and microcopy lens.
+ */
+
+/**
+ * @param {object} state - BMAD interview state
+ * @returns {{ section: string, confidence: string }}
+ */
+function analyze(state) {
+  const input = state.input || ''
+  const answers = state.answers || {}
+
+  // UX key questions: q7, q8, q9
+  const q7 = answers.q7 || ''
+  const q8 = answers.q8 || ''
+  const q9 = answers.q9 || ''
+
+  const firstImpression = q7 || inferFirstImpression(input)
+  const microcopy = parseMicrocopy(q8)
+  const errorStates = parseErrorStates(q9)
+
+  const section = `## UX Perspective
+**First impression goal:** ${firstImpression}
+
+**Essential microcopy:**
+${microcopy}
+
+**Error states to handle gracefully:**
+${errorStates}
+
+**Accessibility requirements:**
+- WCAG 2.1 AA compliance
+- Keyboard navigable
+- Screen reader labels on all interactive elements
+
+**Delight factors (if time allows):**
+- ${inferDelight(input)}
+`
+
+  const confidence = inferConfidence(q7, q8, q9)
+  return { section, confidence }
+}
+
+function inferFirstImpression(input) {
+  if (!input) return '[describe what the user sees and can do in the first 30 seconds]'
+  const lower = input.toLowerCase()
+  if (lower.includes('landing page')) return 'Professional, credible, immediately clear value proposition above the fold'
+  if (lower.includes('dashboard')) return 'Clean overview, key metric visible, clear navigation to primary action'
+  if (lower.includes('form')) return 'Clear field labels, visible submit button, no distraction from the task'
+  if (lower.includes('notification')) return 'Brief, actionable, dismissible without friction'
+  return `User sees: ${input.slice(0, 100)}. User can: [primary action]. No confusion about what to do next.`
+}
+
+function parseMicrocopy(q8) {
+  if (!q8 || q8.trim().length < 3) {
+    return '- [Button labels]\n- [Field labels]\n- [Error messages]\n- [Success messages]\n- [Empty state messages]'
+  }
+  const items = q8
+    .split(/[,;\n]/)
+    .filter((l) => l.trim())
+    .slice(0, 8)
+    .map((l) => `- ${l.trim()}`)
+  return items.length > 0 ? items.join('\n') : '- [from Q8]'
+}
+
+function parseErrorStates(q9) {
+  if (!q9 || q9.trim().length < 5) {
+    return '| Scenario | Behavior |\n|----------|---------|\n| Network failure | [retry with exponential backoff, user-friendly message] |\n| Empty data | [helpful empty state with clear CTA] |\n| Permission denied | [clear explanation + next action] |'
+  }
+  const lines = q9.split(/[,;\n]/).filter((l) => l.trim()).slice(0, 5)
+  if (lines.length === 0) {
+    return '| Scenario | Behavior |\n|----------|---------|\n| [Error scenario] | [How to handle it] |'
+  }
+  const rows = lines
+    .map((line) => {
+      const parts = line.split(/[-:]/).map((p) => p.trim())
+      return `| ${parts[0] || 'Scenario'} | ${parts.slice(1).join(': ') || 'Handle gracefully'} |`
+    })
+    .join('\n')
+  return `| Scenario | Behavior |\n|----------|---------|\n${rows}`
+}
+
+function inferDelight(input) {
+  const lower = (input || '').toLowerCase()
+  if (lower.includes('landing page') || lower.includes('marketing'))
+    return 'Subtle entrance animations, smooth scroll between sections, trust signals visible'
+  if (lower.includes('dashboard'))
+    return 'Real-time data updates, keyboard shortcuts for power users, customizable views'
+  if (lower.includes('form') || lower.includes('checkout'))
+    return 'Progress indicator, inline validation, satisfying submit confirmation'
+  return 'Consider: entrance animation, hover state feedback, success celebration moment'
+}
+
+function inferConfidence(q7, q8, q9) {
+  const filled = [q7, q8, q9].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/confidence.js

@@ -0,0 +1,129 @@
+/**
+ * BMAD Confidence Score Calculator
+ * Computes a 0-100 score from interview answers and user input.
+ * Thresholds: None <20 | Weak <40 | Medium <70 | Strong ≥70
+ */
+
+const THRESHOLDS = {
+  NONE: 20,
+  WEAK: 40,
+  MEDIUM: 70,
+  // Strong: ≥70
+}
+
+/**
+ * Calculate confidence score from interview state.
+ * @param {object} state - BMAD interview state
+ * @returns {{ score: number, level: string, factors: object }}
+ */
+function calculate(state) {
+  let score = 0
+  const factors = {}
+
+  // --- Factor 1: Input quality (0-30 points) ---
+  const inputLength = (state.input || '').trim().length
+  if (inputLength === 0) {
+    factors.input = { points: 0, note: 'No input provided' }
+  } else if (inputLength < 20) {
+    factors.input = { points: 5, note: 'Very brief input' }
+  } else if (inputLength < 80) {
+    factors.input = { points: 15, note: 'Brief input — interview fills gaps' }
+  } else if (inputLength < 300) {
+    factors.input = { points: 25, note: 'Good input detail' }
+  } else {
+    factors.input = { points: 30, note: 'Detailed input' }
+  }
+  score += factors.input.points
+
+  // --- Factor 2: Interview completion (0-30 points) ---
+  const totalQuestions = 9
+  const answeredCount = Object.keys(state.answers || {}).length
+  const completionRatio = answeredCount / totalQuestions
+
+  if (answeredCount === 0) {
+    factors.interview = { points: 0, note: 'No questions answered' }
+  } else if (completionRatio < 0.4) {
+    factors.interview = { points: 5, note: `${answeredCount}/${totalQuestions} answered` }
+  } else if (completionRatio < 0.7) {
+    factors.interview = { points: 15, note: `${answeredCount}/${totalQuestions} answered` }
+  } else if (completionRatio < 1) {
+    factors.interview = { points: 25, note: `${answeredCount}/${totalQuestions} answered` }
+  } else {
+    factors.interview = { points: 30, note: 'All 9 questions answered' }
+  }
+  score += factors.interview.points
+
+  // --- Factor 3: Problem clarity (0-20 points) ---
+  const problemAnswer = state.answers?.q1 || state.input || ''
+  const hasProblem = (problemAnswer || '').trim().length > 20
+  const problemSpecific =
+    /\d+%|\$\d+|\d+x/i.test(problemAnswer)
+
+  if (!hasProblem) {
+    factors.problemClarity = { points: 0, note: 'No problem statement' }
+  } else if (problemSpecific) {
+    factors.problemClarity = { points: 20, note: 'Specific, measurable problem' }
+  } else if (hasProblem) {
+    factors.problemClarity = { points: 10, note: 'Problem stated but generic' }
+  }
+  score += factors.problemClarity.points
+
+  // --- Factor 4: Technical awareness (0-20 points) ---
+  const techAnswer = state.answers?.q4 || ''
+  const techTerms = /database|api|frontend|backend|auth|sql|json|server|deploy/i.test(
+    techAnswer
+  )
+  const integrationAnswer = state.answers?.q5 || ''
+  const hasIntegration = integrationAnswer.trim().length > 10
+
+  if (!techAnswer && !integrationAnswer) {
+    factors.technicalAwareness = { points: 0, note: 'No technical detail' }
+  } else if (techTerms && hasIntegration) {
+    factors.technicalAwareness = { points: 20, note: 'Good technical awareness' }
+  } else if (techTerms || hasIntegration) {
+    factors.technicalAwareness = { points: 10, note: 'Some technical detail' }
+  } else {
+    factors.technicalAwareness = { points: 5, note: 'Minimal technical detail' }
+  }
+  score += factors.technicalAwareness.points
+
+  // Cap at 100
+  score = Math.min(100, Math.max(0, score))
+
+  // Determine level
+  let level
+  if (score < THRESHOLDS.NONE) {
+    level = 'None'
+  } else if (score < THRESHOLDS.WEAK) {
+    level = 'Weak'
+  } else if (score < THRESHOLDS.MEDIUM) {
+    level = 'Medium'
+  } else {
+    level = 'Strong'
+  }
+
+  return { score, level, factors }
+}
+
+function getLevel(score) {
+  if (score < THRESHOLDS.NONE) return 'None'
+  if (score < THRESHOLDS.WEAK) return 'Weak'
+  if (score < THRESHOLDS.MEDIUM) return 'Medium'
+  return 'Strong'
+}
+
+function canProceed(score) {
+  return score >= THRESHOLDS.NONE
+}
+
+function getWarning(score) {
+  if (score < THRESHOLDS.WEAK) {
+    return '⚠️ Confidence is Weak — consider answering more questions before proceeding.'
+  }
+  if (score < THRESHOLDS.MEDIUM) {
+    return '⚠️ Confidence is Medium — spec may need iteration during implementation.'
+  }
+  return ''
+}
+
+module.exports = { calculate, getLevel, canProceed, getWarning, THRESHOLDS }

package/lib/bmad/index.js

@@ -0,0 +1,140 @@
+/**
+ * BMAD Orchestrator — lib/bmad/index.js
+ * Main entry point for BMAD interactive system.
+ *
+ * Coordinates:
+ * - Problem-first inversion
+ * - 9-question interview framework
+ * - 3-agent synthesis (single-pass LLM mode)
+ * - Confidence scoring
+ * - BMAD-brief.md output
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const questions = require('./questions')
+const problemFirst = require('./problem-first')
+const synthesis = require('./synthesis')
+const confidenceCalc = require('./confidence')
+
+const OUTPUT_FILE = 'BMAD-brief.md'
+const TEMPLATE_DATE = new Date().toISOString().split('T')[0]
+const TEMPLATE_EXPIRY = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)
+  .toISOString()
+  .split('T')[0]
+
+// In-memory interview state (resumable)
+let state = {
+  input: '',
+  answers: {},
+  inversion: {},
+  startedAt: null,
+  currentTier: 0,
+}
+
+/**
+ * Initialize a new BMAD interview session.
+ * @param {string} rawInput - Raw user feature description
+ * @returns {{ sessionId: string, tier: number, questions: array, inversion: object }}
+ */
+function init(rawInput) {
+  state = {
+    input: rawInput.trim(),
+    answers: {},
+    inversion: problemFirst.invert(rawInput),
+    startedAt: new Date().toISOString(),
+    currentTier: 1,
+  }
+  return {
+    tier: 1,
+    inversion: state.inversion,
+    questions: questions.getAllQuestions().filter((q) => q.tier === 1),
+  }
+}
+
+/**
+ * Record an answer to a question.
+ * @param {string} questionId - e.g. 'q1'
+ * @param {string} answer - User's answer
+ */
+function answer(questionId, answer) {
+  state.answers[questionId] = answer
+}
+
+/**
+ * Get the current confidence score.
+ * @returns {{ score: number, level: string, factors: object }}
+ */
+function score() {
+  return confidenceCalc.calculate(state)
+}
+
+/**
+ * Check if the user can proceed to /sdd-spec.
+ * @returns {{ canProceed: boolean, level: string, message: string }}
+ */
+function canProceed() {
+  const c = confidenceCalc.calculate(state)
+  return {
+    canProceed: confidenceCalc.canProceed(c.score),
+    level: c.level,
+    score: c.score,
+    message: confidenceCalc.getWarning(c.score),
+  }
+}
+
+/**
+ * Generate the BMAD-brief.md file.
+ * @returns {{ filePath: string, confidence: object }}
+ */
+function generateBrief() {
+  const { brief, confidence } = synthesis.synthesize(state)
+
+  const header = `# BMAD Brief — [Project Name]
+
+> Generated: ${TEMPLATE_DATE}. Expires: ${TEMPLATE_EXPIRY}.
+> Confidence: **${confidence.score}/100** — ${confidence.level}
+
+## Input
+> ${state.input}
+`
+
+  const fullContent = header + brief
+
+  fs.writeFileSync(OUTPUT_FILE, fullContent, 'utf8')
+
+  return {
+    filePath: path.resolve(OUTPUT_FILE),
+    confidence,
+  }
+}
+
+/**
+ * Get current interview state (for resume/debug).
+ */
+function getState() {
+  return { ...state }
+}
+
+/**
+ * Get all questions with current answer status.
+ */
+function getQuestionsWithStatus() {
+  return questions.getAllQuestions().map((q) => ({
+    ...q,
+    answered: !!state.answers[q.id],
+    answer: state.answers[q.id] || null,
+  }))
+}
+
+module.exports = {
+  init,
+  answer,
+  score,
+  canProceed,
+  generateBrief,
+  getState,
+  getQuestionsWithStatus,
+  OUTPUT_FILE,
+}

package/lib/bmad/problem-first.js

@@ -0,0 +1,85 @@
+/**
+ * Problem-First Inversion
+ * Transforms a solution-first description into a problem-first brief.
+ * Rule: Always state the PROBLEM before describing the solution.
+ */
+
+/**
+ * Apply problem-first inversion to user input.
+ * @param {string} input - Raw user description (often solution-first)
+ * @returns {{ problem: string, solution: string, inversionNote: string }}
+ */
+function invert(input) {
+  // Common solution-first patterns to detect
+  const SOLUTION_PATTERNS = [
+    /\bbuild\b/i,
+    /\bcreate\b/i,
+    /\bimplement\b/i,
+    /\bmake\b/i,
+    /\bput\b/i,
+    /\badd\b/i,
+    /\blanding page\b/i,
+    /\bdashboard\b/i,
+    /\bfeature\b/i,
+    /\bfunctionality\b/i,
+    /\bbutton\b/i,
+    /\bform\b/i,
+    /\bapp\b/i,
+    /\bwebsite\b/i,
+  ]
+
+  const hasSolutionFocus = SOLUTION_PATTERNS.some((p) => p.test(input))
+
+  if (!hasSolutionFocus) {
+    return {
+      problem: input,
+      solution: '',
+      inversionNote: 'Input already problem-focused.',
+    }
+  }
+
+  // Extract what they think they want (the solution)
+  const solutionFragment = input
+
+  // Infer the likely problem (best effort heuristic)
+  const problem = inferProblem(input)
+
+  return {
+    problem,
+    solution: solutionFragment,
+    inversionNote:
+      '⚠️ INVERSION APPLIED: Your request described a solution. The problem it addresses is stated first above.',
+  }
+}
+
+/**
+ * Best-effort problem inference from solution-first input.
+ * This is heuristic — the user corrects it during the interview.
+ */
+function inferProblem(input) {
+  const lower = input.toLowerCase()
+
+  if (lower.includes('landing page')) {
+    return 'Users are not converting or not finding us credible — we need a way to communicate value and capture interest quickly.'
+  }
+  if (lower.includes('dashboard')) {
+    return 'Users lack visibility into key metrics or workflows — decisions are made blind or based on incomplete data.'
+  }
+  if (lower.includes('login') || lower.includes('auth')) {
+    return 'Users cannot securely access their accounts or data — engagement and retention are blocked.'
+  }
+  if (lower.includes('notification') || lower.includes('email')) {
+    return 'Users are missing important information or actions — engagement and retention suffer.'
+  }
+  if (lower.includes('search')) {
+    return 'Users cannot find what they need — they leave frustrated or submit support requests.'
+  }
+  if (lower.includes('export') || lower.includes('report')) {
+    return 'Users cannot act on their data — business decisions are slowed or made without full information.'
+  }
+
+  // Generic fallback
+  return 'Users face a friction point that prevents them from completing their goal — specific symptoms and impact are being confirmed in the interview.'
+}
+
+module.exports = { invert }

package/lib/bmad/questions.js

@@ -0,0 +1,110 @@
+/**
+ * BMAD 9-Question Framework
+ * Tier 1 (3) → Tier 2 (3) → Tier 3 (3) = 9 questions total
+ */
+
+const TIERS = {
+  TIER1: {
+    name: 'Problem Definition',
+    questions: [
+      {
+        id: 'q1',
+        tier: 1,
+        question: 'What specific problem does this solve for the user?',
+        hint: 'Be specific — not "improve UX" but "reduce checkout abandonment by 40%"',
+        perspective: 'pm',
+      },
+      {
+        id: 'q2',
+        tier: 1,
+        question: 'Who is the target user, and what is their current workaround?',
+        hint: 'Describe the person and what they do today without this feature',
+        perspective: 'pm',
+      },
+      {
+        id: 'q3',
+        tier: 1,
+        question: 'What does success look like in 90 days? (measurable outcome)',
+        hint: 'Specific metric: "X% conversion", "N fewer support tickets", "$Y revenue"',
+        perspective: 'pm',
+      },
+    ],
+  },
+  TIER2: {
+    name: 'Technical & Feasibility',
+    questions: [
+      {
+        id: 'q4',
+        tier: 2,
+        question: 'What is the minimum viable version of this — one paragraph?',
+        hint: 'Strip everything optional. What remains is the core?',
+        perspective: 'architect',
+      },
+      {
+        id: 'q5',
+        tier: 2,
+        question: 'What existing systems or data does this need to connect to?',
+        hint: 'List integrations, APIs, databases, or services required',
+        perspective: 'architect',
+      },
+      {
+        id: 'q6',
+        tier: 2,
+        question: 'What are the top 2 technical risks, and how do we mitigate them?',
+        hint: 'Think: data loss, downtime, security, scale, third-party dependency',
+        perspective: 'architect',
+      },
+    ],
+  },
+  TIER3: {
+    name: 'UX & Polish',
+    questions: [
+      {
+        id: 'q7',
+        tier: 3,
+        question: 'What is the first thing the user sees and does? (first impression)',
+        hint: 'Describe the screen — what appears, what can they click?',
+        perspective: 'ux',
+      },
+      {
+        id: 'q8',
+        tier: 3,
+        question: 'What microcopy is essential? (labels, buttons, errors, empty states)',
+        hint: 'List specific phrases that must appear in the UI',
+        perspective: 'ux',
+      },
+      {
+        id: 'q9',
+        tier: 3,
+        question: 'What could go wrong that we need to handle gracefully?',
+        hint: 'Network failure, empty data, permission denied, slow loading',
+        perspective: 'ux',
+      },
+    ],
+  },
+}
+
+function getAllQuestions() {
+  return [
+    ...TIERS.TIER1.questions,
+    ...TIERS.TIER2.questions,
+    ...TIERS.TIER3.questions,
+  ]
+}
+
+function getQuestionById(id) {
+  for (const tier of Object.values(TIERS)) {
+    const found = tier.questions.find((q) => q.id === id)
+    if (found) return found
+  }
+  return null
+}
+
+function getQuestionsByTier(tier) {
+  for (const t of Object.values(TIERS)) {
+    if (t.questions[0]?.tier === tier) return t.questions
+  }
+  return []
+}
+
+module.exports = { TIERS, getAllQuestions, getQuestionById, getQuestionsByTier }

package/lib/bmad/synthesis.js

@@ -0,0 +1,109 @@
+/**
+ * BMAD Synthesis — merges three agent perspectives into a unified brief.
+ * Uses single-pass LLM synthesis mode (Claude Code analyzes all 3 perspectives).
+ */
+
+const pmAgent = require('./agents/pm')
+const architectAgent = require('./agents/architect')
+const uxAgent = require('./agents/ux')
+const confidenceCalc = require('./confidence')
+
+/**
+ * Synthesize a full BMAD brief from interview state.
+ * @param {object} state - { input, answers, inversion }
+ * @returns {{ brief: string, confidence: object }}
+ */
+function synthesize(state) {
+  // Run all three agents in parallel (synchronous in Node.js — single pass)
+  const pmResult = pmAgent.analyze(state)
+  const architectResult = architectAgent.analyze(state)
+  const uxResult = uxAgent.analyze(state)
+
+  // Calculate confidence
+  const confidence = confidenceCalc.calculate(state)
+
+  // Build problem-first note if inversion was applied
+  const inversionBlock = state.inversion?.inversionNote
+    ? `\n## ⚠️ Problem-First Inversion Applied\n${state.inversion.inversionNote}\n`
+    : ''
+
+  const synthesis = `${inversionBlock}
+## Synthesis
+
+**What we're building:** ${synthesizeWhat(state)}
+
+**What we're NOT building:** ${synthesizeNotBuilding(state)}
+
+## Open Questions
+| # | Question | Impact |
+|---|----------|--------|
+| 1 | [Open question from interview] | [Blocking?] |
+| 2 | [Another unresolved item] | [Clarify before implementation] |
+`
+
+  // Concatenate all sections
+  const brief = `${pmResult.section}
+
+${architectResult.section}
+
+${uxResult.section}
+
+${synthesis}
+
+## Confidence Score
+**Score:** ${confidence.score}/100 — ${confidence.level}
+${confidenceCalc.getWarning(confidence.score)}
+
+_Scoring breakdown:_
+${formatFactors(confidence.factors)}
+
+## Prompt Injection Check
+- Input was sanitized before processing
+- No system prompt overrides accepted
+`
+
+  return { brief, confidence }
+}
+
+function synthesizeWhat(state) {
+  const input = state.input || ''
+  const problem = state.inversion?.problem || input
+  const q1 = state.answers?.q1 || ''
+  const q4 = state.answers?.q4 || ''
+
+  const problemStatement = q1 || problem
+  const approach = q4
+    ? q4.split('.')[0] + '.'
+    : `Build the feature described as: ${input.slice(0, 80)}`
+
+  return `${problemStatement}. ${approach}`
+}
+
+function synthesizeNotBuilding(state) {
+  const exclusions = [
+    'Second-order features — ship core first, add polish in v2',
+    'Nice-to-have integrations — MVP ships with zero mandatory external dependencies',
+    'Re-architecture of existing systems — integrate within current constraints',
+  ]
+
+  // Extract explicit exclusions from Q9 or other answers
+  const q9 = state.answers?.q9 || ''
+  if (q9.length > 0) {
+    const dynamic = q9
+      .split(/[,;\n]/)
+      .filter((l) => l.toLowerCase().includes('not ') || l.toLowerCase().includes("won't "))
+      .slice(0, 2)
+      .map((l) => l.trim())
+    exclusions.unshift(...dynamic)
+  }
+
+  return exclusions.map((e, i) => `${i + 1}. ${e}`).join('\n')
+}
+
+function formatFactors(factors) {
+  return Object.entries(factors)
+    .map(([key, val]) => `  - **${key}:** ${val.points} pts — ${val.note}`)
+    .join('\n')
+}
+
+module.exports = { synthesize }