substrate-ai 0.2.4 → 0.2.6

package/dist/{run-Bwyy5-RY.js → run-Chc5BzIz.js}

@@ -1,6 +1,6 @@
 import "./logger-C6n1g8uP.js";
 import "./event-bus-J-bw-pkp.js";
-import { registerRunCommand, runRunAction } from "./run-D3ZscMlL.js";
+import { registerRunCommand, runRunAction } from "./run-0IlA2ubQ.js";
 import "./decisions-DNYByk0U.js";
 import "./metrics-BSg8VIHd.js";
 

package/package.json

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

package/packs/bmad/manifest.yaml

@@ -2,12 +2,37 @@ name: bmad
 version: 1.0.0
 description: BMAD methodology for autonomous software development
 
+# Optional research phase (Story 20.1).
+# When true, a 'research' phase runs before analysis, conducting market/competitive research.
+# Set to false (or omit) to skip research and proceed directly to analysis.
+research: true
+
 # 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: research
+    description: Market research, competitive landscape analysis, and technical feasibility (runs before analysis when research is enabled)
+    entryGates: []
+    exitGates: [research-complete]
+    artifacts: [research-findings]
+    steps:
+      - name: research-step-1-discovery
+        template: research-step-1-discovery
+        context:
+          - placeholder: concept
+            source: "param:concept"
+        elicitate: true
+      - name: research-step-2-synthesis
+        template: research-step-2-synthesis
+        context:
+          - placeholder: concept
+            source: "param:concept"
+          - placeholder: raw_findings
+            source: "step:research-step-1-discovery"
+        critique: true
   - name: analysis
     description: Product discovery and brief creation
     entryGates: []
@@ -175,6 +200,10 @@ prompts:
   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
+  # Research phase prompts (Story 20-2)
+  research-step-1-discovery: prompts/research-step-1-discovery.md
+  research-step-2-synthesis: prompts/research-step-2-synthesis.md
+  critique-research: prompts/critique-research.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

package/packs/bmad/prompts/critique-research.md

@@ -0,0 +1,92 @@
+# BMAD Critique Agent — Research Phase
+
+## Artifact Under Review
+
+{{artifact_content}}
+
+## Project Context
+
+{{project_context}}
+
+---
+
+## Your Role
+
+You are an adversarial quality reviewer. Your job is to find what's wrong with this research document before the team builds a product brief on a flawed foundation.
+
+Adopt a critical mindset: assume the research is incomplete, biased, or stale until proven otherwise.
+
+---
+
+## Quality Standards for Research Artifacts
+
+A high-quality research artifact must satisfy ALL of these criteria:
+
+### 1. Source Credibility
+- Findings must reference identifiable, credible sources (industry reports, named companies, published standards, or well-known open source projects).
+- Vague attributions like "industry experts say" or "research shows" without specifics are unacceptable.
+- Market sizing claims must include a source or methodology (e.g., "Gartner 2024", "company 10-K", "author's estimate based on TAM").
+- At minimum, 2-3 named companies or products must be referenced as evidence.
+
+### 2. Finding Relevance
+- Every finding must be directly relevant to the stated concept — tangential observations about adjacent markets are noise.
+- Market findings must describe the actual target buyer, not a proxy audience.
+- Technical findings must reflect the technology decisions the concept will actually face, not hypothetical stacks.
+- Risk flags must be specific and actionable (not generic "the market is competitive").
+
+### 3. Gap Identification
+- The research must acknowledge what it does NOT know — gaps are acceptable, but must be named explicitly.
+- If web search was unavailable, the agent must state that findings are based on training knowledge and may be stale.
+- Missing dimensions: if any of market, competitive, technical, or risk analysis is absent, it is a blocker.
+- Opportunity signals must be grounded in research — speculative "we could do X" signals are unacceptable.
+
+### 4. Synthesis Coherence
+- The competitive landscape must identify named competitors, not generic categories ("some incumbents").
+- Risk flags must be distinct from each other — no duplicates or slight rewording of the same risk.
+- Opportunity signals must logically follow from the findings — they must be traceable to specific evidence in the research.
+- Market context and competitive landscape must be internally consistent — contradictions are blockers.
+
+---
+
+## Instructions
+
+1. Read the artifact carefully. Do not assume anything is correct.
+2. For each quality dimension above, identify whether it is met, partially met, or missing.
+3. For each issue found, classify its severity:
+   - **blocker**: The research cannot be used to proceed — a critical dimension is missing, contradictory, or completely uncredible.
+   - **major**: Significant quality gap that will bias the product brief if not addressed.
+   - **minor**: Improvement that would increase quality but does not block progress.
+
+4. If the artifact meets all criteria, emit a `pass` verdict with zero issues.
+
+---
+
+## Output Contract
+
+Emit ONLY this YAML block — no preamble, no explanation, no other text.
+
+If no issues found:
+
+```yaml
+verdict: pass
+issue_count: 0
+issues: []
+```
+
+If issues found:
+
+```yaml
+verdict: needs_work
+issue_count: 2
+issues:
+  - severity: major
+    category: source-credibility
+    description: "Market size claim of '$15B by 2027' has no cited source or methodology."
+    suggestion: "Add the source (e.g., 'per Gartner 2024 Cloud Infrastructure Report') or note it as an author estimate with the derivation method."
+  - severity: minor
+    category: finding-relevance
+    description: "Technical findings describe a microservices architecture that is not relevant to the stated single-tenant SaaS concept."
+    suggestion: "Replace with findings specific to single-tenant deployment patterns, data isolation models, and per-tenant customization approaches."
+```
+
+**IMPORTANT**: `issue_count` must equal the exact number of items in `issues`.

