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

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

@@ -21,6 +21,34 @@ trigger: "Run AFTER completing an epic"
 required_inputs:
   - agent_manifest: "{project-root}/bmad/_cfg/agent-manifest.csv"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives
+input_file_patterns:
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  previous_retrospective:
+    pattern: "{output_folder}/retrospectives/epic-{{prev_epic_num}}-retro-*.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Required files
+sprint_status_file: "{output_folder}/sprint-status.yaml"
+story_directory: "{config_source}:dev_story_location"
+retrospectives_folder: "{output_folder}/retrospectives"
+
 output_artifacts:
   - retrospective_summary: "Comprehensive review of what went well and what could improve"
   - lessons_learned: "Key insights for future epics"

package/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -3,6 +3,23 @@
 <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/4-implementation/sprint-planning/workflow.yaml</critical>
 
+## 📚 Document Discovery - Full Epic Loading
+
+**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking.
+
+**Epic Discovery Process:**
+
+1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file
+2. **Check for sharded version** - If whole document not found, look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.)
+   - Process all epics and their stories from the combined content
+   - This ensures complete sprint status coverage
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc.
+
 <workflow>
 
 <step n="1" goal="Parse epic files and extract all work items">

package/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -33,6 +33,14 @@ variables:
   # Output configuration
   status_file: "{output_folder}/sprint-status.yaml"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status
+input_file_patterns:
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
 # Output configuration
 default_output_file: "{status_file}"
 

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

@@ -11,6 +11,35 @@
 
 <critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</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 key - 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="Find drafted story and check for existing context" tag="sprint-status">
     <check if="{{story_path}} is provided">
@@ -91,7 +120,8 @@ All stories are either still in backlog or already marked ready/in-progress/done
 
   <step n="2" goal="Collect relevant documentation">
     <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks.</action>
-    <action>Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
+    <action>Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
+    <action>Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
     <action>For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md").</action>
     <template-output file="{default_output_file}">
       Add artifacts.docs entries with {path, title, section, snippet}:
@@ -178,12 +208,14 @@ You may need to run sprint-planning to refresh tracking.
     <output>✅ Story context generated successfully, {user_name}!
 
 **Story Details:**
+
 - Story: {{epic_id}}.{{story_id}} - {{story_title}}
 - Story Key: {{story_key}}
 - Context File: {default_output_file}
 - Status: drafted → ready-for-dev
 
 **Context Includes:**
+
 - Documentation artifacts and references
 - Existing code and interfaces
 - Dependencies and frameworks
@@ -191,6 +223,7 @@ You may need to run sprint-planning to refresh tracking.
 - Development constraints
 
 **Next Steps:**
+
 1. Review the context file: {default_output_file}
 2. Run `dev-story` to implement the story
 3. Generate context for more drafted stories if needed

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

@@ -23,6 +23,33 @@ variables:
   story_path: "" # Optional: Explicit story path. If not provided, finds first story with status "drafted"
   story_dir: "{config_source}:dev_story_location"
 
+# 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"
+
 # Output configuration
 # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
 default_output_file: "{story_dir}/{{story_key}}.context.xml"

package/src/modules/bmm/workflows/techdoc/documentation-standards.md

