3d4ea5ffd2
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
|
||
|---|---|---|
| .claude/commands/bmad | ||
| .github | ||
| .husky | ||
| .vscode | ||
| bmad | ||
| bmd | ||
| docs | ||
| src | ||
| test | ||
| tools | ||
| .gitignore | ||
| .npmrc | ||
| .nvmrc | ||
| .prettierignore | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
| eslint.config.mjs | ||
| package-lock.json | ||
| package.json | ||
| prettier.config.mjs | ||
| v6-open-items.md | ||
README.md
BMad CORE + BMad Method
🚨 ALPHA VERSION DOCUMENTATION
- Install v6 Alpha:
npx bmad-method@alpha install- Install stable v4:
npx bmad-method install- View v4 documentation
Universal Human-AI Collaboration Platform
BMad-CORE (Collaboration Optimized Reflection Engine) amplifies human potential through specialized AI agents. Unlike tools that replace thinking, BMad-CORE guides reflective workflows that bring out your best ideas and AI's full capabilities.
🎯 Human Amplification • 🎨 Domain Agnostic • ⚡ Agent-Powered
Table of Contents
Quick Start
- New to v6? → BMad Method V6 Quick Start Guide
- Upgrading? → v4 to v6 Upgrade Guide
What is BMad-CORE?
Foundation framework powering all BMad modules:
- Agent Orchestration - Specialized AI personas with unique capabilities
- Workflow Engine - Guided multi-step processes
- Modular Architecture - Domain-specific extensions
- IDE Integration - Works across development environments
- Update-Safe Customization - Persistent configuration through updates
v6 Core Enhancements
- 🎨 Agent Customization - Modify names, roles, personalities via
bmad/_cfg/agents/ - 🌐 Multi-Language - Independent language settings for communication and output
- 👤 Personalization - Agents adapt to your name, technical level, preferences
- 🔄 Persistent Config - Customizations survive all updates
- ⚙️ Flexible Settings - Module or global configuration options
C.O.R.E. Philosophy
- Collaboration: Human-AI partnership leveraging unique strengths
- Optimized: Refined processes for maximum effectiveness
- Reflection: Guided thinking unlocking better solutions
- Engine: Framework orchestrating specialized agents and workflows
BMad-CORE helps you discover better solutions through strategic questioning and structured thinking.
Modules
BMad Method (BMM) - Agile AI Development
AI-driven agile framework revolutionizing software and game development. Adapts from bug fixes to enterprise systems.
v6 Highlights
🎯 Scale-Adaptive Workflows (Levels 0-4)
- Automatically adjusts complexity from quick fixes to enterprise projects
- Greenfield & brownfield support with smart context engine
🏗️ Project-Adaptive Architecture
- Documents adapt to project type (web, mobile, embedded, game)
- Engine-specific game development (Unity, Phaser, Godot, Unreal)
📋 Four-Phase Methodology
- Analysis - Brainstorming, research, briefs
- Planning - Scale-adaptive PRD/GDD
- Solutioning - Architecture and tech specs
- Implementation - Stories, development, review
Specialized Agents: PM, Analyst, Architect, Scrum Master, Developer, Game Designer/Developer/Architect, UX, Test Architect
Documentation: 📚 BMM Module | 📖 Workflows Guide
BMad Builder (BMB) - Create Custom Solutions
Build custom agents, workflows, and modules using BMad-CORE framework.
- Agent Creation - Custom roles and behaviors
- Workflow Design - Structured multi-step processes
- Module Development - Complete domain solutions
- Three Agent Types - Full module, hybrid, standalone
Documentation:
- 📚 BMB Module - Complete module reference
- 🎯 Create Agent - Agent builder workflow
- 📋 Create Workflow - Workflow designer
- 📦 Create Module - Module scaffolding
Creative Intelligence Suite (CIS) - Innovation & Creativity
AI-powered creative facilitation across five domains.
- 5 Interactive Workflows - Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
- 150+ Creative Techniques - Proven frameworks and methodologies
- 5 Specialized Agents - Unique personas and facilitation styles
- Shared Resource - Powers creative workflows in other modules
Documentation: 📚 CIS Module | 📖 CIS Workflows
Installation
Prerequisites: Node.js v20+ (Download)
# Install v6 Alpha
npx bmad-method@alpha install
# Install stable v4
npx bmad-method install
Interactive installer guides you through:
- Project location - Installation directory
- Module selection - BMM, BMB, CIS
- Configuration - Name, language, game dev options
- IDE integration - Environment setup
Project Structure
your-project/
└── bmad/
├── core/ # Core framework
├── bmm/ # BMad Method
├── bmb/ # BMad Builder
├── cis/ # Creative Intelligence
└── _cfg/ # Your customizations
└── agents/ # Agent configs
Getting Started
After installation, activate Analyst agent and run:
/workflow-init
This initializes the workflow system and helps choose your starting point.
Key Features
🎨 Update-Safe Customization
- Agent modification via
bmad/_cfg/agents/ - Persistent settings through updates
- Multi-language support
- Flexible configuration
🚀 Intelligent Installation
- Auto-detects v4 installations
- Configures IDE integrations
- Resolves dependencies
- Creates unified manifests
📁 Unified Architecture
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
Documentation
- 📚 Documentation Index - Complete documentation map
- v4 to v6 Upgrade Guide - Migration instructions
- CLI Tool Guide - Installer reference
- Contributing Guide - Contribution guidelines
Community & Support
- 💬 Discord - Community help
- 🐛 Issues - Bug reports
- 🎥 YouTube - Tutorials
- ⭐ Star this repo - Updates
Contributing
See CONTRIBUTING.md for guidelines.
License
MIT License - See LICENSE
Trademark: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
Built with ❤️ for the human-AI collaboration community