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
235
src/modules/bmm/docs/README.md
Normal file
235
src/modules/bmm/docs/README.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# BMM Documentation
|
||||
|
||||
Complete guides for the BMad Method Module (BMM) - AI-powered agile development workflows that adapt to your project's complexity.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
**New to BMM?** Start here:
|
||||
|
||||
- **[Quick Start Guide](./quick-start.md)** - Step-by-step guide to building your first project (15 min read)
|
||||
- Installation and setup
|
||||
- Understanding the four phases
|
||||
- Running your first workflows
|
||||
- Agent-based development flow
|
||||
|
||||
**Quick Path:** Install → workflow-init → Follow agent guidance
|
||||
|
||||
---
|
||||
|
||||
## 📖 Core Concepts
|
||||
|
||||
Understanding how BMM adapts to your needs:
|
||||
|
||||
- **[Scale Adaptive System](./scale-adaptive-system.md)** - How BMM adapts to project size and complexity (42 min read)
|
||||
- The five complexity levels (0-4)
|
||||
- Automatic level detection
|
||||
- Documentation requirements per level
|
||||
- Planning workflow routing
|
||||
|
||||
- **[Quick Spec Flow](./quick-spec-flow.md)** - Fast-track workflow for Level 0-1 projects (26 min read)
|
||||
- Bug fixes and small features
|
||||
- Rapid prototyping approach
|
||||
- Auto-detection of stack and patterns
|
||||
- Minutes to implementation
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Agents & Collaboration
|
||||
|
||||
Complete guide to BMM's AI agent team:
|
||||
|
||||
- **[Agents Guide](./agents-guide.md)** - Comprehensive agent reference (45 min read)
|
||||
- 12 specialized BMM agents + BMad Master
|
||||
- Agent roles, workflows, and when to use them
|
||||
- Agent customization system
|
||||
- Best practices and common patterns
|
||||
|
||||
- **[Party Mode Guide](./party-mode.md)** - Multi-agent collaboration (20 min read)
|
||||
- How party mode works (19+ agents collaborate in real-time)
|
||||
- When to use it (strategic, creative, cross-functional, complex)
|
||||
- Example party compositions
|
||||
- Multi-module integration (BMM + CIS + BMB + custom)
|
||||
- Agent customization in party mode
|
||||
- Best practices and troubleshooting
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Working with Existing Code
|
||||
|
||||
Comprehensive guide for brownfield development:
|
||||
|
||||
- **[Brownfield Development Guide](./brownfield-guide.md)** - Complete guide for existing codebases (53 min read)
|
||||
- Documentation phase strategies
|
||||
- Level detection for brownfield
|
||||
- Integration with existing patterns
|
||||
- Phase-by-phase workflow guidance
|
||||
- Common scenarios and troubleshooting
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick References
|
||||
|
||||
Essential reference materials:
|
||||
|
||||
- **[Glossary](./glossary.md)** - Key terminology and concepts
|
||||
- **[FAQ](./faq.md)** - Frequently asked questions across all topics
|
||||
- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
|
||||
- **[Enterprise Agentic Development](./enterprise-agentic-development.md)** - Team collaboration strategies
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Choose Your Path
|
||||
|
||||
### I need to...
|
||||
|
||||
**Build something new (greenfield)**
|
||||
→ Start with [Quick Start Guide](./quick-start.md)
|
||||
→ Then review [Scale Adaptive System](./scale-adaptive-system.md) to understand levels
|
||||
|
||||
**Fix a bug or add small feature**
|
||||
→ Go directly to [Quick Spec Flow](./quick-spec-flow.md)
|
||||
|
||||
**Work with existing codebase (brownfield)**
|
||||
→ Read [Brownfield Development Guide](./brownfield-guide.md)
|
||||
→ Pay special attention to Phase 0 documentation requirements
|
||||
|
||||
**Understand project complexity levels**
|
||||
→ See [Scale Adaptive System](./scale-adaptive-system.md)
|
||||
|
||||
**Find specific commands or answers**
|
||||
→ Check [FAQ](./faq.md) or [Troubleshooting](./troubleshooting.md)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Workflow Guides
|
||||
|
||||
Comprehensive documentation for all BMM workflows organized by phase:
|
||||
|
||||
- **[Phase 1: Analysis Workflows](./workflows-analysis.md)** - Optional exploration and research workflows (595 lines)
|
||||
- brainstorm-project, product-brief, research, and more
|
||||
- When to use analysis workflows
|
||||
- Creative and strategic tools
|
||||
|
||||
- **[Phase 2: Planning Workflows](./workflows-planning.md)** - Scale-adaptive planning (967 lines)
|
||||
- prd, tech-spec, gdd, narrative, ux
|
||||
- Level 0-4 planning approach
|
||||
- Which planning workflow to use
|
||||
|
||||
- **[Phase 3: Solutioning Workflows](./workflows-solutioning.md)** - Architecture and validation (638 lines)
|
||||
- architecture, solutioning-gate-check
|
||||
- Required for Level 3-4 projects
|
||||
- Preventing agent conflicts
|
||||
|
||||
- **[Phase 4: Implementation Workflows](./workflows-implementation.md)** - Sprint-based development (1,634 lines)
|
||||
- sprint-planning, create-story, dev-story, code-review
|
||||
- Complete story lifecycle
|
||||
- One-story-at-a-time discipline
|
||||
|
||||
- **[Testing & QA Workflows](./workflows-testing.md)** - Comprehensive quality assurance (1,420 lines)
|
||||
- Test strategy, automation, quality gates
|
||||
- TEA agent and test healing
|
||||
- BMad-integrated vs standalone modes
|
||||
|
||||
**Total: 34 workflows documented across all phases**
|
||||
|
||||
### Advanced Workflow References
|
||||
|
||||
For detailed technical documentation on specific complex workflows:
|
||||
|
||||
- **[Document Project Workflow Reference](./workflow-document-project-reference.md)** - Technical deep-dive (445 lines)
|
||||
- v1.2.0 context-safe architecture
|
||||
- Scan levels, resumability, write-as-you-go
|
||||
- Multi-part project detection
|
||||
- Deep-dive mode for targeted analysis
|
||||
|
||||
- **[Architecture Workflow Reference](./workflow-architecture-reference.md)** - Decision architecture guide (320 lines)
|
||||
- Starter template intelligence
|
||||
- Novel pattern design
|
||||
- Implementation patterns for agent consistency
|
||||
- Adaptive facilitation approach
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing & Quality
|
||||
|
||||
Quality assurance guidance:
|
||||
|
||||
- **[Test Architect Guide](../testarch/README.md)** - Comprehensive testing strategy
|
||||
- Test design workflows
|
||||
- Quality gates
|
||||
- Risk assessment
|
||||
- NFR validation
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Module Structure
|
||||
|
||||
Understanding BMM components:
|
||||
|
||||
- **[BMM Module README](../README.md)** - Overview of module structure
|
||||
- Agent roster and roles
|
||||
- Workflow organization
|
||||
- Teams and collaboration
|
||||
- Best practices
|
||||
|
||||
---
|
||||
|
||||
## 🌐 External Resources
|
||||
|
||||
### Community & Support
|
||||
|
||||
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help from the community (#general-dev, #bugs-issues)
|
||||
- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features
|
||||
- **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and walkthroughs
|
||||
|
||||
### Additional Documentation
|
||||
|
||||
- **[IDE Setup Guides](../../../docs/ide-info/)** - Configure your development environment
|
||||
- Claude Code
|
||||
- Cursor
|
||||
- Windsurf
|
||||
- VS Code
|
||||
- Other IDEs
|
||||
|
||||
---
|
||||
|
||||
## 📊 Documentation Map
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START[New to BMM?]
|
||||
START --> QS[Quick Start Guide]
|
||||
|
||||
QS --> DECIDE{What are you building?}
|
||||
|
||||
DECIDE -->|Bug fix or<br/>small feature| QSF[Quick Spec Flow]
|
||||
DECIDE -->|New project| SAS[Scale Adaptive System]
|
||||
DECIDE -->|Existing codebase| BF[Brownfield Guide]
|
||||
|
||||
QSF --> IMPL[Implementation]
|
||||
SAS --> IMPL
|
||||
BF --> IMPL
|
||||
|
||||
IMPL --> REF[Quick References<br/>Glossary, FAQ, Troubleshooting]
|
||||
|
||||
style START fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style QS fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style DECIDE fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style IMPL fill:#f9f,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Tips for Using This Documentation
|
||||
|
||||
1. **Start with Quick Start** if you're new - it provides the essential foundation
|
||||
2. **Use the FAQ** to find quick answers without reading entire guides
|
||||
3. **Bookmark Glossary** for terminology references while reading other docs
|
||||
4. **Follow the suggested paths** above based on your specific situation
|
||||
5. **Join Discord** for interactive help and community insights
|
||||
|
||||
---
|
||||
|
||||
**Ready to begin?** → [Start with the Quick Start Guide](./quick-start.md)
|
||||
Reference in New Issue
Block a user