bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

package/src/modules/bmm/README.md

@@ -1,141 +1,128 @@
 # BMM - BMad Method Module
 
-The BMM (BMad Method Module) is the core orchestration system for the BMad Method, providing comprehensive software development lifecycle management through specialized agents, workflows, teams, and tasks.
+Core orchestration system for AI-driven agile development, providing comprehensive lifecycle management through specialized agents and workflows.
 
-## 📚 Essential Reading
-
-**Before using BMM, you MUST read the [BMM v6 Workflows Guide](./workflows/README.md).** This document explains the revolutionary v6a workflow system and how all components work together.
-
-## Module Structure
-
-### 🤖 `/agents`
+---
 
-Specialized AI agents for different development roles:
+## 📚 Complete Documentation
 
-- **PM** (Product Manager) - Product planning and requirements
-- **Analyst** - Business analysis and research
-- **Architect** - Technical architecture and design
-- **SM** (Scrum Master) - Sprint and story management
-- **DEV** (Developer) - Code implementation
-- **TEA** (Test Architect) - Test Architect
-- **UX** - User experience design
-- And more specialized roles
+👉 **[BMM Documentation Hub](./docs/README.md)** - Start here for complete guides, tutorials, and references
 
-**Game Development Agents** (Optional):
-During installation, you can optionally include game development specialists:
+**Quick Links:**
 
-- **Game Designer** - Creative vision and game design documents (GDD)
-- **Game Developer** - Game-specific implementation
-- **Game Architect** - Game systems and technical infrastructure
+- **[Quick Start Guide](./docs/quick-start.md)** - New to BMM? Start here (15 min)
+- **[Agents Guide](./docs/agents-guide.md)** - Meet your 12 specialized AI agents (45 min)
+- **[Scale Adaptive System](./docs/scale-adaptive-system.md)** - How BMM adapts to project size (42 min)
+- **[FAQ](./docs/faq.md)** - Quick answers to common questions
+- **[Glossary](./docs/glossary.md)** - Key terminology reference
 
-These agents come with specialized workflows (`brainstorm-game`, `game-brief`, `gdd`) and are only installed if you select "Include Game Planning Agents and Workflows" during BMM installation.
+---
 
-### 📋 `/workflows`
+## 🏗️ Module Structure
 
-The heart of BMM - structured workflows for the four development phases:
+This module contains:
 
-1. **Analysis Phase** (Optional)
-   - `brainstorm-project` - Project ideation
-   - `research` - Market/technical research
-   - `product-brief` - Product strategy
+```
+bmm/
+├── agents/          # 12 specialized AI agents (PM, Architect, SM, DEV, TEA, etc.)
+├── workflows/       # 34 workflows across 4 phases + testing
+├── teams/           # Pre-configured agent groups
+├── tasks/           # Atomic work units
+├── testarch/        # Comprehensive testing infrastructure
+└── docs/            # Complete user documentation
+```
 
-2. **Planning Phase** (Required)
-   - `prd` - Scale-adaptive project planning
-   - Routes to appropriate documentation based on project complexity
+### Agent Roster
 
-3. **Solutioning Phase** (Level 3-4 projects)
-   - `3-solutioning` - Architecture design
-   - `tech-spec` - Epic-specific technical specifications
+**Core Development:** PM, Analyst, Architect, SM, DEV, TEA, UX Designer, Paige
+**Game Development:** Game Designer, Game Developer, Game Architect
+**Orchestration:** BMad Master (from Core)
 
-4. **Implementation Phase** (Iterative)
-   - `create-story` - Story drafting (SM agent)
-   - `story-ready` - Approve story for development (SM agent)
-   - `story-context` - Expertise injection (SM agent)
-   - `dev-story` - Implementation (DEV agent)
-   - `story-done` - Mark story done (DEV agent)
-   - `code-review` - Quality validation (DEV/SR agent)
-   - `correct-course` - Issue resolution
-   - `retrospective` - Continuous improvement
+👉 **[Full Agents Guide](./docs/agents-guide.md)** - Roles, workflows, and when to use each agent
 
