bmad-method 5.1.2 → 6.0.0-Beta.0

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

@@ -0,0 +1,110 @@
+---
+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 to Avoid
+
+:::caution[Common Mistakes]
+- **Implicit Decisions** — "We'll figure out the API style as we go" leads to inconsistency
+- **Over-Documentation** — Documenting every minor choice causes analysis paralysis
+- **Stale Architecture** — Documents written once and never updated cause agents to follow outdated patterns
+:::
+
+:::tip[Correct Approach]
+- Document decisions that cross epic boundaries
+- Focus on conflict-prone areas
+- Update architecture as you learn
+- Use `correct-course` for significant changes
+:::

package/docs/explanation/quick-flow.md

@@ -0,0 +1,27 @@
+---
+title: "Quick Flow"
+description: Fast-track for small changes - skip the full methodology
+---
+
+Quick Flow is for when you don't need the full BMad Method. Skip Product Brief, PRD, and Architecture - go straight to implementation.
+
+## How It Works
+
+1. **Run `quick-spec`** — generates a focused tech-spec
+2. **Run `quick-dev`** — implements it
+
+That's it.
+
+## When to Use It
+
+- Bug fixes
+- Refactoring
+- Small features
+- Prototyping
+
+## When to Use Full BMad Method Instead
+
+- New products
+- Major features
+- Multiple teams involved
+- Stakeholder alignment needed

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

