bmad-method 6.0.0-alpha.3 → 6.0.0-alpha.5

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md

@@ -3,21 +3,97 @@
 **Author:** {{user_name}}
 **Date:** {{date}}
 **Project Level:** {{project_level}}
-**Project Type:** {{project_type}}
+**Change Type:** {{change_type}}
 **Development Context:** {{development_context}}
 
 ---
 
-## Source Tree Structure
+## Context
 
-{{source_tree}}
+### Available Documents
+
+{{loaded_documents_summary}}
+
+### Project Stack
+
+{{project_stack_summary}}
+
+### Existing Codebase Structure
+
+{{existing_structure_summary}}
+
+---
+
+## The Change
+
+### Problem Statement
+
+{{problem_statement}}
+
+### Proposed Solution
+
+{{solution_overview}}
+
+### Scope
+
+**In Scope:**
+
+{{scope_in}}
+
+**Out of Scope:**
+
+{{scope_out}}
 
 ---
 
-## Technical Approach
+## Implementation Details
+
+### Source Tree Changes
+
+{{source_tree_changes}}
+
+### Technical Approach
 
 {{technical_approach}}
 
+### Existing Patterns to Follow
+
+{{existing_patterns}}
+
+### Integration Points
+
+{{integration_points}}
+
+---
+
+## Development Context
+
+### Relevant Existing Code
+
+{{existing_code_references}}
+
+### Dependencies
+
+**Framework/Libraries:**
+
+{{framework_dependencies}}
+
+**Internal Modules:**
+
+{{internal_dependencies}}
+
+### Configuration Changes
+
+{{configuration_changes}}
+
+### Existing Conventions (Brownfield)
+
+{{existing_conventions}}
+
+### Test Framework & Standards
+
+{{test_framework_info}}
+
 ---
 
 ## Implementation Stack
@@ -40,7 +116,47 @@
 
 ## Implementation Guide
 
-{{implementation_guide}}
+### Setup Steps
+
+{{setup_steps}}
+
+### Implementation Steps
+
+{{implementation_steps}}
+
+### Testing Strategy
+
+{{testing_strategy}}
+
+### Acceptance Criteria
+
+{{acceptance_criteria}}
+
+---
+
+## Developer Resources
+
+### File Paths Reference
+
+{{file_paths_complete}}
+
+### Key Code Locations
+
+{{key_code_locations}}
+
+### Testing Locations
+
+{{testing_locations}}
+
+### Documentation to Update
+
+{{documentation_updates}}
+
+---
+
+## UX/UI Considerations
+
+{{ux_ui_considerations}}
 
 ---
 
@@ -52,4 +168,14 @@
 
 ## Deployment Strategy
 
-{{deployment_strategy}}
+### Deployment Steps
+
+{{deployment_steps}}
+
+### Rollback Plan
+
+{{rollback_plan}}
+
+### Monitoring
+
+{{monitoring_approach}}

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md

@@ -1,22 +1,32 @@
-# Story: {{story_title}}
+# Story {{N}}.{{M}}: {{story_title}}
 
-Status: Draft
+**Status:** Draft
 
-## Story
+---
 
-As a {{role}},
+## User Story
+
+As a {{user_type}},
 I want {{capability}},
-so that {{benefit}}.
+So that {{value_benefit}}.
+
+---
 
 ## Acceptance Criteria
 
-{{acceptance_criteria}}
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
 
-## Tasks / Subtasks
+**And** {{additional_criteria}}
 
-{{tasks_subtasks}}
+---
+
+## Implementation Details
+
+### Tasks / Subtasks
 
-## Dev Notes
+{{tasks_subtasks}}
 
 ### Technical Summary
 
@@ -24,20 +34,34 @@ so that {{benefit}}.
 
 ### Project Structure Notes
 
-- Files to modify: {{files_to_modify}}
-- Expected test locations: {{test_locations}}
-- Estimated effort: {{story_points}} story points ({{time_estimate}})
+- **Files to modify:** {{files_to_modify}}
+- **Expected test locations:** {{test_locations}}
+- **Estimated effort:** {{story_points}} story points ({{time_estimate}})
+- **Prerequisites:** {{dependencies}}
 
-### References
+### Key Code References
 
-- **Tech Spec:** See tech-spec.md for detailed implementation
-- **Architecture:** {{architecture_references}}
+{{existing_code_references}}
 
-## Dev Agent Record
+---
+
+## Context References
+
+**Tech-Spec:** [tech-spec.md](../tech-spec.md) - Primary context document containing:
+
+- Brownfield codebase analysis (if applicable)
+- Framework and library details with versions
+- Existing patterns to follow
+- Integration points and dependencies
+- Complete implementation guidance
 
-### Context Reference
+**Architecture:** {{architecture_references}}
 
-<!-- Path(s) to story context XML will be added here by context workflow -->
+<!-- Additional context XML paths will be added here if story-context workflow is run -->
+
+---
+
+## Dev Agent Record
 
 ### Agent Model Used
 
