2025-11-18 23:16:23 -06:00
# BMad Method & BMad Core
2025-06-08 02:30:28 -05:00
2025-11-03 21:46:49 -06:00
[](https://www.npmjs.com/package/bmad-method)
[](https://www.npmjs.com/package/bmad-method)
2025-06-13 20:16:33 -05:00
[](LICENSE)
2025-06-17 09:35:39 -05:00
[](https://nodejs.org)
2025-06-28 08:36:12 -05:00
[](https://discord.gg/gk8jAdXWmj)
2025-06-08 02:30:28 -05:00
2025-11-18 23:16:23 -06:00
## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
2025-09-29 08:00:30 -05:00
2025-11-18 23:16:23 -06:00
**Build More, Architect Dreams** (BMAD) with **19 specialized AI agents** and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms.
2025-09-29 10:13:22 -05:00
2025-11-18 23:16:23 -06:00
> **🚀 v6 is a MASSIVE upgrade from v4!** Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. [See what's new →](#whats-new-in-v6)
2025-06-29 21:09:13 -05:00
2025-11-18 23:16:23 -06:00
> **📌 v6 Alpha Status:** Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to [BMadCode YouTube](https://www.youtube.com/@BMadCode).
2025-10-18 12:19:47 -05:00
2025-11-18 23:16:23 -06:00
## 🎯 Why BMad Method?
2025-09-29 10:13:22 -05:00
2025-11-18 23:16:23 -06:00
Unlike generic AI coding assistants, BMad Method provides **structured, battle-tested workflows** powered by specialized agents who understand agile development. Each agent has deep domain expertise—from product management to architecture to testing—working together seamlessly.
2025-06-13 20:16:33 -05:00
2025-11-18 23:16:23 -06:00
**✨ Key Benefits:**
2025-10-04 01:26:38 -05:00
2025-11-18 23:16:23 -06:00
- **Scale-Adaptive Intelligence** - Automatically adjusts planning depth from bug fixes to enterprise systems
- **Complete Development Lifecycle** - Analysis → Planning → Architecture → Implementation
- **Specialized Expertise** - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.)
- **Proven Methodologies** - Built on agile best practices with AI amplification
- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code
2025-06-13 20:16:33 -05:00
2025-11-18 23:16:23 -06:00
## 🏗️ The Power of BMad Core
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
**BMad Method** is actually a sophisticated module built on top of **BMad Core** (**C**ollaboration **O**ptimized **R**eflection **E**ngine). This revolutionary architecture means:
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
- **BMad Core** provides the universal framework for human-AI collaboration
- **BMad Method** leverages Core to deliver agile development workflows
- **BMad Builder** lets YOU create custom modules as powerful as BMad Method itself
2025-06-28 16:12:01 -05:00
2025-11-18 23:16:23 -06:00
With **BMad Builder** , you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an **official community marketplace** . Imagine building and sharing your own specialized AI team!
2025-06-28 16:12:01 -05:00
2025-11-18 23:16:23 -06:00
## 📊 See It In Action
2025-10-18 12:19:47 -05:00
2025-11-18 23:16:23 -06:00
< p align = "center" >
< img src = "./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt = "BMad Method Workflow" width = "100%" >
< / p >
2025-06-16 22:26:30 -05:00
2025-11-18 23:16:23 -06:00
< p align = "center" >
< em > Complete BMad Method workflow showing all phases, agents, and decision points< / em >
< / p >
2025-06-16 22:26:30 -05:00
2025-11-18 23:16:23 -06:00
## 🚀 Get Started in 3 Steps
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
### 1. Install BMad Method
feat: Complete BMAD agent creation system with install tooling, references, and field guidance
## Overview
This commit represents a complete overhaul of the BMAD agent creation system, establishing clear standards for agent development, installation workflows, and persona design. The changes span documentation, tooling, reference implementations, and field-specific guidance.
## Key Components
### 1. Agent Installation Infrastructure
**New CLI Command: `agent-install`**
- Interactive agent installation with persona customization
- Supports Simple (single YAML), Expert (sidecar files), and Module agents
- Template variable processing with Handlebars-style syntax
- Automatic compilation from YAML to XML (.md) format
- Manifest tracking and IDE integration (Claude Code, Cursor, Windsurf, etc.)
- Source preservation in `_cfg/custom/agents/` for reinstallation
**Files Created:**
- `tools/cli/commands/agent-install.js` - Main CLI command
- `tools/cli/lib/agent/compiler.js` - YAML to XML compilation engine
- `tools/cli/lib/agent/installer.js` - Installation orchestration
- `tools/cli/lib/agent/template-engine.js` - Handlebars template processing
**Compiler Features:**
- Auto-injects frontmatter, activation, handlers, help/exit menu items
- Smart handler inclusion (only includes action/workflow/exec/tmpl handlers actually used)
- Proper XML escaping and formatting
- Persona name customization (e.g., "Fred the Commit Poet")
### 2. Documentation Overhaul
**Deleted Bloated/Outdated Docs (2,651 lines removed):**
- Old verbose architecture docs
- Redundant pattern files
- Outdated workflow guides
**Created Focused, Type-Specific Docs:**
- `src/modules/bmb/docs/understanding-agent-types.md` - Architecture vs capability distinction
- `src/modules/bmb/docs/simple-agent-architecture.md` - Self-contained agents
- `src/modules/bmb/docs/expert-agent-architecture.md` - Agents with sidecar files
- `src/modules/bmb/docs/module-agent-architecture.md` - Workflow-integrated agents
- `src/modules/bmb/docs/agent-compilation.md` - YAML → XML process
- `src/modules/bmb/docs/agent-menu-patterns.md` - Menu design patterns
- `src/modules/bmb/docs/index.md` - Documentation hub
**Net Result:** ~1,930 line reduction while adding MORE value through focused content
### 3. Create-Agent Workflow Enhancements
**Critical Persona Field Guidance Added to Step 4:**
Explains how the LLM interprets each persona field when the agent activates:
- **role** → "What knowledge, skills, and capabilities do I possess?"
- **identity** → "What background, experience, and context shape my responses?"
- **communication_style** → "What verbal patterns, word choice, quirks, and phrasing do I use?"
- **principles** → "What beliefs and operating philosophy drive my choices?"
**Key Insight:** `communication_style` should ONLY describe HOW the agent talks, not restate role/identity/principles. The `communication-presets.csv` provides 60 pure communication styles with NO role/identity/principles mixed in.
**Files Updated:**
- `src/modules/bmb/workflows/create-agent/instructions.md` - Added persona field interpretation guide
- `src/modules/bmb/workflows/create-agent/brainstorm-context.md` - Refined to 137 lines
- `src/modules/bmb/workflows/create-agent/communication-presets.csv` - 60 styles across 13 categories
### 4. Reference Agent Cleanup
**Removed install_config Personality Bloat:**
Understanding: Future installer will handle personality customization, so stripped all personality toggles from reference agents.
**commit-poet.agent.yaml** (Simple Agent):
- BEFORE: 36 personality combinations (3 enthusiasm × 3 depths × 4 styles) = decision fatigue
- AFTER: Single concise persona with pure communication style
- Changed from verbose conditionals to: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
- Reduction: 248 lines → 153 lines (38% reduction)
**journal-keeper.agent.yaml** (Expert Agent):
- Stripped install_config, simplified communication_style
- Shows proper Expert agent structure with sidecar files
**security-engineer.agent.yaml & trend-analyst.agent.yaml** (Module Agents):
- Added header comments explaining WHY Module Agent (design intent, not just location)
- Clarified: Module agents are designed FOR ecosystem integration, not capability-limited
**Files Updated:**
- `src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml`
- `src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml`
### 5. BMM Agent Voice Enhancement
**Gave all 9 BMM agents distinct, memorable communication voices:**
**Mary (analyst)** - The favorite! Changed from generic "systematic and probing" to:
"Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision."
**Other Notable Voices:**
- **John (pm):** "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
- **Winston (architect):** "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
- **Amelia (dev):** "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
- **Bob (sm):** "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
- **Sally (ux-designer):** "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
**Pattern Applied:** Moved behaviors from communication_style to principles, keeping communication_style as PURE verbal patterns.
**Files Updated:**
- `src/modules/bmm/agents/analyst.agent.yaml`
- `src/modules/bmm/agents/pm.agent.yaml`
- `src/modules/bmm/agents/architect.agent.yaml`
- `src/modules/bmm/agents/dev.agent.yaml`
- `src/modules/bmm/agents/sm.agent.yaml`
- `src/modules/bmm/agents/tea.agent.yaml`
- `src/modules/bmm/agents/tech-writer.agent.yaml`
- `src/modules/bmm/agents/ux-designer.agent.yaml`
- `src/modules/bmm/agents/frame-expert.agent.yaml`
### 6. Linting Fixes
**ESLint Compliance:**
- Replaced all `'utf-8'` with `'utf8'` (unicorn/text-encoding-identifier-case)
- Changed `variables.hasOwnProperty(varName)` to `Object.hasOwn(variables, varName)` (unicorn/prefer-object-has-own)
- Replaced `JSON.parse(JSON.stringify(...))` with `structuredClone(...)` (unicorn/prefer-structured-clone)
- Fixed empty YAML mapping values in sample files
**Files Fixed:**
- 7 JavaScript files across agent tooling (compiler, installer, commands, IDE integration)
- 1 YAML sample file
## Architecture Decisions
### Agent Types Are About Architecture, Not Capability
- **Simple:** Self-contained in single YAML (NOT limited in capability)
- **Expert:** Includes sidecar files (templates, docs, etc.)
- **Module:** Designed for BMAD ecosystem integration (workflows, cross-agent coordination)
### Persona Field Separation Critical for LLM Interpretation
The LLM needs distinct fields to understand its role:
- Mixing role/identity/principles into communication_style confuses the persona
- Pure communication styles (from communication-presets.csv) have ZERO role/identity/principles content
- Example DON'T: "Experienced analyst who uses systematic approaches..." (mixing identity + style)
- Example DO: "Systematic and probing. Structures findings hierarchically." (pure style)
### Install-Time vs Runtime Configuration
- Template variables ({{var}}) resolve at compile-time
- Runtime variables ({user_name}, {bmad_folder}) resolve when agent activates
- Future installer will handle personality customization, so agents should ship with single default persona
## Testing
- All linting passes (ESLint with max-warnings=0)
- Agent compilation tested with commit-poet, journal-keeper examples
- Install workflow validated with Simple and Expert agent types
- Manifest tracking and IDE integration verified
## Impact
This establishes BMAD as having a complete, production-ready agent creation and installation system with:
- Clear documentation for all agent types
- Automated compilation and installation
- Strong persona design guidance
- Reference implementations showing best practices
- Distinct, memorable agent voices throughout BMM module
Co-Authored-By: BMad Builder <builder@bmad.dev>
Co-Authored-By: Mary the Analyst <analyst@bmad.dev>
Co-Authored-By: Paige the Tech Writer <tech-writer@bmad.dev>
2025-11-17 22:25:15 -06:00
```bash
2025-11-18 23:16:23 -06:00
# Install v6 Alpha (recommended)
2025-10-29 09:12:27 -05:00
npx bmad-method@alpha install
2025-11-18 23:16:23 -06:00
# Or stable v4 for production
2025-10-26 23:25:48 -05:00
npx bmad-method install
2025-10-18 12:19:47 -05:00
```
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
### 2. Initialize Your Project
2025-10-18 12:19:47 -05:00
2025-11-18 23:16:23 -06:00
Load any agent in your IDE and run:
2025-10-18 12:19:47 -05:00
```
2025-11-18 23:16:23 -06:00
*workflow-init
2025-10-18 12:19:47 -05:00
```
2025-11-18 23:16:23 -06:00
This analyzes your project and recommends the right workflow track.
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
### 3. Choose Your Track
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
BMad Method adapts to your needs with three intelligent tracks:
2025-11-11 13:35:30 -06:00
2025-11-18 23:16:23 -06:00
| Track | Use For | Planning | Time to Start |
| ------------------ | ------------------------- | ----------------------- | ------------- |
| ** ⚡ Quick Flow** | Bug fixes, small features | Tech spec only | < 5 minutes |
| ** 📋 BMad Method** | Products, platforms | PRD + Architecture + UX | < 15 minutes |
| ** 🏢 Enterprise** | Compliance, scale | Full governance suite | < 30 minutes |
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal.
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
## 🔄 How It Works: 4-Phase Methodology
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
BMad Method guides you through a proven development lifecycle:
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
1. ** 📊 Analysis** (Optional) - Brainstorm, research, and explore solutions
2. ** 📝 Planning** - Create PRDs, tech specs, or game design documents
3. ** 🏗️ Solutioning** - Design architecture, UX, and technical approach
4. ** ⚡ Implementation** - Story-driven development with continuous validation
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
Each phase has specialized workflows and agents working together to deliver exceptional results.
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
## 🤖 Meet Your Team
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
**12 Specialized Agents** working in concert:
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
| Development | Architecture | Product | Leadership |
| ----------- | -------------- | ------------- | -------------- |
| Developer | Architect | PM | Scrum Master |
| UX Designer | Test Architect | Analyst | BMad Master |
| Tech Writer | Game Architect | Game Designer | Game Developer |
2025-11-03 21:46:49 -06:00
2025-11-20 17:34:08 -06:00
**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready fixture-based utilities.
2025-11-18 23:16:23 -06:00
Each agent brings deep expertise and can be customized to match your team's style.
2025-11-03 21:46:49 -06:00
2025-11-18 23:16:23 -06:00
## 📦 What's Included
2025-10-18 12:19:47 -05:00
2025-11-18 23:16:23 -06:00
### Core Modules
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
- **BMad Method (BMM)** - Complete agile development framework
- 12 specialized agents
- 34 workflows across 4 phases
- Scale-adaptive planning
- [→ Documentation Hub ](./src/modules/bmm/docs/README.md )
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
- **BMad Builder (BMB)** - Create custom agents and workflows
- Build anything from simple agents to complex modules
- Create domain-specific solutions (legal, medical, finance, education)
- Share your creations in the upcoming community marketplace
- [→ Builder Guide ](./src/modules/bmb/README.md )
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
- Brainstorming, design thinking, storytelling
- 5 creative facilitation workflows
- [→ Creative Workflows ](./src/modules/cis/README.md )
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
### Key Features
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
- **🎨 Customizable Agents** - Modify personalities, expertise, and communication styles
- **🌐 Multi-Language Support** - Separate settings for communication and code output
- **📄 Document Sharding** - 90% token savings for large projects
- **🔄 Update-Safe** - Your customizations persist through updates
- **🚀 Web Bundles** - Use in ChatGPT, Claude Projects, or Gemini Gems
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
## 📚 Documentation
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
### Quick Links
2025-10-18 12:19:47 -05:00
2025-11-18 23:16:23 -06:00
- **[Quick Start Guide ](./src/modules/bmm/docs/quick-start.md )** - 15-minute introduction
- **[Complete BMM Documentation ](./src/modules/bmm/docs/README.md )** - All guides and references
- **[Agent Customization ](./docs/agent-customization-guide.md )** - Personalize your agents
- **[All Documentation ](./docs/index.md )** - Complete documentation index
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
### For v4 Users
2025-09-28 23:17:07 -05:00
2025-11-18 23:16:23 -06:00
- **[v4 Documentation ](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4 )**
- **[v4 to v6 Upgrade Guide ](./docs/v4-to-v6-upgrade.md )**
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-18 23:16:23 -06:00
## 💬 Community & Support
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-18 23:16:23 -06:00
- **[Discord Community ](https://discord.gg/gk8jAdXWmj )** - Get help, share projects
- **[GitHub Issues ](https://github.com/bmad-code-org/BMAD-METHOD/issues )** - Report bugs, request features
- **[YouTube Channel ](https://www.youtube.com/@BMadCode )** - Video tutorials and demos
- **[Web Bundles ](https://bmad-code-org.github.io/bmad-bundles/ )** - Pre-built agent bundles
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
## 🛠️ Development
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-18 23:16:23 -06:00
For contributors working on the BMad codebase:
2025-11-05 14:14:31 -06:00
```bash
2025-11-18 23:16:23 -06:00
# Run all quality checks
2025-11-05 14:14:31 -06:00
npm test
2025-11-18 23:16:23 -06:00
# Development commands
2025-11-20 17:34:08 -06:00
npm run lint:fix # Fix code style
2025-11-18 23:16:23 -06:00
npm run format:fix # Auto-format code
npm run bundle # Build web bundles
2025-11-05 14:14:31 -06:00
```
2025-11-18 23:16:23 -06:00
See [CONTRIBUTING.md ](CONTRIBUTING.md ) for full development guidelines.
2025-11-05 14:14:31 -06:00
2025-11-18 23:16:23 -06:00
## What's New in v6
2025-11-05 14:14:31 -06:00
2025-11-18 23:16:23 -06:00
**v6 represents a complete architectural revolution from v4:**
2025-11-05 14:14:31 -06:00
2025-11-18 23:16:23 -06:00
### 🚀 Major Upgrades
2025-11-05 14:14:31 -06:00
2025-11-18 23:16:23 -06:00
- **BMad Core Framework** - Modular architecture enabling custom domain solutions
- **Scale-Adaptive Intelligence** - Automatic adjustment from bug fixes to enterprise
- **Visual Workflows** - Beautiful SVG diagrams showing complete methodology
- **BMad Builder Module** - Create and share your own AI agent teams
- **50+ Workflows** - Up from 20 in v4, covering every development scenario
- **19 Specialized Agents** - Enhanced with customizable personalities and expertise
- **Update-Safe Customization** - Your configs persist through all updates
- **Web Bundles** - Use agents in ChatGPT, Claude, and Gemini
- **Multi-Language Support** - Separate settings for communication and code
- **Document Sharding** - 90% token savings for large projects
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
### 🔄 For v4 Users
2025-11-02 21:18:33 -06:00
2025-11-18 23:16:23 -06:00
- **[Comprehensive Upgrade Guide ](./docs/v4-to-v6-upgrade.md )** - Step-by-step migration
- **[v4 Documentation Archive ](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4 )** - Legacy reference
- Backwards compatibility where possible
- Smooth migration path with installer detection
2025-10-18 12:19:47 -05:00
2025-11-18 23:16:23 -06:00
## 📄 License
2025-10-26 23:25:48 -05:00
2025-11-18 23:16:23 -06:00
MIT License - See [LICENSE ](LICENSE ) for details.
2025-08-17 19:23:50 -05:00
2025-11-02 21:18:33 -06:00
**Trademarks:** BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
2025-08-17 19:23:50 -05:00
2025-10-18 12:19:47 -05:00
---
2025-11-18 23:16:23 -06:00
< p align = "center" >
< a href = "https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors" >
< img src = "https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD" alt = "Contributors" >
< / a >
< / p >
2025-06-13 07:27:22 -05:00
2025-11-18 23:16:23 -06:00
< p align = "center" >
< sub > Built with ❤️ for the human-AI collaboration community< / sub >
< / p >
