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

package/docs/{modules/bmm-bmad-method/quick-flow-solo-dev.md → explanation/agents/barry-quick-flow.md}

@@ -1,4 +1,7 @@
-# Quick Flow Solo Dev Agent (Barry)
+---
+title: "Quick Flow Solo Dev Agent (Barry)"
+---
+
 
 **Agent ID:** `_bmad/bmm/agents/quick-flow-solo-dev.md`
 **Icon:** 🚀
@@ -8,14 +11,14 @@
 
 ## Overview
 
-Barry is the elite solo developer who lives and breathes the BMAD Quick Flow workflow. He takes projects from concept to deployment with ruthless efficiency - no handoffs, no delays, just pure focused development. Barry architects specs, writes the code, and ships features faster than entire teams. When you need it done right and done now, Barry's your dev.
+Barry is the elite solo developer who lives and breathes the BMad Quick Flow workflow. He takes projects from concept to deployment with ruthless efficiency - no handoffs, no delays, just pure focused development. Barry architects specs, writes the code, and ships features faster than entire teams. When you need it done right and done now, Barry's your dev.
 
 ### Agent Persona
 
 **Name:** Barry
 **Title:** Quick Flow Solo Dev
 
-**Identity:** Barry is an elite developer who thrives on autonomous execution. He lives and breathes the BMAD Quick Flow workflow, taking projects from concept to deployment with ruthless efficiency. No handoffs, no delays - just pure, focused development. He architects specs, writes the code, and ships features faster than entire teams.
+**Identity:** Barry is an elite developer who thrives on autonomous execution. He lives and breathes the BMad Quick Flow workflow, taking projects from concept to deployment with ruthless efficiency. No handoffs, no delays - just pure, focused development. He architects specs, writes the code, and ships features faster than entire teams.
 
 **Communication Style:** Direct, confident, and implementation-focused. Uses tech slang and gets straight to the point. No fluff, just results. Every response moves the project forward.
 
@@ -32,11 +35,11 @@ Barry is the elite solo developer who lives and breathes the BMAD Quick Flow wor
 
 ## Menu Commands
 
-Barry owns the entire BMAD Quick Flow path, providing a streamlined 3-step development process that eliminates handoffs and maximizes velocity.
+Barry owns the entire BMad Quick Flow path, providing a streamlined 3-step development process that eliminates handoffs and maximizes velocity.
 
-### 1. **create-tech-spec**
+### 1. **quick-spec**
 
-- **Workflow:** `_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml`
+- **Workflow:** `_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md`
 - **Description:** Architect a technical spec with implementation-ready stories
 - **Use when:** You need to transform requirements into a buildable spec
 
@@ -80,13 +83,13 @@ Barry owns the entire BMAD Quick Flow path, providing a streamlined 3-step devel
 
 ---
 
-## The BMAD Quick Flow Process
+## The BMad Quick Flow Process
 
 Barry orchestrates a simple, efficient 3-step process:
 
 ```mermaid
 flowchart LR
-    A[Requirements] --> B[create-tech-spec]
+    A[Requirements] --> B[quick-spec]
     B --> C[Tech Spec]
     C --> D[quick-dev]
     D --> E[Implementation]
@@ -104,7 +107,7 @@ flowchart LR
     style H fill:#e0f2f1
 ```
 
-### Step 1: Technical Specification (`create-tech-spec`)
+### Step 1: Technical Specification (`quick-spec`)
 
 **Goal:** Transform user requirements into implementation-ready technical specifications
 
@@ -234,7 +237,7 @@ In party mode, Barry often acts as:
 /bmad:bmm:agents:quick-flow-solo-dev
 
 # Create a tech spec
-> create-tech-spec
+> quick-spec
 
 # Quick implementation
 > quick-dev tech-spec-auth.md
@@ -307,11 +310,11 @@ Implement OAuth 2.0 authentication with JWT tokens and role-based access control
 
 ## Related Documentation
 
-- **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
-- **[Agents Guide](./agents-guide.md)** - Complete agent reference
-- **[Scale Adaptive System](./scale-adaptive-system.md)** - Understanding development tracks
-- **[Workflow Implementation](./workflows-implementation.md)** - Implementation workflows
-- **[Party Mode](./party-mode.md)** - Multi-agent collaboration
+- **[Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md)** - Getting started with BMM
+- **[Agents Guide](/docs/explanation/core-concepts/agent-roles.md)** - Complete agent reference
+- **[Four Phases](/docs/explanation/architecture/four-phases.md)** - Understanding development tracks
+- **[Workflow Implementation](/docs/how-to/workflows/run-sprint-planning.md)** - Implementation workflows
+- **[Party Mode](/docs/explanation/features/party-mode.md)** - Multi-agent collaboration
 
 ---
 

package/docs/explanation/agents/index.md