@@ -0,0 +1,75 @@
+---
+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 |
+
+:::tip[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
+
+:::caution[Cost Multiplier]
+Catching alignment issues in solutioning is 10× faster than discovering them during implementation.
+:::

package/docs/how-to/brownfield/index.md

@@ -0,0 +1,84 @@
+---
+title: "Brownfield Development"
+description: How to use BMad Method on existing codebases
+---
+
+Use BMad Method effectively when working on existing projects and legacy codebases.
+
+## What is Brownfield Development?
+
+**Brownfield** refers to working on existing projects with established codebases and patterns, as opposed to **greenfield** which means starting from scratch with a clean slate.
+
+This guide covers the essential workflow for onboarding to brownfield projects with BMad Method.
+
+:::note[Prerequisites]
+- BMad Method installed (`npx bmad-method install`)
+- An existing codebase you want to work on
+- Access to an AI-powered IDE (Claude Code, Cursor, or Windsurf)
+:::
+
+## Step 1: Clean Up Completed Planning Artifacts
+
+If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
+
+- `docs/`
+- `_bmad-output/planning-artifacts/`
+- `_bmad-output/implementation-artifacts/`
+
+## Step 2: Maintain Quality Project Documentation
+
+Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
+
+- Intent and business rationale
+- Business rules
+- Architecture
+- Any other relevant project information
+
+For complex projects, consider using the `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
+
+## Step 3: Get Help
+
+Get help to know what to do next based on your unique needs
+
+Run `bmad-help` to get guidance when you are not sure what to do next.
+
+### Choosing Your Approach
+
+You have two primary options depending on the scope of changes:
+
+| Scope                          | Recommended Approach                                                                                                          |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad method is likely overkill. |
+| **Major changes or additions** | Start with the BMad method, applying as much or as little rigor as needed.                                                    |
+
+### During PRD Creation
+
+When creating a brief or jumping directly into the PRD, ensure the agent:
+
+- Finds and analyzes your existing project documentation
+- Reads the proper context about your current system
+
+You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
+
+### UX Considerations
+
+UX work is optional. The decision depends not on whether your project has a UX, but on:
+
+- Whether you will be working on UX changes
+- Whether significant new UX designs or patterns are needed
+
+If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
+
+### Architecture Considerations
+
+When doing architecture, ensure the architect:
+
+- Uses the proper documented files
+- Scans the existing codebase
+
+Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
+
+## More Information
+
+- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes
+- **[Brownfield FAQ](/docs/explanation/brownfield-faq.md)** - Common questions about brownfield development

package/docs/how-to/brownfield/quick-fix-in-brownfield.md

@@ -0,0 +1,76 @@
+---
+title: "How to Make Quick Fixes in Brownfield Projects"
+description: How to make quick fixes and ad-hoc changes in brownfield projects
+---
+
+Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad method or Quick Flow.
+
+## When to Use This
+
+- Simple bug fixes
+- Small refactorings and changes that don't need extensive ideation, planning, or architectural shifts
+- Larger refactorings or improvement with built in tool planning and execution mode combination, or better yet use quick flow
+- Learning about your codebase
+
+## Steps
+
+### 1. Load an Agent
+
+For quick fixes, you can use:
+
+- **DEV agent** - For implementation-focused work
+- **Quick Flow Solo Dev** - For slightly larger changes that still need a quick-spec to keep the agent aligned to planning and standards
+
+### 2. Describe the Change
+
+Simply tell the agent what you need:
+
+```
+Fix the login validation bug that allows empty passwords
+```
+
+or
+
+```
+Refactor the UserService to use async/await instead of callbacks
+```
+
+### 3. Let the Agent Work
+
+The agent will:
+
+- Analyze the relevant code
+- Propose a solution
+- Implement the change
+- Run tests (if available)
+
+### 4. Review and Commit
+
+Review the changes made and commit when satisfied.
+
+## Learning Your Codebase
+
+This approach is also excellent for exploring unfamiliar code:
+
+```
+Explain how the authentication system works in this codebase
+```
+
+```
+Show me where error handling happens in the API layer
+```
+
+LLMs are excellent at interpreting and analyzing code, whether it was AI-generated or not. Use the agent to:
+
+- Learn about your project
+- Understand how things are built
+- Explore unfamiliar parts of the codebase
+
+## When to Upgrade to Formal Planning
+
+Consider using Quick Flow or full BMad Method when:
+
+- The change affects multiple files or systems
+- You're unsure about the scope
+- The fix keeps growing in complexity
+- You need documentation for the change

package/docs/how-to/customize-bmad.md

@@ -0,0 +1,158 @@
+---
+title: "BMad Method Customization Guide"
+---
+
+The ability to customize the BMad Method and its core to your needs, while still being able to get updates and enhancements is a critical idea within the BMad Ecosystem.
+
+The Customization Guidance outlined here, while targeted at understanding BMad Method customization, applies to any other module use within the BMad Method.
+
+## Types of Customization
+
+Customization includes Agent Customization, Workflow/Skill customization, the addition of new MCPs or Skills to be used by existing agents. Aside from all of this, a whole other realm of customization involves creating / adding your own relevant BMad Builder workflows, skills, agents and maybe even your own net new modules to compliment the BMad Method Module.
+
+Warning: The reason for customizing as this guide will prescribe will allow you to continue getting updates without worrying about losing your customization changes. And by continuing to get updates as BMad modules advance, you will be able to continue to evolve as the system improves.
+
+## Agent Customization
+
+### Agent Customization Areas
+
+- Change agent names, personas or manner of speech
+- Add project-specific memories or context
+- Add custom menu items to custom or inline prompts, skills or custom BMad workflows
+- Define critical actions that occur agent startup for consistent behavior
+
+## How to customize an agent.
+
+**1. Locate Customization Files**
+
+After installation, find agent customization files in:
+
+```
+_bmad/_config/agents/
+├── core-bmad-master.customize.yaml
+├── bmm-dev.customize.yaml
+├── bmm-pm.customize.yaml
+└── ... (one file per installed agent)
+```
+
+**2. Edit Any Agent**
+
+Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
+
+**3. Rebuild the Agent**
+
+After editing, IT IS CRITICAL to rebuild the agent to apply changes:
+
+```bash
+npx bmad-method install
+```
+
+You can either then:
+
+- Select `Quick Update` - This will also ensure all packages are up to date AND compile all agents to include any updates or customizations
+- Select `Rebuild Agents` - This will only rebuild and apply customizations to agents, without pulling the latest
+
+There will be additional tools shortly after beta launch to allow install of individual agents, workflows, skills and modules without the need for using the full bmad installer.
+
+### What Agent Properties Can Be Customized?
+
+#### Agent Name
+
+Change how the agent introduces itself:
+
+```yaml
+agent:
+  metadata:
+    name: 'Spongebob' # Default: "Amelia"
+```
+
+#### Persona
+
+Replace the agent's personality, role, and communication style:
+
+```yaml
+persona:
+  role: 'Senior Full-Stack Engineer'
+  identity: 'Lives in a pineapple (under the sea)'
+  communication_style: 'Spongebob annoying'
+  principles:
+    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
+    - 'Favor composition over inheritance'
+```
+
+**Note:** The persona section replaces the entire default persona (not merged).
+
+#### Memories
+
+Add persistent context the agent will always remember:
+
+```yaml
+memories:
+  - 'Works at Krusty Krab'
+  - 'Favorite Celebrity: David Hasslehoff'
+  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
+```
+
+### Custom Menu Items
+
+Any custom items you add here will be included in the agents display menu.
+
+```yaml
+menu:
+  - trigger: my-workflow
+    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
+    description: My custom workflow
+  - trigger: deploy
+    action: '#deploy-prompt'
+    description: Deploy to production
+```
+
+### Critical Actions
+
+Add instructions that execute before the agent starts:
+
+```yaml
+critical_actions:
+  - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
+```
+
+### Custom Prompts
+
+Define reusable prompts for `action="#id"` menu handlers:
+
+```yaml
+prompts:
+  - id: deploy-prompt
+    content: |
+      Deploy the current branch to production:
+      1. Run all tests
+      2. Build the project
+      3. Execute deployment script
+```
+
+## Troubleshooting
+
+**Changes not appearing?**
+
+- Make sure you ran `npx bmad-method build <agent-name>` after editing
+- Check YAML syntax is valid (indentation matters!)
+- Verify the agent name matches the file name pattern
+
+**Agent not loading?**
+
+- Check for YAML syntax errors
+- Ensure required fields aren't left empty if you uncommented them
+- Try reverting to the template and rebuilding
+
+**Need to reset?**
+
+- Remove content from the `.customize.yaml` file (or delete the file)
+- Run `npx bmad-method build <agent-name>` to regenerate defaults
+
+## Workflow Customization
+
+Information about customizing existing BMad MEthod workflows and skills are coming soon.
+
+## Module Customization
+
+Information on how to build expansion modules that augment BMad, or make other existing module customizations are coming soon.

package/docs/how-to/get-answers-about-bmad.md

@@ -0,0 +1,102 @@
+---
+title: "How to Get Answers About BMad"
+description: Use an LLM to quickly answer your own BMad questions
+---
+
+If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working.
+
+## When to Use This
+
+- You have a question about how BMad works or what to do next with BMad
+- You want to understand a specific agent or workflow
+- You need quick answers without waiting for Discord
+
+:::note[Prerequisites]
+An AI tool (Claude Code, Cursor, ChatGPT, Claude.ai, etc.) and either BMad installed in your project or access to the GitHub repo.
+:::
+
+## Steps
+
+### 1. Choose Your Source
+
+| Source               | Best For                                  | Examples                     |
+| -------------------- | ----------------------------------------- | ---------------------------- |
+| **`_bmad` folder**   | How BMad works—agents, workflows, prompts | "What does the PM agent do?" |
+| **Full GitHub repo** | History, installer, architecture          | "What changed in v6?"        |
+| **`llms-full.txt`**  | Quick overview from docs                  | "Explain BMad's four phases" |
+
+The `_bmad` folder is created when you install BMad. If you don't have it yet, clone the repo instead.
+
+### 2. Point Your AI at the Source
+
+**If your AI can read files (Claude Code, Cursor, etc.):**
+
+- **BMad installed:** Point at the `_bmad` folder and ask directly
+- **Want deeper context:** Clone the [full repo](https://github.com/bmad-code-org/BMAD-METHOD)
+
+**If you use ChatGPT or Claude.ai:**
+
+Fetch `llms-full.txt` into your session:
+
+```
+https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
+```
+
+See the [Downloads page](/docs/downloads.md) for other downloadable resources.
+
+### 3. Ask Your Question
+
+:::note[Example]
+**Q:** "Tell me the fastest way to build something with BMad"
+
+**A:** Use Quick Flow: Run `quick-spec` to write a technical specification, then `quick-dev` to implement it—skipping the full planning phases.
+:::
+
+## What You Get
+
+Direct answers about BMad—how agents work, what workflows do, why things are structured the way they are—without waiting for someone else to respond.
+
+## Tips
+
+- **Verify surprising answers** — LLMs occasionally get things wrong. Check the source file or ask on Discord.
+- **Be specific** — "What does step 3 of the PRD workflow do?" beats "How does PRD work?"
+
+## Still Stuck?
+
+Tried the LLM approach and still need help? You now have a much better question to ask.
+
+| Channel                   | Use For                                     |
+| ------------------------- | ------------------------------------------- |
+| `#bmad-method-help`       | Quick questions (real-time chat)            |
+| `help-requests` forum     | Detailed questions (searchable, persistent) |
+| `#suggestions-feedback`   | Ideas and feature requests                  |
+| `#report-bugs-and-issues` | Bug reports                                 |
+
+**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
+
+**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) (for clear bugs)
+
+*You!*
+        *Stuck*
+             *in the queue—*
+                      *waiting*
+                              *for who?*
+
+*The source*
+        *is there,*
+                *plain to see!*
+
+*Point*
+     *your machine.*
+              *Set it free.*
+
+*It reads.*
+        *It speaks.*
+                *Ask away—*
+
+*Why wait*
+        *for tomorrow*
+                *when you have*
+                        *today?*
+
+*—Claude*