@@ -0,0 +1,239 @@
+# Technical Documentation Standards for BMAD
+
+**For Agent: Paige (Documentation Guide)**
+**Purpose: Concise reference for documentation creation and review**
+
+---
+
+## CRITICAL RULE: CommonMark Strict Compliance
+
+ALL documentation MUST follow CommonMark specification exactly. No exceptions.
+
+### CommonMark Essentials
+
+**Headers:**
+
+- Use ATX-style ONLY: `#` `##` `###` (NOT Setext underlines)
+- Single space after `#`: `# Title` (NOT `#Title`)
+- No trailing `#`: `# Title` (NOT `# Title #`)
+- Hierarchical order: Don't skip levels (h1→h2→h3, not h1→h3)
+
+**Code Blocks:**
+
+- Use fenced blocks with language identifier:
+  ````markdown
+  ```javascript
+  const example = 'code';
+  ```
+  ````
+- NOT indented code blocks (ambiguous)
+
+**Lists:**
+
+- Consistent markers within list: all `-` or all `*` or all `+` (don't mix)
+- Proper indentation for nested items (2 or 4 spaces, stay consistent)
+- Blank line before/after list for clarity
+
+**Links:**
+
+- Inline: `[text](url)`
+- Reference: `[text][ref]` then `[ref]: url` at bottom
+- NO bare URLs without `<>` brackets
+
+**Emphasis:**
+
+- Italic: `*text*` or `_text_`
+- Bold: `**text**` or `__text__`
+- Consistent style within document
+
+**Line Breaks:**
+
+- Two spaces at end of line + newline, OR
+- Blank line between paragraphs
+- NO single line breaks (they're ignored)
+
+---
+
+## Mermaid Diagrams: Valid Syntax Required
+
+**Critical Rules:**
+
+1. Always specify diagram type first line
+2. Use valid Mermaid v10+ syntax
+3. Test syntax before outputting (mental validation)
+4. Keep focused: 5-10 nodes ideal, max 15
+
+**Diagram Type Selection:**
+
+- **flowchart** - Process flows, decision trees, workflows
+- **sequenceDiagram** - API interactions, message flows, time-based processes
+- **classDiagram** - Object models, class relationships, system structure
+- **erDiagram** - Database schemas, entity relationships
+- **stateDiagram-v2** - State machines, lifecycle stages
+- **gitGraph** - Branch strategies, version control flows
+
+**Formatting:**
+
+````markdown
+```mermaid
+flowchart TD
+    Start[Clear Label] --> Decision{Question?}
+    Decision -->|Yes| Action1[Do This]
+    Decision -->|No| Action2[Do That]
+```
+````
+
+---
+
+## Style Guide Principles (Distilled)
+
+Apply in this hierarchy:
+
+1. **Project-specific guide** (if exists) - always ask first
+2. **BMAD conventions** (this document)
+3. **Google Developer Docs style** (defaults below)
+4. **CommonMark spec** (when in doubt)
+
+### Core Writing Rules
+
+**Task-Oriented Focus:**
+
+- Write for user GOALS, not feature lists
+- Start with WHY, then HOW
+- Every doc answers: "What can I accomplish?"
+
+**Clarity Principles:**
+
+- Active voice: "Click the button" NOT "The button should be clicked"
+- Present tense: "The function returns" NOT "The function will return"
+- Direct language: "Use X for Y" NOT "X can be used for Y"
+- Second person: "You configure" NOT "Users configure" or "One configures"
+
+**Structure:**
+
+- One idea per sentence
+- One topic per paragraph
+- Headings describe content accurately
+- Examples follow explanations
+
+**Accessibility:**
+
+- Descriptive link text: "See the API reference" NOT "Click here"
+- Alt text for diagrams: Describe what it shows
+- Semantic heading hierarchy (don't skip levels)
+- Tables have headers
+- Emojis are acceptable if user preferences allow (modern accessibility tools support emojis well)
+
+---
+
+## OpenAPI/API Documentation
+
+**Required Elements:**
+
+- Endpoint path and method
+- Authentication requirements
+- Request parameters (path, query, body) with types
+- Request example (realistic, working)
+- Response schema with types
+- Response examples (success + common errors)
+- Error codes and meanings
+
+**Quality Standards:**
+
+- OpenAPI 3.0+ specification compliance
+- Complete schemas (no missing fields)
+- Examples that actually work
+- Clear error messages
+- Security schemes documented
+
+---
+
+## Documentation Types: Quick Reference
+
+**README:**
+
+- What (overview), Why (purpose), How (quick start)
+- Installation, Usage, Contributing, License
+- Under 500 lines (link to detailed docs)
+
+**API Reference:**
+
+- Complete endpoint coverage
+- Request/response examples
+- Authentication details
+- Error handling
+- Rate limits if applicable
+
+**User Guide:**
+
+- Task-based sections (How to...)
+- Step-by-step instructions
+- Screenshots/diagrams where helpful
+- Troubleshooting section
+
+**Architecture Docs:**
+
+- System overview diagram (Mermaid)
+- Component descriptions
+- Data flow
+- Technology decisions (ADRs)
+- Deployment architecture
+
+**Developer Guide:**
+
+- Setup/environment requirements
+- Code organization
+- Development workflow
+- Testing approach
+- Contribution guidelines
+
+---
+
+## Quality Checklist
+
+Before finalizing ANY documentation:
+
+- [ ] CommonMark compliant (no violations)
+- [ ] Headers in proper hierarchy
+- [ ] All code blocks have language tags
+- [ ] Links work and have descriptive text
+- [ ] Mermaid diagrams render correctly
+- [ ] Active voice, present tense
+- [ ] Task-oriented (answers "how do I...")
+- [ ] Examples are concrete and working
+- [ ] Accessibility standards met
+- [ ] Spelling/grammar checked
+- [ ] Reads clearly at target skill level
+
+---
+
+## BMAD-Specific Conventions
+
+**File Organization:**
+
+- `README.md` at root of each major component
+- `docs/` folder for extensive documentation
+- Workflow-specific docs in workflow folder
+- Cross-references use relative paths
+
+**Frontmatter:**
+Use YAML frontmatter when appropriate:
+
+```yaml
+---
+title: Document Title
+description: Brief description
+author: Author name
+date: YYYY-MM-DD
+---
+```
+
+**Metadata:**
+
+- Always include last-updated date
+- Version info for versioned docs
+- Author attribution for accountability
+
+---
+
+**Remember: This is your foundation. Follow these rules consistently, and all documentation will be clear, accessible, and maintainable.**

package/src/modules/bmm/workflows/workflow-status/init/instructions.md

@@ -261,36 +261,129 @@ Here's the complexity scale for reference:
 <template-output>workflow_path_file</template-output>
 </step>
 
-<step n="5" goal="Generate workflow summary">
-<action>Build workflow from loaded path file</action>
-<action>Display phases and workflows</action>
-<action>Set initial values for status file</action>
-
-<template-output>current_phase</template-output>
-<template-output>current_workflow</template-output>
-<template-output>current_agent</template-output>
-<template-output>next_action</template-output>
-<template-output>next_command</template-output>
-<template-output>next_agent</template-output>
+<step n="5" goal="Build workflow status YAML structure">
+<action>Parse the loaded workflow path file and extract all workflows</action>
+
+<action>For each phase in the path file:
+
+- Extract phase number and name
+- Extract all workflows in that phase
+- For each workflow, determine its status type:
+  - required: true → status = "required"
+  - recommended: true → status = "recommended"
+  - conditional: "if_has_ui" → status = "conditional"
+  - optional: true → status = "optional"
+  - Default if not specified → status = "required"
+    </action>
+
+<action>Build the workflow_items list in this format:
+
+For each phase:
+
+1. Add comment header: `  # Phase {n}: {Phase Name}`
+2. For each workflow in phase:
+   - Add entry: `  {workflow-id}: {status}`
+3. Add blank line between phases
+
+Example structure:
+
+```
+  # Phase 1: Analysis
+  brainstorm-project: optional
+  research: optional
+  product-brief: recommended
+
+  # Phase 2: Planning
+  prd: required
+  validate-prd: optional
+  create-design: conditional
+```
+
+</action>
+
+<action>Scan for existing workflow output files to auto-detect completion:
+
+For each workflow in the list, check common output locations:
+
+- {output_folder}/brainstorm-\*.md for brainstorm-project
+- {output_folder}/research-\*.md for research
+- {output_folder}/product-brief.md for product-brief
+- {output_folder}/prd.md for prd
+- {output_folder}/ux-design.md for create-design
+- {output_folder}/architecture.md for create-architecture
+- {output_folder}/tech-spec.md for tech-spec
+- {output_folder}/sprint-status.yaml for sprint-planning
+
+CRITICAL: If file exists, replace status with ONLY the file path - nothing else.
+Example: product-brief: docs/product-brief.md
+NOT: product-brief: "completed - docs/product-brief.md" or any other text.
+</action>
+
+<template-output>workflow_items</template-output>
 </step>
 
-<step n="6" goal="Create status file">
-<action>Initialize all status values</action>
-<template-output>start_date</template-output>
-<template-output>last_updated</template-output>
-<template-output>phase_1_complete</template-output>
-<template-output>phase_2_complete</template-output>
-<template-output>phase_3_complete</template-output>
-<template-output>phase_4_complete</template-output>
+<step n="6" goal="Create workflow status file">
+<action>Set generated date to current date</action>
+<template-output>generated</template-output>
+
+<action>Prepare all template variables for workflow-status-template.yaml:
+
+- generated: {current_date}
+- project_name: {project_name}
+- project_type: {project_type}
+- project_level: {project_level}
+- field_type: {field_type}
+- workflow_path_file: {workflow_path_file}
+- workflow_items: {workflow_items from step 5}
+  </action>
+
+<action>Display a preview of what will be created:
+
+Show the first workflow in each phase and total count:
+
+"Ready to create workflow status tracking:
+
+- Phase 1 ({phase_1_workflow_count} workflows): Starting with {first_workflow_phase_1}
+- Phase 2 ({phase_2_workflow_count} workflows): Starting with {first_workflow_phase_2}
+- Phase 3 ({phase_3_workflow_count} workflows): Starting with {first_workflow_phase_3}
+- Phase 4 (Implementation tracked separately in sprint-status.yaml)
+
+{{#if detected_completed_workflows}}
+Found existing work:
+{{#each detected_files}}
+
+- {{workflow_name}}: {{file_path}}
+  {{/each}}
+  {{/if}}"
+  </action>
 
 <ask>Ready to create your workflow status file? (y/n)</ask>
 
 <check if="answer == y">
-  <action>Save status file to {output_folder}/bmm-workflow-status.md</action>
-  <output>✅ Status file created! Next up: {{next_agent}} agent, run `{{next_command}}`</output>
-  <check if="next_agent !== current_agent">
-    <output>It is strongly recommended to clear the context or start a new chat and load the next agent to execute the next command from that agents help menu, unless there is something else I can do for you first.</output>
-  </check>
+  <action>Generate YAML from workflow-status-template.yaml with all variables</action>
+  <action>Save status file to {output_folder}/bmm-workflow-status.yaml</action>
+
+<action>Identify the first non-completed workflow in the list</action>
+<action>Look up that workflow's agent and command from the path file</action>
+
+<output>✅ Workflow status file created at {output_folder}/bmm-workflow-status.yaml
+
+**Next Steps:**
+
+{{#if detected_completed_workflows}}
+You have {{detected_count}} workflow(s) already completed. Great progress!
+{{/if}}
+
+**Next Workflow:** {{next_workflow_name}}
+
+**Agent:** {{next_agent}}
+
+**Command:** /bmad:bmm:workflows:{{next_workflow_id}}
+
+{{#if next_agent !== 'pm'}}
+It is recommended to start a new chat and load the {{next_agent}} agent before running the next workflow.
+{{/if}}
+</output>
 </check>
 </step>
 

package/src/modules/bmm/workflows/workflow-status/init/workflow.yaml

@@ -16,13 +16,13 @@ date: system-generated
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/workflow-status/init"
 instructions: "{installed_path}/instructions.md"
-template: "{project-root}/bmad/bmm/workflows/workflow-status/workflow-status-template.md"
+template: "{project-root}/bmad/bmm/workflows/workflow-status/workflow-status-template.yaml"
 
 # Path data files
 path_files: "{project-root}/bmad/bmm/workflows/workflow-status/paths/"
 
 # Output configuration
-default_output_file: "{output_folder}/bmm-workflow-status.md"
+default_output_file: "{output_folder}/bmm-workflow-status.yaml"
 
 standalone: true
 web_bundle: false