substrate-ai 0.1.21 → 0.1.23

package/dist/index.d.ts

@@ -231,6 +231,68 @@ interface StoryStallEvent {
   /** Milliseconds since the last progress event */
   elapsed_ms: number;
 }
+/**
+ * Emitted when the supervisor kills a stalled pipeline process tree.
+ */
+interface SupervisorKillEvent {
+  type: 'supervisor:kill';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Pipeline run ID that was killed */
+  run_id: string | null;
+  /** Reason for the kill — always 'stall' for threshold-triggered kills */
+  reason: 'stall';
+  /** Seconds the pipeline had been stalled */
+  staleness_seconds: number;
+  /** PIDs that were killed (orchestrator + child processes) */
+  pids: number[];
+}
+/**
+ * Emitted when the supervisor restarts a killed pipeline.
+ */
+interface SupervisorRestartEvent {
+  type: 'supervisor:restart';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Pipeline run ID being resumed */
+  run_id: string | null;
+  /** Restart attempt number (1-based) */
+  attempt: number;
+}
+/**
+ * Emitted when the supervisor exceeds the maximum restart limit and aborts.
+ */
+interface SupervisorAbortEvent {
+  type: 'supervisor:abort';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Pipeline run ID that was abandoned */
+  run_id: string | null;
+  /** Reason for aborting */
+  reason: 'max_restarts_exceeded';
+  /** Number of restart attempts that were made */
+  attempts: number;
+}
+/**
+ * Emitted when the supervisor detects a terminal pipeline state and exits.
+ */
+interface SupervisorSummaryEvent {
+  type: 'supervisor:summary';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Pipeline run ID */
+  run_id: string | null;
+  /** Total elapsed seconds from supervisor start to terminal state */
+  elapsed_seconds: number;
+  /** Story keys that completed successfully */
+  succeeded: string[];
+  /** Story keys that failed (non-COMPLETE, non-PENDING phases) */
+  failed: string[];
+  /** Story keys that were escalated */
+  escalated: string[];
+  /** Number of restart cycles performed by the supervisor */
+  restarts: number;
+}
 /**
  * Discriminated union of all pipeline event types.
  *
@@ -243,7 +305,7 @@ interface StoryStallEvent {
  * }
  * ```
  */
-type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent; //#endregion
+type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent | SupervisorKillEvent | SupervisorRestartEvent | SupervisorAbortEvent | SupervisorSummaryEvent; //#endregion
 //#region src/core/errors.d.ts
 
 /**
@@ -841,6 +903,26 @@ interface OrchestratorEvents {
     phase: string;
     elapsedMs: number;
   };
+  /** Readiness check has completed — emitted for all verdicts (READY, NEEDS_WORK, NOT_READY) */
+  'solutioning:readiness-check': {
+    runId: string;
+    verdict: 'READY' | 'NEEDS_WORK' | 'NOT_READY';
+    coverageScore: number;
+    findingCount: number;
+    blockerCount: number;
+  };
+  /** Readiness check returned NOT_READY — solutioning phase will not proceed to implementation */
+  'solutioning:readiness-failed': {
+    runId: string;
+    verdict: 'NOT_READY';
+    coverageScore: number;
+    findings: Array<{
+      category: string;
+      severity: string;
+      description: string;
+      affected_items: string[];
+    }>;
+  };
 }
 
 //#endregion

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AdapterRegistry, AdtError, BudgetExceededError, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, GeminiCLIAdapter, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError, childLogger, computeChangedKeys, createConfigWatcher, createDatabaseService, createEventBus, createGitWorktreeManager, createLogger, createMonitorAgent, createMonitorDatabase, createRoutingEngine, createTaskGraphEngine, createTuiApp, createWorkerPoolManager, isTuiCapable, logger, printNonTtyWarning } from "./app-Bltq6BEm.js";
+import { AdapterRegistry, AdtError, BudgetExceededError, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, GeminiCLIAdapter, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError, childLogger, computeChangedKeys, createConfigWatcher, createDatabaseService, createEventBus, createGitWorktreeManager, createLogger, createMonitorAgent, createMonitorDatabase, createRoutingEngine, createTaskGraphEngine, createTuiApp, createWorkerPoolManager, isTuiCapable, logger, printNonTtyWarning } from "./app-CY3MaJtP.js";
 import "./config-schema-C9tTMcm1.js";
 import { join } from "node:path";
 import { randomUUID } from "crypto";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -64,7 +64,7 @@
     "js-yaml": "^4.1.1",
     "pino": "^9.6.0",
     "semver": "^7.6.3",
