substrate-ai 0.1.22 → 0.1.23

package/dist/index.d.ts

@@ -903,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.22",
+  "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,6 +2,11 @@ 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
@@ -14,6 +19,7 @@ phases:
         context:
           - placeholder: concept
             source: "param:concept"
+        elicitate: true
       - name: analysis-step-2-scope
         template: analysis-step-2-scope
         context:
@@ -21,6 +27,7 @@ phases:
             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]
@@ -39,6 +46,7 @@ phases:
             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:
@@ -48,6 +56,43 @@ phases:
             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]
@@ -69,13 +114,17 @@ phases:
             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:
@@ -84,6 +133,7 @@ phases:
           - placeholder: architecture_decisions
             source: "decision:solutioning.architecture"
         outputCategory: epic-design
+        elicitate: true
       - name: stories-step-2-stories
         template: stories-step-2-stories
         context:
@@ -94,6 +144,7 @@ phases:
           - placeholder: architecture_decisions
             source: "decision:solutioning.architecture"
         outputCategory: stories
+        critique: true
   - name: implementation
     description: Code generation, testing, and review
     entryGates: [stories-complete]
@@ -120,6 +171,20 @@ 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
+  # 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/architecture-step-2-decisions.md

@@ -8,12 +8,17 @@
 ### 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:**
@@ -21,9 +26,11 @@ Building on the foundational architecture decisions, produce **detailed architec
    - **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
 

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

@@ -0,0 +1,88 @@
+# BMAD Critique Agent — Analysis 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 product brief before the team wastes time building on a flawed foundation.
+
+Adopt a critical mindset: assume the document is incomplete until proven otherwise.
+
+---
+
+## Quality Standards for Analysis Artifacts
+
+A high-quality analysis artifact must satisfy ALL of these criteria:
+
+### 1. Problem Clarity
+- The problem statement must be specific and grounded in user pain, not technology.
+- It must explain *who* experiences the problem, *what* the impact is, and *why* existing solutions fall short.
+- Vague statements like "users need a better way to..." are insufficient.
+
+### 2. User Persona Specificity
+- Target users must be real, named segments (not "end users" or "developers").
+- Each segment must include their role, context, and motivation.
+- Minimum 2 distinct user segments required.
+
+### 3. Metrics Measurability
+- Success metrics must be quantifiable with specific numbers and timeframes.
+- Metrics like "improve user experience" or "increase engagement" are unacceptable — they cannot be measured.
+- Each metric must have a clear threshold (e.g., ">60% daily active usage within 30 days").
+
+### 4. Scope Boundaries
+- Core features must directly address the stated problem — not wishlist items.
+- Out-of-scope boundaries should be implicit or explicit in what is NOT included.
+- Constraints must be real limitations (technical, regulatory, budgetary), not vague caveats.
+
+---
+
+## 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 artifact cannot be used to proceed — critical information is missing or wrong.
+   - **major**: Significant quality gap that will cause downstream problems 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: problem-clarity
+    description: "Problem statement does not explain why existing solutions fail."
+    suggestion: "Add a sentence contrasting this approach with existing alternatives and why they fall short."
+  - severity: minor
+    category: metrics-measurability
+    description: "Success metric 'increase user satisfaction' has no numeric threshold."
+    suggestion: "Replace with a specific measurable metric, e.g., 'NPS score > 50 within 6 months'."
+```
+
+**IMPORTANT**: `issue_count` must equal the exact number of items in `issues`.

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

@@ -0,0 +1,96 @@
+# BMAD Critique Agent — Architecture 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 architecture document before the development team builds on a flawed technical foundation.
+
+Adopt a critical mindset: assume the document is incomplete or inconsistent until proven otherwise.
+
+---
+
+## Quality Standards for Architecture Artifacts
+
+A high-quality architecture artifact must satisfy ALL of these criteria:
+
+### 1. Decision Consistency
+- Architecture decisions must not contradict each other.
+- If the language is TypeScript but the database ORM chosen is Python-only, that is a blocker.
+- Decisions within a category (e.g., "infrastructure") must be internally consistent.
+- The overall architecture must form a coherent system, not a collection of ad-hoc choices.
+
+### 2. Technology Version Currency
+- Technologies must be recent, maintained, and not approaching end-of-life.
+- Version-specific decisions must reference known, stable versions (not hypothetical future versions).
+- Deprecated or abandoned libraries should be flagged as blockers.
+
+### 3. Scalability Coverage
+- The architecture must address horizontal scaling if the NFRs require it.
+- Database choices must support the required read/write throughput.
+- If the system expects high concurrency, the architecture must explain how it handles it.
+- Missing scalability considerations for NFRs that require scale are major issues.
+
+### 4. Security Coverage
+- Authentication and authorization patterns must be explicitly decided.
+- Sensitive data (passwords, API keys, PII) must have an explicit storage and handling strategy.
+- Network security (HTTPS, CORS, rate limiting) must be addressed.
+- Missing security decisions are blockers if the application handles user data.
+
+### 5. Pattern Coherence
+- Architectural patterns (e.g., layered, event-driven, microservices) must be applied consistently.
+- If a CQRS pattern is chosen, all major data flows must respect the read/write separation.
+- Pattern violations — where the code structure contradicts the stated architectural intent — are major issues.
+
+---
+
+## 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**: A decision that is technically incorrect, contradictory, or will cause systemic failure.
+   - **major**: A significant gap or inconsistency that will require architectural rework later.
+   - **minor**: An improvement or clarification that would increase quality without blocking 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: blocker
+    category: decision-consistency
+    description: "Database decision selects PostgreSQL but the caching layer decision uses Redis in a way that bypasses DB consistency guarantees — no cache invalidation strategy is defined."
+    suggestion: "Add explicit cache invalidation rules: define TTL strategy and specify which write operations must invalidate which cache keys."
+  - severity: major
+    category: security-coverage
+    description: "No authentication pattern is defined despite the FR requiring user accounts."
+    suggestion: "Add architecture decisions for: session management strategy (JWT vs cookie), token expiry policy, and refresh token handling."
+```
+
+**IMPORTANT**: `issue_count` must equal the exact number of items in `issues`.

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

