mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)
## 📚 Complete Documentation Restructure **BMM Documentation Hub Created:** - New centralized documentation system at `src/modules/bmm/docs/` - 18 comprehensive guides organized by topic (7000+ lines total) - Clear learning paths for greenfield, brownfield, and quick spec flows - Professional technical writing standards throughout **New Documentation:** - `README.md` - Complete documentation hub with navigation - `quick-start.md` - 15-minute getting started guide - `agents-guide.md` - Comprehensive 12-agent reference (45 min read) - `party-mode.md` - Multi-agent collaboration guide (20 min read) - `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read) - `brownfield-guide.md` - Existing codebase development (53 min read) - `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read) - `workflows-analysis.md` - Phase 1 workflows (12 min read) - `workflows-planning.md` - Phase 2 workflows (19 min read) - `workflows-solutioning.md` - Phase 3 workflows (13 min read) - `workflows-implementation.md` - Phase 4 workflows (33 min read) - `workflows-testing.md` - Testing & QA workflows (29 min read) - `workflow-architecture-reference.md` - Architecture workflow deep-dive - `workflow-document-project-reference.md` - Document-project workflow reference - `enterprise-agentic-development.md` - Team collaboration patterns - `faq.md` - Comprehensive Q&A covering all topics - `glossary.md` - Complete terminology reference - `troubleshooting.md` - Common issues and solutions **Documentation Improvements:** - Removed all version/date footers (git handles versioning) - Agent customization docs now include full rebuild process - Cross-referenced links between all guides - Reading time estimates for all major docs - Consistent professional formatting and structure **Consolidated & Streamlined:** - Module README (`src/modules/bmm/README.md`) streamlined to lean signpost - Root README polished with better hierarchy and clear CTAs - Moved docs from root `docs/` to module-specific locations - Better separation of user docs vs. developer reference ## 🤖 New Agent: Paige (Documentation Guide) **Role:** Technical documentation specialist and information architect **Expertise:** - Professional technical writing standards - Documentation structure and organization - Information architecture and navigation - User-focused content design - Style guide enforcement **Status:** Work in progress - Paige will evolve as documentation needs grow **Integration:** - Listed in agents-guide.md, glossary.md, FAQ - Available for all phases (documentation is continuous) - Can be customized like all BMM agents ## 🔧 Additional Changes - Updated agent manifest with Paige - Updated workflow manifest with new documentation workflows - Fixed workflow-to-agent mappings across all guides - Improved root README with clearer Quick Start section - Better module structure explanations - Enhanced community links with Discord channel names **Total Impact:** - 18 new/restructured documentation files - 7000+ lines of professional technical documentation - Complete navigation system with cross-references - Clear learning paths for all user types - Foundation for knowledge base (coming in beta) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Brian Madison
@@ -1020,6 +1020,164 @@ _Generated on {{date}}_
|
||||
- **Unclosed check tags** - Always close `<check if="">...</check>` blocks
|
||||
- **Wrong conditional pattern** - Use `<action if="">` for single items, `<check if="">` for blocks
|
||||
|
||||
## Document Sharding Support
|
||||
|
||||
If your workflow loads large planning documents (PRDs, epics, architecture, etc.), implement sharding support for efficiency.
|
||||
|
||||
### What is Document Sharding?
|
||||
|
||||
Document sharding splits large markdown files into smaller section-based files:
|
||||
|
||||
- `PRD.md` (50k tokens) → `prd/epic-1.md`, `prd/epic-2.md`, etc.
|
||||
- Enables selective loading (90%+ token savings)
|
||||
- All BMM workflows support both whole and sharded documents
|
||||
|
||||
### When to Add Sharding Support
|
||||
|
||||
**Add sharding support if your workflow:**
|
||||
|
||||
- Loads planning documents (PRD, epics, architecture, UX specs)
|
||||
- May be used in large multi-epic projects
|
||||
- Processes documents that could exceed 20k tokens
|
||||
- Would benefit from selective section loading
|
||||
|
||||
**Skip sharding support if your workflow:**
|
||||
|
||||
- Only generates small documents
|
||||
- Doesn't load external documents
|
||||
- Works with code files (not planning docs)
|
||||
|
||||
### Implementation Pattern
|
||||
|
||||
#### 1. Add input_file_patterns to workflow.yaml
|
||||
|
||||
```yaml
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: '{output_folder}/*prd*.md'
|
||||
sharded: '{output_folder}/*prd*/index.md'
|
||||
|
||||
epics:
|
||||
whole: '{output_folder}/*epic*.md'
|
||||
sharded_index: '{output_folder}/*epic*/index.md'
|
||||
sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md' # For selective load
|
||||
|
||||
architecture:
|
||||
whole: '{output_folder}/*architecture*.md'
|
||||
sharded: '{output_folder}/*architecture*/index.md'
|
||||
|
||||
document_project:
|
||||
sharded: '{output_folder}/docs/index.md' # Brownfield always uses index
|
||||
```
|
||||
|
||||
#### 2. Add Discovery Instructions to instructions.md
|
||||
|
||||
Place early in instructions (after critical declarations, before workflow steps):
|
||||
|
||||
```markdown
|
||||
## 📚 Document Discovery
|
||||
|
||||
This workflow requires: [list required documents]
|
||||
|
||||
**Discovery Process** (execute for each document):
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand the document structure
|
||||
- Read ALL section files listed in the index (or specific sections for selective load)
|
||||
- Treat the combined content as if it were a single document
|
||||
4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**Fuzzy matching**: Be flexible with document names - users may use variations.
|
||||
```
|
||||
|
||||
#### 3. Choose Loading Strategy
|
||||
|
||||
**Full Load Strategy** (most workflows):
|
||||
|
||||
```xml
|
||||
<action>Search for document using fuzzy pattern: {output_folder}/*prd*.md</action>
|
||||
<action>If not found, check for sharded version: {output_folder}/*prd*/index.md</action>
|
||||
<action if="sharded found">Read index.md to understand structure</action>
|
||||
<action if="sharded found">Read ALL section files listed in index</action>
|
||||
<action if="sharded found">Combine content as single document</action>
|
||||
```
|
||||
|
||||
**Selective Load Strategy** (advanced - for phase 4 type workflows):
|
||||
|
||||
```xml
|
||||
<action>Determine section needed (e.g., epic_num from story key)</action>
|
||||
<action>Check for sharded version: {output_folder}/*epics*/index.md</action>
|
||||
<action if="sharded found">Read ONLY the specific section file: epics/epic-{{epic_num}}.md</action>
|
||||
<action if="sharded found">Skip all other section files (efficiency optimization)</action>
|
||||
<action if="whole document found">Load complete document and extract relevant section</action>
|
||||
```
|
||||
|
||||
### Pattern Examples
|
||||
|
||||
**Example 1: Simple Full Load**
|
||||
|
||||
```yaml
|
||||
# workflow.yaml
|
||||
input_file_patterns:
|
||||
requirements:
|
||||
whole: '{output_folder}/*requirements*.md'
|
||||
sharded: '{output_folder}/*requirements*/index.md'
|
||||
```
|
||||
|
||||
```markdown
|
||||
<!-- instructions.md -->
|
||||
|
||||
## Document Discovery
|
||||
|
||||
Load requirements document (whole or sharded).
|
||||
|
||||
1. Try whole: _requirements_.md
|
||||
2. If not found, try sharded: _requirements_/index.md
|
||||
3. If sharded: Read index + ALL section files
|
||||
```
|
||||
|
||||
**Example 2: Selective Load with Epic Number**
|
||||
|
||||
```yaml
|
||||
# workflow.yaml
|
||||
input_file_patterns:
|
||||
epics:
|
||||
whole: '{output_folder}/*epic*.md'
|
||||
sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
|
||||
```
|
||||
|
||||
```xml
|
||||
<!-- instructions.md step -->
|
||||
<step n="2" goal="Load Epic Content">
|
||||
<action>Extract epic number from story key (e.g., "3-2-feature" → epic_num = 3)</action>
|
||||
<action>Check for sharded epics: {output_folder}/*epic*/index.md</action>
|
||||
<action if="sharded found">Load ONLY epics/epic-{{epic_num}}.md (selective optimization)</action>
|
||||
<action if="whole document found">Load full epics.md and extract Epic {{epic_num}}</action>
|
||||
</step>
|
||||
```
|
||||
|
||||
### Testing Your Sharding Support
|
||||
|
||||
1. **Test with whole document**: Verify workflow works with single `document.md`
|
||||
2. **Test with sharded document**: Create sharded version and verify discovery
|
||||
3. **Test with both present**: Ensure whole document takes priority
|
||||
4. **Test selective loading**: Verify only needed sections are loaded (if applicable)
|
||||
|
||||
### Complete Reference
|
||||
|
||||
**[→ Document Sharding Guide](../../../../docs/document-sharding-guide.md)** - Comprehensive guide with examples
|
||||
|
||||
**BMM Examples**:
|
||||
|
||||
- Full Load: `src/modules/bmm/workflows/2-plan-workflows/prd/`
|
||||
- Selective Load: `src/modules/bmm/workflows/4-implementation/epic-tech-context/`
|
||||
|
||||
## Web Bundles
|
||||
|
||||
Web bundles allow workflows to be deployed as self-contained packages for web environments.
|
||||
|
||||
Reference in New Issue
Block a user