Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bmad-code-org/BMAD-METHOD/llms.txt

Use this file to discover all available pages before exploring further.

Use the BMad installer to upgrade from v4 or v5 to v6, which includes automatic detection of legacy installations and migration assistance.

​
When to Use This

  • You have BMad v4 or v5 installed (.bmad-method folder)
  • You want to migrate to the new v6 architecture
  • You have existing planning artifacts to preserve
Prerequisites
  • Node.js 20+
  • Existing BMad v4 or v5 installation

​
What’s New in v6

BMad v6 is the first stable release after extensive beta testing. Key improvements:

​
Unified Architecture

  • Single _bmad/ folder for all modules (was .bmad-method, .bmad-core, etc.)
  • Simplified configuration with per-module config.yaml files
  • Clean separation between core framework and method modules

​
Non-Interactive Installation

Full CI/CD support with command-line flags:
  • --directory, --modules, --tools, --custom-content
  • --action for update modes (install, update, quick-update, compile-agents)
  • -y, --yes for fully automated installations

​
Enhanced Workflows

  • Improved PRD workflow with vision/differentiators and executive summary steps
  • Better project context generation for existing codebases
  • Enhanced Quick Flow for rapid development
  • New /bmad-help intelligent guide

​
Better Customization

  • .customize.yaml files for all agents
  • Update-safe customizations (preserved across updates)
  • More granular control over agent behavior

​
Steps

​
1. Run the Installer

Follow the Installer Instructions: 
npx bmad-method install
For the latest stable version, specify the version explicitly:
npx bmad-method@6.0.4 install

​
2. Handle Legacy Installation

When v4/v5 is detected, you can:
  • Allow the installer to back up and remove .bmad-method
  • Exit and handle cleanup manually
If you named your bmad method folder something else - you will need to manually remove the folder yourself.

​
3. Clean Up IDE Commands

Manually remove legacy v4/v5 IDE commands - for example if you have claude, look for any nested folders that start with bmad and remove them: Claude Code: 
rm -rf .claude/commands/BMad/agents
rm -rf .claude/commands/BMad/tasks
Cursor: 
rm -rf .cursor/prompts/BMad
The v6 installer will create new commands in the correct locations.

​
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
Example: 
mkdir -p _bmad-output/planning-artifacts
mv old-docs/prd.md _bmad-output/planning-artifacts/myapp-PRD.md
mv old-docs/architecture.md _bmad-output/planning-artifacts/myapp-architecture.md
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

​
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/v5 Modulev6 Status
.bmad-2d-phaser-game-devIntegrated into BMGD Module
.bmad-2d-unity-game-devIntegrated into BMGD Module
.bmad-godot-game-devIntegrated into BMGD Module
.bmad-infrastructure-devopsDeprecated — new DevOps agent coming soon
.bmad-creative-writingNot adapted — new v6 module coming soon

​
Key Changes

Conceptv4/v5v6
Core_bmad-core was actually BMad Method_bmad/core/ is universal framework
Method_bmad-method_bmad/bmm/
ConfigModified files directlyconfig.yaml per module
DocumentsSharded or unsharded required setupFully flexible, auto-scanned
CommandsNested folder structureFlat structure for IDE commands

​
Troubleshooting

​
”Legacy installation detected” but no .bmad-method folder

The installer might detect other legacy folders like .bmad-core. Remove them manually: 
rm -rf .bmad-*

​
Workflows not showing up in IDE

Restart your IDE after installation to reload the command palette.

​
Old commands still appearing

Manually clean up legacy command folders (see Step 3 above) and restart your IDE.

​
Lost customizations

If you edited agent files directly in v4/v5, those changes are lost. In v6, always use .customize.yaml files to preserve your changes across updates.
After upgrading, run /bmad-help to verify your installation and see what’s new in v6.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us