-    "substrate-ai": "^0.1.19",
+    "substrate-ai": "^0.1.22",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/packs/bmad/data/elicitation-methods.csv

@@ -0,0 +1,51 @@
+num,category,method_name,description,output_pattern
+1,collaboration,Stakeholder Round Table,Convene multiple personas to contribute diverse perspectives - essential for requirements gathering and finding balanced solutions across competing interests,perspectives → synthesis → alignment
+2,collaboration,Expert Panel Review,Assemble domain experts for deep specialized analysis - ideal when technical depth and peer review quality are needed,expert views → consensus → recommendations
+3,collaboration,Debate Club Showdown,Two personas argue opposing positions while a moderator scores points - great for exploring controversial decisions and finding middle ground,thesis → antithesis → synthesis
+4,collaboration,User Persona Focus Group,Gather your product's user personas to react to proposals and share frustrations - essential for validating features and discovering unmet needs,reactions → concerns → priorities
+5,collaboration,Time Traveler Council,Past-you and future-you advise present-you on decisions - powerful for gaining perspective on long-term consequences vs short-term pressures,past wisdom → present choice → future impact
+6,collaboration,Cross-Functional War Room,Product manager + engineer + designer tackle a problem together - reveals trade-offs between feasibility desirability and viability,constraints → trade-offs → balanced solution
+7,collaboration,Mentor and Apprentice,Senior expert teaches junior while junior asks naive questions - surfaces hidden assumptions through teaching,explanation → questions → deeper understanding
+8,collaboration,Good Cop Bad Cop,Supportive persona and critical persona alternate - finds both strengths to build on and weaknesses to address,encouragement → criticism → balanced view
+9,collaboration,Improv Yes-And,Multiple personas build on each other's ideas without blocking - generates unexpected creative directions through collaborative building,idea → build → build → surprising result
+10,collaboration,Customer Support Theater,Angry customer and support rep roleplay to find pain points - reveals real user frustrations and service gaps,complaint → investigation → resolution → prevention
+11,advanced,Tree of Thoughts,Explore multiple reasoning paths simultaneously then evaluate and select the best - perfect for complex problems with multiple valid approaches,paths → evaluation → selection
+12,advanced,Graph of Thoughts,Model reasoning as an interconnected network of ideas to reveal hidden relationships - ideal for systems thinking and discovering emergent patterns,nodes → connections → patterns
+13,advanced,Thread of Thought,Maintain coherent reasoning across long contexts by weaving a continuous narrative thread - essential for RAG systems and maintaining consistency,context → thread → synthesis
+14,advanced,Self-Consistency Validation,Generate multiple independent approaches then compare for consistency - crucial for high-stakes decisions where verification matters,approaches → comparison → consensus
+15,advanced,Meta-Prompting Analysis,Step back to analyze the approach structure and methodology itself - valuable for optimizing prompts and improving problem-solving,current → analysis → optimization
+16,advanced,Reasoning via Planning,Build a reasoning tree guided by world models and goal states - excellent for strategic planning and sequential decision-making,model → planning → strategy
+17,competitive,Red Team vs Blue Team,Adversarial attack-defend analysis to find vulnerabilities - critical for security testing and building robust solutions,defense → attack → hardening
+18,competitive,Shark Tank Pitch,Entrepreneur pitches to skeptical investors who poke holes - stress-tests business viability and forces clarity on value proposition,pitch → challenges → refinement
+19,competitive,Code Review Gauntlet,Senior devs with different philosophies review the same code - surfaces style debates and finds consensus on best practices,reviews → debates → standards
+20,technical,Architecture Decision Records,Multiple architect personas propose and debate architectural choices with explicit trade-offs - ensures decisions are well-reasoned and documented,options → trade-offs → decision → rationale
+21,technical,Rubber Duck Debugging Evolved,Explain your code to progressively more technical ducks until you find the bug - forces clarity at multiple abstraction levels,simple → detailed → technical → aha
+22,technical,Algorithm Olympics,Multiple approaches compete on the same problem with benchmarks - finds optimal solution through direct comparison,implementations → benchmarks → winner
+23,technical,Security Audit Personas,Hacker + defender + auditor examine system from different threat models - comprehensive security review from multiple angles,vulnerabilities → defenses → compliance
+24,technical,Performance Profiler Panel,Database expert + frontend specialist + DevOps engineer diagnose slowness - finds bottlenecks across the full stack,symptoms → analysis → optimizations
+25,creative,SCAMPER Method,Apply seven creativity lenses (Substitute/Combine/Adapt/Modify/Put/Eliminate/Reverse) - systematic ideation for product innovation,S→C→A→M→P→E→R
+26,creative,Reverse Engineering,Work backwards from desired outcome to find implementation path - powerful for goal achievement and understanding endpoints,end state → steps backward → path forward
+27,creative,What If Scenarios,Explore alternative realities to understand possibilities and implications - valuable for contingency planning and exploration,scenarios → implications → insights
+28,creative,Random Input Stimulus,Inject unrelated concepts to spark unexpected connections - breaks creative blocks through forced lateral thinking,random word → associations → novel ideas
+29,creative,Exquisite Corpse Brainstorm,Each persona adds to the idea seeing only the previous contribution - generates surprising combinations through constrained collaboration,contribution → handoff → contribution → surprise
+30,creative,Genre Mashup,Combine two unrelated domains to find fresh approaches - innovation through unexpected cross-pollination,domain A + domain B → hybrid insights
+31,research,Literature Review Personas,Optimist researcher + skeptic researcher + synthesizer review sources - balanced assessment of evidence quality,sources → critiques → synthesis
+32,research,Thesis Defense Simulation,Student defends hypothesis against committee with different concerns - stress-tests research methodology and conclusions,thesis → challenges → defense → refinements
+33,research,Comparative Analysis Matrix,Multiple analysts evaluate options against weighted criteria - structured decision-making with explicit scoring,options → criteria → scores → recommendation
+34,risk,Pre-mortem Analysis,Imagine future failure then work backwards to prevent it - powerful technique for risk mitigation before major launches,failure scenario → causes → prevention
+35,risk,Failure Mode Analysis,Systematically explore how each component could fail - critical for reliability engineering and safety-critical systems,components → failures → prevention
+36,risk,Challenge from Critical Perspective,Play devil's advocate to stress-test ideas and find weaknesses - essential for overcoming groupthink,assumptions → challenges → strengthening
+37,risk,Identify Potential Risks,Brainstorm what could go wrong across all categories - fundamental for project planning and deployment preparation,categories → risks → mitigations
+38,risk,Chaos Monkey Scenarios,Deliberately break things to test resilience and recovery - ensures systems handle failures gracefully,break → observe → harden
+39,core,First Principles Analysis,Strip away assumptions to rebuild from fundamental truths - breakthrough technique for innovation and solving impossible problems,assumptions → truths → new approach
+40,core,5 Whys Deep Dive,Repeatedly ask why to drill down to root causes - simple but powerful for understanding failures,why chain → root cause → solution
+41,core,Socratic Questioning,Use targeted questions to reveal hidden assumptions and guide discovery - excellent for teaching and self-discovery,questions → revelations → understanding
+42,core,Critique and Refine,Systematic review to identify strengths and weaknesses then improve - standard quality check for drafts,strengths/weaknesses → improvements → refined
+43,core,Explain Reasoning,Walk through step-by-step thinking to show how conclusions were reached - crucial for transparency,steps → logic → conclusion
+44,core,Expand or Contract for Audience,Dynamically adjust detail level and technical depth for target audience - matches content to reader capabilities,audience → adjustments → refined content
+45,learning,Feynman Technique,Explain complex concepts simply as if teaching a child - the ultimate test of true understanding,complex → simple → gaps → mastery
+46,learning,Active Recall Testing,Test understanding without references to verify true knowledge - essential for identifying gaps,test → gaps → reinforcement
+47,philosophical,Occam's Razor Application,Find the simplest sufficient explanation by eliminating unnecessary complexity - essential for debugging,options → simplification → selection
+48,philosophical,Trolley Problem Variations,Explore ethical trade-offs through moral dilemmas - valuable for understanding values and difficult decisions,dilemma → analysis → decision
+49,retrospective,Hindsight Reflection,Imagine looking back from the future to gain perspective - powerful for project reviews,future view → insights → application
+50,retrospective,Lessons Learned Extraction,Systematically identify key takeaways and actionable improvements - essential for continuous improvement,experience → lessons → actions