@@ -47,10 +71,20 @@ so that {{benefit}}.
 
 <!-- Will be populated during dev-story execution -->
 
-### Completion Notes List
+### Completion Notes
 
 <!-- Will be populated during dev-story execution -->
 
-### File List
+### Files Modified
 
 <!-- Will be populated during dev-story execution -->
+
+### Test Results
+
+<!-- Will be populated during dev-story execution -->
+
+---
+
+## Review Notes
+
+<!-- Will be populated during code review -->

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml

@@ -1,5 +1,5 @@
-# Technical Specification Workflow (Level 0)
-name: tech-spec-sm
+# Technical Specification
+name: tech-spec
 description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed."
 author: "BMad"
 
@@ -13,6 +13,13 @@ document_output_language: "{config_source}:document_output_language"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 
+# Runtime variables (captured during workflow execution)
+project_level: runtime-captured
+project_type: runtime-captured
+development_context: runtime-captured
+change_type: runtime-captured
+field_type: runtime-captured
+
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec"
 instructions: "{installed_path}/instructions.md"
@@ -36,6 +43,20 @@ recommended_inputs:
   - bug_report: "Bug description or issue ticket"
   - feature_request: "Brief feature description"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle:

package/src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md

@@ -1,4 +1,4 @@
-# Decision Architecture
+# Architecture
 
 ## Executive Summary
 

package/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md

@@ -9,6 +9,8 @@
 <critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow replaces architecture with a conversation-driven approach</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+<critical>ELICITATION POINTS: After completing each major architectural decision area (identified by template-output tags for decision_record, project_structure, novel_pattern_designs, implementation_patterns, and architecture_document), invoke advanced elicitation to refine decisions before proceeding</critical>
 
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">
 <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
@@ -35,7 +37,7 @@
   <check if="project_level < 3">
     <output>**Note: Level {{project_level}} Project**
 
-Decision Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
+The Detailed Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
 
 For Level {{project_level}}, we'll keep the architecture appropriately scoped.
 </output>
@@ -70,11 +72,11 @@ For Level {{project_level}}, we'll keep the architecture appropriately scoped.
 
 Decision Architecture works from your Product Requirements Document (PRD).
 
-Looking for: bmm-PRD.md, PRD.md, or product-requirements.md in {output_folder}
+Looking for: _PRD_, PRD.md, or prd/index.md + files in {output_folder}
 
 Please run the PRD workflow first to define your requirements.
 
-Run: `workflow prd`
+Architect: `create-prd`
 </output>
 <action>Exit workflow - PRD required</action>
 </check>
@@ -82,7 +84,7 @@ Run: `workflow prd`
 </step>
 
 <step n="1" goal="Load and understand project context">
-  <action>Load the PRD using fuzzy matching: {prd_file}</action>
+  <action>Load the PRD using fuzzy matching: {prd_file}, if the PRD is mulitple files in a folder, load the index file and all files associated with the PRD</action>
   <action>Load epics file using fuzzy matching: {epics_file}</action>
 
 <action>Check for UX specification using fuzzy matching:
@@ -96,7 +98,7 @@ Run: `workflow prd`
 <action>Extract and understand from PRD: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned
 </action>
 
-<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists)
+<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists) - Novel features
 </action>
 
 <action>Reflect understanding back to {user_name}:
@@ -135,8 +137,8 @@ I see {{epic_count}} epics with {{story_count}} total stories.
     </action>
   </check>
 
-<action>Search for relevant starter templates:
-<WebSearch>{{primary_technology}} starter template CLI create command latest 2024</WebSearch>
+<action>Search for relevant starter templates with websearch, examples:
+<WebSearch>{{primary_technology}} starter template CLI create command latest {date}</WebSearch>
 <WebSearch>{{primary_technology}} boilerplate generator latest options</WebSearch>
 </action>
 
@@ -206,7 +208,7 @@ I see {{epic_count}} epics with {{story_count}} total stories.
 
   <check if="no_starter_found_or_applicable">
     <action>Note: No standard starter template found for this project type.
-            Will need to make all architectural decisions explicitly.</action>
+            We will make all architectural decisions explicitly.</action>
   </check>
 
 <template-output>starter_template_decision</template-output>
@@ -285,34 +287,39 @@ Let's work through the remaining {{remaining_count}} decisions."
 <action>Present the decision based on mode:
 <check if="mode == 'EXPERT'">
 "{{Decision_Category}}: {{Specific_Decision}}
-Options: {{concise_option_list_with_tradeoffs}}
-Recommendation: {{recommendation}} for {{reason}}"
-</check>
 
-    <check if="mode == 'INTERMEDIATE'">
-      "Next decision: {{Human_Friendly_Category}}
+    Options: {{concise_option_list_with_tradeoffs}}
 
-       We need to choose {{Specific_Decision}}.
+    Recommendation: {{recommendation}} for {{reason}}"
 
-       Common options:
-       {{option_list_with_brief_explanations}}
+  </check>
 
-       For your project, {{recommendation}} would work well because {{reason}}."
-    </check>
+  <check if="mode == 'INTERMEDIATE'">
+    "Next decision: {{Human_Friendly_Category}}
 