-### 👥 `/teams`
+### Workflow Phases
 
-Pre-configured agent teams for different project types and phases. Teams coordinate multiple agents working together on complex tasks.
+**Phase 0:** Documentation (brownfield only)
+**Phase 1:** Analysis (optional) - 5 workflows
+**Phase 2:** Planning (required) - 6 workflows
+**Phase 3:** Solutioning (Level 3-4) - 2 workflows
+**Phase 4:** Implementation (iterative) - 10 workflows
+**Testing:** Quality assurance (parallel) - 9 workflows
 
-### 📝 `/tasks`
+👉 **[Workflow Guides](./docs/README.md#-workflow-guides)** - Detailed documentation for each phase
 
-Reusable task definitions that agents execute within workflows. These are the atomic units of work that compose into larger workflows.
+---
 
-### 🔧 `/sub-modules`
+## 🚀 Getting Started
 
-Extension modules that add specialized capabilities to BMM.
+**New Project:**
 
-### 🏗️ `/testarch`
+```bash
+# Install BMM
+npx bmad-method@alpha install
 
-Test architecture and quality assurance components. The **[Test Architect (TEA) Guide](./testarch/README.md)** provides comprehensive testing strategy across 9 workflows: framework setup, CI/CD, test design, ATDD, automation, traceability, NFR assessment, quality gates, and test review.
+# Load Analyst agent in your IDE, then:
+*workflow-init
+```
 
-## Quick Start
+**Existing Project (Brownfield):**
 
 ```bash
-# Load the PM agent - either via slash command or drag and drop or @ the agent file.
-# Once loaded, the agent should greet you and offer a menu of options. You can enter:
-`*prd`
+# Document your codebase first
+*document-project
+
+# Then initialize
+*workflow-init
 ```
 
-## Key Concepts
+👉 **[Quick Start Guide](./docs/quick-start.md)** - Complete setup and first project walkthrough
 
-### Scale Levels
+---
 
-BMM automatically adapts to project complexity:
+## 🎯 Key Concepts
 
-- **Level 0**: Single atomic change
-- **Level 1**: 1-10 stories, minimal documentation
-- **Level 2**: 5-15 stories, focused PRD
-- **Level 3**: 12-40 stories, full architecture
-- **Level 4**: 40+ stories, enterprise scale
+### Scale-Adaptive Design
 
-### Just-In-Time Design
+BMM automatically adjusts to project complexity (Levels 0-4):
 
-Technical specifications are created one epic at a time during implementation, not all upfront, allowing for learning and adaptation.
+- **Level 0-1:** Quick Spec Flow for bug fixes and small features
+- **Level 2:** PRD with optional architecture
+- **Level 3-4:** Full PRD + comprehensive architecture
 
-### Story State Machine
+👉 **[Scale Adaptive System](./docs/scale-adaptive-system.md)** - Complete level breakdown
 
-Stories flow through a 4-state lifecycle tracked in the status file:
+### Story-Centric Implementation
 
-```
-BACKLOG → TODO → IN PROGRESS → DONE
-```
+Stories move through a defined lifecycle: `backlog → drafted → ready → in-progress → review → done`
 
-- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition)
-- **TODO**: Single story ready for SM to draft (or drafted, awaiting approval)
-- **IN PROGRESS**: Single story approved for DEV to implement
-- **DONE**: Completed stories with dates and points
+Just-in-time epic context and story context provide exact expertise when needed.
 
-Agents never search for "next story" - they always read the exact story from the status file. Simple workflows (`story-ready`, `story-done`) advance the queue automatically.
+👉 **[Implementation Workflows](./docs/workflows-implementation.md)** - Complete story lifecycle guide
 
-### Context Injection
+### Multi-Agent Collaboration
 
