Every folder and file BMAD+ creates in a project and on your machine, which command creates it, and whether it is yours to edit, BMAD+’s to manage, or state to leave alone.
BMAD+ writes into a handful of well-named places, and nothing else. Knowing which is which answers the three practical questions: what can I edit, what should I commit, and what is removed if I uninstall. This page maps them all.
Ownership is recorded, not guessed. At install, BMAD+ stores a content hash for every file it copies under .agents/ and for _bmad/module.yaml and _bmad/module-help.csv: that list is the file inventory in the manifest. A file whose hash still matches is BMAD+’s and is refreshed by update and removed by uninstall. A file you changed, or one BMAD+ never shipped, is yours: update preserves it and reports a conflict, and uninstall keeps it. Your settings, your memory and the deliverables in _bmad-output/ are never in the inventory.
Every location, who creates it, and whether you edit it
Generated from the registry. If you edit one, BMAD+ keeps your version and stops refreshing it. See the adapters page.
.agents/skills/
install, update
No: BMAD+ owns it
One folder per agent (agent-*), per pack (pack-<name>) and per skill (bmad-plus-*, dev-studio, design, ...). Edited files are preserved as conflicts.
.agents/data/role-triggers.yaml
install, update
No: BMAD+ owns it
The auto-activation rules for agent roles.
.agents/memory/
install with the Memory pack; agents write into it
Yes
decisions.md, lessons.md, patterns.md, context.md, a sessions/ folder and a .brain-link pointer to the brain in use. Existing files are never overwritten, and uninstall keeps the folder.
_bmad/config.yaml
install
Yes
Your settings; see the configuration page. Kept by uninstall.
_bmad/module.yaml, _bmad/module-help.csv
install, update
No: BMAD+ owns it
Module description and help index, tracked in the inventory.
_bmad/.bmad-plus-install.json
install, update
Never by hand
The manifest: version, packs, tools, language, execution mode, adapter fingerprints and the file inventory. If it cannot be read, install copies it to .bmad-plus-install.json.corrupt.bak before repairing it.
_bmad/update-policy.json
update-policy (when you save a policy)
Through the command
Absent means the default policy: notify. An invalid file makes the update commands refuse to run.
Design briefs and reviews, Dev Studio reports (<workflow-id>.md), OSINT dossiers, and packaged agents. A brief written by intake render carries an ownership line and is rewritten by the command: edit the answers, not the brief.
.bmad/update-check.json
update-check
Never by hand
A 24-hour cache of the last registry answer, with a retry delay after a failure. Safe to delete: it is rebuilt.
.bmad/update.lock
install, update (while running)
Only when stale
Prevents two installs or updates at once. doctor says when it is stale (owner gone, or older than 60 minutes) and the message names the file to delete.
.bmad/updates/<receipt-id>/
update
Never by hand
receipt.json and backups/ of one update. They are what update --restore <receipt-id> reads, so keep them as long as you may want to go back.
.bmad/venv/<pack>/
install --provision-python
Never by hand
The isolated Python environment of a pack that needs one (SEO).
.bmad/memory/
mem commands
Never by hand
journal.ndjson, pattern-scores.json and the promotion and outcome logs: the memory journal.
install does not edit .gitignore: whatever you do not ignore will show in git status. The choice is yours; the table above gives the facts to decide with. In the recorded acceptance run, the demo project already ignored the installed paths, and git status --short stayed empty after the install.
Worth sharing with the team: _bmad/config.yaml (shared behaviour), .agents/memory/ (shared decisions and lessons), the deliverables in _bmad-output/, and _bmad/update-policy.json if the policy is a team rule.
Reproducible from the package, so a team may prefer to ignore them: .agents/skills/, .agents/data/, the generated adapter files. Whoever clones the project then runs install once.
Local state that means nothing on another machine: .bmad/ and .bmad-plus/.
Note· This is a suggestion
The split above follows how each location is produced and used; BMAD+ itself imposes no version-control policy.
Files byte-identical to what BMAD+ ships under .agents/skills/ and .agents/data/, including skills copied from the Design package
.agents/memory/, _bmad/config.yaml, _bmad-output/, any file you edited, any file BMAD+ did not ship
The module files, the install manifest, and the adapters that still carry the install marker and a matching fingerprint (AGENTS.md, CLAUDE.md, ...)
.bmad/, .bmad-plus/ (run state and receipts), and ~/.bmad-plus/brain
Folders that end up empty are removed; nothing is deleted recursively
Anything under a symbolic link or junction: uninstall refuses to touch linked paths
Uninstall in practice
$ npx bmad-plus uninstall --yes --directory .\demo-appT BMAD+ Uninstaller• BMAD+ v0.23.0 (installé le 2026-10-18)• Packs sélectionnés: core, design— La mémoire, les réglages et les fichiers inconnus ou modifiés ont été conservés.# The line giving the number of removed items is left out on purpose: the first recorded run, which exposed a bug that left the Design skills behind, printed a count that no longer applies after the fix.
Output captured from a real run. Source: Captured during two 0.23.0 acceptance runs, 2026-10-18 (header lines, then the expectation of step 7); the installer ran in French
Clearing local state without losing anything that matters#
The project folder is cluttered after months of updates and swarm runs, and you want to know what is safe to delete.
In your AI assistant
List what is under .bmad and .bmad-plus in this project, say what each item is, and tell me which of them I can delete without losing project memory, settings or the ability to restore an update.
What you should get A faithful answer separates three groups. update-check.json is a cache and is rebuilt on the next check. updates/<receipt-id>/ holds the backups that update --restore needs, so delete only receipts you will never roll back to. update.lock is deleted only when doctor reports it as stale. .bmad/memory/ holds the event journal and the outcome records that mem recall and mem observe read, and swarm/runs/ and nexus/runs/ are the evidence of past runs: delete them only if you no longer need that history or that evidence. The Markdown project memory lives in .agents/memory/ and the settings in _bmad/config.yaml, neither of which is touched.