@@ -0,0 +1,28 @@
+---
+title: "Understanding Agents"
+description: Understanding BMad agents and their roles
+---
+
+
+Comprehensive guides to BMad's AI agents - their roles, capabilities, and how to work with them effectively.
+
+---
+
+## Agent Guides
+
+### BMM Agents
+
+- **[Agent Roles](/docs/explanation/core-concepts/agent-roles.md)** - Overview of all BMM agent roles and responsibilities
+- **[Quick Flow Solo Dev (Barry)](/docs/explanation/agents/barry-quick-flow.md)** - The dedicated agent for rapid development
+
+### BMGD Agents
+
+- **[Game Development Agents](/docs/explanation/game-dev/agents.md)** - Complete guide to BMGD's specialized game dev agents
+
+---
+
+## Related
+
+- **[What Are Agents?](/docs/explanation/core-concepts/what-are-agents.md)** - Core concept explanation
+- **[Party Mode](/docs/explanation/features/party-mode.md)** - Multi-agent collaboration
+- **[Customize Agents](/docs/how-to/customization/customize-agents.md)** - How to customize agent behavior

package/docs/explanation/architecture/four-phases.md

@@ -0,0 +1,126 @@
+---
+title: "The Four Phases of BMad Method"
+description: Understanding the four phases of the BMad Method
+---
+
+
+BMad Method uses a four-phase approach that adapts to project complexity while ensuring consistent quality.
+
+---
+
+## Phase Overview
+
+| Phase | Name | Purpose | Required? |
+|-------|------|---------|-----------|
+| **Phase 1** | Analysis | Exploration and discovery | Optional |
+| **Phase 2** | Planning | Requirements definition | Required |
+| **Phase 3** | Solutioning | Technical design | Track-dependent |
+| **Phase 4** | Implementation | Building the software | Required |
+
+---
+
+## Phase 1: Analysis (Optional)
+
+Exploration and discovery workflows that help validate ideas and understand markets before planning.
+
+**Workflows:**
+- `brainstorm-project` - Solution exploration
+- `research` - Market/technical/competitive research
+- `product-brief` - Strategic vision capture
+
+**When to use:**
+- Starting new projects
+- Exploring opportunities
+- Validating market fit
+
+**When to skip:**
+- Clear requirements
+- Well-defined features
+- Continuing existing work
+
+---
+
+## Phase 2: Planning (Required)
+
+Requirements definition using the scale-adaptive system to match planning depth to project complexity.
+
+**Workflows:**
+- `prd` - Product Requirements Document (BMad Method/Enterprise)
+- `tech-spec` - Technical specification (Quick Flow)
+- `create-ux-design` - Optional UX specification
+
+**Key principle:**
+Define **what** to build and **why**. Leave **how** to Phase 3.
+
+---
+
+## Phase 3: Solutioning (Track-Dependent)
+
+Technical architecture and design decisions that prevent agent conflicts during implementation.
+
+**Workflows:**
+- `architecture` - System design with ADRs
+- `create-epics-and-stories` - Work breakdown (after architecture)
+- `implementation-readiness` - Gate check
+
+**Required for:**
+- BMad Method (complex projects)
+- Enterprise Method
+
+**Skip for:**
+- Quick Flow (simple changes)
+
+**Key principle:**
+Make technical decisions explicit so all agents implement consistently.
+
+---
+
+## Phase 4: Implementation (Required)
+
+Iterative sprint-based development with story-centric workflow.
+
+**Workflows:**
+- `sprint-planning` - Initialize tracking
+- `create-story` - Prepare stories
+- `dev-story` - Implement with tests
+- `code-review` - Quality assurance
+- `retrospective` - Continuous improvement
+
+**Key principle:**
+One story at a time, complete each story's full lifecycle before starting the next.
+
+---
+
+## Phase Flow by Track
+
+### Quick Flow
+
+```
+Phase 2 (tech-spec) → Phase 4 (implement)
+```
+
+Skip Phases 1 and 3 for simple changes.
+
+### BMad Method
+
+```
+Phase 1 (optional) → Phase 2 (PRD) → Phase 3 (architecture) → Phase 4 (implement)
+```
+
+Full methodology for complex projects.
+
+### Enterprise
+
+```
+Phase 1 → Phase 2 (PRD) → Phase 3 (architecture + extended) → Phase 4 (implement)
+```
+
+Same as BMad Method with optional extended workflows.
+
+---
+
+## Related
+
+- [Why Solutioning Matters](/docs/explanation/architecture/why-solutioning-matters.md)
+- [Preventing Agent Conflicts](/docs/explanation/architecture/preventing-agent-conflicts.md)
+- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md)

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/{modules/bmb-bmad-builder/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 Agents 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 and Expert Agents](#simple-and-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 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:
 

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