-Story-specific technical guidance is generated dynamically, providing developers with exactly the expertise needed for each task.
+Use party mode to engage all 19+ agents (from BMM, CIS, BMB, custom modules) in group discussions for strategic decisions, creative brainstorming, and complex problem-solving.
 
-## Integration with BMad Core
+👉 **[Party Mode Guide](./docs/party-mode.md)** - How to orchestrate multi-agent collaboration
 
-BMM integrates seamlessly with the BMad Core framework, leveraging:
+---
 
-- The agent execution engine
-- Workflow orchestration
-- Task management
-- Team coordination
+## 📖 Additional Resources
 
-## Related Documentation
+- **[Brownfield Guide](./docs/brownfield-guide.md)** - Working with existing codebases
+- **[Quick Spec Flow](./docs/quick-spec-flow.md)** - Fast-track for Level 0-1 projects
+- **[Enterprise Agentic Development](./docs/enterprise-agentic-development.md)** - Team collaboration patterns
+- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions
+- **[IDE Setup Guides](../../../docs/ide-info/)** - Configure Claude Code, Cursor, Windsurf, etc.
 
-- [BMM Workflows Guide](./workflows/README.md) - **Start here!**
-- [Test Architect (TEA) Guide](./testarch/README.md) - Quality assurance and testing strategy
+---
 
-## Best Practices
+## 🤝 Community
 
