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-12-07 14:11:17 -06:00
**Build More, Architect Dreams** (BMAD) with **21 specialized AI agents** across 4 official modules, and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms, and new step file workflows that allow for incredibly long workflows to stay on the rails longer than ever before!
Additionally - when we say 'Build More, Architect Dreams' - we mean it! The BMad Builder has landed, and now as of Alpha.15 is fully supported in the installation flow via NPX - custom stand along agents, workflows and the modules of your dreams! The community forge will soon open, endless possibility awaits!
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-12-07 14:55:44 -06:00
- **[Code of Conduct ](.github/CODE_OF_CONDUCT.md )** - Community guidelines
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-12-15 17:30:12 +08: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 >