-    <check if="mode == 'BEGINNER'">
-      "Let's talk about {{Human_Friendly_Category}}.
+      We need to choose {{Specific_Decision}}.
 
-       {{Educational_Context_About_Why_This_Matters}}
+      Common options:
+      {{option_list_with_brief_explanations}}
 
-       Think of it like {{real_world_analogy}}.
+      For your project, {{recommendation}} would work well because {{reason}}."
 
-       Your main options:
-       {{friendly_options_with_pros_cons}}
+  </check>
 
-       My suggestion: {{recommendation}}
-       This is good for you because {{beginner_friendly_reason}}."
-    </check>
+  <check if="mode == 'BEGINNER'">
+    "Let's talk about {{Human_Friendly_Category}}.
+
+      {{Educational_Context_About_Why_This_Matters}}
+
+      Think of it like {{real_world_analogy}}.
+
+      Your main options:
+      {{friendly_options_with_pros_cons}}
+
+      My suggestion: {{recommendation}}
+      This is good for you because {{beginner_friendly_reason}}."
+
+  </check>
 
   </action>
 
@@ -356,6 +363,7 @@ Provided by Starter: {{yes_if_from_starter}}
 </action>
 
 <template-output>decision_record</template-output>
+<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="5" goal="Address cross-cutting concerns">
@@ -365,11 +373,7 @@ Provided by Starter: {{yes_if_from_starter}}
 </action>
 
   <check if="{user_skill_level} == 'beginner'">
-    <action>Explain why these matter:
-      "These are rules that EVERY part of your app must follow.
-       If we don't decide now, each AI agent will do it differently,
-       and your app won't work properly when the pieces come together."
-    </action>
+    <action>Explain why these matter why its critical to go through and decide these things now.</action>
   </check>
 
 <template-output>cross_cutting_decisions</template-output>
@@ -389,6 +393,7 @@ Provided by Starter: {{yes_if_from_starter}}
 </action>
 
 <template-output>project_structure</template-output>
+<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="7" goal="Design novel architectural patterns" optional="true">
@@ -462,6 +467,7 @@ Provided by Starter: {{yes_if_from_starter}}
   </check>
 
 <template-output>novel_pattern_designs</template-output>
+<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="8" goal="Define implementation patterns to prevent agent conflicts">
@@ -554,6 +560,7 @@ Enforcement: "All agents MUST follow this pattern"
 </action>
 
 <template-output>implementation_patterns</template-output>
+<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="9" goal="Validate architectural coherence">
@@ -607,6 +614,7 @@ Enforcement: "All agents MUST follow this pattern"
   </action>
 
 <template-output>architecture_document</template-output>
+<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="11" goal="Validate document completeness">

package/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml

@@ -18,10 +18,23 @@ recommended_inputs:
   - epics: "Epic definitions with user stories and acceptance criteria"
   - ux_spec: "UX specification with interface designs and interaction patterns (optional)"
 
-# Input file references (fuzzy matched from output folder)
-prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
-epics_file: "{output_folder}/bmm-epics.md or epics.md or user-stories.md"
-ux_spec_file: "{output_folder}/ux-spec.md or ux-specification.md or user-experience.md"
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
 
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture"

package/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md

@@ -3,6 +3,7 @@
 <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml</critical>
 <critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
 
 <workflow>
 

package/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml

@@ -24,13 +24,39 @@ validation: "{installed_path}/checklist.md"
 # Output configuration
 default_output_file: "{output_folder}/implementation-readiness-report-{{date}}.md"
 
-# Expected input documents (varies by project level)
+# Input requirements
 recommended_inputs:
-  - prd: "{output_folder}/prd*.md"
-  - architecture: "{output_folder}/architecture*.md or {output_folder}/architecture*.md"
-  - tech_spec: "{output_folder}/tech-spec*.md"
-  - epics_stories: "{output_folder}/epic*.md"
-  - ux_artifacts: "{output_folder}/ux*.md"
+  - prd: "Product Requirements Document with FRs and NFRs"
+  - architecture: "System Architecture with decisions and patterns"
+  - tech_spec: "Technical Specification (for Quick Flow track)"
+  - epics: "Epic breakdown with user stories"
+  - ux_design: "UX design specification (if UI components)"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  tech_spec:
+    whole: "{output_folder}/*tech-spec*.md"
+    sharded: "{output_folder}/*tech-spec*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
 
 # Validation criteria data
 validation_criteria: "{installed_path}/validation-criteria.yaml"

package/src/modules/bmm/workflows/4-implementation/code-review/instructions.md

@@ -16,6 +16,35 @@
 
 <critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
 
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories.
+
 <workflow>
 
   <step n="1" goal="Find story ready for review" tag="sprint-status">

package/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -51,6 +51,26 @@ recommended_inputs:
   - tech_spec: "Epic technical specification document (auto-discovered)"
   - story_context_file: "Story context file (.context.xml) (auto-discovered)"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
+input_file_patterns:
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle: false