package/packs/bmad/manifest.yaml

@@ -2,22 +2,149 @@ name: bmad
 version: 1.0.0
 description: BMAD methodology for autonomous software development
 
+# Optional UX design phase (Story 16.5).
+# When true, a 'ux-design' phase runs between planning and solutioning.
+# Set to false (or omit) to skip UX design and proceed directly to solutioning.
+uxDesign: true
+
 phases:
   - name: analysis
     description: Product discovery and brief creation
     entryGates: []
     exitGates: [product-brief-complete]
     artifacts: [product-brief]
+    steps:
+      - name: analysis-step-1-vision
+        template: analysis-step-1-vision
+        context:
+          - placeholder: concept
+            source: "param:concept"
+        elicitate: true
+      - name: analysis-step-2-scope
+        template: analysis-step-2-scope
+        context:
+          - placeholder: concept
+            source: "param:concept"
+          - placeholder: vision_output
+            source: "step:analysis-step-1-vision"
+        critique: true
   - name: planning
     description: PRD and requirements generation
     entryGates: [product-brief-complete]
     exitGates: [prd-complete]
     artifacts: [prd]
+    steps:
+      - name: planning-step-1-classification
+        template: planning-step-1-classification
+        context:
+          - placeholder: product_brief
+            source: "decision:analysis.product-brief"
+      - name: planning-step-2-frs
+        template: planning-step-2-frs
+        context:
+          - placeholder: product_brief
+            source: "decision:analysis.product-brief"
+          - placeholder: classification
+            source: "step:planning-step-1-classification"
+        elicitate: true
+      - name: planning-step-3-nfrs
+        template: planning-step-3-nfrs
+        context:
+          - placeholder: product_brief
+            source: "decision:analysis.product-brief"
+          - placeholder: classification
+            source: "step:planning-step-1-classification"
+          - placeholder: functional_requirements
+            source: "step:planning-step-2-frs"
+        critique: true
+  - name: ux-design
+    description: UX discovery, design system, and user journey mapping (optional — runs when uxDesign is true)
+    entryGates: [prd-complete]
+    exitGates: [ux-design-complete]
+    artifacts: [ux-design]
+    steps:
+      - name: ux-step-1-discovery
+        template: ux-step-1-discovery
+        context:
+          - placeholder: product_brief
+            source: "decision:analysis.product-brief"
+          - placeholder: requirements
+            source: "decision:planning.functional-requirements"
+        elicitate: true
+      - name: ux-step-2-design-system
+        template: ux-step-2-design-system
+        context:
+          - placeholder: product_brief
+            source: "decision:analysis.product-brief"
+          - placeholder: requirements
+            source: "decision:planning.functional-requirements"
+          - placeholder: ux_discovery
+            source: "step:ux-step-1-discovery"
+        elicitate: true
+      - name: ux-step-3-journeys
+        template: ux-step-3-journeys
+        context:
+          - placeholder: product_brief
+            source: "decision:analysis.product-brief"
+          - placeholder: requirements
+            source: "decision:planning.functional-requirements"
+          - placeholder: ux_discovery
+            source: "step:ux-step-1-discovery"
+          - placeholder: design_system
+            source: "step:ux-step-2-design-system"
+        critique: true
   - name: solutioning
     description: Architecture and epic/story breakdown
     entryGates: [prd-complete]
     exitGates: [architecture-complete, stories-complete, readiness-check]
     artifacts: [architecture, epics, stories]
