External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-17 09:45:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
BMAD-METHOD/docs/v4-to-v6-upgrade.md
Brian Madison ae9851acab _cfg -> _config
2025-12-13 19:41:09 +08:00

7.6 KiB
Raw Blame History

BMad v4 to v6 Upgrade Guide

Overview

BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.

Automatic V4 Detection

When you run npm run install:bmad on a project with v4 installed, the installer automatically detects:

  • Legacy folders: Any folders starting with _bmad, bmad (lowercase), or Bmad
  • IDE command artifacts: Legacy bmad folders in IDE configuration directories (.claude/commands/, .cursor/commands/, etc.)

What Happens During Detection

  1. Automatic Backup of v4 Modules: All _bmad-* folders are moved to v4-backup/ in your project root

    • If a backup already exists, a timestamp is added to avoid conflicts
    • Example: _bmad-core → v4-backup/_bmad-core
    • Your project files and data are NOT affected

  2. IDE Command Cleanup Recommended: Legacy v4 IDE commands should be manually removed

    • Located in IDE config folders: .claude/commands/, .cursor/commands/, etc.
    • These old commands would still reference v4 folder structure if left in place
    • The installer provides copy/paste terminal commands for your platform
    • You can proceed without cleanup, but removing them prevents confusion with old v4 commands

Module Migration

Deprecated Modules

v4 Module v6 Status
_bmad-2d-phaser-game-dev Integrated into BMM
_bmad-2d-unity-game-dev Integrated into BMM
_bmad-godot-game-dev Integrated into BMM
_bmad-*-game-dev (any) Integrated into BMM
_bmad-infrastructure-devops Deprecated - New core devops agent coming in BMM
_bmad-creative-writing Not adapted - New module releasing soon

Game Development: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine.

Architecture Changes

Folder Structure

v4 "Expansion Packs" Structure:

your-project/
├── _bmad-core/           # Was actually the BMad Method
├── _bmad-game-dev/       # Separate expansion packs
├── _bmad-creative-writing/
└── _bmad-infrastructure-devops/

v6 Unified Structure:

your-project/
└── _bmad/       # Single installation folder, default _bmad
    ├── core/            # Real core framework (applies to all modules)
    ├── bmm/             # BMad Method (software/game dev)
    ├── bmb/             # BMad Builder (create agents/workflows)
    ├── cis/             # Creative Intelligence Suite
    └── _config/            # Your customizations
        └── agents/      # Agent customization files

Key Concept Changes

  • v4 _bmad-core: Was actually the BMad Method
  • v6 _bmad/core/: Is the real universal core framework
  • v6 _bmad/bmm/: Is the BMad Method module
  • Module identification: All modules now have a config.yaml file

Project Progress Migration

If You've Completed Planning Phase (PRD/Architecture) with the BMad Method:

After running the v6 installer:

  1. Run workflow-init workflow to set up the guided workflow system
  2. Specify your project level when prompted:
    • If you followed v4's full workflow (PRD → Architecture → Stories), select Level 3 or 4
    • This tells v6 you've already completed planning and solutioning phases
  3. Document paths: Keep your existing paths during installation
    • Default PRD/Architecture location: docs/
    • Default stories location: docs/sprint-artifacts/
    • Accept these defaults if you're already using them in v4

Important

: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.

If You're Mid-Development (Stories Created/Implemented)

  1. Complete the v6 installation as above
  2. Run workflow-init and specify Level 3 or 4
  3. When ready to continue development, run the sprint-planning workflow (Phase 4)

Agent Customization Migration

v4 Agent Customization

In v4, you may have modified agent files directly in _bmad-* folders.

v6 Agent Customization

All customizations now go in _bmad/_config/agents/ using customize files:

Example: Renaming an agent and changing communication style

File: _bmad/_config/agents/bmm-pm.customize.yaml

# Customize the PM agent
persona:
  name: 'Captain Jack' # Override agent name
  role: 'Swashbuckling Product Owner'
  communication_style: |
    - Talk like a pirate
    - Use nautical metaphors for software concepts
    - Always upbeat and adventurous

How it works:

  • Base agent: _bmad/bmm/agents/pm.md
  • Customization: _bmad/_config/agents/bmm-pm.customize.yaml
  • Result: Agent uses your custom name and style, but updates don't overwrite your changes

Document Compatibility

Sharded vs Unsharded Documents

Good news: Unlike v4, v6 workflows are fully flexible with document structure:

  • ✅ Sharded documents (split into multiple files)
  • ✅ Unsharded documents (single file per section)
  • ✅ Custom sections for your project type
  • ✅ Mixed approaches

All workflow files are scanned automatically. No manual configuration needed.

Installation Steps

1. Clone Repository

git clone https://github.com/bmad-code-org/BMAD-METHOD
cd BMAD-METHOD
npm install

2. Run Installer on Your v4 Project

npx bmad-method install

Enter the full path to your v4 project when prompted.

3. Follow Interactive Prompts

The installer will:

  1. Detect v4 installation and offer to backup _bmad-* folders
  2. Prompt for recommended cleanup (you can skip)
  3. Let you select modules (recommend: BMM for software and or game development)
  4. Configure core settings (name, language, etc.)
  5. Configure module-specific options
  6. Configure IDE integrations

4. Accept Default Paths

If you're using:

  • docs/ for PRD and architecture
  • docs/sprint-artifacts/ for story files

Accept these defaults during installation.

5. Initialize Workflow

After installation:

  1. Load the Analyst agent - See your IDE-specific instructions in docs/ide-info for how to activate agents:

  2. Wait for the agent's menu to appear

  3. Tell the agent: *workflow-init - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow"

Since you are migrating an existing project from v4, it's most likely Level 3 or 4 you will want to suggest when asked - if you've already completed PRD/architecture in v4.

Post-Migration Checklist

  • v4 folders backed up to v4-backup/
  • v6 installed to _bmad/ folder
  • workflow-init run with correct project level selected
  • Agent customizations migrated to _bmad/_config/agents/ if needed
  • IDE integration working (test by listing agents)
  • For active development: sprint-planning workflow executed

Getting Help