@@ -0,0 +1,96 @@
+# BMAD Critique Agent — Planning 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 planning document before the architecture team makes irreversible decisions based on flawed requirements.
+
+Adopt a critical mindset: assume the document is incomplete until proven otherwise.
+
+---
+
+## Quality Standards for Planning Artifacts
+
+A high-quality planning artifact must satisfy ALL of these criteria:
+
+### 1. Functional Requirement (FR) Completeness
+- Every feature mentioned in the product brief must have at least one corresponding FR.
+- FRs must be stated as observable system behaviors: "The system shall..." or "The system must...".
+- Each FR must have a priority classification: must / should / could.
+- FRs must be specific enough that a developer can write acceptance tests from them.
+- Vague FRs like "the system shall be user-friendly" are unacceptable.
+
+### 2. NFR Measurability
+- Non-functional requirements must be quantifiable with specific thresholds.
+- NFRs like "the system shall be fast" or "the system shall be secure" are unacceptable.
+- Each NFR must have a specific numeric target (e.g., "p99 latency < 200ms under 1000 concurrent users").
+- At minimum, performance, security, and availability NFRs should be covered.
+
+### 3. User Story Quality
+- User stories must follow the "As a [persona], I want [capability], so that [benefit]" format.
+- Each story must map to one or more FRs — orphaned stories indicate scope creep.
+- Stories must be completable in a single sprint (not too large).
+
+### 4. Tech Stack Justification
+- Technology choices must be justified, not arbitrary.
+- Each major technology decision (language, framework, database) must have a rationale tied to the NFRs.
+- Inconsistencies between technology choices and stated NFRs are blockers.
+
+### 5. Requirement Traceability
+- There must be a clear chain from business goals → FRs → user stories.
+- Every user story must trace back to at least one FR.
+- Every FR must trace back to the core features defined in the product brief.
+
+---
+
+## 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**: A missing or contradictory requirement that blocks architecture or development.
+   - **major**: A significant quality gap that will cause downstream rework if not addressed.
+   - **minor**: An 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: blocker
+    category: fr-completeness
+    description: "No FRs cover the authentication workflow mentioned in core features."
+    suggestion: "Add FRs for: user registration, login, logout, password reset, and session management."
+  - severity: major
+    category: nfr-measurability
+    description: "Security NFR 'system shall be secure' has no measurable criteria."
+    suggestion: "Replace with specific NFRs: 'Passwords must be hashed with bcrypt (cost factor ≥ 12)', 'All API endpoints must require authentication', 'Input must be sanitized to prevent SQL injection'."
+```
+
+**IMPORTANT**: `issue_count` must equal the exact number of items in `issues`.

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

@@ -0,0 +1,93 @@
+# BMAD Critique Agent — Stories 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 stories document before developers start implementing based on incomplete or untestable requirements.
+
+Adopt a critical mindset: assume the stories are incomplete or ambiguous until proven otherwise.
+
+---
+
+## Quality Standards for Stories Artifacts
+
+A high-quality stories artifact must satisfy ALL of these criteria:
+
+### 1. FR Coverage
+- Every functional requirement from the planning phase must be covered by at least one story.
+- Orphaned stories (not tracing to any FR) indicate scope creep and should be flagged.
+- If the project context includes FRs, cross-reference each story against them.
+- Missing coverage of critical FRs (priority: must) is a blocker.
+
+### 2. Acceptance Criteria (AC) Testability
+- Every story must have at least 3 acceptance criteria.
+- Each acceptance criterion must be independently verifiable — a developer must be able to write a test for it.
+- ACs stated as "the feature works correctly" or "the user can use the feature" are unacceptable.
+- Each AC must specify the precise observable outcome: "Given X, when Y, then Z."
+- Unmeasurable ACs are major issues; missing ACs are blockers.
+
+### 3. Task Granularity
+- Each story must have a task breakdown that covers the full implementation scope.
+- Tasks should be completable in 1-4 hours by a single developer.
+- Tasks that are too vague ("implement feature") or too large ("build entire authentication system") should be flagged.
+- Missing tasks for database migrations, tests, or documentation are minor issues.
+
+### 4. Dependency Validity
+- Story dependencies must be valid — referencing story keys that actually exist.
+- Circular dependencies are blockers.
+- Missing dependencies — where a story assumes work from a story not listed as a dependency — are major issues.
+- Stories in the first epic should have no cross-story dependencies.
+
+---
+
+## 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**: A missing story for a critical FR, circular dependency, or completely untestable ACs.
+   - **major**: Vague ACs, uncovered important FRs, or missing cross-story dependencies.
+   - **minor**: Task granularity improvements, documentation gaps, or style issues.
+
+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: blocker
+    category: fr-coverage
+    description: "FR-3 (user authentication) has no corresponding story in any epic."
+    suggestion: "Add stories for: user registration, login flow, session management, and password reset — these are required by FR-3 which has priority 'must'."
+  - severity: major
+    category: ac-testability
+    description: "Story 1-2 AC2 states 'the CLI command works correctly' — this cannot be tested without knowing what 'correctly' means."
+    suggestion: "Replace with specific testable criteria: 'Given a valid config file, when the user runs `substrate init`, then a CLAUDE.md file is created at the project root containing the project name and methodology.'"
+```
+
+**IMPORTANT**: `issue_count` must equal the exact number of items in `issues`.