feat: add universal document sharding support with dual-strategy loading

Implement comprehensive document sharding system across all BMM workflows enabling 90%+ token savings for large multi-epic projects through selective loading optimization. ## Document Sharding System ### Core Features - **Universal Support**: All 12 BMM workflows (Phase 1-4) handle both whole and sharded documents - **Dual Loading Strategy**: Full Load (Phase 1-3) vs Selective Load (Phase 4) - **Automatic Discovery**: Workflows detect format transparently (whole → sharded priority) - **Efficiency Optimization**: 90%+ token reduction for 10+ epic projects in Phase 4 ### Implementation Details **Phase 1-3 Workflows (7 workflows) - Full Load Strategy:** - product-brief, prd, gdd, create-ux-design, tech-spec, architecture, solutioning-gate-check - Load entire sharded documents when present - Transparent to user experience - Better organization for large projects **Phase 4 Workflows (5 workflows) - Selective Load Strategy:** - sprint-planning (Full Load exception - needs all epics) - epic-tech-context, create-story, story-context, code-review (Selective Load) - Load ONLY the specific epic needed (e.g., epic-3.md for Epic 3 stories) - Massive efficiency: Skip loading 9 other epics in 10-epic project ### Workflow Enhancements **Added to all workflows:** - `input_file_patterns` in workflow.yaml with wildcard discovery - Document Discovery section in instructions.md - Support for sharded index + section files - Brownfield `docs/index.md` support **Pattern standardization:** ```yaml input_file_patterns: document: whole: "{output_folder}/*doc*.md" sharded: "{output_folder}/*doc*/index.md" sharded_single: "{output_folder}/*doc*/section-{{id}}.md" # Selective load ``` ### Retrospective Workflow Major Overhaul Transformed retrospective into immersive, interactive team experience: **Epic Discovery Priority (Fixed):** - Priority 1: Check sprint-status.yaml for last completed epic - Priority 2: Ask user directly - Priority 3: Scan stories folder (last resort) **New Capabilities:** - Deep story analysis: Extract dev notes, mistakes, review feedback, lessons learned - Previous retro integration: Track action items, verify lessons applied - Significant change detection: Alert when discoveries require epic updates - Intent-based facilitation: Natural conversation vs scripted phrases - Party mode protocol: Clear speaker identification (Name (Role): dialogue) - Team dynamics: Drama, disagreements, diverse perspectives, authentic conflict **Structure:** - 12 whole-number steps (no decimals) - Highly interactive with constant user engagement - Cross-references previous retro for accountability - Synthesizes patterns across all stories - Detects architectural assumption changes ## Documentation **Created:** - `docs/document-sharding-guide.md` - Comprehensive 300+ line guide - What is sharding, when to use it (token thresholds) - How sharding works (discovery system, loading strategies) - Using shard-doc tool - Full Load vs Selective Load patterns - Complete examples and troubleshooting - Custom workflow integration patterns **Updated:** - `README.md` - Added Document Sharding feature section - `docs/index.md` - Added under Advanced Topics → Optimization - `src/modules/bmm/workflows/README.md` - Added sharding section with usage - `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md` - Added complete implementation patterns for workflow builders **Documentation levels:** 1. Overview (README.md) - Quick feature highlight 2. User guide (BMM workflows README) - Practical usage 3. Reference (document-sharding-guide.md) - Complete details 4. Builder guide (workflow-creation-guide.md) - Implementation patterns ## Efficiency Gains **Example: 10-Epic Project** Before sharding: - epic-tech-context for Epic 3: Load all 10 epics (~50k tokens) - create-story for Epic 3: Load all 10 epics (~50k tokens) - story-context for Epic 3: Load all 10 epics (~50k tokens) After sharding with selective load: - epic-tech-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction - create-story for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction - story-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction ## Breaking Changes None - fully backward compatible. Workflows work with existing whole documents. ## Files Changed **Workflows Updated (25 files):** - 7 Phase 1-3 workflows: Added full load sharding support - 5 Phase 4 workflows: Added selective load sharding support - 1 retrospective workflow: Complete overhaul with sharding support **Documentation (5 files):** - Created: document-sharding-guide.md - Updated: README.md, docs/index.md, BMM workflows README, BMB workflow-creation-guide - Removed: Old conversion report (obsolete) ## Future Extensibility - BMB workflows now aware of sharding patterns - Custom modules can easily implement sharding support - Standard patterns documented for consistency - No need to explain concept in future development
2025-11-02 00:13:33 -05:00 · 2025-11-02 00:13:33 -05:00 · 3d4ea5ffd2
parent f77babcd5e
commit 3d4ea5ffd2
32 changed files with 2397 additions and 437 deletions
--- a/README.md
+++ b/README.md
@ -180,6 +180,17 @@ This initializes the workflow system and helps choose your starting point.

 Single `bmad/` folder - clean, organized, maintainable.

