bmad-method 5.1.2 → 6.0.0-Beta.0

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

@@ -0,0 +1,82 @@
+---
+title: "How to Install BMad"
+description: Step-by-step guide to installing BMad in your project
+---
+
+Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
+
+## When to Use This
+
+- Starting a new project with BMad
+- Adding BMad to an existing codebase
+- Update the existing BMad Installation
+
+:::note[Prerequisites]
+- **Node.js** 20+ (required for the installer)
+- **Git** (recommended)
+- **AI tool** (Claude Code, Cursor, Windsurf, or similar)
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+npx bmad-method install
+```
+
+### 2. Choose Installation Location
+
+The installer will ask where to install BMad files:
+
+- Current directory (recommended for new projects if you created the directory yourself and ran from within the directory)
+- Custom path
+
+### 3. Select Your AI Tools
+
+Pick which AI tools you use:
+
+- Claude Code
+- Cursor
+- Windsurf
+- Others
+
+Each tool has its own way of integrating commands. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them.
+
+### 4. Choose Modules
+
+The installer shows available modules. Select whichever ones you need — most users just want **BMad Method** (the software development module).
+
+### 5. Follow the Prompts
+
+The installer guides you through the rest — custom content, settings, etc.
+
+## What You Get
+
+```
+your-project/
+├── _bmad/
+│   ├── bmm/            # Your selected modules
+│   │   └── config.yaml # Module settings (if you ever need to change them)
+│   ├── core/           # Required core module
+│   └── ...
+├── _bmad-output/       # Generated artifacts
+└── .claude/            # Claude Code commands (if using Claude Code)
+```
+
+## Verify Installation
+
+Run the `help` workflow (`/bmad-help` on most platforms) to verify everything works and see what to do next.
+
+**Latest from main branch:**
+```bash
+npx github:bmad-code-org/BMAD-METHOD install
+```
+
+Use these if you want the newest features before they're officially released. Things might break.
+
+## Troubleshooting
+
+**Installer throws an error** — Copy-paste the output into your AI assistant and let it figure it out.
+
+**Installer worked but something doesn't work later** — Your AI needs BMad context to help. See [How to Get Answers About BMad](/docs/how-to/get-answers-about-bmad.md) for how to point your AI at the right sources.

package/docs/how-to/shard-large-documents.md

@@ -0,0 +1,101 @@
+---
+title: "Document Sharding Guide"
+---
+
+Use the `shard-doc` tool to split large markdown files into smaller, organized files for better context management.
+
+## When to Use This
+
+- Very large complex PRDs
+- Architecture documents with multiple system layers
+- Epic files with 4+ epics (especially for Phase 4)
+- UX design specs covering multiple subsystems
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
+
+- **Selective Loading** - Workflows load only the sections they need
+- **Reduced Token Usage** - Massive efficiency gains for large projects
+- **Better Organization** - Logical section-based file structure
+- **Maintained Context** - Index file preserves document structure
+
+### Architecture
+
+```
+Before Sharding:
+docs/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+docs/
+└── prd/
+    ├── index.md                    # Table of contents with descriptions
+    ├── overview.md                 # Section 1
+    ├── user-requirements.md        # Section 2
+    ├── technical-requirements.md   # Section 3
+    └── ...                         # Additional sections
+```
+
+## Steps
+
+### 1. Run the Shard-Doc Tool
+
+```bash
+/bmad:core:tools:shard-doc
+```
+
+### 2. Follow the Interactive Process
+
+```
+Agent: Which document would you like to shard?
+User: docs/PRD.md
+
+Agent: Default destination: docs/prd/
+       Accept default? [y/n]
+User: y
+
+Agent: Sharding PRD.md...
+       ✓ Created 12 section files
+       ✓ Generated index.md
+       ✓ Complete!
+```
+
+## What You Get
+
+**index.md structure:**
+
+```markdown
+
+## Sections
+
+1. [Overview](./overview.md) - Project vision and objectives
+2. [User Requirements](./user-requirements.md) - Feature specifications
+3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
+4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
+   ...
+```
+
+**Individual section files:**
+
+- Named from heading text (kebab-case)
+- Contains complete section content
+- Preserves all markdown formatting
+- Can be read independently
+
+## How Workflow Discovery Works
+
+BMad workflows use a **dual discovery system**:
+
+1. **Try whole document first** - Look for `document-name.md`
+2. **Check for sharded version** - Look for `document-name/index.md`
+3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead
+
+## Workflow Support
+
+All BMM workflows support both formats:
+
+- Whole documents
+- Sharded documents
+- Automatic detection
+- Transparent to user

package/docs/how-to/upgrade-to-v6.md

@@ -0,0 +1,131 @@
+---
+title: "How to Upgrade to v6"
+description: Migrate from BMad v4 to v6
+---
+
+Use the BMad installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance.
+
+## When to Use This
+
+- You have BMad v4 installed (`.bmad-method` folder)
+- You want to migrate to the new v6 architecture
+- You have existing planning artifacts to preserve
+
+:::note[Prerequisites]
+- Node.js 20+
+- Existing BMad v4 installation
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+npx bmad-method install
+```
+
+The installer automatically detects:
+
+- **Legacy v4 folder**: `.bmad-method`
+- **IDE command artifacts**: Legacy bmad folders in `.claude/commands/`, `.cursor/commands/`, etc.
+
+### 2. Handle Legacy Installation
+
+When v4 is detected, you can:
+
+- Allow the installer to back up and remove `.bmad-method`
+- Exit and handle cleanup manually
+- Keep both (not recommended for same project)
+
+### 3. Clean Up IDE Commands
+
+Manually remove legacy v4 IDE commands:
+
+- `.claude/commands/BMad/agents`
+- `.claude/commands/BMad/tasks`
+
+New v6 commands will be at `.claude/commands/bmad/<module>/agents|workflows`.
+
+:::tip[Accidentally Deleted Commands?]
+If you delete the wrong commands, rerun the installer and choose "quick update" to restore them.
+:::
+
+### 4. Migrate Planning Artifacts
+
+**If you have planning documents (Brief/PRD/UX/Architecture):**
+
+Move them to `_bmad-output/planning-artifacts/` with descriptive names:
+
+- Include `PRD` in filename for PRD documents
+- Include `brief`, `architecture`, or `ux-design` accordingly
+- Sharded documents can be in named subfolders
+
+**If you're mid-planning:** Consider restarting with v6 workflows. Use your existing documents as inputs—the new progressive discovery workflows with web search and IDE plan mode produce better results.
+
+### 5. Migrate In-Progress Development
+
+If you have stories created or implemented:
+
+1. Complete the v6 installation
+2. Place `epics.md` or `epics/epic*.md` in `_bmad-output/planning-artifacts/`
+3. Run the Scrum Master's `sprint-planning` workflow
+4. Tell the SM which epics/stories are already complete
+
+### 6. Migrate Agent Customizations
+
+**v4:** Modified agent files directly in `_bmad-*` folders
+
+**v6:** All customizations go in `_bmad/_config/agents/` using customize files:
+
+```yaml
+# _bmad/_config/agents/bmm-pm.customize.yaml
+persona:
+  name: 'Captain Jack'
+  role: 'Swashbuckling Product Owner'
+  communication_style: |
+    - Talk like a pirate
+    - Use nautical metaphors
+```
+
+After modifying customization files, rerun the installer and choose "rebuild all agents" or "quick update".
+
+## What You Get
+
+**v6 unified structure:**
+
+```
+your-project/
+└── _bmad/               # Single installation folder
+    ├── _config/         # Your customizations
+    │   └── agents/      # Agent customization files
+    ├── core/            # Universal core framework
+    ├── bmm/             # BMad Method module
+    ├── bmb/             # BMad Builder
+    └── cis/             # Creative Intelligence Suite
+├── _bmad-output/        # Output folder (was doc folder in v4)
+```
+
+## Module Migration
+
+| v4 Module | v6 Status |
+|-----------|-----------|
+| `_bmad-2d-phaser-game-dev` | Integrated into BMGD Module |
+| `_bmad-2d-unity-game-dev` | Integrated into BMGD Module |
+| `_bmad-godot-game-dev` | Integrated into BMGD Module |
+| `_bmad-infrastructure-devops` | Deprecated — new DevOps agent coming soon |
+| `_bmad-creative-writing` | Not adapted — new v6 module coming soon |
+
+## Key Changes
+
+| Concept | v4 | v6 |
+|---------|----|----|
+| **Core** | `_bmad-core` was actually BMad Method | `_bmad/core/` is universal framework |
+| **Method** | `_bmad-method` | `_bmad/bmm/` |
+| **Config** | Modified files directly | `config.yaml` per module |
+| **Documents** | Sharded or unsharded required setup | Fully flexible, auto-scanned |
+
+## Tips
+
+- **Back up first** — Keep your v4 installation until you verify v6 works
+- **Use v6 workflows** — Even partial planning docs benefit from v6's improved discovery
+- **Rebuild after customizing** — Always run the installer after changing customize files

