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

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

@@ -22,22 +22,43 @@ so that {{benefit}}.
 
 {{technical_summary}}
 
+### Tech-Spec Reference
+
+**Full details:** See [tech-spec.md](../tech-spec.md)
+
+The tech-spec contains comprehensive context including:
+
+- Brownfield codebase analysis (if applicable)
+- Framework and library details with versions
+- Existing patterns to follow
+- Integration points and dependencies
+- Complete implementation guidance
+
 ### 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}})
+- **Dependencies:** {{dependencies}}
+
+### Key Code References
+
+{{existing_code_references}}
 
 ### References
 
-- **Tech Spec:** See tech-spec.md for detailed implementation
+- **Tech Spec:** [tech-spec.md](../tech-spec.md) - Primary context document
 - **Architecture:** {{architecture_references}}
 
+---
+
 ## Dev Agent Record
 
 ### Context Reference
 
-<!-- Path(s) to story context XML will be added here by context workflow -->
+**Primary Context:** [tech-spec.md](../tech-spec.md) - Contains all brownfield analysis, framework details, and implementation guidance
+
+<!-- Additional context XML paths will be added here if story-context workflow is run -->
 
 ### Agent Model Used
 
@@ -54,3 +75,13 @@ so that {{benefit}}.
 ### File List
 
 <!-- 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

@@ -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

@@ -10,6 +10,24 @@
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow replaces architecture with a conversation-driven approach</critical>
 
+## 📚 Input Document Discovery
+
+This workflow requires: PRD and epics/stories, and may reference UX design specifications or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+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 the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
+
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">
 <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
@@ -35,7 +53,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 +88,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 +100,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 +114,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 +153,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 +224,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 +303,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>
 
@@ -365,11 +388,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>

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

@@ -4,6 +4,24 @@
 <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>
 
+## 📚 Input Document Discovery
+
+This workflow validates: PRD, epics/stories, architecture, and may reference UX design, tech specs, or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+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 the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
+
 <workflow>
 
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">

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

@@ -32,6 +32,32 @@ recommended_inputs:
   - epics_stories: "{output_folder}/epic*.md"
   - ux_artifacts: "{output_folder}/ux*.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"
+
+  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

package/src/modules/bmm/workflows/4-implementation/create-story/instructions.md

@@ -7,6 +7,35 @@
 <critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
 <critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
 
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, 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 context - 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 (prd, 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 UI-focused stories.
+
 <workflow>
 
   <step n="1" goal="Load config and initialize">

package/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -44,6 +44,33 @@ recommended_inputs:
   - prd: "PRD document"
   - architecture: "Architecture (optional)"
 
+# 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
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  tech_spec:
+    whole: "{output_folder}/tech-spec.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"
+
+  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