substrate-ai 0.1.22 → 0.1.24

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`.

package/packs/bmad/prompts/elicitation-apply.md

@@ -0,0 +1,40 @@
+# Elicitation: {{method_name}}
+
+You are an expert analyst applying a structured elicitation method to improve an artifact.
+
+## Method
+
+**Name:** {{method_name}}
+
+**Description:** {{method_description}}
+
+**Output Pattern:** {{output_pattern}}
+
+## Artifact to Enhance
+
+{{artifact_content}}
+
+## Instructions
+
+Apply the **{{method_name}}** method to the artifact content above.
+
+Follow the output pattern: `{{output_pattern}}`
+
+Work through the method systematically. Identify non-obvious insights, hidden assumptions, risks, or improvements that the artifact does not already capture. Mark each insight clearly.
+
+Return your analysis as structured YAML:
+
+```yaml
+result: success
+insights: |
+  [Your enhanced content with insights clearly marked. Use markdown formatting.
+   Each insight should be labeled with the method step that generated it.
+   Be specific and actionable — avoid restating what is already in the artifact.]
+```
+
+If you cannot apply the method meaningfully (e.g., the artifact is insufficient), return:
+
+```yaml
+result: failed
+insights: ""
+```

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

@@ -11,6 +11,9 @@
 ### Functional Requirements (from Step 2)
 {{functional_requirements}}
 
+### Technology Constraints (from Analysis Phase)
+{{technology_constraints}}
+
 ---
 
 ## Mission
@@ -29,7 +32,8 @@ Complete the PRD by defining **non-functional requirements**, **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
+   - **MUST honor stated technology constraints** — if the analysis specifies a cloud platform, language, or framework preference, use it. Do not substitute alternatives unless the constraint is technically impossible for the requirements.
+   - If you must deviate from a stated constraint, explicitly note the deviation and rationale
 
 3. **Build the domain model:**
    - Key entities and their relationships

package/packs/bmad/prompts/readiness-check.md

@@ -0,0 +1,146 @@
+# BMAD Adversarial Readiness Check Agent
+
+## Context (pre-assembled by pipeline)
+
+### Functional Requirements
+{{functional_requirements}}
+
+### Non-Functional Requirements
+{{non_functional_requirements}}
+
+### Architecture Decisions
+{{architecture_decisions}}
+
+### Generated Stories
+{{stories}}
+
+{{ux_decisions}}
+
+---
+
+## Mission
+
+You are a senior engineering lead conducting a go/no-go review before implementation begins.
+**Your success is measured by finding gaps others missed — not by confirming everything is fine.**
+
+Approach this review with professional skepticism. Assume gaps exist until proven otherwise.
+Your job is to protect the engineering team from starting implementation with an incomplete or
+contradictory plan. A false READY verdict costs 10x more than a correct NEEDS_WORK verdict.
+
+---
+
+## Review Protocol
+
+Work through each check in order. Be thorough. Be adversarial.
+
+### Step 1: FR Coverage Analysis
+
+For EVERY functional requirement listed above:
+1. Identify which story (by key) explicitly covers this FR in its acceptance criteria
+2. Determine if the coverage is **full** (AC directly tests the FR), **partial** (FR mentioned but not tested), or **missing** (no story covers it)
+3. Flag missing coverage as a **blocker** finding
+4. Flag partial coverage as a **major** finding
+
+Ask yourself: "If I only built the stories as written, would this FR be implemented?" If the answer is "maybe" or "no", flag it.
+
+### Step 2: Architecture Compliance Check
+
+For EVERY story:
+1. Check if the story's implementation implies a technology or pattern **not in the architecture decisions**
+2. Check if the story **contradicts** an architecture decision (e.g., story uses REST when architecture specifies GraphQL)
+3. Flag contradictions as **blocker** findings
+4. Flag implicit technology references not in architecture as **major** findings
+
+### Step 3: Story Quality Assessment
+
+For EVERY story:
+1. Are the acceptance criteria in Given/When/Then or clearly testable format?
+   - Vague ACs like "the system works correctly" = **major** finding
+2. Are the tasks granular enough to estimate? (Each task should be < 1 day)
+   - Monolithic tasks like "implement the entire auth system" = **major** finding
+3. Does the story have a clear definition of done?
+   - Missing or ambiguous DoD = **minor** finding
+
+### Step 4: Constraint Adherence
+
+1. Does the architecture honor all technology constraints from the product brief?
+2. If any technology constraint was overridden, is there an explicit rationale?
+3. Flag any silent deviations (constraint ignored without explanation) as **blocker** findings
+4. Flag deviations with rationale as **major** findings
+
+### Step 5: UX Alignment (Conditional)
+
+**Only if UX decisions are provided above:**
+
+For EVERY story that involves user-facing functionality:
+1. Does the story reference the component strategy or design system from UX decisions?
+2. Does the story account for accessibility requirements?
+3. Does the story align with the user journey flows?
+4. Flag missing UX alignment as **major** findings
+
+**If no UX decisions were provided, skip this step entirely.**
+
+### Step 6: Dependency Validity
+
+For EVERY story with dependencies on other stories:
+1. Do the referenced stories actually exist (check story keys)?
+2. Are the dependency chains acyclic?
+3. Flag invalid references as **blocker** findings
+4. Flag potentially circular dependencies as **major** findings
+
+### Step 7: Final Verdict
+
+Determine your verdict:
+- **NOT_READY**: Any of these conditions are true:
+  - 3 or more blocker findings
+  - FR coverage_score < 50%
+  - Multiple critical architecture contradictions
+- **NEEDS_WORK**: Any of these conditions are true:
+  - 1-2 blocker findings (auto-remediable via story regeneration)
+  - FR coverage_score 50-79%
+  - Several major findings
+- **READY**: All of these conditions are true:
+  - Zero blocker findings
+  - FR coverage_score >= 80%
+  - Only minor findings (if any)
+
+---
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text.
+
+**CRITICAL YAML RULES**: All string values MUST be quoted with double quotes. Arrays use `-` notation. Keep values on single lines.
+
+```yaml
+verdict: "READY"
+coverage_score: 95
+findings:
+  - category: "fr_coverage"
+    severity: "blocker"
+    description: "FR-3 (User can export reports as PDF) has no story covering it. Story 2-4 mentions reporting but does not include export functionality."
+    affected_items:
+      - "FR-3"
+      - "2-4"
+  - category: "story_quality"
+    severity: "minor"
+    description: "Story 1-2 AC3 is vague: 'the system responds appropriately'. Should specify expected response time and format."
+    affected_items:
+      - "1-2"
+```
+
+Valid verdict values: READY, NEEDS_WORK, NOT_READY
+Valid category values: fr_coverage, architecture_compliance, story_quality, constraint_adherence, ux_alignment, dependency_validity
+Valid severity values: blocker, major, minor
+
+If you cannot perform the review:
+
+```yaml
+verdict: "NOT_READY"
+coverage_score: 0
+findings:
+  - category: "fr_coverage"
+    severity: "blocker"
+    description: "Unable to perform readiness review: insufficient context provided."
+    affected_items: []
+```

package/packs/bmad/prompts/refine-artifact.md

@@ -0,0 +1,52 @@
+# BMAD Refinement Agent
+
+## Phase Context
+
+{{phase_context}}
+
+## Original Artifact
+
+{{original_artifact}}
+
+## Critique Issues to Address
+
+The following issues were identified by the quality reviewer. You must address each one:
+
+{{critique_issues}}
+
+---
+
+## Your Role
+
+You are a skilled technical writer and architect. Your job is to improve the artifact above by addressing every issue in the critique list.
+
+---
+
+## Instructions
+
+1. Read the original artifact carefully to understand its full content and intent.
+
+2. Review each critique issue and understand exactly what needs to change:
+   - **blocker** issues must be fully resolved — the refined artifact must not contain the original deficiency.
+   - **major** issues must be addressed with substantive improvements, not cosmetic changes.
+   - **minor** issues should be addressed where possible without disrupting the overall structure.
+
+3. Produce a revised version of the artifact that:
+   - Addresses every listed issue
+   - Preserves all correct and valid content from the original
+   - Maintains the same format and structure as the original (YAML fields, markdown sections, etc.)
+   - Does NOT introduce new problems while fixing existing ones
+
+4. The refined artifact must be complete and self-contained — it replaces the original entirely.
+
+---
+
+## Output
+
+Return ONLY the refined artifact content — no preamble, no "Here is the refined version:", no explanation.
+
+Start directly with the artifact content, exactly as the original was formatted.
+
+If the original was a YAML block, return a YAML block.
+If the original was a markdown document, return a markdown document.
+If the original was structured text, maintain that structure.

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

@@ -0,0 +1,69 @@
+# BMAD UX Design Step 1: Discovery + Core Experience
+
+## Context (pre-assembled by pipeline)
+
+### Product Brief (from Analysis Phase)
+{{product_brief}}
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+---
+
+## Mission
+
+Conduct a thorough **UX discovery** for this product. Your goal is to define:
+1. The target user personas and their goals
+2. The core experience vision — what should it feel like to use this product?
+3. Emotional response targets — what emotions should users feel?
+4. Inspiration references — existing products, design patterns, or aesthetics to reference
+
+This is the foundation for all subsequent UX design decisions. Be specific and user-centered.
+
+## Instructions
+
+1. **Define target personas** (2-4 personas):
+   - Name + role (e.g., "Alex, startup founder")
+   - Primary goal when using this product
+   - Key frustrations the product should solve
+   - Technical comfort level
+
+2. **Articulate the core experience vision**:
+   - What is the ONE sentence that captures how users should experience this product?
+   - Example: "Effortless, like having a brilliant assistant who anticipates your needs"
+
+3. **Set emotional response targets** (3-5 emotional goals):
+   - What should users feel when they first open the product?
+   - What should they feel after completing a key task?
+   - Example: "Confident, not overwhelmed; Surprised by how fast it works"
+
+4. **Identify inspiration references** (2-4 references):
+   - Products, apps, or design systems whose UX quality to emulate
+   - What specifically to borrow (interaction model, visual clarity, information density)
+
+## 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
+target_personas:
+  - "Alex (startup founder): wants rapid iteration; frustrated by slow dev tools; high technical comfort"
+  - "Sam (product manager): needs clear status visibility; frustrated by context-switching; moderate technical comfort"
+core_experience: "Instant clarity — every action produces visible, understandable results within seconds"
+emotional_goals:
+  - "Empowered: users feel in control of a complex process"
+  - "Focused: the interface surfaces only what matters right now"
+  - "Confident: clear feedback means users always know what's happening"
+inspiration_references:
+  - "Linear.app: information density and keyboard-first workflow"
+  - "Raycast: speed and discoverability without cognitive overload"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/ux-step-2-design-system.md

@@ -0,0 +1,64 @@
+# BMAD UX Design Step 2: Design System + Visual Foundation
+
+## Context (pre-assembled by pipeline)
+
+### Product Brief (from Analysis Phase)
+{{product_brief}}
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### UX Discovery (from Step 1)
+{{ux_discovery}}
+
+---
+
+## Mission
+
+Build on the UX discovery to define the **design system and visual foundation** for this product. Your goal is to establish the design language that will guide all UI development decisions.
+
+## Instructions
+
+1. **Define the design system approach**:
+   - Should this product use an existing component library (e.g., shadcn/ui, MUI, Chakra) or custom?
+   - What is the rationale based on the target personas and core experience vision?
+   - Example: "shadcn/ui with Tailwind CSS — minimal overhead, full customization, matches developer-focused audience"
+
+2. **Establish the visual foundation** — the overall aesthetic:
+   - Layout philosophy: spacious or dense? Grid or freeform?
+   - Motion: animated transitions or static? Micro-interactions?
+   - Personality: professional/corporate, playful/approachable, technical/utilitarian?
+
+3. **Define 3-5 design principles**:
+   - Short, actionable statements that guide UI decisions
+   - Example: "Progressive disclosure: show complexity only when needed"
+   - Example: "Keyboard first: every action reachable without a mouse"
+
+4. **Specify color and typography direction**:
+   - Color palette: light/dark mode? Primary accent color family?
+   - Typography: serif, sans-serif, monospace for code? Specific families if known?
+   - Example: "Dark-mode-first with neutral gray base, blue accent. Inter for UI, JetBrains Mono for code"
+
+## 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
+design_system: "shadcn/ui with Tailwind CSS — provides accessible, composable primitives with full design token control"
+visual_foundation: "Dense-information layout with generous whitespace at page level. Subtle motion for state changes only. Technical-utilitarian personality with warm accents to reduce coldness."
+design_principles:
+  - "Progressive disclosure: surface complexity only when the user requests it"
+  - "Keyboard-first: every interaction is achievable without a mouse"
+  - "Visible state: system status is always visible, never hidden"
+  - "Consistent feedback: every action produces an immediate, unambiguous response"
+color_and_typography: "Dark-mode primary with light-mode option. Slate gray base with indigo accent. Inter 400/500/600 for UI text, JetBrains Mono for code and terminal output."
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/ux-step-3-journeys.md

@@ -0,0 +1,80 @@
+# BMAD UX Design Step 3: User Journeys + Component Strategy + Accessibility
+
+## Context (pre-assembled by pipeline)
+
+### Product Brief (from Analysis Phase)
+{{product_brief}}
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### UX Discovery (from Step 1)
+{{ux_discovery}}
+
+### Design System (from Step 2)
+{{design_system}}
+
+---
+
+## Mission
+
+Complete the UX design by mapping **user journeys**, defining the **component strategy**, identifying key **UX patterns**, and establishing **accessibility and responsive design guidelines**.
+
+## Instructions
+
+1. **Map 2-4 critical user journeys**:
+   - Each journey covers a key workflow from the user's perspective
+   - Format: "User goal → Entry point → Steps → Success state → Failure state"
+   - Focus on the 2-4 highest-value workflows from the requirements
+   - Example: "New user onboarding → Landing page → Sign up → Dashboard → First action → Completion"
+
+2. **Define the component strategy**:
+   - What are the 3-5 most complex/critical UI components to design first?
+   - For each: name, purpose, key interactions, and data requirements
+   - Example: "Pipeline status dashboard: real-time progress visualization with expandable step details"
+
+3. **Identify 3-5 key UX patterns**:
+   - Specific interaction patterns that recur across the product
+   - Example: "Optimistic updates: apply changes immediately, roll back on error"
+   - Example: "Command palette (Cmd+K): global action access without navigation"
+   - Example: "Toast notifications: transient feedback for async operations"
+
+4. **Establish accessibility and responsive design guidelines**:
+   - WCAG target level (AA recommended minimum)
+   - Keyboard navigation requirements
+   - Screen reader support priorities
+   - Responsive breakpoints and mobile strategy (mobile-first? adaptive? PWA?)
+   - Example: "WCAG AA minimum. Full keyboard navigation for all core flows. ARIA labels on all interactive elements. Mobile-responsive at 320px+ breakpoints."
+
+## 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
+user_journeys:
+  - "First run: User installs CLI → runs 'substrate auto init' → provides project concept → pipeline starts automatically → watches real-time progress → reviews results"
+  - "Resume after failure: User sees failed story → inspects error → runs 'substrate auto resume' → pipeline retries from last checkpoint → completes successfully"
+  - "Amend existing run: User wants to change direction → runs 'substrate auto amend --concept ...' → sees diff of changes → approves → pipeline re-runs affected phases"
+component_strategy: "Priority components: (1) Pipeline status view — hierarchical phase/story progress with real-time updates; (2) Story detail panel — structured view of AC, tasks, and test results; (3) Error inspector — contextual error display with suggested fixes"
+ux_patterns:
+  - "Streaming output: display pipeline logs in real-time with ANSI color preservation"
+  - "Progressive detail: collapsed by default, expand on demand"
+  - "Inline error recovery: show fix suggestions adjacent to failure context"
+  - "Persistent state: remember last run context across sessions"
+accessibility_guidelines:
+  - "WCAG AA compliance minimum"
+  - "Full keyboard navigation for all interactive elements"
+  - "High-contrast mode support via prefers-color-scheme"
+  - "Reduced motion media query respected for animations"
+  - "ARIA live regions for streaming output updates"
+  - "Mobile-responsive at 320px minimum width"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```