substrate-ai 0.1.21 → 0.1.23

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

@@ -0,0 +1,139 @@
+# 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: 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 5: 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 6: 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, 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/stories-step-1-epics.md

@@ -0,0 +1,59 @@
+# BMAD Stories Step 1: Epic Design
+
+## Context (pre-assembled by pipeline)
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### Architecture Decisions (from Solutioning Phase)
+{{architecture_decisions}}
+
+---
+
+## Mission
+
+Design the **epic structure** — high-level groupings of work organized by user value, with explicit mapping to functional requirements. This ensures full FR coverage before diving into story details.
+
+## Instructions
+
+1. **Organize epics by user value, never by technical layer:**
+   - GOOD: "User Authentication & Onboarding", "Dashboard & Analytics"
+   - BAD: "Database Setup", "API Development", "Frontend Components"
+   - Each epic must be independently valuable
+   - No forward dependencies — Epic N should not require Epic N+1
+
+2. **Map FRs to epics:**
+   - Use `fr_coverage` to list which functional requirements each epic addresses
+   - Every FR from the planning phase must appear in at least one epic's coverage
+   - This creates traceability before detailed story writing begins
+
+3. **Keep descriptions focused:**
+   - Each epic's description should explain the user value it delivers
+   - Include enough context for story generation in the next step
+
+## 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
+epics:
+  - title: "User Onboarding and Habit Management"
+    description: "Core habit tracking functionality that delivers immediate user value"
+    fr_coverage:
+      - "FR-0"
+      - "FR-1"
+  - title: "Analytics and Streak Visualization"
+    description: "Insight features that motivate continued usage"
+    fr_coverage:
+      - "FR-2"
+      - "FR-3"
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/stories-step-2-stories.md

@@ -0,0 +1,78 @@
+# BMAD Stories Step 2: Story Generation
+
+## Context (pre-assembled by pipeline)
+
+### Epic Structure (from Step 1)
+{{epic_structure}}
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### Architecture Decisions (from Solutioning Phase)
+{{architecture_decisions}}
+
+---
+
+## Mission
+
+Expand the epic structure into **implementation-ready stories** with acceptance criteria. Each story should be sized for a single developer in 1-3 days.
+
+## Instructions
+
+1. **Write implementation-ready stories:**
+   - `key`: Short identifier like "1-1" or "2-3" (epic number - story number)
+   - `title`: Clear, action-oriented (e.g., "User registration with email verification")
+   - `description`: What the developer needs to build and why. Include enough context to start coding.
+   - `acceptance_criteria`: Specific, testable conditions. Minimum 1 per story. Use concrete language.
+   - `priority`: must (MVP-critical), should (high-value post-MVP), could (nice-to-have)
+
+2. **Ensure full FR coverage:**
+   - The epic structure from Step 1 maps FRs to epics — generate stories that fulfill each FR
+   - Cross-reference: every FR should be covered by at least one story's acceptance criteria
+
+3. **Respect architecture decisions:**
+   - Stories should reference the chosen tech stack and patterns
+   - If architecture specifies a project structure, Epic 1 Story 1 should be project scaffolding
+
+4. **Size stories appropriately:**
+   - Each story completable by one developer in 1-3 days
+   - If too large, split into multiple stories within the same epic
+   - If an epic has more than 8 stories, consider if the epic should be split
+
+## 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.
+- Acceptance criteria must be plain English descriptions — NO code snippets, function calls, or special characters inside strings.
+- BAD: `- "convertMarkdown('# hello') returns '<h1>hello</h1>'"` (embedded quotes break YAML)
+- GOOD: `- "Converting a heading produces the correct HTML h1 tag"`
+
+```yaml
+result: success
+epics:
+  - title: "User Onboarding and Habit Management"
+    description: "Core habit tracking functionality that delivers immediate user value"
+    stories:
+      - key: "1-1"
+        title: "Project scaffolding and CLI setup"
+        description: "Initialize the project with TypeScript, Commander, and SQLite"
+        acceptance_criteria:
+          - "CLI binary runs and shows help text"
+          - "SQLite database is created on first run"
+        priority: must
+      - key: "1-2"
+        title: "Register and list habits"
+        description: "Users can create habits and view all tracked habits"
+        acceptance_criteria:
+          - "habit add command creates a new habit"
+          - "habit list command shows all habits with status"
+        priority: must
+```
+
+If you cannot produce valid output:
+
+```yaml
+result: failed
+```

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