package/packs/bmad/prompts/research-step-1-discovery.md

@@ -0,0 +1,76 @@
+# BMAD Research Step 1: Discovery
+
+## Context (pre-assembled by pipeline)
+
+### Concept
+{{concept}}
+
+---
+
+## Mission
+
+Conduct a thorough **research discovery** for this concept. Your goal is to gather and organize raw findings across three dimensions:
+
+1. **Concept Classification** — what type of product or tool is this, who is it for, and what domain does it operate in?
+2. **Market Findings** — market size, target customers, pricing models, and market trends
+3. **Domain Findings** — best practices, industry standards, regulatory requirements, and use cases
+4. **Technical Findings** — technical architecture patterns, technology stacks, open source alternatives, and implementation challenges
+
+This raw discovery output will feed directly into a synthesis step that distills the findings into actionable insights.
+
+## Instructions
+
+### 1. Classify the Concept
+
+Before searching, classify the concept:
+- **Product type**: Is this a product sold to customers, or an internal tool / developer tooling?
+- **Industry vertical**: What industry or sector does it primarily serve (e.g., fintech, healthcare, devtools, SaaS platform, e-commerce)?
+- **Tech domain**: What is the primary technical domain (e.g., data pipelines, mobile apps, APIs, AI/ML, infrastructure)?
+
+### 2. Conduct Web Research
+
+Use web search to gather findings across the three dimensions below. Execute approximately 12 searches total — 3-4 per dimension.
+
+**Market dimension queries:**
+- `"{{concept}} market size"`
+- `"{{concept}} target customers"`
+- `"{{concept}} pricing models"`
+- `"{{concept}} market trends 2025"`
+
+**Domain dimension queries:**
+- `"{{concept}} best practices"`
+- `"{{concept}} industry standards"`
+- `"{{concept}} regulatory requirements"`
+- `"{{concept}} use cases"`
+
+**Technical dimension queries:**
+- `"{{concept}} technical architecture"`
+- `"{{concept}} technology stack"`
+- `"{{concept}} open source alternatives"`
+- `"{{concept}} implementation challenges"`
+
+> **Fallback**: If web search is unavailable in your environment, proceed with concept analysis using your training knowledge — acknowledge that findings may not reflect the latest market conditions.
+
+### 3. Organize Findings
+
+For each dimension, summarize the key findings in 2-4 sentences. Be specific: name actual companies, technologies, standards, or regulations where found. Avoid vague generalizations.
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text, no preamble.
+
+**CRITICAL**: All string values MUST be quoted with double quotes.
+
+```yaml
+result: success
+concept_classification: "B2B SaaS product targeting mid-market DevOps teams in the cloud infrastructure space"
+market_findings: "The cloud infrastructure automation market is valued at $12B in 2024, growing at 18% CAGR. Primary customers are platform engineering teams at companies with 50-500 engineers. Pricing models cluster around per-seat ($30-80/month) and usage-based (per compute hour). Key trend: shift from IaaS to developer-experience platforms."
+domain_findings: "Industry standards include Terraform HCL for IaC and GitOps workflows (CNCF). Regulatory requirements vary by industry: SOC 2 Type II is table stakes for enterprise; HIPAA for healthcare customers. Key use cases: multi-cloud deployment, drift detection, cost optimization, and compliance reporting."
+technical_findings: "Dominant architectural pattern is event-driven with a control plane / data plane separation. Common stack: Go or Rust for the agent, React for dashboard, PostgreSQL + TimescaleDB for time-series data. Open source alternatives include Pulumi, OpenTofu, and Crossplane. Primary implementation challenges are state reconciliation under network partitions and secret management at scale."
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/research-step-2-synthesis.md

@@ -0,0 +1,64 @@
+# BMAD Research Step 2: Synthesis
+
+## Context (pre-assembled by pipeline)
+
+### Concept
+{{concept}}
+
+### Raw Research Findings
+{{raw_findings}}
+
+---
+
+## Mission
+
+Synthesize the raw research findings into a structured, actionable research report. Your goal is to distill the discovery output into five key sections:
+
+1. **Market Context** — the market landscape, sizing, and customer dynamics
+2. **Competitive Landscape** — who the key competitors are, their positioning, and differentiation opportunities
+3. **Technical Feasibility** — how technically viable this concept is, key technology choices, and build vs. buy considerations
+4. **Risk Flags** — specific risks that could threaten success (market, technical, regulatory, execution)
+5. **Opportunity Signals** — specific indicators of where this concept has an advantage or untapped potential
+
+This synthesis output feeds directly into the analysis phase to ground the product brief in real-world context.
+
+## Instructions
+
+1. **Market Context**: Synthesize the market dimension findings. Quantify the opportunity where possible. Identify the primary buyer profile and decision-maker. Note any market timing signals (growing, contracting, consolidating).
+
+2. **Competitive Landscape**: Identify named competitors (direct and adjacent). Describe how they are positioned. Identify gaps or differentiation opportunities that the concept could exploit.
+
+3. **Technical Feasibility**: Assess how technically achievable the concept is given the technology landscape. Highlight proven patterns to adopt, and identify areas where the technical approach is risky or unproven.
+
+4. **Risk Flags**: List 3-6 specific, concrete risks. Each risk should name the threat and its potential impact. Avoid generic risks like "execution risk" — be specific (e.g., "Compliance with HIPAA BAA requirements may add 3-6 months to enterprise sales cycles").
+
+5. **Opportunity Signals**: List 3-6 specific indicators that suggest this concept has real potential. These should be grounded in the research findings, not wishful thinking.
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text, no preamble.
+
+**CRITICAL**: All string values MUST be quoted with double quotes. List items in `risk_flags` and `opportunity_signals` must also be double-quoted.
+
+```yaml
+result: success
+market_context: "The cloud infrastructure automation market is a $12B opportunity growing at 18% CAGR, driven by the shift from DevOps to platform engineering. Primary buyers are VPs of Engineering and Platform Engineering leads at Series B+ startups and mid-market companies. Market is in early growth phase with high willingness to pay for workflow automation."
+competitive_landscape: "Direct competitors are Terraform Cloud (HashiCorp/IBM), Spacelift, and Scalr — all targeting the same DevOps persona. Pulumi competes on developer experience with a code-first approach. Differentiation opportunity: none of the incumbent tools offer AI-assisted drift detection or natural-language policy authoring. Open source (OpenTofu) commoditizes the IaC layer, making the control plane the primary value surface."
+technical_feasibility: "High feasibility using proven patterns: Go agent with event-driven control plane (used by Argo CD, Flux), React dashboard, and PostgreSQL for state. Primary technical risk is distributed state reconciliation under network partitions. Build recommendation: agent core in Go, leverage existing Terraform/OpenTofu compatibility, avoid building a custom DSL."
+risk_flags:
+  - "Regulatory: HIPAA and SOC 2 Type II compliance are table stakes for enterprise sales — adds 4-6 months to first enterprise close"
+  - "Competitive: HashiCorp's BSL license change accelerated OpenTofu adoption — if IBM reverses the decision, momentum could shift back"
+  - "Technical: Distributed state reconciliation under network partitions is an unsolved problem that all incumbents struggle with — high engineering cost"
+  - "Market: Per-seat pricing erodes at scale (>500 engineers) — customers will demand volume discounts or switch to usage-based pricing"
+opportunity_signals:
+  - "AI-native workflows: no incumbent offers natural-language policy authoring or AI-assisted remediation — clear whitespace"
+  - "OpenTofu migration wave: 30%+ of Terraform users are evaluating alternatives following the BSL license change — timing is favorable"
+  - "Platform engineering trend: Gartner predicts 80% of large orgs will have platform engineering teams by 2026 — growing buyer segment"
+  - "Developer experience gap: incumbent UIs are functional but dated — a modern, keyboard-first interface is a differentiator"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```