2025-10-30 11:26:15 -05:00
# BMad Documentation Index
Complete map of all BMad Method v6 documentation with recommended reading paths.
---
## 🎯 Getting Started (Start Here!)
**New users:** Start with one of these based on your situation:
| Your Situation | Start Here | Then Read |
| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------- |
| **Brand new to BMad** | [Quick Start Guide ](./BMad-Method-V6-Quick-Start.md ) | [BMM Workflows Guide ](../src/modules/bmm/workflows/README.md ) |
| **Upgrading from v4** | [v4 to v6 Upgrade Guide ](./v4-to-v6-upgrade.md ) | [Quick Start Guide ](./BMad-Method-V6-Quick-Start.md ) |
| **Brownfield project** | [Brownfield Guide ](./bmad-brownfield-guide.md ) | [Quick Start Guide ](./BMad-Method-V6-Quick-Start.md ) |
---
## 📋 Core Documentation
### Project-Level Docs (Root)
- **[README.md ](../README.md )** - Main project overview, feature summary, and module introductions
- **[CONTRIBUTING.md ](../CONTRIBUTING.md )** - How to contribute, pull request guidelines, code style
- **[CHANGELOG.md ](../CHANGELOG.md )** - Version history and breaking changes
- **[CLAUDE.md ](../CLAUDE.md )** - Claude Code specific guidelines for this project
### Installation & Setup
- **[BMad Method V6 Quick Start ](./BMad-Method-V6-Quick-Start.md )** - Step-by-step guide to building your first project with BMM
- **[v4 to v6 Upgrade Guide ](./v4-to-v6-upgrade.md )** - Migration path for v4 users
- **[Brownfield Guide ](./bmad-brownfield-guide.md )** - Guidance for working with existing codebases
---
## 🏗️ Module Documentation
### BMad Method (BMM) - Software & Game Development
The flagship module for agile AI-driven development.
- **[BMM Module README ](../src/modules/bmm/README.md )** - Module overview, agents, and structure
- **[BMM Workflows Guide ](../src/modules/bmm/workflows/README.md )** - **ESSENTIAL READING** - Complete v6 workflow system explanation
- Phase 1: Analysis (optional)
- Phase 2: Planning (required, scale-adaptive)
- Phase 3: Solutioning (complex projects)
- Phase 4: Implementation (iterative)
- **[Test Architect Guide ](../src/modules/bmm/testarch/README.md )** - Testing strategy and quality assurance
### BMad Builder (BMB) - Create Custom Solutions
Build your own agents, workflows, and modules.
- **[BMB Module README ](../src/modules/bmb/README.md )** - Module overview and capabilities
- **[Agent Creation Guide ](../src/modules/bmb/workflows/create-agent/README.md )** - Design custom agents
### Creative Intelligence Suite (CIS) - Innovation & Creativity
AI-powered creative thinking and brainstorming.
- **[CIS Module README ](../src/modules/cis/README.md )** - Module overview and workflows
---
## 🖥️ IDE-Specific Guides
Instructions for loading agents and running workflows in your development environment.
**Popular IDEs:**
- [Claude Code ](./ide-info/claude-code.md )
- [Cursor ](./ide-info/cursor.md )
- [VS Code ](./ide-info/windsurf.md )
**Other Supported IDEs:**
- [Augment ](./ide-info/auggie.md )
- [Cline ](./ide-info/cline.md )
- [Codex ](./ide-info/codex.md )
- [Crush ](./ide-info/crush.md )
- [Gemini ](./ide-info/gemini.md )
- [GitHub Copilot ](./ide-info/github-copilot.md )
- [IFlow ](./ide-info/iflow.md )
- [Kilo ](./ide-info/kilo.md )
- [OpenCode ](./ide-info/opencode.md )
- [Qwen ](./ide-info/qwen.md )
- [Roo ](./ide-info/roo.md )
- [Trae ](./ide-info/trae.md )
**Key concept:** Every reference to "load an agent" or "activate an agent" in the main docs links to the [ide-info ](./ide-info/ ) directory for IDE-specific instructions.
---
## 🔧 Advanced Topics
### Installation & Bundling
- [IDE Injections Reference ](./installers-bundlers/ide-injections.md ) - How agents are installed to IDEs
- [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
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
### Optimization & Efficiency
- **[Document Sharding Guide ](./document-sharding-guide.md )** - Split large documents for 90%+ token savings in Phase 4 workflows
2025-10-30 11:26:15 -05:00
---
## 📊 Documentation Map
```
docs/
├── index.md (this file)
├── BMad-Method-V6-Quick-Start.md
├── v4-to-v6-upgrade.md
├── bmad-brownfield-guide.md
├── ide-info/
│ ├── claude-code.md
│ ├── cursor.md
│ ├── windsurf.md
│ └── [14+ other IDEs]
└── installers-bundlers/
├── ide-injections.md
├── installers-modules-platforms-reference.md
└── web-bundler-usage.md
src/
├── modules/
│ ├── bmm/
│ │ ├── README.md
│ │ ├── workflows/README.md (ESSENTIAL)
│ │ └── testarch/README.md
│ ├── bmb/
│ │ ├── README.md
│ │ └── workflows/create-agent/README.md
│ └── cis/
│ └── README.md
```
---
## 🎓 Recommended Reading Paths
### Path 1: Brand New to BMad (Software Project)
1. [README.md ](../README.md ) - Understand the vision
2. [Quick Start Guide ](./BMad-Method-V6-Quick-Start.md ) - Get hands-on
3. [BMM Module README ](../src/modules/bmm/README.md ) - Understand agents
4. [BMM Workflows Guide ](../src/modules/bmm/workflows/README.md ) - Master the methodology
5. [Your IDE guide ](./ide-info/ ) - Optimize your workflow
### Path 2: Game Development Project
1. [README.md ](../README.md ) - Understand the vision
2. [Quick Start Guide ](./BMad-Method-V6-Quick-Start.md ) - Get hands-on
3. [BMM Module README ](../src/modules/bmm/README.md ) - Game agents are included
4. [BMM Workflows Guide ](../src/modules/bmm/workflows/README.md ) - Game workflows
5. [Your IDE guide ](./ide-info/ ) - Optimize your workflow
### Path 3: Upgrading from v4
1. [v4 to v6 Upgrade Guide ](./v4-to-v6-upgrade.md ) - Understand what changed
2. [Quick Start Guide ](./BMad-Method-V6-Quick-Start.md ) - Reorient yourself
3. [BMM Workflows Guide ](../src/modules/bmm/workflows/README.md ) - Learn new v6 workflows
### Path 4: Working with Existing Codebase (Brownfield)
1. [Brownfield Guide ](./bmad-brownfield-guide.md ) - Approach for legacy code
2. [Quick Start Guide ](./BMad-Method-V6-Quick-Start.md ) - Follow the process
3. [BMM Workflows Guide ](../src/modules/bmm/workflows/README.md ) - Master the methodology
### Path 5: Building Custom Solutions
1. [BMB Module README ](../src/modules/bmb/README.md ) - Understand capabilities
2. [Agent Creation Guide ](../src/modules/bmb/workflows/create-agent/README.md ) - Create agents
3. [BMM Workflows Guide ](../src/modules/bmm/workflows/README.md ) - Understand workflow structure
### Path 6: Contributing to BMad
1. [CONTRIBUTING.md ](../CONTRIBUTING.md ) - Contribution guidelines
2. Relevant module README - Understand the area you're contributing to
3. [Code Style section in CONTRIBUTING.md ](../CONTRIBUTING.md#code-style ) - Follow standards
---
## 🔍 Quick Reference
**What is each module for?**
- **BMM** - AI-driven software and game development
- **BMB** - Create custom agents and workflows
- **CIS** - Creative thinking and brainstorming
**How do I load an agent?**
→ See [ide-info ](./ide-info/ ) folder for your IDE
**I'm stuck, what's next?**
→ Check the [BMM Workflows Guide ](../src/modules/bmm/workflows/README.md ) or run `workflow-status`
**I want to contribute**
→ Start with [CONTRIBUTING.md ](../CONTRIBUTING.md )
---
## 📚 Important Concepts
### Fresh Chats
Each workflow should run in a fresh chat with the specified agent to avoid context limitations. This is emphasized throughout the docs because it's critical to successful workflows.
### Scale Levels
BMM adapts to project complexity (Levels 0-4). Documentation is scale-adaptive - you only need what's relevant to your project size.
### Update-Safe Customization
All agent customizations go in `bmad/_cfg/agents/` and survive updates. See your IDE guide and module README for details.
---
## 🆘 Getting Help
- **Discord**: [Join the BMad Community ](https://discord.gg/gk8jAdXWmj )
- #general -dev - Technical questions
- #bugs -issues - Bug reports
- **Issues**: [GitHub Issue Tracker ](https://github.com/bmad-code-org/BMAD-METHOD/issues )
- **YouTube**: [BMad Code Channel ](https://www.youtube.com/@BMadCode )
---
**Version**: v6-alpha
**Last Updated**: 2025-10-30
---
