bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

package/docs/explanation/architecture/preventing-agent-conflicts.md

@@ -0,0 +1,138 @@
+---
+title: "Preventing Agent Conflicts"
+description: How architecture prevents conflicts when multiple agents implement a system
+---
+
+
+When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
+
+---
+
+## Common Conflict Types
+
+### API Style Conflicts
+
+Without architecture:
+- Agent A uses REST with `/users/{id}`
+- Agent B uses GraphQL mutations
+- Result: Inconsistent API patterns, confused consumers
+
+With architecture:
+- ADR specifies: "Use GraphQL for all client-server communication"
+- All agents follow the same pattern
+
+### Database Design Conflicts
+
+Without architecture:
+- Agent A uses snake_case column names
+- Agent B uses camelCase column names
+- Result: Inconsistent schema, confusing queries
+
+With architecture:
+- Standards document specifies naming conventions
+- All agents follow the same patterns
+
+### State Management Conflicts
+
+Without architecture:
+- Agent A uses Redux for global state
+- Agent B uses React Context
+- Result: Multiple state management approaches, complexity
+
+With architecture:
+- ADR specifies state management approach
+- All agents implement consistently
+
+---
+
+## How Architecture Prevents Conflicts
+
+### 1. Explicit Decisions via ADRs
+
+Every significant technology choice is documented with:
+- Context (why this decision matters)
+- Options considered (what alternatives exist)
+- Decision (what we chose)
+- Rationale (why we chose it)
+- Consequences (trade-offs accepted)
+
+### 2. FR/NFR-Specific Guidance
+
+Architecture maps each functional requirement to technical approach:
+- FR-001: User Management → GraphQL mutations
+- FR-002: Mobile App → Optimized queries
+
+### 3. Standards and Conventions
+
+Explicit documentation of:
+- Directory structure
+- Naming conventions
+- Code organization
+- Testing patterns
+
+---
+
+## Architecture as Shared Context
+
+Think of architecture as the shared context that all agents read before implementing:
+
+```
+PRD: "What to build"
+     ↓
+Architecture: "How to build it"
+     ↓
+Agent A reads architecture → implements Epic 1
+Agent B reads architecture → implements Epic 2
+Agent C reads architecture → implements Epic 3
+     ↓
+Result: Consistent implementation
+```
+
+---
+
+## Key ADR Topics
+
+Common decisions that prevent conflicts:
+
+| Topic | Example Decision |
+|-------|-----------------|
+| API Style | GraphQL vs REST vs gRPC |
+| Database | PostgreSQL vs MongoDB |
+| Auth | JWT vs Sessions |
+| State Management | Redux vs Context vs Zustand |
+| Styling | CSS Modules vs Tailwind vs Styled Components |
+| Testing | Jest + Playwright vs Vitest + Cypress |
+
+---
+
+## Anti-Patterns
+
+### ❌ Implicit Decisions
+
+"We'll figure out the API style as we go"
+→ Leads to inconsistency
+
+### ❌ Over-Documentation
+
+Every minor choice documented
+→ Analysis paralysis, wasted time
+
+### ❌ Stale Architecture
+
+Document written once, never updated
+→ Agents follow outdated patterns
+
+### ✅ Correct Approach
+
+- Document decisions that cross epic boundaries
+- Focus on conflict-prone areas
+- Update architecture as you learn
+- Use `correct-course` for significant changes
+
+---
+
+## Related
+
+- [Why Solutioning Matters](/docs/explanation/architecture/why-solutioning-matters.md)
+- [Four Phases](/docs/explanation/architecture/four-phases.md)
+- [Create Architecture](/docs/how-to/workflows/create-architecture.md)

package/docs/explanation/architecture/why-solutioning-matters.md

