Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

  1. 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.
  2. Install uv and confirm it runs. If uv run fails 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.
  3. 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 '*' and npx 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. Run Build on one small story first. Pick a story with a visible, checkable result and run bmad-build on it. Check the ticket's .memlog.md and 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

Limits

Related playbooks

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