+    steps:
+      - name: architecture-step-1-context
+        template: architecture-step-1-context
+        context:
+          - placeholder: requirements
+            source: "decision:planning.functional-requirements"
+          - placeholder: nfr
+            source: "decision:planning.non-functional-requirements"
+        outputCategory: architecture
+      - name: architecture-step-2-decisions
+        template: architecture-step-2-decisions
+        context:
+          - placeholder: requirements
+            source: "decision:planning.functional-requirements"
+          - placeholder: starter_decisions
+            source: "step:architecture-step-1-context"
+          - placeholder: ux_decisions
+            source: "decision:ux-design.ux-design"
+        outputCategory: architecture
+        elicitate: true
+      - name: architecture-step-3-patterns
+        template: architecture-step-3-patterns
+        context:
+          - placeholder: architecture_decisions
+            source: "decision:solutioning.architecture"
+        outputCategory: architecture
+        critique: true
+      - name: stories-step-1-epics
+        template: stories-step-1-epics
+        context:
+          - placeholder: requirements
+            source: "decision:planning.functional-requirements"
+          - placeholder: architecture_decisions
+            source: "decision:solutioning.architecture"
+        outputCategory: epic-design
+        elicitate: true
+      - name: stories-step-2-stories
+        template: stories-step-2-stories
+        context:
+          - placeholder: epic_structure
+            source: "step:stories-step-1-epics"
+          - placeholder: requirements
+            source: "decision:planning.functional-requirements"
+          - placeholder: architecture_decisions
+            source: "decision:solutioning.architecture"
+        outputCategory: stories
+        critique: true
   - name: implementation
     description: Code generation, testing, and review
     entryGates: [stories-complete]