+### 📄 Document Sharding
+
+Optional efficiency optimization for large projects:
+
+- **Automatic Support** - All workflows handle whole or sharded documents
+- **Selective Loading** - Phase 4 workflows load only needed sections (90%+ token savings)
+- **Easy Sharding** - Built-in tool splits documents by headings
+- **Smart Discovery** - Workflows auto-detect format
+
+**[→ Document Sharding Guide](./docs/document-sharding-guide.md)**
+
 ## Documentation

 - **[📚 Documentation Index](./docs/index.md)** - Complete documentation map
--- a/docs/conversion-report-shard-doc-2025-10-26.md
+++ b/docs/conversion-report-shard-doc-2025-10-26.md
@ -1,188 +0,0 @@
-# Legacy Task Conversion Report
-
-**Generated**: 2025-10-26
-**Converted By**: BMad Builder Agent
-**Conversion Type**: Legacy Task → v6 XML Task
-
---
-
-## Source Information
-
- **Original Location**: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/bmad-core/tasks/shard-doc.md
- **Original Format**: Markdown task (v4/legacy format)
- **Original Type**: Document sharding utility task
-
---
-
-## Target Information
-
- **New Location**: `/Users/brianmadison/dev/BMAD-METHOD/src/core/tasks/shard-doc.xml`
- **New Format**: v6 XML task format
- **Task ID**: `bmad/core/tasks/shard-doc`
- **Task Name**: Shard Document
-
---
-
-## Conversion Summary
-
-### Components Converted
-
-✅ **Task Structure**: Converted from markdown to XML format
-✅ **Execution Flow**: 6 steps properly structured in `<flow>` section (simplified to tool-only)
-✅ **Critical Instructions**: Moved to `<llm critical="true">` section
-✅ **Validation Rules**: Extracted to `<validation>` section
-✅ **Halt Conditions**: Extracted to `<halt-conditions>` section
-✅ **Special Guidelines**: Moved to `<critical-context>` section
-✅ **Output Format**: Documented in `<output-format>` section
-✅ **Tool Information**: Preserved in `<tool-info>` section
-
-### Key Features Preserved
-
- **Automated Tool**: Uses @kayvan/markdown-tree-parser exclusively
- **Simplified Flow**: Removed all manual steps, tool handles everything
- **Code Block Awareness**: Tool automatically handles ## inside code blocks
- **Content Preservation**: Tool preserves all markdown formatting and special content
- **Heading Adjustment**: Tool automatically reduces heading levels by one
- **Index Generation**: Tool automatically creates index.md
- **Validation Steps**: Verification of tool installation and output
- **Error Handling**: Halt conditions for tool and file system issues
-
-### v6 Conventions Applied
-
- ✅ Proper `<task>` wrapper with id and name attributes
- ✅ `<llm critical="true">` section with mandatory instructions
- ✅ `<flow>` section with numbered `<step>` elements
- ✅ Used `<action>` tags for required actions
- ✅ Used `<i>` tags for instruction lists and context
- ✅ Conditional logic with `if` attributes on actions
- ✅ Optional steps marked with `optional="true"`
- ✅ Supporting sections for validation, halt conditions, output format
- ✅ Consistent with existing v6 tasks (workflow.xml, adv-elicit.xml, index-docs.xml)
-
---
-
-## Structural Comparison
-
-### Legacy Format (Markdown)
-
-```
-# Document Sharding Task
-## Primary Method: Automated Approach
-## Manual Method (Fallback)
-1. Identify target location
-2. Parse sections
-...
-## Critical Guidelines
-```
-
-### v6 Format (XML)
-
-```xml
-<task id="bmad/core/tasks/shard-doc" name="Shard Document">
-  <objective>...</objective>
-  <llm critical="true">...</llm>
-  <critical-context>...</critical-context>
-  <flow>
-    <step n="1" title="...">
-      <action>...</action>
-    </step>
-  </flow>
-  <halt-conditions>...</halt-conditions>
-  <validation>...</validation>
-</task>
-```
-
---
-
-## Validation Results
-
-### XML Structure
-
- ✅ Valid XML syntax
- ✅ Properly nested elements
- ✅ All tags closed correctly
- ✅ Attributes properly formatted
-
-### v6 Compliance
-
- ✅ Matches v6 task conventions
- ✅ Follows existing core task patterns
- ✅ Uses standard v6 tag set
- ✅ Proper section organization
-
-### Content Integrity
-
- ✅ All original instructions preserved
- ✅ No functionality lost in conversion
- ✅ Critical warnings maintained
- ✅ Tool information preserved
- ✅ Validation logic intact
-
-### File System
-
- ✅ Saved to correct location: `src/core/tasks/`
- ✅ Proper filename: `shard-doc.xml`
- ✅ Follows core task naming convention
-
---
-
-## Usage Notes
-
-### How to Invoke This Task
-
-From an agent or workflow, reference:
-
-```xml
-<invoke-task>{project-root}/bmad/core/tasks/shard-doc.xml</invoke-task>
-```
-
-Or from agent menu:
-
-```yaml
-menu:
-  - trigger: shard
-    description: 'Split large document into organized files'
-    exec: '{project-root}/bmad/core/tasks/shard-doc.xml'
-```
-
-### Task Capabilities
-
-1. **Automated Mode**: Uses @kayvan/markdown-tree-parser for fast sharding
-2. **Manual Mode**: Step-by-step guided process for controlled sharding
-3. **Safety Checks**: Validates code blocks aren't treated as headers
-4. **Content Preservation**: Maintains all formatting, code, tables, diagrams
-5. **Index Generation**: Creates navigable index.md automatically
-6. **Validation**: Verifies completeness and integrity
-
---
-
-## Post-Conversion Actions
-
-### Recommended Next Steps
-
-1. ✅ **Task Created**: File saved to core tasks directory
-2. **Test Task**: Invoke from an agent or workflow to verify functionality
-3. **Update Documentation**: Reference in core task documentation if needed
-4. **Integration**: Add to relevant agent menus if appropriate
-
-### No Manual Adjustments Required
-
-The conversion is complete and ready for use. All legacy functionality has been successfully migrated to v6 XML format.
-
---
-
-## Notes
-
- Original legacy file can be archived or left as-is (located on GitHub)
- This task is now a core BMAD task available to all modules
- The task follows v6 conventions and is fully compatible with BMAD-CORE v6 alpha
- **UPDATED 2025-10-26**: Manual fallback steps removed - task now exclusively uses @kayvan/markdown-tree-parser
- Flow simplified from 8 steps to 6 steps (tool installation → execution → verification)
- All manual parsing, file creation, and index generation logic removed (tool handles automatically)
-
---
-
-**Conversion Status**: ✅ COMPLETE (Updated)
-**Ready for Use**: YES
-**Manual Adjustments Needed**: NONE
-**Approach**: Automated tool only (no manual fallback)
--- a/docs/document-sharding-guide.md
+++ b/docs/document-sharding-guide.md
@ -0,0 +1,447 @@
+# Document Sharding Guide
+
+Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
+
+## Table of Contents
+
+- [What is Document Sharding?](#what-is-document-sharding)
+- [When to Use Sharding](#when-to-use-sharding)
+- [How Sharding Works](#how-sharding-works)
+- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
+- [Workflow Support](#workflow-support)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
+
+- **Selective Loading** - Workflows load only the sections they need
+- **Reduced Token Usage** - Massive efficiency gains for large projects
+- **Better Organization** - Logical section-based file structure
+- **Maintained Context** - Index file preserves document structure
+
+### Architecture
+
+```
+Before Sharding:
+docs/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+docs/
+└── prd/
+    ├── index.md                    # Table of contents with descriptions
+    ├── overview.md                 # Section 1
+    ├── user-requirements.md        # Section 2
+    ├── technical-requirements.md   # Section 3
+    └── ...                         # Additional sections
+```
+
+## When to Use Sharding
+
+### Ideal Candidates
+
+**Large Multi-Epic Projects:**
+
+- Very large complex PRDs
+- Architecture documents with multiple system layers
+- Epic files with 4+ epics (especially for Phase 4)
+- UX design specs covering multiple subsystems
+
+**Token Thresholds:**
+
+- **Consider sharding**: Documents > 20k tokens
+- **Strongly recommended**: Documents > 40k tokens
+- **Critical for efficiency**: Documents > 60k tokens
+
+### When NOT to Shard
+
+**Small Projects:**
+
+- Single epic projects
+- Level 0-1 projects (tech-spec only)
+- Documents under 10k tokens
+- Quick prototypes
+
+**Frequently Updated Docs:**
+
+- Active work-in-progress documents
+- Documents updated daily
+- Documents where whole-file context is essential
+
+## How Sharding Works
+
+### Sharding Process
+
+1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools.
+2. **Section Extraction**: Tool splits by level 2 headings
+3. **File Creation**: Each section becomes a separate file
+4. **Index Generation**: `index.md` created with structure and descriptions
+
+### Workflow Discovery
+
+BMad workflows use a **dual discovery system**:
+
+1. **Try whole document first** - Look for `document-name.md`
+2. **Check for sharded version** - Look for `document-name/index.md`
+3. **Priority rule** - Whole document takes precedence if both exist
+
+### Loading Strategies
+
+**Full Load (Phase 1-3 workflows):**
+
+```
+If sharded:
+  - Read index.md
+  - Read ALL section files
+  - Treat as single combined document
+```
+
+**Selective Load (Phase 4 workflows):**
+
+```
+If sharded epics and working on Epic 3:
+  - Read epics/index.md
+  - Load ONLY epics/epic-3.md
+  - Skip all other epic files
+  - 90%+ token savings!
+```
+
+## Using the Shard-Doc Tool
+
+### CLI Command
+
+```bash
+# Activate bmad-master or analyst agent, then:
+/shard-doc
+```
+
+### Interactive Process
+
+```
+Agent: Which document would you like to shard?
+User: docs/PRD.md
+
+Agent: Default destination: docs/prd/
+       Accept default? [y/n]
+User: y
+
+Agent: Sharding PRD.md...
+       ✓ Created 12 section files
+       ✓ Generated index.md
+       ✓ Complete!
+```
+
+### What Gets Created
+
+**index.md structure:**
+
+```markdown
+# PRD - Index
+
+## Sections
+
+1. [Overview](./overview.md) - Project vision and objectives
+2. [User Requirements](./user-requirements.md) - Feature specifications
+3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
+4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
+   ...
+```
+
+**Individual section files:**
+
+- Named from heading text (kebab-case)
+- Contains complete section content
+- Preserves all markdown formatting
+- Can be read independently
+
+## Workflow Support
+
+### Universal Support
+
+**All BMM workflows support both formats:**
+
+- ✅ Whole documents
+- ✅ Sharded documents
+- ✅ Automatic detection
+- ✅ Transparent to user
+
+### Workflow-Specific Patterns
+
+#### Phase 1-3 (Full Load)
+
+Workflows load entire sharded documents:
+
+- `product-brief` - Research, brainstorming docs
+- `prd` - Product brief, research
+- `gdd` - Game brief, research
+- `create-ux-design` - PRD, brief, epics
+- `tech-spec` - Brief, research
+- `architecture` - PRD, epics, UX design
+- `solutioning-gate-check` - All planning docs
+
+#### Phase 4 (Selective Load)
+
+Workflows load only needed sections:
+
+**sprint-planning** (Full Load):
+
+- Needs ALL epics to build complete status
+
+**epic-tech-context, create-story, story-context, code-review** (Selective):
+
+```
+Working on Epic 3, Story 2:
+  ✓ Load epics/epic-3.md only
+  ✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc.
+
+Result: 90%+ token reduction for 10-epic projects!
+```
+
+### Input File Patterns
+
+Workflows use standardized patterns:
+
+```yaml
+input_file_patterns:
+  prd:
+    whole: '{output_folder}/*prd*.md'
+    sharded: '{output_folder}/*prd*/index.md'
+
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_index: '{output_folder}/*epic*/index.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
+```
+
+## Best Practices
+
+### Sharding Strategy
+
+**Do:**
+
+- ✅ Shard after planning phase complete
+- ✅ Keep level 2 headings well-organized
+- ✅ Use descriptive section names
+- ✅ Shard before Phase 4 implementation
+- ✅ Keep original file as backup initially
+
+**Don't:**
+
+- ❌ Shard work-in-progress documents
+- ❌ Shard small documents (<20k tokens)
+- ❌ Mix sharded and whole versions
+- ❌ Manually edit index.md structure
+
+### Naming Conventions
+
+**Good Section Names:**
+
+```markdown
+## Epic 1: User Authentication
+
+## Technical Requirements
+
+## System Architecture
+
+## UX Design Principles
+```
+
+**Poor Section Names:**
+
+```markdown
+## Section 1
+
+## Part A
+
+## Details
+
+## More Info
+```
+
+### File Management
+
+**When to Re-shard:**
+
+- Significant structural changes to document
+- Adding/removing major sections
+- After major refactoring
+
+**Updating Sharded Docs:**
+
+1. Edit individual section files directly
+2. OR edit original, delete sharded folder, re-shard
+3. Don't manually edit index.md
+
+## Examples
+
+### Example 1: Large PRD
+
+**Scenario:** 15-epic project, PRD is 45k tokens
+
+**Before Sharding:**
+
+```
+Every workflow loads entire 45k token PRD
+Epic-tech-context for Epic 3: 45k tokens
+Create-story for Epic 3: 45k tokens
+```
+
+**After Sharding:**
+
+```bash
+/shard-doc
+Source: docs/PRD.md
+Destination: docs/prd/
+
+Created:
+  prd/index.md
+  prd/overview.md (3k tokens)
+  prd/epic-1-auth.md (3k tokens)
+  prd/epic-2-dashboard.md (3k tokens)
+  prd/epic-3-reports.md (3k tokens)
+  ...15 epic files
+```
+
+**Result:**
+
+```
+Epic-tech-context for Epic 3: 3k tokens (93% reduction!)
+Create-story for Epic 3: 3k tokens (93% reduction!)
+```
+
+### Example 2: Sharding Epics File
+
+**Scenario:** 8 epics with detailed stories, 35k tokens total
+
+```bash
+/shard-doc
+Source: docs/bmm-epics.md
+Destination: docs/epics/
+
+Created:
+  epics/index.md
+  epics/epic-1.md
+  epics/epic-2.md
+  ...
+  epics/epic-8.md
+```
+
+**Efficiency Gain:**
+
+```
+Working on Epic 5 stories:
+  Old: Load all 8 epics (35k tokens)
+  New: Load epic-5.md only (4k tokens)
+  Savings: 88% reduction
+```
+
+### Example 3: Architecture Document
+
+**Scenario:** Multi-layer system architecture, 28k tokens
+
+```bash
+/shard-doc
+Source: docs/architecture.md
+Destination: docs/architecture/
+
+Created:
+  architecture/index.md
+  architecture/system-overview.md
+  architecture/frontend-architecture.md
+  architecture/backend-services.md
+  architecture/data-layer.md
+  architecture/infrastructure.md
+  architecture/security-architecture.md
+```
+
+**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc.
+
+## Custom Workflow Integration
+
+### For Workflow Builders
+
+When creating custom workflows that load large documents:
+
+**1. Add input_file_patterns to workflow.yaml:**
+
+```yaml
+input_file_patterns:
+  your_document:
+    whole: '{output_folder}/*your-doc*.md'
+    sharded: '{output_folder}/*your-doc*/index.md'
+```
+
+**2. Add discovery instructions to instructions.md:**
+
+```markdown
+## Document Discovery
+
+1. Search for whole document: _your-doc_.md
+2. Check for sharded version: _your-doc_/index.md
+3. If sharded: Read index + ALL sections (or specific sections if selective load)
+4. Priority: Whole document first
+```
+
+**3. Choose loading strategy:**
+
+- **Full Load**: Read all sections when sharded
+- **Selective Load**: Read only relevant sections (requires section identification logic)
+
+### Pattern Templates
+
+**Full Load Pattern:**
+
+```xml
+<action>Search for document: {output_folder}/*doc-name*.md</action>
+<action>If not found, check for sharded: {output_folder}/*doc-name*/index.md</action>
+<action if="sharded found">Read index.md to understand structure</action>
+<action if="sharded found">Read ALL section files listed in index</action>
+<action if="sharded found">Combine content as single document</action>
+```
+
+**Selective Load Pattern (with section ID):**
+
+```xml
+<action>Determine section needed (e.g., epic_num = 3)</action>
+<action>Check for sharded version: {output_folder}/*doc-name*/index.md</action>
+<action if="sharded found">Read ONLY the specific section file needed</action>
+<action if="sharded found">Skip all other section files</action>
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Both whole and sharded exist:**
+
+- Workflows will use whole document (priority rule)
+- Delete or archive the one you don't want
+
+**Index.md out of sync:**
+
+- Delete sharded folder
+- Re-run shard-doc on original
+
+**Workflow can't find document:**
+
+- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.)
+- Verify index.md exists in sharded folder
+- Check output_folder path in config
+
+**Sections too granular:**
+
+- Combine sections in original document
+- Use fewer level 2 headings
+- Re-shard
+
+## Related Documentation
+
+- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation
+- [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Workflow overview
+- [Workflow Creation Guide](../src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md) - Custom workflow patterns
+
+---
+
+**Document sharding is optional but powerful** - use it when efficiency matters for large projects!
--- a/docs/index.md
+++ b/docs/index.md
@ -99,6 +99,10 @@ Instructions for loading agents and running workflows in your development enviro
 - [Installers & Platforms Reference](./installers-bundlers/installers-modules-platforms-reference.md) - CLI tool and platform support
 - [Web Bundler Usage](./installers-bundlers/web-bundler-usage.md) - Creating web-compatible bundles

+### Optimization & Efficiency
+
+- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings in Phase 4 workflows
+
 ---

 ## 📊 Documentation Map
--- a/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md
+++ b/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md
@ -1020,6 +1020,164 @@ _Generated on {{date}}_
 - **Unclosed check tags** - Always close `<check if="">...</check>` blocks
 - **Wrong conditional pattern** - Use `<action if="">` for single items, `<check if="">` for blocks

+## Document Sharding Support
+
+If your workflow loads large planning documents (PRDs, epics, architecture, etc.), implement sharding support for efficiency.
+
+### What is Document Sharding?
+
+Document sharding splits large markdown files into smaller section-based files:
+
+- `PRD.md` (50k tokens) → `prd/epic-1.md`, `prd/epic-2.md`, etc.
+- Enables selective loading (90%+ token savings)
+- All BMM workflows support both whole and sharded documents
+
+### When to Add Sharding Support
+
+**Add sharding support if your workflow:**
+
+- Loads planning documents (PRD, epics, architecture, UX specs)
+- May be used in large multi-epic projects
+- Processes documents that could exceed 20k tokens
+- Would benefit from selective section loading
+
+**Skip sharding support if your workflow:**
+
+- Only generates small documents
+- Doesn't load external documents
+- Works with code files (not planning docs)
+
+### Implementation Pattern
+
+#### 1. Add input_file_patterns to workflow.yaml
+
+```yaml
+# 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_index: '{output_folder}/*epic*/index.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md' # For selective load
+
+  architecture:
+    whole: '{output_folder}/*architecture*.md'
+    sharded: '{output_folder}/*architecture*/index.md'
+
+  document_project:
+    sharded: '{output_folder}/docs/index.md' # Brownfield always uses index
+```
+
+#### 2. Add Discovery Instructions to instructions.md
+
+Place early in instructions (after critical declarations, before workflow steps):
+
+```markdown
+## 📚 Document Discovery
+
+This workflow requires: [list required documents]
+
+**Discovery Process** (execute for each document):
+
+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 the document structure
+   - Read ALL section files listed in the index (or specific sections for selective load)
+   - Treat the combined content as if it were a 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.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations.
+```
+
+#### 3. Choose Loading Strategy
+
+**Full Load Strategy** (most workflows):
+
+```xml
+<action>Search for document using fuzzy pattern: {output_folder}/*prd*.md</action>
+<action>If not found, check for sharded version: {output_folder}/*prd*/index.md</action>
+<action if="sharded found">Read index.md to understand structure</action>
+<action if="sharded found">Read ALL section files listed in index</action>
+<action if="sharded found">Combine content as single document</action>
+```
+
+**Selective Load Strategy** (advanced - for phase 4 type workflows):
+
+```xml
+<action>Determine section needed (e.g., epic_num from story key)</action>
+<action>Check for sharded version: {output_folder}/*epics*/index.md</action>
+<action if="sharded found">Read ONLY the specific section file: epics/epic-{{epic_num}}.md</action>
+<action if="sharded found">Skip all other section files (efficiency optimization)</action>
+<action if="whole document found">Load complete document and extract relevant section</action>
+```
+
+### Pattern Examples
+
+**Example 1: Simple Full Load**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  requirements:
+    whole: '{output_folder}/*requirements*.md'
+    sharded: '{output_folder}/*requirements*/index.md'
+```
+
+```markdown
+<!-- instructions.md -->
+
+## Document Discovery
+
+Load requirements document (whole or sharded).
+
+1. Try whole: _requirements_.md
+2. If not found, try sharded: _requirements_/index.md
+3. If sharded: Read index + ALL section files
+```
+
+**Example 2: Selective Load with Epic Number**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
+```
+
+```xml
+<!-- instructions.md step -->
+<step n="2" goal="Load Epic Content">
+  <action>Extract epic number from story key (e.g., "3-2-feature" → epic_num = 3)</action>
+  <action>Check for sharded epics: {output_folder}/*epic*/index.md</action>
+  <action if="sharded found">Load ONLY epics/epic-{{epic_num}}.md (selective optimization)</action>
+  <action if="whole document found">Load full epics.md and extract Epic {{epic_num}}</action>
+</step>
+```
+
+### Testing Your Sharding Support
+
+1. **Test with whole document**: Verify workflow works with single `document.md`
+2. **Test with sharded document**: Create sharded version and verify discovery
+3. **Test with both present**: Ensure whole document takes priority
+4. **Test selective loading**: Verify only needed sections are loaded (if applicable)
+
+### Complete Reference
+
+**[→ Document Sharding Guide](../../../../docs/document-sharding-guide.md)** - Comprehensive guide with examples
+
+**BMM Examples**:
+
+- Full Load: `src/modules/bmm/workflows/2-plan-workflows/prd/`
+- Selective Load: `src/modules/bmm/workflows/4-implementation/epic-tech-context/`
+
 ## Web Bundles

 Web bundles allow workflows to be deployed as self-contained packages for web environments.
--- a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
@ -8,6 +8,24 @@
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>LIVING DOCUMENT: Write to the document continuously as you discover - never wait until the end</critical>

+## Input Document Discovery
+
+This workflow may reference: market research, brainstorming documents, user specified other inputs, 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">
--- a/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml
+++ b/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml
@ -19,6 +19,20 @@ recommended_inputs:
  - competitive_analysis: "Competitive analysis (optional)"
  - initial_ideas: "Initial product ideas or notes (optional)"

+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  brainstorming:
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief"
 template: "{installed_path}/template.md"
--- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md
@ -12,6 +12,24 @@

 <critical>DOCUMENT OUTPUT: Professional, specific, actionable UX design decisions WITH RATIONALE. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>

+## 📚 Input Document Discovery
+
+This workflow requires: PRD or product brief, and may reference epics/stories, brainstorming documents, 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>

--- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml
@ -23,6 +23,28 @@ prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
 brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
 brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.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"
+
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  brainstorming:
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
 instructions: "{installed_path}/instructions.md"
--- a/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md
@ -14,6 +14,24 @@

 <critical>DOCUMENT OUTPUT: Concise, clear, actionable game design specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>

+## Input Document Discovery
+
+This workflow requires: game brief, and may reference market research 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 and extract project configuration">

 <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
--- a/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml
@ -30,6 +30,20 @@ recommended_inputs:
  - narrative_design: "{output_folder}/narrative-design.md"
  - market_research: "{output_folder}/market-research.md"

+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  game_brief:
+    whole: "{output_folder}/*game-brief*.md"
+    sharded: "{output_folder}/*game-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:
--- a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
@ -8,6 +8,24 @@
 <critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
 <critical>GUIDING PRINCIPLE: Find and weave the product's magic throughout - what makes it special should inspire every section</critical>

+## 📚 Input Document Discovery
+
+This workflow requires: product brief, and may reference market research 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">
--- a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
@ -29,6 +29,20 @@ recommended_inputs:
  - product_brief: "{output_folder}/product-brief.md"
  - market_research: "{output_folder}/market-research.md"

+# 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:
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
@ -13,6 +13,24 @@

 <critical>DOCUMENT OUTPUT: Technical, precise, definitive. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>

+## 📚 Input Document Discovery
+
+This workflow may reference: product brief, research documents, 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>

--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
@ -36,6 +36,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:
--- a/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md
+++ b/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>

--- a/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml
+++ b/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}/*PRD*, PRD.md, or prd/index.md + files"
-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"
--- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md
+++ b/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">
--- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml
+++ b/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"

--- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md
+++ b/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">
--- a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml
+++ b/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
--- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md
+++ b/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">
--- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
@ -44,6 +44,30 @@ 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"
+
+  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
--- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md
+++ b/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>
--- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
@ -13,13 +13,39 @@ date: system-generated
 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"
--- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md
--- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml
+++ b/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"
--- a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md
+++ b/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">
--- a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml
+++ b/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}"

--- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md
+++ b/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">
--- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
@ -23,6 +23,30 @@ 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"
+
+  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"
--- a/src/modules/bmm/workflows/README.md
+++ b/src/modules/bmm/workflows/README.md
@ -23,6 +23,7 @@ Master guide for BMM's four-phase methodology that adapts to project scale (Leve
 - **Just-In-Time Design** - Tech specs created per epic during implementation
 - **Dynamic Expertise Injection** - Story-specific technical guidance
 - **Continuous Learning Loop** - Retrospectives improve each cycle
+- **Document Sharding Support** - All workflows handle whole or sharded documents for efficiency

 ## Universal Entry Point

@ -209,6 +210,46 @@ document-project (if needed) → Phase 1 (optional) → Phase 2 → Phase 3 (L2-
 2. **Respect scale** - Don't over-document small projects
 3. **Use status tracking** - Always know where you are
 4. **Iterate and learn** - Each epic improves the next
+5. **Consider sharding** - Split large documents (PRD, epics, architecture) for efficiency
+
+## Document Sharding
+
+For large multi-epic projects, consider sharding planning documents to improve workflow efficiency.
+
+### What is Sharding?
+
+Splits large markdown files into smaller section-based files:
+
+- PRD with 15 epics → `prd/epic-1.md`, `prd/epic-2.md`, etc.
+- Large epics file → Individual epic files
+- Architecture layers → Separate layer files
+
+### Benefits
+
+**Phase 1-3 Workflows:**
+
+- Workflows load entire sharded documents (transparent to user)
+- Better organization for large projects
+
+**Phase 4 Workflows:**
+
+- **Selective loading** - Only load the epic/section needed
+- **Massive efficiency** - 90%+ token reduction for 10+ epic projects
+- Examples: `epic-tech-context`, `create-story`, `story-context`, `code-review`
+
+### Usage
+
+```
+Load bmad-master or analyst agent:
+/shard-doc
+
+Source: docs/PRD.md
+Destination: docs/prd/
+```
+
+**All BMM workflows automatically support both whole and sharded documents.**
+
+**[→ Complete Sharding Guide](../../../docs/document-sharding-guide.md)**

 ---