substrate-ai 0.1.21 → 0.1.23

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

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

package/packs/bmad/prompts/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`.

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-1-classification.md

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

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

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

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

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