@@ -33,6 +160,31 @@ prompts:
   dev-story: prompts/dev-story.md
   code-review: prompts/code-review.md
   fix-story: prompts/fix-story.md
+  # Multi-step phase decomposition prompts
+  analysis-step-1-vision: prompts/analysis-step-1-vision.md
+  analysis-step-2-scope: prompts/analysis-step-2-scope.md
+  planning-step-1-classification: prompts/planning-step-1-classification.md
+  planning-step-2-frs: prompts/planning-step-2-frs.md
+  planning-step-3-nfrs: prompts/planning-step-3-nfrs.md
+  architecture-step-1-context: prompts/architecture-step-1-context.md
+  architecture-step-2-decisions: prompts/architecture-step-2-decisions.md
+  architecture-step-3-patterns: prompts/architecture-step-3-patterns.md
+  stories-step-1-epics: prompts/stories-step-1-epics.md
+  stories-step-2-stories: prompts/stories-step-2-stories.md
+  # UX design step prompts (Story 16-5)
+  ux-step-1-discovery: prompts/ux-step-1-discovery.md
+  ux-step-2-design-system: prompts/ux-step-2-design-system.md
+  ux-step-3-journeys: prompts/ux-step-3-journeys.md
+  # Elicitation prompt (Story 16-3)
+  elicitation-apply: prompts/elicitation-apply.md
+  # Critique and refinement prompts (Story 16-4)
+  critique-analysis: prompts/critique-analysis.md
+  critique-planning: prompts/critique-planning.md
+  critique-architecture: prompts/critique-architecture.md
+  critique-stories: prompts/critique-stories.md
+  refine-artifact: prompts/refine-artifact.md
+  # Readiness check prompt (Story 16-6)
+  readiness-check: prompts/readiness-check.md
 
 constraints:
   create-story: constraints/create-story.yaml

