BMAD-METHOD/docs/how-to/upgrade-to-v6.md

title, description

title	description
How to Upgrade to v6	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

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:

# _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