-1. **Always start with the workflows** - Let workflows guide your process
-2. **Respect the scale** - Don't over-document small projects
-3. **Trust the process** - The methodology has been carefully designed
+- **[Discord](https://discord.gg/gk8jAdXWmj)** - Get help, share feedback (#general-dev, #bugs-issues)
+- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features
+- **[YouTube](https://www.youtube.com/@BMadCode)** - Video tutorials and walkthroughs
 
 ---
 
-For detailed information about the complete BMad Method workflow system, see the [BMM Workflows README](./workflows/README.md).
+**Ready to build?** → [Start with the Quick Start Guide](./docs/quick-start.md)

package/src/modules/bmm/agents/game-designer.agent.yaml

@@ -30,11 +30,11 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml"
       description: Guide me through Game Brainstorming
 
-    - trigger: game-brief
+    - trigger: create-game-brief
       workflow: "{project-root}/bmad/bmm/workflows/1-analysis/game-brief/workflow.yaml"
       description: Create Game Brief
 
-    - trigger: gdd
+    - trigger: create-gdd
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/gdd/workflow.yaml"
       description: Create Game Design Document (GDD)
 

package/src/modules/bmm/agents/paige.agent.yaml

@@ -0,0 +1,69 @@
+# Paige - Documentation Guide Agent Definition
+
+agent:
+  metadata:
+    id: bmad/bmm/agents/paige.md
+    name: Paige
+    title: Documentation Guide
+    icon: 📚
+    module: bmm
+
+  persona:
+    role: Technical Documentation Specialist + Knowledge Curator
+    identity: Experienced technical writer with deep expertise in documentation standards (CommonMark, DITA, OpenAPI), API documentation, and developer experience. Master of clarity - transforms complex technical concepts into accessible, well-structured documentation. Proficient in multiple style guides (Google Developer Docs, Microsoft Manual of Style) and modern documentation practices including docs-as-code, structured authoring, and task-oriented writing. Specializes in creating comprehensive technical documentation across the full spectrum - API references, architecture decision records, user guides, developer onboarding, and living knowledge bases.
+    communication_style: Patient and supportive teacher who makes documentation feel approachable rather than daunting. Uses clear examples and analogies to explain complex topics. Balances precision with accessibility - knows when to be technically detailed and when to simplify. Encourages good documentation habits while being pragmatic about real-world constraints. Celebrates well-written docs and helps improve unclear ones without judgment.
+    principles:
+      - I believe documentation is teaching - every doc should help someone accomplish a specific task, not just describe features.
+      - My philosophy embraces clarity above all - I use plain language, structured content, and visual aids (Mermaid diagrams) to make complex topics accessible.
+      - I treat documentation as living artifacts that evolve with the codebase, advocating for docs-as-code practices and continuous maintenance rather than one-time creation.
+      - I operate with a standards-first mindset (CommonMark, OpenAPI, style guides) while remaining flexible to project needs, always prioritizing the reader's experience over rigid adherence to rules.
+
+  critical_actions:
+    - "CRITICAL: Load COMPLETE file {project-root}/src/modules/bmm/workflows/techdoc/documentation-standards.md into permanent memory and follow ALL rules within"
+    - "Load into memory {project-root}/bmad/bmm/config.yaml and set variables"
+    - "Remember the user's name is {user_name}"
+    - "ALWAYS communicate in {communication_language}"
+    - "ALWAYS write documentation in {document_output_language}"
+    - "CRITICAL: All documentation MUST follow CommonMark specification strictly - zero tolerance for violations"
+    - "CRITICAL: All Mermaid diagrams MUST use valid syntax - mentally validate before outputting"
+
+  menu:
+    - trigger: document-project
+      workflow: "{project-root}/bmad/bmm/workflows/document-project/workflow.yaml"
+      description: Comprehensive project documentation (brownfield analysis, architecture scanning)
+
+    - trigger: create-api-docs
+      workflow: "todo"
+      description: Create API documentation with OpenAPI/Swagger standards
+
+    - trigger: create-architecture-docs
+      workflow: "todo"
+      description: Create architecture documentation with diagrams and ADRs
+
+    - trigger: create-user-guide
+      workflow: "todo"
+      description: Create user-facing guides and tutorials
+
+    - trigger: audit-docs
+      workflow: "todo"
+      description: Review documentation quality and suggest improvements
+
+    - trigger: generate-diagram
+      action: "Create a Mermaid diagram based on user description. Ask for diagram type (flowchart, sequence, class, ER, state, git) and content, then generate properly formatted Mermaid syntax following CommonMark fenced code block standards."
+      description: Generate Mermaid diagrams (architecture, sequence, flow, ER, class, state)
+
+    - trigger: validate-doc
+      action: "Review the specified document against CommonMark standards, technical writing best practices, and style guide compliance. Provide specific, actionable improvement suggestions organized by priority."
+      description: Validate documentation against standards and best practices
+
+    - trigger: improve-readme
+      action: "Analyze the current README file and suggest improvements for clarity, completeness, and structure. Follow task-oriented writing principles and ensure all essential sections are present (Overview, Getting Started, Usage, Contributing, License)."
+      description: Review and improve README files
+
+    - trigger: explain-concept
+      action: "Create a clear technical explanation with examples and diagrams for a complex concept. Break it down into digestible sections using task-oriented approach. Include code examples and Mermaid diagrams where helpful."
+      description: Create clear technical explanations with examples
+
+    - trigger: standards-guide
+      action: "Display the complete documentation standards from {project-root}/src/modules/bmm/workflows/techdoc/documentation-standards.md in a clear, formatted way for the user."
+      description: Show BMAD documentation standards reference (CommonMark, Mermaid, OpenAPI)

package/src/modules/bmm/agents/pm.agent.yaml

@@ -31,10 +31,20 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
-    - trigger: prd
+    - trigger: create-prd
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
       description: Create Product Requirements Document (PRD) for Level 2-4 projects
 
+    - trigger: create-epics-and-stories
+      workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"
+      description: Break PRD requirements into implementable epics and stories
+
+    - trigger: validate-prd
+      validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
+      checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/checklist.md"
+      document: "{output_folder}/PRD.md"
+      description: Validate PRD + Epics + Stories completeness and quality
+
     - trigger: tech-spec
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
       description: Create Tech Spec for Level 0-1 (sometimes Level 2) projects

package/src/modules/bmm/docs/README.md

@@ -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)