substrate-ai 0.1.9 → 0.1.11

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://github.com/user-attachments/assets/622dd577-2814-4657-bb28-112ed272486d" alt="Substrate — Autonomous Software Development Pipeline" />
+  <img src="https://raw.githubusercontent.com/johnplanow/substrate/main/assets/substrate-header.png" alt="Substrate — Autonomous Software Development Pipeline" />
 </p>
 
 # Substrate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,6 @@
   "bin": {
     "substrate": "./dist/cli/index.js"
   },
-  "readme": "README.npm.md",
   "main": "./dist/index.js",
   "exports": {
     ".": {
@@ -40,12 +39,12 @@
     "dist/**/*.d.ts",
     "dist/**/*.json",
     "dist/cli/templates",
-    "README.md",
-    "README.npm.md"
+    "packs",
+    "README.md"
   ],
   "scripts": {
     "build": "tsdown",
-    "postbuild": "cp -r src/cli/templates dist/cli/templates && sed 's|assets/substrate-header.png|https://github.com/user-attachments/assets/622dd577-2814-4657-bb28-112ed272486d|' README.md > README.npm.md",
+    "postbuild": "cp -r src/cli/templates dist/cli/templates",
     "dev": "tsx watch src/cli/index.ts",
     "test": "vitest run --coverage",
     "test:watch": "vitest",

package/packs/bmad/constraints/code-review.yaml

@@ -0,0 +1,59 @@
+- name: minimum-three-issues
+  description: At least 3 specific issues must be found in every review
+  severity: required
+  check: issue_list contains at least 3 entries
+
+- name: maximum-ten-issues
+  description: If fewer than 10 issues found, re-examine before finalizing
+  severity: recommended
+  check: issue_list contains between 3 and 10 entries or reviewer has documented re-examination
+
+- name: adversarial-framing
+  description: Review must actively seek problems, not confirm correctness
+  severity: required
+  check: Review posture is "find what is wrong" not "validate what is right"
+
+- name: ac-validation-required
+  description: Every acceptance criterion must be validated against implementation
+  severity: required
+  check: Each AC has IMPLEMENTED, PARTIAL, or MISSING determination
+
+- name: task-completion-audit
+  description: Every task marked [x] must be verified as actually done
+  severity: required
+  check: Each [x] task has evidence of actual implementation
+
+- name: git-reality-check
+  description: Story File List must be cross-referenced with actual git changes
+  severity: required
+  check: git status and git diff output compared to story File List
+
+- name: false-claims-are-critical
+  description: Tasks or files claimed done/changed but with no git evidence are CRITICAL findings
+  severity: required
+  check: Any story claim without git evidence is flagged as high or critical
+
+- name: test-quality-check
+  description: Tests must have real assertions, not placeholder expectations
+  severity: required
+  check: Test files reviewed for meaningful assertions vs placeholder stubs
+
+- name: security-review
+  description: Code must be reviewed for injection risks, missing validation, auth issues
+  severity: required
+  check: Security audit performed on all implementation files
+
+- name: verdict-criteria
+  description: Verdict must match issue severity distribution
+  severity: required
+  check: approve only if no CRITICAL/HIGH; changes_requested if MEDIUM/HIGH; blocked if CRITICAL
+
+- name: no-bmad-folder-review
+  description: _bmad/ and _bmad-output/ folders must not be reviewed
+  severity: required
+  check: Review scope excludes _bmad/, _bmad-output/, .cursor/, .windsurf/, .claude/
+
+- name: location-required-for-issues
+  description: Every issue must have a specific file and line reference
+  severity: recommended
+  check: Each issue in issue_list has a location field with file:line reference

package/packs/bmad/constraints/create-story.yaml

@@ -0,0 +1,99 @@
+- name: story-has-user-story
+  description: Story must have a user story statement with As a/I want/so that
+  severity: required
+  check: Story section contains As a, I want, so that
+
+- name: acs-in-bdd-format
+  description: All acceptance criteria must use Given/When/Then format
+  severity: required
+  check: Each AC has Given, When, Then keywords
+
+- name: at-least-three-acs
+  description: Story must have at least 3 acceptance criteria
+  severity: required
+  check: Count of ACs >= 3
+
+- name: tasks-map-to-acs
+  description: Each task must reference at least one AC
+  severity: required
+  check: Each task has an AC annotation referencing an AC number
+
+- name: tasks-are-granular
+  description: Tasks should be implementable in 2-4 hours with subtasks
+  severity: recommended
+  check: Tasks with significant scope have subtasks
+
+- name: dev-notes-present
+  description: Dev Notes section must have architecture constraints
+  severity: required
+  check: Dev Notes section exists and is non-empty
+
+- name: esm-imports-noted
+  description: Dev Notes must mention ESM import requirements if TypeScript project
+  severity: recommended
+  check: Dev Notes mentions .js extension requirement for ESM imports
+
+- name: test-requirements-specified
+  description: Dev Notes should specify test framework and patterns
+  severity: recommended
+  check: Dev Notes has Testing Requirements or similar section
+
+- name: file-structure-specified
+  description: Dev Notes should specify where new files go
+  severity: recommended
+  check: Dev Notes references file paths or directory structure
+
+- name: no-vague-tasks
+  description: Tasks must be specific and implementable not vague
+  severity: required
+  check: No task descriptions contain only implement, add, create without specifics
+
+- name: story-status-ready-for-dev
+  description: Story status must be set to ready-for-dev when complete
+  severity: required
+  check: Status field equals ready-for-dev
+
+- name: sprint-status-updated
+  description: Sprint status yaml must be updated to ready-for-dev
+  severity: required
+  check: development_status story_key equals ready-for-dev in sprint-status.yaml
+
+- name: no-copy-paste-from-epics
+  description: Story must add context beyond what is in epics
+  severity: required
+  check: Dev Notes contains architecture/technical content not present in epic source
+
+- name: previous-story-learnings-applied
+  description: If previous story exists learnings should be reflected
+  severity: recommended
+  check: Dev Notes references previous story findings when story_num > 1
+
+- name: acceptance-criteria-testable
+  description: ACs must be testable with a clear pass/fail condition
+  severity: required
+  check: Each AC has a concrete measurable outcome in Then clause
+
+- name: no-ambiguous-requirements
+  description: Requirements must be specific enough to implement without clarification
+  severity: required
+  check: No AC or task contains etc or and so on without specification
+
+- name: dev-agent-record-present
+  description: Story must have Dev Agent Record section
+  severity: required
+  check: Story has Dev Agent Record section with subsections
+
+- name: file-list-section-present
+  description: Story must have File List section in Dev Agent Record
+  severity: required
+  check: Dev Agent Record has File List subsection
+
+- name: change-log-section-present
+  description: Story must have Change Log section
+  severity: recommended
+  check: Story has Change Log section
+
+- name: story-key-matches-filename
+  description: Story key derived from filename must match epic/story numbers
+  severity: required
+  check: Filename pattern N-N-title.md matches epic_num and story_num in content

package/packs/bmad/constraints/dev-story.yaml

@@ -0,0 +1,64 @@
+- name: sequential-task-execution
+  description: Tasks must be executed in the exact order listed in the story file
+  severity: required
+  check: Implementation follows task order without skipping
+
+- name: red-green-refactor
+  description: Tests must be written and fail before implementation code is written
+  severity: required
+  check: Tests exist and were confirmed failing before implementation
+
+- name: tests-pass-before-complete
+  description: All tests must pass before marking a task complete
+  severity: required
+  check: Full test suite passes before checkbox is marked [x]
+
+- name: no-regression-allowed
+  description: No existing tests may be broken by implementation
+  severity: required
+  check: Full test suite passes after each task implementation
+
+- name: halt-on-new-dependency
+  description: New dependencies beyond story spec require user approval before proceeding
+  severity: required
+  check: Agent stops and requests approval when new dependency needed
+
+- name: halt-on-repeated-failure
+  description: Three consecutive implementation failures require guidance
+  severity: required
+  check: Agent halts after 3 failures on same task
+
+- name: permitted-sections-only
+  description: Only permitted story sections may be modified
+  severity: required
+  check: Only Tasks/Subtasks, Dev Agent Record, File List, Change Log, Status are modified
+
+- name: no-extra-features
+  description: Implementation must match exactly what task specifies, no more
+  severity: required
+  check: No functionality implemented beyond task/subtask scope
+
+- name: file-list-complete
+  description: File List must include every new, modified, or deleted file
+  severity: required
+  check: Every file touched is listed in Dev Agent Record -> File List
+
+- name: completion-notes-required
+  description: Dev Agent Record must have completion notes describing what was implemented
+  severity: required
+  check: Completion Notes section is non-empty when story is complete
+
+- name: all-acs-satisfied
+  description: Every acceptance criterion must be satisfied before status can be review
+  severity: required
+  check: All ACs verified against implementation before status = review
+
+- name: status-review-on-completion
+  description: Story status must be set to review when all tasks done
+  severity: required
+  check: Status field equals "review" after completion
+
+- name: change-log-entry
+  description: Change Log must have at least one entry describing the implementation
+  severity: required
+  check: Change Log section has at least one dated entry

package/packs/bmad/manifest.yaml

@@ -0,0 +1,43 @@
+name: bmad
+version: 1.0.0
+description: BMAD methodology for autonomous software development
+
+phases:
+  - name: analysis
+    description: Product discovery and brief creation
+    entryGates: []
+    exitGates: [product-brief-complete]
+    artifacts: [product-brief]
+  - name: planning
+    description: PRD and requirements generation
+    entryGates: [product-brief-complete]
+    exitGates: [prd-complete]
+    artifacts: [prd]
+  - name: solutioning
+    description: Architecture and epic/story breakdown
+    entryGates: [prd-complete]
+    exitGates: [architecture-complete, stories-complete, readiness-check]
+    artifacts: [architecture, epics, stories]
+  - name: implementation
+    description: Code generation, testing, and review
+    entryGates: [stories-complete]
+    exitGates: [all-stories-shipped]
+    artifacts: [code, tests]
+
+prompts:
+  analysis: prompts/analysis.md
+  planning: prompts/planning.md
+  architecture: prompts/architecture.md
+  story-generation: prompts/story-generation.md
+  create-story: prompts/create-story.md
+  dev-story: prompts/dev-story.md
+  code-review: prompts/code-review.md
+  fix-story: prompts/fix-story.md
+
+constraints:
+  create-story: constraints/create-story.yaml
+  dev-story: constraints/dev-story.yaml
+  code-review: constraints/code-review.yaml
+
+templates:
+  story: templates/story.md

package/packs/bmad/prompts/analysis.md

@@ -0,0 +1,61 @@
+# BMAD Compiled Analysis Agent
+
+## Context (pre-assembled by pipeline)
+
+### Project Concept
+{{concept}}
+
+---
+
+## Mission
+
+Analyze the project concept above and produce a structured **Product Brief** that captures the essential product definition. Think like a senior business analyst conducting market analysis, user research, and feasibility assessment.
+
+## Instructions
+
+1. **Analyze the concept deeply** before generating output:
+   - What problem does this solve? Who experiences this problem most acutely?
+   - What existing solutions exist? Why do they fall short?
+   - What are the real technical constraints and market dynamics?
+   - What would make this succeed vs. fail?
+
+2. **Generate each field with research-grade depth:**
+   - `problem_statement`: A clear, specific articulation of the problem (minimum 2-3 sentences). Ground it in user pain, not technology. Include the impact of the problem remaining unsolved.
+   - `target_users`: Specific user segments (not generic labels). Include role, context, and why they care. Minimum 2 distinct segments.
+   - `core_features`: Capabilities that directly address the problem statement. Each feature should be a concrete capability, not a vague category. Prioritize by user impact.
+   - `success_metrics`: Measurable outcomes tied to user value and business objectives. Include both leading indicators (engagement, adoption) and lagging indicators (retention, revenue). Be specific enough to measure.
+   - `constraints`: Technical limitations, regulatory requirements, budget boundaries, timeline pressures, platform restrictions, or integration requirements. Omit if genuinely none exist.
+
+3. **Quality bar**: Every field should contain enough detail that a product manager could begin writing a PRD from this brief alone. Avoid placeholder text, generic statements, or single-word items.
+
+4. **Amendment awareness**: If amendment context from a parent run is provided below, refine and build upon existing decisions rather than starting from scratch. Identify what changes, what stays, and what new elements the amendment introduces.
+
+## Output Contract
+
+Emit ONLY this YAML block as your final output — no other text.
+
+**CRITICAL**: All array items MUST be plain strings, NOT objects/maps. Write each item as a single descriptive string on one line.
+
+```yaml
+result: success
+product_brief:
+  problem_statement: "A clear articulation of the problem in 2-3 sentences."
+  target_users:
+    - "Software developers who work in terminal environments and want habit tracking"
+    - "DevOps engineers who need to maintain daily operational checklists"
+  core_features:
+    - "CLI command to register, check-off, and view daily habits with streak tracking"
+    - "Local SQLite storage with export to JSON/CSV for portability"
+  success_metrics:
+    - "Daily active usage rate >60% among onboarded users within 30 days"
+    - "Streak completion rate >40% across all tracked habits"
+  constraints:
+    - "CLI-only interface limits audience to terminal-comfortable users"
+    - "Must work offline with local storage, no cloud dependency"
+```
+
+If you cannot produce a valid product brief:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/architecture.md

@@ -0,0 +1,71 @@
+# BMAD Compiled Architecture Agent
+
+## Context (pre-assembled by pipeline)
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+---
+
+## Mission
+
+Produce concrete **architecture decisions** that translate the requirements above into a buildable technical design. Think like a pragmatic senior architect — choose boring technology that ships, not cutting-edge technology that impresses.
+
+## Instructions
+
+1. **Make concrete decisions, not suggestions:**
+   - Each decision is a key-value pair capturing one architectural concern
+   - The `key` identifies WHAT is being decided (e.g., "api-style", "auth-strategy", "state-management", "deployment-target")
+   - The `value` states the CHOICE (e.g., "REST with OpenAPI 3.1", "JWT with refresh tokens", "React Context + useReducer", "Docker on AWS ECS")
+   - The `rationale` explains WHY this choice over alternatives (optional but strongly recommended)
+
+2. **Cover these architectural concerns at minimum:**
+   - **System architecture**: Monolith, modular monolith, microservices, or serverless
+   - **API design**: REST, GraphQL, gRPC, or hybrid
+   - **Data storage**: Database engine, schema strategy, migration approach
+   - **Authentication/authorization**: Strategy and implementation approach
+   - **Project structure**: Directory layout, module boundaries, dependency rules
+   - **Error handling**: Strategy for errors, logging, monitoring
+   - **Testing strategy**: Unit/integration/E2E split, framework choices
+
+3. **Align with requirements:**
+   - Every `must` functional requirement should be architecturally supportable
+   - NFRs (performance, security, scalability) should directly inform decisions
+   - Tech stack choices from planning should be respected unless there's a strong reason to deviate
+
+4. **Use the `category` field** to group related decisions:
+   - `infrastructure`: deployment, hosting, CI/CD
+   - `backend`: API, database, auth, services
+   - `frontend`: UI framework, state, routing
+   - `crosscutting`: logging, error handling, testing, security
+
+5. **Amendment awareness**: If amendment context from a parent run is provided below, build upon the existing architecture. Add new decisions for new capabilities, refine existing decisions where the amendment changes requirements, and preserve decisions that remain valid.
+
+## 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. This prevents YAML parse errors from colons, special characters, or multi-line values. Keep each value on a single line.
+
+```yaml
+result: success
+architecture_decisions:
+  - category: "backend"
+    key: "api-style"
+    value: "REST with OpenAPI 3.1 spec"
+    rationale: "Industry standard, excellent tooling, team familiarity"
+  - category: "backend"
+    key: "database"
+    value: "SQLite with better-sqlite3 driver"
+    rationale: "Zero-config local storage, perfect for CLI tools"
+  - category: "crosscutting"
+    key: "testing-strategy"
+    value: "Vitest for unit and integration, no E2E needed for CLI"
+    rationale: "Fast execution, native ESM support, compatible with TypeScript"
+```
+
+If you cannot produce valid architecture output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/code-review.md

@@ -0,0 +1,80 @@
+# BMAD Compiled Code-Review Agent
+
+## Context (pre-assembled by pipeline)
+
+### Story File Content
+{{story_content}}
+
+### Git Diff
+{{git_diff}}
+
+### Previous Review Findings
+{{previous_findings}}
+
+### Architecture Constraints
+{{arch_constraints}}
+
+---
+
+## Mission
+
+Adversarial code review. Find what's wrong. Validate story claims against actual implementation.
+
+## Instructions
+
+1. **Parse the story file** to extract:
+   - Acceptance Criteria (AC1, AC2, etc.)
+   - Tasks with their completion status (`[x]` or `[ ]`)
+   - Dev Notes and File List
+
+2. **Review the git diff** for:
+   - Files changed vs files listed in the story File List
+   - Whether each AC is actually implemented
+   - Whether each `[x]` task is actually done
+
+3. **Execute adversarial review** across 4 dimensions:
+   - **AC Validation** — Is each acceptance criterion implemented?
+   - **Task Audit** — Tasks marked `[x]` that aren't done are BLOCKER issues
+   - **Code Quality** — Security, error handling, edge cases, maintainability
+   - **Test Quality** — Real assertions, not placeholders or skipped tests
+
+4. **Severity classification:**
+   - **blocker** — Task `[x]` but not implemented; security vulnerability; data loss risk
+   - **major** — AC not implemented; false claims; missing error handling on boundaries
+   - **minor** — Style; documentation gap; naming; low-risk edge case
+
+## Output Contract
+
+After completing the review, emit ONLY this YAML block — no other text:
+
+```yaml
+verdict: SHIP_IT
+issues: 0
+issue_list: []
+```
+
+Or if issues were found:
+
+```yaml
+verdict: NEEDS_MINOR_FIXES
+issues: 3
+issue_list:
+  - severity: major
+    description: "AC2 not implemented — getConstraints() always returns []"
+    file: "src/modules/foo/foo.ts"
+    line: 42
+  - severity: minor
+    description: "Missing JSDoc on exported function"
+    file: "src/modules/foo/foo.ts"
+  - severity: minor
+    description: "Variable name `d` should be more descriptive"
+    file: "src/modules/foo/foo.ts"
+    line: 15
+```
+
+**IMPORTANT**: `issues` must equal the number of items in `issue_list`.
+
+**Verdict rules:**
+- `SHIP_IT` — zero blocker/major issues (minor issues acceptable)
+- `NEEDS_MINOR_FIXES` — minor issues only, or 1-2 major with no blockers
+- `NEEDS_MAJOR_REWORK` — any blocker issue, or 3+ major issues

package/packs/bmad/prompts/create-story.md

@@ -0,0 +1,64 @@
+# BMAD Compiled Create-Story Agent
+
+## Context (pre-assembled by pipeline)
+
+### Epic Scope
+{{epic_shard}}
+
+### Architecture Constraints
+{{arch_constraints}}
+
+### Previous Story Dev Notes
+{{prev_dev_notes}}
+
+### Story File Template
+{{story_template}}
+
+---
+
+## Mission
+
+Using the context above, write a complete, implementation-ready story file for story **{{story_key}}**.
+
+## Instructions
+
+1. **Parse the epic scope** to understand what this epic is building and where this story fits
+2. **Apply architecture constraints** — every constraint listed above is mandatory (file paths, import style, test framework, etc.)
+3. **Use previous dev notes** as guardrails — don't repeat mistakes, build on patterns that worked
+4. **Fill out the story template** with:
+   - A clear user story (As a / I want / So that)
+   - Acceptance criteria in BDD Given/When/Then format (minimum 3, maximum 8)
+   - Concrete tasks broken into 2–4 hour subtasks, each tied to specific ACs
+   - Dev Notes with file paths, import patterns, testing requirements
+5. **Apply the scope cap** — see Scope Cap Guidance below
+6. **Write the story file** to: `_bmad-output/implementation-artifacts/{{story_key}}-<kebab-title>.md`
+   - Status must be: `ready-for-dev`
+   - Dev Agent Record section must be present but left blank (to be filled by dev agent)
+
+## Scope Cap Guidance
+
+**Aim for 6-7 acceptance criteria and 7-8 tasks per story.**
+
+Each story will be implemented by an AI agent in a single pass. Stories with more than 7 ACs tend to exceed agent capabilities and require decomposition, adding latency and complexity to the pipeline.
+
+If the scope requires more than 7 ACs, split into multiple sequential stories (e.g., `7-1a: Core Setup`, `7-1b: Advanced Features`). Splitting is preferable to cramming too much scope into a single story.
+
+This is guidance, not enforcement — if the scope genuinely fits in a slightly larger story, use your judgment. The goal is to avoid stories that will predictably fail during implementation.
+
+## Output Contract
+
+After writing the story file, emit ONLY this YAML block as your final message — no other text:
+
+```yaml
+result: success
+story_file: <absolute path to the written story file>
+story_key: {{story_key}}
+story_title: <one-line title of the story>
+```
+
+If you cannot write the story file for any reason:
+
+```yaml
+result: failure
+error: <reason>
+```

package/packs/bmad/prompts/dev-story.md

@@ -0,0 +1,86 @@
+# BMAD Compiled Dev-Story Agent
+
+## Context (pre-assembled by pipeline)
+
+### Story File Content
+{{story_content}}
+
+{{task_scope}}
+
+{{prior_files}}
+
+{{files_in_scope}}
+
+{{project_context}}
+
+### Test Patterns
+{{test_patterns}}
+
+---
+
+## Mission
+
+Implement the story above completely. Follow tasks in exact order. Do not stop until all tasks are done.
+
+## Instructions
+
+1. **Parse the story file** to understand:
+   - Acceptance Criteria (AC1, AC2, etc.)
+   - Tasks/Subtasks (ordered list with `[ ]` checkboxes)
+   - Dev Notes (file paths, import patterns, test requirements)
+
+2. **Implement each task in order** (Red-Green-Refactor):
+   - Write failing tests first
+   - Make tests pass with minimal code
+   - Refactor while keeping tests green
+
+3. **After each task**:
+   - Verify tests pass
+   - Run the full test suite to check for regressions
+   - Mark the task `[x]` in the story file
+   - Update the story File List with all new/modified files
+
+4. **After all tasks complete**:
+   - Run the full test suite one final time
+   - Update story Status to `review`
+
+## CRITICAL: Output Contract Emission
+
+**You MUST emit the YAML output block (see Output Contract below) as the very last thing you produce.** The downstream pipeline depends on `files_modified` to generate scoped code-review diffs. If you exhaust your turns without emitting the YAML block, the pipeline cannot review your work properly.
+
+- If you are running low on turns, **stop implementation and emit the YAML block immediately** with whatever progress you have made. A partial `files_modified` list is far more valuable than none at all.
+- The YAML block must be the final output — no summary text, no emoji, no explanation after it.
+- **Narrating about the YAML block is NOT the same as emitting it.** Do not say "the YAML has been emitted" — actually emit the literal YAML block starting with `result:`.
+
+## HALT Conditions (stop and report as failed)
+
+- New dependency required beyond story spec
+- 3 consecutive implementation failures with no progress
+- Story requirements are ambiguous with no way to resolve
+
+## Output Contract
+
+After completing all tasks (or hitting a HALT condition), emit ONLY this YAML block — no other text:
+
+```yaml
+result: success
+ac_met:
+  - AC1
+  - AC2
+ac_failures: []
+files_modified:
+  - <absolute path to modified file>
+tests: pass
+```
+
+If a HALT condition was hit:
+
+```yaml
+result: failed
+ac_met: []
+ac_failures:
+  - <which AC could not be met>
+files_modified: []
+tests: fail
+notes: <reason for failure>
+```

package/packs/bmad/prompts/fix-story.md

@@ -0,0 +1,65 @@
+# BMAD Compiled Fix-Story Agent
+
+## Context (pre-assembled by pipeline)
+
+### Story File Content
+{{story_content}}
+
+### Review Feedback
+{{review_feedback}}
+
+### Architecture Constraints
+{{arch_constraints}}
+
+---
+
+## Mission
+
+Fix the issues identified in the code review above. Address every issue listed in the review feedback.
+
+## Instructions
+
+1. **Parse the review feedback** to understand:
+   - The verdict (NEEDS_MINOR_FIXES or NEEDS_MAJOR_REWORK)
+   - Each issue's severity (blocker, major, minor)
+   - Each issue's description, file, and line number (if provided)
+
+2. **Fix issues in severity order**: blockers first, then major, then minor.
+
+3. **For each fix**:
+   - Make the code change
+   - Run relevant tests to verify the fix
+   - Ensure no regressions
+
+4. **After all fixes**:
+   - Run the full test suite
+   - Verify all issues from the review have been addressed
+
+## HALT Conditions (stop and report as failed)
+
+- Contradictory requirements between story and review feedback
+- 3 consecutive fix attempts with no progress
+- Fix requires architectural changes beyond the story scope
+
+## Output Contract
+
+After all fixes are applied (or a HALT condition is hit), emit ONLY this YAML block:
+
+```yaml
+result: success
+fixes_applied:
+  - <description of fix>
+files_modified:
+  - <absolute path to modified file>
+tests: pass
+```
+
+If a HALT condition was hit:
+
+```yaml
+result: failed
+fixes_applied: []
+files_modified: []
+tests: fail
+notes: <reason for failure>
+```

package/packs/bmad/prompts/planning.md

@@ -0,0 +1,91 @@
+# BMAD Compiled Planning Agent
+
+## Context (pre-assembled by pipeline)
+
+### Product Brief (from Analysis Phase)
+{{product_brief}}
+
+---
+
+## Mission
+
+Transform the product brief above into a structured **Product Requirements Document (PRD)** — the complete specification that drives architecture, epic creation, and implementation. Think like a veteran product manager who ships products, not one who writes documents.
+
+## Instructions
+
+1. **Derive functional requirements from the product brief:**
+   - 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, not implementation details ("Users can filter by date range" not "Add a date picker component")
+
+2. **Define non-functional requirements:**
+   - Each NFR must have a category (performance, security, scalability, accessibility, reliability, etc.)
+   - Be concrete: "API responses under 200ms at p95" not "System should be fast"
+   - Minimum 2 NFRs covering different categories
+
+3. **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 — they tell the human story behind the FRs
+
+4. **Specify the tech stack:**
+   - Key-value pairs mapping technology concerns to specific choices
+   - Use real, current technologies — do not fabricate frameworks or versions
+   - Cover at minimum: language, framework, database, testing
+   - Choices should align with the product brief constraints
+
+5. **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
+
+6. **Define out-of-scope items** to prevent scope creep — what this product explicitly does NOT do in its initial version.
+
+7. **Amendment awareness**: If amendment context from a parent run is provided below, evolve the existing requirements rather than replacing them wholesale. Add new FRs for new scope, adjust priorities where the amendment changes emphasis, and note any FRs that the amendment renders obsolete.
+
+## 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. This prevents YAML parse errors from colons or special characters. Keep each value on a single line. Array items must be plain strings, NOT objects.
+
+```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
+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"
+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"
+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 planning output:
+
+```yaml
+result: failed
+```

package/packs/bmad/prompts/story-generation.md

@@ -0,0 +1,84 @@
+# BMAD Compiled Story Generation Agent
+
+## Context (pre-assembled by pipeline)
+
+### Requirements (from Planning Phase)
+{{requirements}}
+
+### Architecture Decisions (from Solutioning Phase)
+{{architecture_decisions}}
+
+### Gap Analysis (retry context — may be empty)
+{{gap_analysis}}
+
+---
+
+## Mission
+
+Break down the requirements and architecture above into **epics and stories** — the work breakdown structure that drives implementation. Think like a product manager and scrum master working together: epics organized by user value, stories sized for a single developer in a single sprint.
+
+## Instructions
+
+1. **Organize epics by user value, never by technical layer:**
+   - GOOD: "User Authentication & Onboarding", "Dashboard & Analytics", "Content Management"
+   - BAD: "Database Setup", "API Development", "Frontend Components"
+   - Each epic must be independently valuable — a user should benefit from just that epic being complete
+   - No forward dependencies — Epic N should not require Epic N+1 to be useful
+
+2. **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 it matters. Include enough context to start coding.
+   - `acceptance_criteria`: Specific, testable conditions. Minimum 1 per story. Use concrete language ("User sees error message when password is under 8 characters") not vague language ("Error handling works")
+   - `priority`: must (MVP-critical), should (high-value post-MVP), could (nice-to-have)
+
+3. **Ensure full FR coverage:**
+   - Every functional requirement from the planning phase must be addressed by at least one story
+   - If gap analysis is provided above, it lists specific uncovered requirements — generate stories to cover them
+   - Cross-reference: scan each FR and verify you have a story that addresses it
+
+4. **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
+   - Database tables, API endpoints, and infrastructure are created in the epic where they are FIRST NEEDED
+
+5. **Size stories appropriately:**
+   - Each story should be completable by one developer in 1-3 days
+   - If a story feels too large, split it into multiple stories within the same epic
+   - If an epic has more than 8 stories, consider splitting the epic
+
+6. **Amendment awareness**: If amendment context from a parent run is provided below, generate stories for the NEW scope introduced by the amendment. Do not regenerate stories for unchanged requirements.
+
+## 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. This prevents YAML parse errors from colons or special characters. Keep values on single lines. Acceptance criteria items must be plain strings.
+
+```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 story output:
+
+```yaml
+result: failed
+```

package/packs/bmad/templates/story.md

@@ -0,0 +1,37 @@
+# Story {epic_num}.{story_num}: {Title}
+
+Status: draft
+
+## Story
+
+As a {role},
+I want {capability},
+so that {benefit}.
+
+## Acceptance Criteria
+
+### AC1: {Title}
+**Given** {context}
+**When** {action}
+**Then** {outcome}
+
+## Tasks / Subtasks
+
+- [ ] Task 1: {description} (AC: #1)
+  - [ ] {subtask}
+
+## Dev Notes
+
+### Architecture Constraints
+- {constraint}
+
+### Testing Requirements
+- {requirement}
+
+## Dev Agent Record
+
+### Agent Model Used
+### Completion Notes List
+### File List
+
+## Change Log

package/README.npm.md

@@ -1,206 +0,0 @@
-<p align="center">
-  <img src="https://github.com/user-attachments/assets/622dd577-2814-4657-bb28-112ed272486d" alt="Substrate — Autonomous Software Development Pipeline" />
-</p>
-
-# Substrate
-
-Autonomous software development pipeline powered by multi-agent orchestration. Substrate takes a project idea from concept through analysis, planning, architecture, implementation, and code review — coordinating CLI-based AI agents (Claude Code, Codex, Gemini CLI) to do the work.
-
-Substrate follows a modular monolith pattern running as a single Node.js process. The orchestrator never calls LLMs directly — all intelligent work is delegated to CLI agents running as child processes in isolated git worktrees. The autonomous pipeline compiles BMAD methodology workflows into token-efficient agent dispatches.
-
-## Prerequisites
-
-- **Node.js** 22.0.0 or later
-- **git** 2.20 or later
-- At least one supported AI CLI agent installed:
-  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
-  - [Codex CLI](https://github.com/openai/codex) (`codex`)
-  - Gemini CLI (`gemini`)
-
-## Installation
-
-Install as a project dependency:
-
-```bash
-npm install substrate-ai
-```
-
-Or install globally:
-
-```bash
-npm install -g substrate-ai
-```
-
-Verify the installation:
-
-```bash
-npx substrate --version   # project install
-substrate --version        # global install
-```
-
-> Examples below use `[npx] substrate` — include `npx` for project installs, omit for global.
-
-## Quick Start
-
-### Autonomous Pipeline (recommended)
-
-Got an idea? Substrate can take it from concept to working code.
-
-1. **Brainstorm** — explore your idea with a multi-persona AI session:
-
-```bash
-[npx] substrate brainstorm
-```
-
-2. **Initialize the pipeline** — set up the methodology pack and decision store:
-
-```bash
-[npx] substrate auto init
-```
-
-3. **Run the full pipeline** — analysis, planning, solutioning, and implementation:
-
-```bash
-[npx] substrate auto run
-```
-
-Substrate walks through the entire software development lifecycle autonomously:
-- **Analysis** — generates a product brief from your brainstorm
-- **Planning** — creates a PRD with requirements
-- **Solutioning** — produces architecture, epics, and stories
-- **Implementation** — dispatches agents to build, test, and code-review each story
-
-You can start from any phase or resume an interrupted run:
-
-```bash
-[npx] substrate auto run --from solutioning   # Skip to a specific phase
-[npx] substrate auto resume                    # Pick up where you left off
-[npx] substrate auto status                    # Check pipeline progress
-```
-
-### Pick Up an Existing BMAD Project
-
-Already have a project with BMAD artifacts (vanilla BMAD or the Beads-based ai-toolkit)? Substrate can pick up the remaining implementation work. It reads one directory — `_bmad-output/` — and doesn't care which tool created it.
-
-**What Substrate needs from your project:**
-
-| File | Required? | Purpose |
-|------|-----------|---------|
-| `_bmad-output/planning-artifacts/epics.md` | Yes | Parsed into per-epic context shards |
-| `_bmad-output/planning-artifacts/architecture.md` | Yes | Tech stack and constraints for agents |
-| `_bmad-output/implementation-artifacts/*.md` | Optional | Existing story files — Substrate skips create-story for any it finds |
-| `package.json` | Optional | Test framework detection |
-
-**Three commands:**
-
-```bash
-npm install substrate-ai
-[npx] substrate auto init                          # Seeds context from _bmad-output/
-[npx] substrate auto run --stories 5-3,5-4,6-1    # Only the unfinished story keys
-```
-
-For each story, Substrate runs: **create-story** (skipped if story file exists) → **dev-story** (implement) → **code-review** (adversarial review). Non-conflicting stories run in parallel automatically.
-
-Substrate does not read `sprint-status.yaml` or `.beads/` — you decide what's left by choosing which story keys to pass.
-
-## Supported Agents
-
-| Agent ID | CLI Tool | Billing |
-|----------|----------|---------|
-| `claude-code` | Claude Code | Subscription (Max) or API key |
-| `codex` | Codex CLI | Subscription (ChatGPT Plus/Pro) or API key |
-| `gemini` | Gemini CLI | Subscription or API key |
-
-## Commands
-
-### Pipeline
-
-| Command | Description |
-|---------|-------------|
-| `substrate brainstorm` | Interactive multi-persona ideation session |
-| `substrate auto init` | Initialize methodology pack for autonomous pipeline |
-| `substrate auto run` | Run the full pipeline (analysis → implement) |
-| `substrate auto run --from <phase>` | Start from a specific phase |
-| `substrate auto resume` | Resume an interrupted pipeline run |
-| `substrate auto status` | Show pipeline run status |
-
-### Monitoring
-
-| Command | Description |
-|---------|-------------|
-| `substrate monitor status` | View task metrics and agent performance |
-| `substrate monitor report` | Generate a detailed performance report |
-| `substrate cost-report` | View cost and token usage summary |
-
-### Setup
-
-| Command | Description |
-|---------|-------------|
-| `substrate init` | Initialize project configuration |
-| `substrate --help` | Show all available commands |
-
-## Configuration
-
-Substrate reads configuration from `.substrate/config.yaml` in your project root. Run `[npx] substrate init` to generate a default config.
-
-## Development
-
-```bash
-# Clone and install
-git clone https://github.com/johnplanow/substrate.git
-cd substrate
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Development mode (watch)
-npm run dev
-
-# Type check
-npm run typecheck
-
-# Lint
-npm run lint
-```
-
-## Manual Task Graphs
-
-For fine-grained control, you can define exactly what agents should do in a YAML task graph:
-
-```yaml
-version: "1"
-session:
-  name: "my-tasks"
-tasks:
-  write-tests:
-    name: "Write unit tests"
-    prompt: |
-      Look at the src/utils/ directory.
-      Write comprehensive unit tests for all exported functions.
-    type: testing
-    agent: claude-code
-  update-docs:
-    name: "Update README"
-    prompt: |
-      Read the README.md and verify it accurately describes
-      the project. Fix any inaccuracies.
-    type: docs
-    agent: codex
-    depends_on:
-      - write-tests
-```
-
-```bash
-[npx] substrate start --graph tasks.yaml              # Execute the graph
-[npx] substrate plan --graph tasks.yaml               # Preview without running
-```
-
-Tasks without dependencies run in parallel. Each agent gets its own isolated git worktree.
-
-## License
-
-MIT