## 📚 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>
* fix: add CommonMark-compliant markdown formatting rules to workflow
Problem:
--------
BMAD generates markdown that violates CommonMark specification by omitting
required blank lines around lists, tables, and code blocks. While GitHub's
renderer (GFM) handles this gracefully, strict parsers like Mac Markdown.app
break completely, rendering lists as plain text and losing document structure.
Solution:
---------
Add 6 mandatory markdown formatting rules to workflow.xml (line 73) that
enforce proper spacing and consistency:
1. ALWAYS add blank line before and after bullet lists
2. ALWAYS add blank line before and after numbered lists
3. ALWAYS add blank line before and after tables
4. ALWAYS add blank line before and after code blocks
5. Use - for bullets consistently (not * or +)
6. Use language identifier for code fences
Impact:
-------
- Makes BMAD output CommonMark compliant
- Ensures compatibility with ALL markdown parsers, not just GitHub
- Follows industry best practices for professional documentation
- Future-proofs against stricter parser implementations
- Zero content changes - only formatting improved
Testing:
--------
Comprehensive three-phase testing completed:
- Phase 1: Synthetic test validating fix mechanism
- Phase 2: Fresh install end-to-end test (API Gateway project)
- Phase 3: GitHub validation with visual proof
Results: 1,112 lines of formatting improvements, 0 content changes,
100% CommonMark compliance achieved.
Test Evidence:
--------------
Complete test repository with before/after comparison, Mac Markdown.app
screenshot proving the issue, and comprehensive documentation:
https://github.com/jheyworth/bmad-markdown-formatting-test
See TEST.md for full documentation, test methodology, and evidence.
🤖 Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Remove TEST.md per maintainer feedback
As requested by @bmadcode - the test documentation was useful during review but is not needed in the repository. Testing evidence remains documented in the PR description and external test repository.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Brian Madison
jheyworth