Playbooks · Coding tasks
Move a v6 BMad project to the v7 preview
Written November 2, 2026
Your v6 install will not upgrade itself to v7. The preview renames the skills you call, standardises on uv, and replaces Quick Dev with Build.
Why your v6 setup does not carry over
BMad's stable release is v6.12, installed by the npm installer and frozen aside from bug fixes. Version 7 is in preview alpha on the project's main branch, and the project's own description of the preview is that its skills, install path, and docs change often. The stated release aim for v7 is mid-November 2026. That is a stated aim, not a release, and nothing about the preview should be treated as stable until v7 actually ships. The preview installs by a different route from v6: through the Skills CLI, as two module installs — core tools and method. The installer notes that v7 is available for preview, but it does not move a v6 project on its own. Not every module moves: CIS and TEA stay at their last v6 releases, and newer releases of those modules target v7.
Install uv first
In v6, a missing uv only warned. In the v7 preview, uv is required: the preview's setup refuses to write the project another way when uv is missing or cannot run, and the rendered Build skills halt if uv is unavailable. Every skill that runs a Python script standardises on uv run in v7, instead of calling python3 directly. Install uv and confirm it runs before touching the project. Custom skills and overrides that shell out to python3 need the same change.
What changes in the names you call
Quick Dev becomes Build, the one official way BMad implements code. The renames are bmad-quick-dev to bmad-build and bmad-dev-auto to bmad-build-auto, and Phase 4 becomes a single chain: sprint planning, then Build, then code review. The old names keep working through forwarding shims kept in v6-shims/ until the v7 cut, when the shims are removed. On a fresh install the deprecated shims are opt-in: pass --shims to keep them. A shim offers the migration, requires your explicit approval, and never overwrites anything. If you decline, or the shim is unavailable, it halts instead of forwarding — so an unattended run on an old name with a legacy customization file refuses to start rather than silently running the old skill.
Other renames recorded in the preview's own retirement list are bmad-help to bmad, bmad-create-ux-design to bmad-ux, bmad-ticket to bmad-agent-po, and bmad-eval-runner to bmad-eval. A retired name is never reused. The core skill set also gets smaller: review and editorial skills become lenses on one bmad-review skill, the three research skills become bmad-deep-recon, and bmad-project-context replaces the two project-documentation skills. Removed outright are bmad-index-docs and bmad-shard-doc; bmad-check-implementation-readiness is removed and folded into sprint planning, and the tech-writer agent is retired. Rename your customization files to match: _bmad/custom/bmad-quick-dev{,.user}.toml becomes bmad-build{,.user}.toml, and the same for bmad-dev-auto to bmad-build-auto.
What happens to your planning files
The preview's v6-to-v7 migration moves planning and implementation artifacts into a new initiative layout. The planning folder is renamed to initiative-<slug>/, and epics.md plus sprint-status.yaml become a ticket tree: a tickets.toml file, epics, entries, and a story-<slug>-plan.md per story. Prerelease spec folders are folded into the same shape. A backup folder named .v6-v7-migration-backup-<datetime>/ is made first, the plan is approved before anything changes, and a checklist is verified at the end. In the migration's own notes, Sofia, the Product Owner (bmad-agent-po), replaces the sprint-planning, epic-and-story, ticket, spec, and correct-course skills. A second migration step covers the move from the v7 preview to final v7, moving each initiative and epic breakdown into a tickets/ folder. Working memory also changes shape: a single shared, append-only memlog replaces the per-skill decision logs, and each ticket carries its own .memlog.md.
Configuration becomes one merged config that every skill reads. The installer manages _bmad/config.toml, and overrides under _bmad/custom/ apply everywhere. The migration script's clean mode drops named v6 keys and backs up _bmad/ first. Do not hand-edit the installer-managed file to force the move; let the setup and migration steps write it.
Steps
- Freeze the v6 project. Commit everything or copy the whole project folder. Keep the v6 copy working until v7 ships; the preview is not the place to discover you needed the old layout.
- Install uv and confirm it runs. If
uv runfails on your machine, stop here. The preview's rendered skills halt without it, and no workaround of writing the project files another way is supported. - Install the preview into a copy of the project. Use the Skills CLI route:
npx skills add bmad-code-org/BMAD-METHOD/skills/core-tools --skill '*'andnpx skills add bmad-code-org/BMAD-METHOD/skills/method --skill '*'— core tools first, since every install needs them. Work on the copy, not the only checkout. - Run
bmad setup. It runs the skills update, refreshes the project, and cleans up renamed and removed skills. It offers to delete skills that are still installed under retired names, and moves a renamed skill's_bmad/custom/files to the new name. Answer the shim migration offer explicitly; declining halts rather than forwarding, which is the safe outcome. - Rename customization files by hand where setup did not. Check
_bmad/custom/for files named after retired skills, especially the Quick Dev pair, and rename them to the Build names above. A customization file under an old name is what makes an unattended run refuse to start. - Approve the migration plan before it runs. The v6-to-v7 migration shows its plan first. Check that the backup folder exists, that the planning folder maps to one
initiative-<slug>/, and that every epic and story lands in the ticket tree. Approve only then. - Check the merged config. Confirm your overrides under
_bmad/custom/are the ones in effect, and that nothing you relied on still lives only in a v6-era config file the clean step dropped. Re-add anything missing through the override files, not the installer-managed base. - Run Build on one small story first. Pick a story with a visible, checkable result and run
bmad-buildon it. Check the ticket's.memlog.mdand the ticket tree afterwards: the story plan, the result, and the log should all be in the new shape. Only then point Build at real work.
What can go wrong
- Treating the preview as the release. Names, paths, and docs change often in preview. A workflow that works this week can be renamed next week; the shim layer is what carries you across, and it is removed at the v7 cut.
- Running unattended on an old name. An old skill name with a legacy customization file halts instead of forwarding when the migration is declined or unavailable. Rename the customization files and answer the migration offer before any unattended run.
- Skipping uv. A machine where uv warns but works under v6 is a machine where the preview's rendered skills halt. Confirm
uv runworks before migrating. - Editing the wrong config layer. Overrides belong under
_bmad/custom/. Edits to the installer-managed base get overwritten on the next refresh. - Migrating the only copy. The migration renames folders and folds files. Without the backup folder and a separate v6 copy, there is no clean way back to the layout your running work expects.
Limits
- The preview changes often by its own description, so a name or path in this guide can be renamed in a later preview build. The release notes and the project's README are the places to recheck before a second migration pass.
- The mid-November 2026 date is the project's stated aim at the time of writing, and the project notes it might be sooner. It is not a shipped release.
- Shims carry old names only until the v7 cut. Anything still calling a retired name after the cut stops working, shim or no shim.
Related playbooks
- BMad v7 is a preview, not the stable release: what changes, and whether to try it before it ships
- Project Eve: Claude plays MMORPGs
- Gemini CLI 0.68 preview: extension checks
- Gemini CLI 0.69.0-preview.0: /stats heatmap for token use
Sources
Back to: Coding playbooks hub · Also: Try the BMad v7 preview on a fresh project · Start work on a codebase you inherited · Write a short product requirements document with BMad · BMad Method, the stable install