package/packs/bmad/prompts/analysis-step-1-vision.md

@@ -0,0 +1,51 @@
+# BMAD Analysis Step 1: Vision & Problem Analysis
+
+## Context (pre-assembled by pipeline)
+
+### Project Concept
+{{concept}}
+
+---
+
+## Mission
+
+Analyze the project concept above and produce a focused **vision analysis**: a clear problem statement and identification of target users. Do NOT define features or metrics yet — those come in a subsequent step.
+
+## Instructions
+
+1. **Analyze the concept deeply:**
+   - What problem does this solve? Who experiences this problem most acutely?
+   - What existing solutions exist? Why do they fall short?
+   - What would make this succeed vs. fail?
+
+2. **Generate a research-grade problem statement:**
+   - A clear, specific articulation of the problem (minimum 2-3 sentences)
+   - Ground it in user pain, not technology
+   - Include the impact of the problem remaining unsolved
+
+3. **Identify target users:**
+   - Specific user segments (not generic labels)
+   - Include role, context, and why they care
+   - Minimum 2 distinct segments
+
+4. **Quality bar**: Every field should contain enough detail that a product manager could begin scoping from this analysis alone.
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text.
+
+**CRITICAL**: All array items MUST be plain strings, NOT objects/maps.
+
+```yaml
+result: success
+problem_statement: "A clear articulation of the problem in 2-3 sentences."
+target_users:
+  - "Software developers who work in terminal environments and want habit tracking"
+  - "DevOps engineers who need to maintain daily operational checklists"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/analysis-step-2-scope.md

@@ -0,0 +1,59 @@
+# BMAD Analysis Step 2: Scope & Features
+
+## Context (pre-assembled by pipeline)
+
+### Project Concept
+{{concept}}
+
+### Vision Analysis (from Step 1)
+{{vision_output}}
+
+---
+
+## Mission
+
+Building on the vision analysis above, define the **scope**: core features, success metrics, and constraints. The problem statement and target users are already established — now determine WHAT to build and HOW to measure success.
+
+## Instructions
+
+1. **Define core features** that directly address the problem statement:
+   - Each feature should be a concrete capability, not a vague category
+   - Prioritize by user impact — list the most critical features first
+   - Ensure features serve the identified target users
+
+2. **Define measurable success metrics:**
+   - Tied to user value and business objectives
+   - Include both leading indicators (engagement, adoption) and lagging indicators (retention, revenue)
+   - Be specific enough to measure
+
+3. **Identify constraints:**
+   - Technical limitations, regulatory requirements, budget boundaries
+   - Timeline pressures, platform restrictions, or integration requirements
+   - Omit if genuinely none exist
+
+4. **Quality bar**: A product manager should be able to write a PRD from the combined vision + scope output.
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text.
+
+**CRITICAL**: All array items MUST be plain strings, NOT objects/maps.
+
+```yaml
+result: success
+core_features:
+  - "CLI command to register, check-off, and view daily habits with streak tracking"
+  - "Local SQLite storage with export to JSON/CSV for portability"
+success_metrics:
+  - "Daily active usage rate >60% among onboarded users within 30 days"
+  - "Streak completion rate >40% across all tracked habits"
+constraints:
+  - "CLI-only interface limits audience to terminal-comfortable users"
+  - "Must work offline with local storage, no cloud dependency"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/architecture-step-1-context.md

