substrate-ai 0.1.21 → 0.1.22

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
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",

package/packs/bmad/manifest.yaml

@@ -8,16 +8,92 @@ phases:
     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"
+      - 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"
   - 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"
+      - 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"
   - 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"
+        outputCategory: architecture
+      - name: architecture-step-3-patterns
+        template: architecture-step-3-patterns
+        context:
+          - placeholder: architecture_decisions
+            source: "decision:solutioning.architecture"
+        outputCategory: architecture
+      - 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
+      - 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
   - name: implementation
     description: Code generation, testing, and review
     entryGates: [stories-complete]
@@ -33,6 +109,17 @@ 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
 
 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,62 @@
+# BMAD Architecture Step 2: Detailed Decisions
+
+## Context (pre-assembled by pipeline)
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### Foundational Decisions (from Step 1)
+{{starter_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.
+
+## 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
+
+2. **Build on foundational decisions:**
+   - Reference the system architecture and data storage choices from Step 1
+   - 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
+```

package/packs/bmad/prompts/architecture-step-3-patterns.md

@@ -0,0 +1,58 @@
+# BMAD Architecture Step 3: Implementation Patterns
+
+## Context (pre-assembled by pipeline)
+
+### Architecture Decisions (from Steps 1 & 2)
+{{architecture_decisions}}
+
+---
+
+## Mission
+
+Based on the accumulated architecture decisions, define **implementation patterns** — the concrete coding patterns, conventions, and structural rules that developers will follow. This bridges architecture decisions and actual code.
+
+## Instructions
+
+1. **Define implementation patterns:**
+   - Module structure and dependency injection approach
+   - Data access patterns (repository pattern, direct queries, ORM)
+   - Configuration management approach
+   - CLI command registration and routing patterns
+
+2. **Codify conventions:**
+   - Naming conventions for files, functions, types
+   - Import organization rules
+   - Error propagation patterns within the codebase
+
+3. **Output as architecture decisions** with category "patterns":
+   - Each pattern is a decision with a clear key, value, and rationale
+   - These are prescriptive — developers follow them, not choose between options
+
+## 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: "patterns"
+    key: "dependency-injection"
+    value: "Constructor injection with interface-based dependencies"
+    rationale: "Enables testing with mocks, keeps modules loosely coupled"
+  - category: "patterns"
+    key: "data-access"
+    value: "Repository pattern wrapping better-sqlite3 prepared statements"
+    rationale: "Centralizes SQL, enables query optimization and caching"
+  - category: "patterns"
+    key: "cli-commands"
+    value: "One file per command in src/commands/, registered via index barrel"
+    rationale: "Easy to find, add, and test individual commands"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/planning-step-1-classification.md

@@ -0,0 +1,50 @@
+# BMAD Planning Step 1: Project Classification
+
+## Context (pre-assembled by pipeline)
+
+### Product Brief (from Analysis Phase)
+{{product_brief}}
+
+---
+
+## Mission
+
+Classify the project and establish a clear **vision statement** with key goals. This classification guides the depth and structure of subsequent planning steps (requirements, tech stack, domain model).
+
+## Instructions
+
+1. **Classify the project type:**
+   - What kind of software is this? (CLI tool, web app, API service, mobile app, library, platform, etc.)
+   - Be specific — "TypeScript CLI tool" not just "application"
+
+2. **Write a vision statement:**
+   - One paragraph capturing the aspirational end-state
+   - What does the world look like when this product succeeds?
+   - Should inspire and constrain — broad enough to motivate, specific enough to guide decisions
+
+3. **Define key goals (3-5):**
+   - Concrete, prioritized goals that the project must achieve
+   - Each goal should be achievable and verifiable
+   - Order by priority — most critical first
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text.
+
+**CRITICAL**: All string values MUST be quoted with double quotes. All array items MUST be plain strings.
+
+```yaml
+result: success
+project_type: "TypeScript CLI tool for personal productivity"
+vision: "A lightweight, terminal-native habit tracker that makes consistency visible and rewarding for developers who live in their terminals."
+key_goals:
+  - "Provide instant habit tracking without leaving the terminal"
+  - "Make streak data visible to motivate daily consistency"
+  - "Zero-config setup with local-first data storage"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/planning-step-2-frs.md

@@ -0,0 +1,60 @@
+# BMAD Planning Step 2: Functional Requirements & User Stories
+
+## Context (pre-assembled by pipeline)
+
+### Product Brief (from Analysis Phase)
+{{product_brief}}
+
+### Project Classification (from Step 1)
+{{classification}}
+
+---
+
+## Mission
+
+Derive **functional requirements** and **user stories** from the product brief and project classification. These define WHAT the system must do from the user's perspective.
+
+## Instructions
+
+1. **Derive functional requirements:**
+   - Each FR must be specific, testable, and traceable to a core feature or user need
+   - Use MoSCoW prioritization: `must` (MVP-critical), `should` (high-value), `could` (nice-to-have)
+   - Minimum 3 FRs, but don't pad — every FR should earn its place
+   - Frame as capabilities: "Users can filter by date range" not "Add a date picker component"
+
+2. **Write user stories:**
+   - Each story captures a user journey or interaction pattern
+   - Title should be scannable; description should explain the "why"
+   - Stories bridge the gap between requirements and implementation
+
+3. **Align with classification:**
+   - FRs should support the key goals from the classification step
+   - Prioritization should reflect the project type and vision
+
+## 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
+functional_requirements:
+  - description: "Users can register new habits with a name and frequency"
+    priority: must
+  - description: "Users can view current streaks for all tracked habits"
+    priority: must
+  - description: "Users can export habit data to JSON or CSV format"
+    priority: should
+user_stories:
+  - title: "Habit Registration"
+    description: "As a developer, I want to register daily habits so I can track my consistency"
+  - title: "Streak Dashboard"
+    description: "As a user, I want to see my current streaks so I stay motivated"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/planning-step-3-nfrs.md

@@ -0,0 +1,75 @@
+# BMAD Planning Step 3: NFRs, Tech Stack, Domain Model & Scope
+
+## Context (pre-assembled by pipeline)
+
+### Product Brief (from Analysis Phase)
+{{product_brief}}
+
+### Project Classification (from Step 1)
+{{classification}}
+
+### Functional Requirements (from Step 2)
+{{functional_requirements}}
+
+---
+
+## Mission
+
+Complete the PRD by defining **non-functional requirements**, **tech stack**, **domain model**, and **out-of-scope items**. These constrain HOW the system is built and what it explicitly does NOT do.
+
+## Instructions
+
+1. **Define non-functional requirements:**
+   - Each NFR must have a category (performance, security, scalability, accessibility, reliability)
+   - Be concrete: "API responses under 200ms at p95" not "System should be fast"
+   - Minimum 2 NFRs covering different categories
+   - NFRs should align with the project type and constraints
+
+2. **Specify the tech stack:**
+   - Key-value pairs mapping technology concerns to specific choices
+   - Use real, current technologies — do not fabricate frameworks
+   - Cover at minimum: language, framework, database, testing
+   - Choices should align with the product brief constraints
+
+3. **Build the domain model:**
+   - Key entities and their relationships
+   - Each entity as a key with its attributes/relationships as the value
+   - This informs database design and API structure downstream
+
+4. **Define out-of-scope items** to prevent scope creep — what this product explicitly does NOT do.
+
+## 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
+non_functional_requirements:
+  - description: "CLI commands complete within 200ms for local operations"
+    category: "performance"
+  - description: "All user data encrypted at rest using AES-256"
+    category: "security"
+tech_stack:
+  language: "TypeScript"
+  framework: "Node.js CLI with Commander"
+  database: "SQLite via better-sqlite3"
+  testing: "Vitest"
+domain_model:
+  Habit:
+    attributes: ["name", "frequency", "created_at"]
+    relationships: ["has_many: Completions"]
+  Completion:
+    attributes: ["habit_id", "completed_at"]
+    relationships: ["belongs_to: Habit"]
+out_of_scope:
+  - "Web or mobile interface"
+  - "Cloud sync or multi-device support"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```