@@ -0,0 +1,91 @@
+---
+title: "Why Solutioning Matters"
+description: Understanding why the solutioning phase is critical for multi-epic projects
+---
+
+
+Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
+
+---
+
+## The Problem Without Solutioning
+
+```
+Agent 1 implements Epic 1 using REST API
+Agent 2 implements Epic 2 using GraphQL
+Result: Inconsistent API design, integration nightmare
+```
+
+When multiple agents implement different parts of a system without shared architectural guidance, they make independent technical decisions that may conflict.
+
+---
+
+## The Solution With Solutioning
+
+```
+architecture workflow decides: "Use GraphQL for all APIs"
+All agents follow architecture decisions
+Result: Consistent implementation, no conflicts
+```
+
+By documenting technical decisions explicitly, all agents implement consistently and integration becomes straightforward.
+
+---
+
+## Solutioning vs Planning
+
+| Aspect   | Planning (Phase 2)      | Solutioning (Phase 3)             |
+| -------- | ----------------------- | --------------------------------- |
+| Question | What and Why?           | How? Then What units of work?     |
+| Output   | FRs/NFRs (Requirements) | Architecture + Epics/Stories      |
+| Agent    | PM                      | Architect → PM                    |
+| Audience | Stakeholders            | Developers                        |
+| Document | PRD (FRs/NFRs)          | Architecture + Epic Files         |
+| Level    | Business logic          | Technical design + Work breakdown |
+
+---
+
+## Key Principle
+
+**Make technical decisions explicit and documented** so all agents implement consistently.
+
+This prevents:
+- API style conflicts (REST vs GraphQL)
+- Database design inconsistencies
+- State management disagreements
+- Naming convention mismatches
+- Security approach variations
+
+---
+
+## When Solutioning is Required
+
+| Track | Solutioning Required? |
+|-------|----------------------|
+| Quick Flow | No - skip entirely |
+| BMad Method Simple | Optional |
+| BMad Method Complex | Yes |
+| Enterprise | Yes |
+
+**Rule of thumb:** If you have multiple epics that could be implemented by different agents, you need solutioning.
+
+---
+
+## The Cost of Skipping
+
+Skipping solutioning on complex projects leads to:
+
+- **Integration issues** discovered mid-sprint
+- **Rework** due to conflicting implementations
+- **Longer development time** overall
+- **Technical debt** from inconsistent patterns
+
+Catching alignment issues in solutioning is 10× faster than discovering them during implementation.
+
+---
+
+## Related
+
+- [Four Phases](/docs/explanation/architecture/four-phases.md) - Overview of all phases
+- [Preventing Agent Conflicts](/docs/explanation/architecture/preventing-agent-conflicts.md) - Detailed conflict prevention
+- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - How to do it

package/docs/{custom-content.md → explanation/bmad-builder/custom-content-types.md}

@@ -1,6 +1,9 @@
-# Custom Content
+---
+title: "Custom Content"
+---
 
-BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agent provides workflows and expertise to plan and build any custom content you can imagine.
+
+BMad supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agents provides workflows and expertise to plan and build any custom content you can imagine.
 
 This flexibility transforms the platform beyond its current capabilities, enabling:
 
@@ -14,30 +17,26 @@ This flexibility transforms the platform beyond its current capabilities, enabli
 
 ## Categories
 