@@ -0,0 +1,69 @@
+# BMAD Architecture Step 1: Context Analysis
+
+## Context (pre-assembled by pipeline)
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### Non-Functional Requirements
+{{nfr}}
+
+---
+
+## Mission
+
+Analyze the requirements context and produce **initial architecture decisions** focused on the foundational technology choices: system architecture style, API design, data storage, and project structure. Think like a pragmatic senior architect — choose boring technology that ships.
+
+## Instructions
+
+1. **Make concrete decisions, not suggestions:**
+   - Each decision is a key-value pair capturing one architectural concern
+   - The `key` identifies WHAT is being decided
+   - The `value` states the CHOICE
+   - The `rationale` explains WHY this choice over alternatives
+
+2. **Focus on foundational decisions:**
+   - **System architecture**: Monolith, modular monolith, microservices, or serverless
+   - **API design**: REST, GraphQL, gRPC, or hybrid
+   - **Data storage**: Database engine, schema strategy, migration approach
+   - **Project structure**: Directory layout, module boundaries, dependency rules
+
+3. **Align with requirements:**
+   - Every `must` functional requirement should be architecturally supportable
+   - NFRs should directly inform decisions
+   - Tech stack choices from planning should be respected
+
+4. **Use the `category` field** to group related decisions:
+   - `infrastructure`: deployment, hosting, CI/CD
+   - `backend`: API, database, auth, services
+   - `frontend`: UI framework, state, routing
+   - `crosscutting`: logging, error handling, testing, security
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text.
+
+**CRITICAL**: All string values MUST be quoted with double quotes.
+
+```yaml
+result: success
+architecture_decisions:
+  - category: "backend"
+    key: "system-architecture"
+    value: "Modular monolith with clear module boundaries"
+    rationale: "Right complexity level for the project scope"
+  - category: "backend"
+    key: "database"
+    value: "SQLite with better-sqlite3 driver"
+    rationale: "Zero-config local storage, perfect for CLI tools"
+  - category: "backend"
+    key: "api-style"
+    value: "CLI command interface with Commander.js"
+    rationale: "Direct command-line interaction, no HTTP needed"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/architecture-step-2-decisions.md

@@ -0,0 +1,69 @@
+# BMAD Architecture Step 2: Detailed Decisions
+
+## Context (pre-assembled by pipeline)
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### Foundational Decisions (from Step 1)
+{{starter_decisions}}
+
+### UX Design Decisions (from UX Design Phase, if applicable)
+{{ux_decisions}}
+
+---
+
+## Mission
+
+Building on the foundational architecture decisions, produce **detailed architecture decisions** covering authentication, error handling, testing strategy, and remaining architectural concerns. Do NOT repeat decisions from Step 1 — extend and complement them.
+
+If UX Design decisions are provided above, use them to inform frontend framework selection, component library choices, and UI rendering approach.
+
+## Instructions
+
+1. **Extend the architecture with detailed decisions:**
+   - **Authentication/authorization**: Strategy and implementation approach
+   - **Error handling**: Strategy for errors, logging, monitoring
+   - **Testing strategy**: Unit/integration/E2E split, framework choices
+   - **Security**: Input validation, data protection, dependency management
+   - **Frontend (if applicable)**: Framework, component library, and rendering strategy — informed by UX design decisions if available
+
+2. **Build on foundational decisions:**
+   - Reference the system architecture and data storage choices from Step 1
+   - If UX decisions are present, align frontend architecture with the specified design system and component strategy
+   - Ensure new decisions are compatible with existing ones
+   - Don't contradict or repeat previous decisions
+
+3. **Be concrete:**
+   - "JWT with RS256 and 15-minute expiry" not "Use tokens"
+   - "Vitest with 80% coverage threshold" not "Write tests"
+   - Include rationale for each decision
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text.
+
+**CRITICAL**: All string values MUST be quoted with double quotes.
+
+```yaml
+result: success
+architecture_decisions:
+  - category: "crosscutting"
+    key: "testing-strategy"
+    value: "Vitest for unit and integration, no E2E needed for CLI"
+    rationale: "Fast execution, native ESM support, compatible with TypeScript"
+  - category: "crosscutting"
+    key: "error-handling"
+    value: "Structured error types with error codes, stderr for errors"
+    rationale: "Machine-parseable errors enable automation and debugging"
+  - category: "crosscutting"
+    key: "logging"
+    value: "Structured JSON logging to stderr, configurable verbosity"
+    rationale: "Separates data output from diagnostic output"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```