package/docs/index.md

@@ -0,0 +1,56 @@
+---
+title: Welcome to the BMad Method
+---
+
+The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework that helps you build software faster and smarter. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity—whether you're fixing a bug or building an enterprise platform.
+
+If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
+
+---
+
+## New Here? Start with a Tutorial
+
+The fastest way to understand BMad is to try it.
+
+- **[Get Started with BMad](/docs/tutorials/getting-started.md)** — Install and understand how BMad works
+- **[Workflow Map](/docs/reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management.
+
+## How to Use These Docs
+
+These docs are organized into four sections based on what you're trying to do:
+
+| Section           | Purpose                                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Tutorials**     | Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new. |
+| **How-To Guides** | Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here.  |
+| **Explanation**   | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*.       |
+| **Reference**     | Information-oriented. Technical specifications for agents, workflows, and configuration.                   |
+
+---
+
+## What You'll Need
+
+BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
+
+- **[Claude Code](https://code.claude.com)** — Anthropic's CLI tool (recommended)
+- **[Cursor](https://cursor.sh)** — AI-first code editor
+- **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
+- **[Roo Code](https://roocode.com)** — VS Code extension
+
+You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMad-style agent systems is required—that's what these docs are for.
+
+---
+
+## Join the Community
+
+Get help, share what you're building, or contribute to BMad:
+
+- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chat with other BMad users, ask questions, share ideas
+- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Source code, issues, and contributions
+- **[YouTube](https://www.youtube.com/@BMadCode)** — Video tutorials and walkthroughs
+
+---
+
+## Next Step
+
+Ready to dive in? **[Get Started with BMad](/docs/tutorials/getting-started.md)** and build your first project.

package/docs/reference/workflow-map.md

@@ -0,0 +1,83 @@
+---
+title: "Workflow Map"
+description: Visual reference for BMad Method workflow phases and outputs
+---
+
+The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following the best practices of context engineering and planning. AI agents work best with clear, structured context. The BMM system builds that context progressively across 4 distinct phases - each phase, and multiple workflows optionally within each phase, produce documents that inform the next, so agents always know what to build and why.
+
+The rationale and concepts come from agile methodologies that have been used across the industry with great success as a mental framework.
+
+If at anytime you are unsure what to do, the `/bmad-help` command will help you stay on track or know what to do next. You can always refer to this for reference also - but /bmad-help is fully interactive and much quicker if you have already installed the BMadMethod. Additionally, if you are using different modules that have extended the BMad Method or added other complimentary non extension modules - the /bmad-help evolves to know all that is available to give you the best in the moment advice.
+
+Final important note: Every workflow below can be run directly with your tool of choice via slash command or by loading an agent first and using the entry from the agents menu.
+
+<iframe src="/workflow-map-diagram.html" width="100%" height="100%" frameborder="0" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
+
+*[Interactive diagram - hover over outputs to see artifact flows]*
+
+## Phase 1: Analysis (Optional)
+
+Explore the problem space and validate ideas before committing to planning.
+
+| Workflow               | Purpose                                                                    | Produces                  |
+| ---------------------- | -------------------------------------------------------------------------- | ------------------------- |
+| `brainstorm`           | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
+| `research`             | Validate market, technical, or domain assumptions                          | Research findings         |
+| `create-product-brief` | Capture strategic vision                                                   | `product-brief.md`        |
+
+## Phase 2: Planning
+
+Define what to build and for whom.
+
+| Workflow           | Purpose                                  | Produces     |
+| ------------------ | ---------------------------------------- | ------------ |
+| `create-prd`       | Define requirements (FRs/NFRs)           | `PRD.md`     |
+| `create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
+
+## Phase 3: Solutioning
+
+Decide how to build it and break work into stories.
+
+| Workflow                         | Purpose                                    | Produces                    |
+| -------------------------------- | ------------------------------------------ | --------------------------- |
+| `create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
+| `create-epics-and-stories`       | Break requirements into implementable work | Epic files with stories     |
+| `check-implementation-readiness` | Gate check before implementation           | PASS/CONCERNS/FAIL decision |
+
+## Phase 4: Implementation
+
+Build it, one story at a time.
+
+| Workflow          | Purpose                                | Produces                      |
+| ----------------- | -------------------------------------- | ----------------------------- |
+| `sprint-planning` | Initialize tracking (once per project) | `sprint-status.yaml`          |
+| `create-story`    | Prepare next story for implementation  | `story-[slug].md`             |
+| `dev-story`       | Implement the story                    | Working code + tests          |
+| `code-review`     | Validate implementation quality        | Approved or changes requested |
+| `correct-course`  | Handle significant mid-sprint changes  | Updated plan or re-routing    |
+| `retrospective`   | Review after epic completion           | Lessons learned               |
+
+## Quick Flow (Parallel Track)
+
+Skip phases 1-3 for small, well-understood work.
+
+| Workflow     | Purpose                                    | Produces                                      |
+| ------------ | ------------------------------------------ | --------------------------------------------- |
+| `quick-spec` | Define an ad-hoc change                    | `tech-spec.md` (story file for small changes) |
+| `quick-dev`  | Implement from spec or direct instructions | Working code + tests                          |
+
+## Context Management
+
+Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions.
+
+For brownfield projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand.
+
+All implementation workflows load `project-context.md` if it exists. Additional context per workflow:
+
+| Workflow       | Also Loads                   |
+| -------------- | ---------------------------- |
+| `create-story` | epics, PRD, architecture, UX |
+| `dev-story`    | story file                   |
+| `code-review`  | architecture, story file     |
+| `quick-spec`   | planning docs (if exist)     |
+| `quick-dev`    | tech-spec                    |