-- [Custom Content](#custom-content)
-  - [Categories](#categories)
-  - [Custom Stand Alone Modules](#custom-stand-alone-modules)
-  - [Custom Add On Modules](#custom-add-on-modules)
-  - [Custom Global Modules](#custom-global-modules)
-  - [Custom Agents](#custom-agents)
-    - [BMad Tiny Agents](#bmad-tiny-agents)
-    - [Simple vs Expert Agents](#simple-vs-expert-agents)
-  - [Custom Workflows](#custom-workflows)
+- [Custom Stand-Alone Modules](#custom-stand-alone-modules)
+- [Custom Add-On Modules](#custom-add-on-modules)
+- [Custom Global Modules](#custom-global-modules)
+- [Custom Agents](#custom-agents)
+- [Custom Workflows](#custom-workflows)
 
-## Custom Stand Alone Modules
+## Custom Stand-Alone Modules
 
 Custom modules range from simple collections of related agents, workflows, and tools designed to work independently, to complex, expansive systems like the BMad Method or even larger applications.
 
-Custom modules are [installable](./custom-content-installation.md) using the standard BMAD method and support advanced features:
+Custom modules are [installable](/docs/how-to/installation/install-custom-modules.md) using the standard BMad method and support advanced features:
 
 - Optional user information collection during installation/updates
 - Versioning and upgrade paths
 - Custom installer functions with IDE-specific post-installation handling (custom hooks, subagents, or vendor-specific tools)
 - Ability to bundle specific tools such as MCP, skills, execution libraries, and code
 
-## Custom Add On Modules
+## Custom Add-On Modules
 
-Custom Add On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
+Custom Add-On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
 
 Examples include:
 
@@ -45,7 +44,7 @@ Examples include:
 - Framework-specific support for particular use cases
 - Game development expansions that add new genre-specific capabilities without reinventing existing functionality
 
-Add on modules can include:
+Add-on modules can include:
 
 - Custom agents with awareness of the target module
 - Access to existing module workflows
@@ -53,13 +52,13 @@ Add on modules can include:
 
 ## Custom Global Modules
 
-Similar to Custom Stand Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMAD ecosystem.
+Similar to Custom Stand-Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMad ecosystem.
 
 Examples include:
 
-- The current TTS (Text-to-Speech) functionality for Claude, which will be rebuilt as a global module
+- The current TTS (Text-to-Speech) functionality for Claude, which will soon be converted to a global module
 - The core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities
-- Installation and update tools that work with any BMAD method configuration
+- Installation and update tools that work with any BMad method configuration
 
 Upcoming standards will document best practices for building global content that affects installed modules through:
 
@@ -81,7 +80,7 @@ Personal agents designed for highly specific needs that may not be suitable for
 
 These are simple, standalone files that can be scoped to focus on specific data or paths when integrated into an information vault or repository.
 
-### Simple vs Expert Agents
+### Simple and Expert Agents
 
 The distinction between simple and expert agents lies in their structure:
 
@@ -89,7 +88,6 @@ The distinction between simple and expert agents lies in their structure:
 
 - Single file containing all prompts and configuration
 - Self-contained and straightforward
-- has metadata type: simple
 
 **Expert Agent:**
 

package/docs/explanation/bmad-builder/index.md

@@ -0,0 +1,66 @@
+---
+title: "BMad Builder (BMB)"
+description: Create custom agents, workflows, and modules for BMad
+---
+
+
+Create custom agents, workflows, and modules for BMad.
+
+---
+
+## Quick Start
+
+- **[Agent Creation Guide](/docs/tutorials/advanced/create-custom-agent.md)** - Step-by-step guide to building your first agent
+
+---
+
+## Agent Architecture
+
+Comprehensive guides for each agent type:
+
+- **Simple Agent Architecture** - Self-contained, optimized, personality-driven
+- **Expert Agent Architecture** - Memory, sidecar files, domain restrictions
+- **Module Agent Architecture** - Workflow integration, professional tools
+
+---
+
+## Key Concepts
+
+### YAML to XML Compilation
+
+Agents are authored in YAML with Handlebars templating. The compiler auto-injects:
+
+1. **Frontmatter** - Name and description from metadata
+2. **Activation Block** - Steps, menu handlers, rules
+3. **Menu Enhancement** - `*help` and `*exit` commands added automatically
+4. **Trigger Prefixing** - Your triggers auto-prefixed with `*`
+
+---
+
+## Reference Examples
+
+Production-ready examples available in the BMB reference folder:
+
+### Simple Agents
+- **commit-poet** - Commit message artisan with style customization
+
+### Expert Agents
+- **journal-keeper** - Personal journal companion with memory and pattern recognition
+
+### Module Agents
+- **security-engineer** - BMM security specialist with threat modeling
+- **trend-analyst** - CIS trend intelligence expert
+
+---
+
+## Installation Guide
+
+For installing standalone simple and expert agents, see:
+- [Install Custom Modules](/docs/how-to/installation/install-custom-modules.md)
+
+---
+
+## Related
+
+- [Custom Content Types](/docs/explanation/bmad-builder/custom-content-types.md) - Understanding content types
+- [Create Custom Agent](/docs/tutorials/advanced/create-custom-agent.md) - Tutorial

package/docs/explanation/bmm/index.md

@@ -0,0 +1,135 @@
+---
+title: "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](/docs/tutorials/getting-started/getting-started-bmadv6.md)** - Step-by-step guide to building your first project
+  - Installation and setup
+  - Understanding the four phases
+  - Running your first workflows
+  - Agent-based development flow
+
+**Quick Path:** Install → workflow-init → Follow agent guidance
+
+### 📊 Visual Overview
+
+**[Complete Workflow Diagram](../../tutorials/getting-started/images/workflow-method-greenfield.svg)** - Visual flowchart showing all phases, agents (color-coded), and decision points for the BMad Method standard greenfield track.
+
+## 📖 Core Concepts
+
+The BMad Method is meant to be adapted and customized to your specific needs. In this realm there is no one size fits all - your needs are unique, and BMad Method is meant to support this (and if it does not, can be further customized or extended with new modules).
+
+First know there is the full BMad Method Process and then there is a Quick Flow for those quicker smaller efforts.
+
+- **[Full Adaptive BMad Method](#workflow-guides)** - Full planning and scope support through extensive development and testing.
+  - Broken down into 4 phases, all of which are comprised of both required and optional phases
+    - Phases 1-3 are all about progressive idea development through planning and preparations to build your project.
+    - Phase 4 is the implementation cycle where you will Just In Time (JIT) produce the contextual stories needed for the dev agent based on the extensive planning completed
+    - All 4 phases have optional steps in them, depending on how rigorous you want to go with planning, research ideation, validation, testing and traceability.
+  - While there is a lot here, know that even this can be distilled down to a simple PRD, Epic and Story list and then jump into the dev cycle. But if that is all you want, you might be better off with the BMad Quick Flow described next
+
+- **[BMad Quick Flow](/docs/explanation/features/quick-flow.md)** - Fast-track development workflow
+  - 3-step process: spec → dev → optional review
+  - Perfect for bug fixes and small features
+  - Rapid prototyping with production quality
+  - Implementation in minutes, not days
+  - Has a specialized single agent that does all of this: **[Quick Flow Solo Dev Agent](/docs/explanation/agents/barry-quick-flow.md)**
+
+- **TEA engagement (optional)** - Choose TEA engagement: none, TEA-only (standalone), or integrated by track. See **[Test Architect Guide](/docs/explanation/features/tea-overview.md)**.
+
+## 🤖 Agents and Collaboration
+
+Complete guide to BMM's AI agent team:
+
+- **[Agents Guide](/docs/explanation/core-concepts/agent-roles.md)** - Comprehensive agent reference
+  - 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](/docs/explanation/features/party-mode.md)** - Multi-agent collaboration
+  - 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
+
+## 🔧 Working with Existing Code
+
+Comprehensive guide for brownfield development:
+
+- **[Brownfield Development Guide](/docs/how-to/brownfield/index.md)** - Complete guide for existing codebases
+  - Documentation phase strategies
+  - Track selection for brownfield
+  - Integration with existing patterns
+  - Phase-by-phase workflow guidance
+  - Common scenarios
+
+## 📚 Quick References
+
+Essential reference materials:
+
+- **[Glossary](/docs/reference/glossary/index.md)** - Key terminology and concepts
+- **[FAQ](/docs/explanation/faq/index.md)** - Frequently asked questions across all topics
+
+## 🎯 Choose Your Path
+
+### I need to...
+
+**Build something new (greenfield)**
+→ Start with [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md)
+
+**Fix a bug or add small feature**
+→ Use the [Quick Flow Solo Dev](/docs/explanation/agents/barry-quick-flow.md) directly with its dedicated stand alone [Quick Bmad Spec Flow](/docs/explanation/features/quick-flow.md) process
+
+**Work with existing codebase (brownfield)**
+→ Read [Brownfield Development Guide](/docs/how-to/brownfield/index.md)
+→ Pay special attention to documentation requirements for brownfield projects
+
+## 📋 Workflow Guides
+
+Comprehensive documentation for all BMM workflows organized by phase:
+
+- **[Phase 1: Analysis Workflows](/docs/how-to/workflows/run-brainstorming-session.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](/docs/how-to/workflows/create-prd.md)** - Scale-adaptive planning (967 lines)
+  - prd, tech-spec, gdd, narrative, ux
+  - Track-based planning approach (Quick Flow, BMad Method, Enterprise Method)
+  - Which planning workflow to use
+
+- **[Phase 3: Solutioning Workflows](/docs/how-to/workflows/create-architecture.md)** - Architecture and validation (638 lines)
+  - architecture, create-epics-and-stories, implementation-readiness
+  - V6: Epics created AFTER architecture for better quality
+  - Required for BMad Method and Enterprise Method tracks
+  - Preventing agent conflicts
+
+- **[Phase 4: Implementation Workflows](/docs/how-to/workflows/run-sprint-planning.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](/docs/explanation/features/tea-overview.md)** - Comprehensive quality assurance (1,420 lines)
+  - Test strategy, automation, quality gates
+  - TEA agent and test healing
+
+## 🌐 External Resources
+
+### Community and Support
+
+- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help from the community (#bmad-method-help, #report-bugs-and-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
+
+**Ready to begin?** → [Start with the Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md)

package/docs/explanation/core/index.md

@@ -0,0 +1,18 @@
+---
+title: "Core Module"
+---
+
+
+The Core Module is installed with all installations of BMad modules and provides common functionality that any module, workflow, or agent can take advantage of.
+
+## Core Module Components
+
+- **[Global Core Config](/docs/reference/configuration/global-config.md)** — Inheritable configuration that impacts all modules and custom content
+- **[Core Workflows](/docs/reference/workflows/core-workflows.md)** — Domain-agnostic workflows usable by any module
+  - [Party Mode](/docs/explanation/features/party-mode.md) — Multi-agent conversation orchestration
+  - [Brainstorming](/docs/explanation/features/brainstorming-techniques.md) — Structured creative sessions with 60+ techniques
+  - [Advanced Elicitation](/docs/explanation/features/advanced-elicitation.md) — LLM rethinking with 50+ reasoning methods
+- **[Core Tasks](/docs/reference/configuration/core-tasks.md)** — Common tasks available across modules
+  - [Index Docs](/docs/reference/configuration/core-tasks.md#index-docs) — Generate directory index files
+  - [Adversarial Review](/docs/reference/configuration/core-tasks.md#adversarial-review-general) — Critical content review
+  - [Shard Document](/docs/reference/configuration/core-tasks.md#shard-document) — Split large documents into sections