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

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

@@ -4,50 +4,74 @@
 <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>
 
-<workflow>
+## 📚 Input Document Discovery
 
-<step n="0" goal="Initialize and understand project context">
-<invoke-workflow path="{workflow_status_workflow}">
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
+This workflow validates: PRD, epics/stories, architecture, and may reference UX design, tech specs, or brownfield project documentation.
 
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
+**Discovery Process** (execute for each referenced document):
 
-The Implementation Ready Check can run standalone or as part of the BMM workflow path.
+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`
 
-**Recommended:** Run `workflow-init` first for:
+**Priority**: If both whole and sharded versions exist, use the whole document.
 
-- Project context tracking
-- Workflow sequencing guidance
-- Progress monitoring across workflows
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
 
-**Or continue standalone** without progress tracking.
-</output>
-<ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
-<check if="continue">
-<action>Set standalone_mode = true</action>
-</check>
-<check if="exit">
-<action>Exit workflow</action>
-</check>
+<workflow>
+
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
+
+<check if="status file not found">
+  <output>No workflow status file found. Implementation Ready Check can run standalone or as part of BMM workflow path.</output>
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
+  <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
+  <check if="continue">
+    <action>Set standalone_mode = true</action>
+  </check>
+  <check if="exit">
+    <action>Exit workflow</action>
+  </check>
 </check>
 
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Store {{project_level}}, {{active_path}}, and {{workflow_phase}} for validation context</action>
+<check if="status file found">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "solutioning-gate-check" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
-<action>Based on the project_level, understand what artifacts should exist:
+<action>Based on the project_level, understand what artifacts should exist: - Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning) - Level 2: PRD, tech spec, epics/stories (no separate architecture doc) - Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
+</action>
 
-- Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning)
-- Level 2: PRD, tech spec, epics/stories (no separate architecture doc)
-- Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
-  </action>
+  <check if="solutioning-gate-check status is file path (already completed)">
+    <output>⚠️ Gate check already completed: {{solutioning-gate-check status}}</output>
+    <ask>Re-running will create a new validation report. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
+  <check if="solutioning-gate-check is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Gate check is out of sequence.</output>
+    <ask>Continue with gate check anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
 </check>
 
+<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
+
 <template-output>project_context</template-output>
 </step>
 
@@ -249,23 +273,48 @@ The Implementation Ready Check can run standalone or as part of the BMM workflow
 <template-output>readiness_assessment</template-output>
 </step>
 
-<step n="7" goal="Workflow status update offer" optional="true">
-<ask>The readiness assessment is complete. Would you like to update the workflow status to proceed to the next phase? [yes/no]
+<step n="7" goal="Update status and complete" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "solutioning-gate-check"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["solutioning-gate-check"] = "{output_folder}/bmm-readiness-assessment-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-Note: This will advance the project workflow to the next phase in your current path.</ask>
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
+</check>
 
-<action if="user_response == 'yes'">
-Determine the next workflow phase based on current status:
-- If Level 0-1: Advance to implementation phase
-- If Level 2-4 in solutioning: Advance to Phase 4 (Implementation)
-- Update the workflow status configuration accordingly
-- Confirm the update with the user
-</action>
+<output>**✅ Implementation Ready Check Complete!**
 
-<action if="user_response == 'no'">
-Acknowledge that the workflow status remains unchanged.
-Remind user they can manually update when ready.
-</action>
+**Assessment Report:**
+
+- Readiness assessment saved to: {output_folder}/bmm-readiness-assessment-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: solutioning-gate-check marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- Review the assessment report and address any critical issues before proceeding
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
 
 <template-output>status_update_result</template-output>
 </step>

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">
@@ -234,6 +263,7 @@ You may need to run sprint-planning to refresh tracking, or manually set the sto
     <output>**✅ Story Created Successfully, {user_name}!**
 
 **Story Details:**
+
 - Story ID: {{story_id}}
 - Story Key: {{story_key}}
 - File: {{story_file}}
@@ -242,6 +272,7 @@ You may need to run sprint-planning to refresh tracking, or manually set the sto
 **⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command.
 
 **Next Steps:**
+
 1. Review the drafted story in {{story_file}}
 2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step)
 3. Or run `story-ready` to manually mark the story ready without generating technical context

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

package/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md

@@ -7,6 +7,35 @@
 <critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
 <critical>If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed.</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 workflow context or user input)
+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, gdd, 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 epics and stories.
+
 <workflow>
   <step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
     <action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>

package/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml

@@ -9,17 +9,43 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
 
-# Inputs expected ( check output_folder or ask user if missing)
+# Inputs expected (check output_folder or ask user if missing)
 recommended_inputs:
   - prd
   - gdd
-  - spec
   - architecture
-  - ux_spec
-  - ux-design
-  - if there is an index.md then read the index.md to find other related docs that could be relevant
+  - ux_design
+  - epics (only the specific epic needed for this tech spec)
   - prior epic tech-specs for model, style and consistency reference
 
+# 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 (epic_num from context)
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  gdd:
+    whole: "{output_folder}/*gdd*.md"
+    sharded: "{output_folder}/*gdd*/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"
+
+  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"
+
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context"
 template: "{installed_path}/template.md"