The whole life of BMAD+ in a project: install, check, update with a policy and receipts, restore, uninstall while keeping your memory. What each step writes and removes, and how it behaves offline.
BMAD+ lives inside your project, next to your code. That raises three fair questions: how do I install it without it taking over, how do I keep it current without losing my own edits, and how do I remove it without losing my work. This page follows one installation from the first command to the last and says, for each step, what is read, what is written and what is removed. The principle is the same everywhere: BMAD+ keeps a list of the files it owns, with a fingerprint of each, and acts only on files that still match.
Install, update, uninstall, and keep your memoryOne install command, a health check with doctor, updates that keep your edits, and an uninstall that leaves memory and configuration in place.Transcript
Run one command from your project folder, and choose your adapters and packs. The installer writes the agent instructions, the shared project spine and the adapters you selected. Then doctor checks the installation and reports how many checks passed. Updates keep the files you customised: BMAD+ tracks which files it manages. A version check only looks. Automatic updates need an explicit project policy. Uninstall removes only files that still match what was installed. Your memory, your edits and your configuration stay where they are. It never deletes a folder recursively, so hidden files and nested content survive.
Plan, back up, write, verify, leave a receipt. Undo with --restore.
In your project terminal
npx --no-install bmad-plus update --latest --yes
06
Uninstall
Remove only what BMAD+ owns; memory, settings and your edits stay.
In your project terminal
npx --no-install bmad-plus uninstall --yes
Warning· Steps 2 to 6 need a local copy
The installer does not put bmad-plus in your project’s node_modules, so npx --no-install bmad-plus ... fails right after step 1 (npx canceled due to missing packages and no YES option). Add the package once with npm install --save-dev bmad-plus, or run those steps as npx bmad-plus ..., which downloads it when needed. The generated CLAUDE.md and AGENTS.md ask the assistant to run npx --no-install bmad-plus update-check; without a local copy the command is unavailable and the assistant skips the update check and carries on with your task. See the CLI overview.
Everything rests on one file written by install: _bmad/.bmad-plus-install.json, the manifest. It records the version, the packs, the tools, your name and language, the execution mode, an adapterHashes map (one fingerprint per instruction file) and a fileInventory: for every agent, skill and data file BMAD+ placed, its SHA-256 fingerprint. Line endings are normalised before fingerprinting instruction files, so a Windows checkout does not look like an edit.
Ownership inventory states shown by doctor
State
Meaning
Consequence
complete
Every shipped file is recorded.
Updates can be automatic when the policy allows.
incomplete
Some file was already there, with different content, at install time.
Those files are treated as yours.
legacy
Installed before ownership hashes existed.
Updates back up the original pack files first; --auto refuses.
invalid
The inventory is malformed.
doctor reports an error; repair the manifest or reinstall.
Once the package is installed locally (add it once with npm install --save-dev bmad-plus, then use npx --no-install bmad-plus ...), install, doctor, update-policy, uninstall and a plain update run with no network at all.
update-check and update --latest are the only commands that ask npm. With no connection, update-check reports status unknown (reason registry-unavailable, or offline with --offline), exits 0, and an assistant simply carries on with your task.
A stale cached answer is shown as such, with stale: true; it is never presented as current.
Only the very first npx bmad-plus install needs the network, to fetch the package, unless you installed it from a file.
A failed update rolls itself back and prints the exact update --restore <id> command. Receipts stay under .bmad/updates/.
A project lock (.bmad/update.lock) older than 60 minutes, or whose process is gone, is reported by doctor as stale with the file to delete. A lock whose process is provably dead on this machine is taken over by the next install or update.
A damaged manifest is copied to _bmad/.bmad-plus-install.json.corrupt.bak before install replaces it.
An installation from before ownership hashes existed (0.12.2 or earlier) is migrated once by running an explicit newer package: npx --yes bmad-plus@0.13.0 update --yes. The originals are backed up first.
A downgrade is always refused. To go back, use update --restore with the receipt of the update you want to undo.
Update a project where you edited instruction files#
You added your own rules to CLAUDE.md and tweaked one agent file, and you want the newest BMAD+ without losing either.
In your AI assistant
Check whether a newer BMAD+ exists for this project. If so, update it, and list exactly which files were kept because I edited them and why.
What you should get The assistant runs update-check, then update --latest --yes with your approval. The command prints a plan such as Planned changes: N files (R no longer shipped, removed with backup); preserved conflicts: 2. and one line per conflict: CLAUDE.md: preserved (local-instructions). and <agent file>: preserved (modified-managed-file). Those two files are untouched; everything else is updated after a backup, and the receipt path under .bmad/updates/ is reported so the update can be undone with update --restore.