# Project layout

> 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.

Canonical: https://bmad-plus.rochetta.fr/docs/reference/project-layout/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ documentation › [Reference](https://bmad-plus.rochetta.fr/docs/reference/) › Project layout

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.

<a id="map"></a>
## The map

**A project with several packs after some use (folders appear as the commands that create them are run)**

```text
your-project/
├── AGENTS.md                      common spine for every assistant
├── CLAUDE.md, GEMINI.md, ...      one adapter per selected tool
├── .agents/
│   ├── skills/                    agents, packs and skills (agent-*, pack-*, bmad-plus-*, ...)
│   ├── data/role-triggers.yaml    auto-activation rules
│   └── memory/                    project memory (Memory pack)
├── _bmad/
│   ├── config.yaml                your settings
│   ├── module.yaml, module-help.csv
│   ├── .bmad-plus-install.json    install manifest (ownership hashes)
│   └── update-policy.json         only after update-policy
├── _bmad-output/                  deliverables written by agents and commands
│   ├── discovery/  build/         created by install
│   └── uat/  review/  assurance/  design/  dev-studio/  osint-reports/  ready-to-integrate/
├── .bmad/                         local state: caches, locks, receipts, journals, Python environments
├── .bmad-plus/                    durable run state: swarm/ and nexus/
├── docs/                          created empty by install
└── backups/                       only with the Backup pack
```

<a id="who-owns-what"></a>
## Who owns what

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**

| Path | Created by | Yours to edit? | Notes |
| --- | --- | --- | --- |
| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONVENTIONS.md`, `.cursor/rules/bmad-plus.mdc`, `.codex/AGENTS.md`, `.opencode/AGENTS.md` | `install`, refreshed by `update` | Not by design | 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. |
| `_bmad/review-rules.yaml`, `_bmad/assurance/`, `_bmad/ai-processing-register.yaml` | You, or `assurance init` and `ai-register init` | Yes | Your project’s own review rules, assurance cases and AI integration register. None exists until you create it. |
| `_bmad-output/discovery/`, `_bmad-output/build/` | `install` (empty) | Yes | Where the product brief, PRD, architecture and stories go. Never in the inventory, so never removed. |
| `_bmad-output/uat/` | `uat` commands, agents | Specs and triage: yes. Pages: regenerate | `specs/`, `pages/`, `results/`, `triage/`, `checks/` and `ORDER.md`. Results are what testers produce; do not edit them. |
| `_bmad-output/review/<id>/` | `review` commands | No: evidence | `scope.json`, `checklist.md`, `findings.json`, `findings.anchored.json`, `coverage.json`, `continue.json`, `compare.json` for one review. |
| `_bmad-output/assurance/` | `assurance` commands | No: evidence | The hash-chained ledger (`runs.jsonl`) of an assurance case. |
| `_bmad-output/design/`, `_bmad-output/dev-studio/`, `_bmad-output/osint-reports/`, `_bmad-output/ready-to-integrate/` | Atelier and `intake`, Dev Studio, Shadow, Maker | Yes | 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. |
| `.bmad-plus/swarm/runs/<run-id>/`, `.bmad-plus/swarm/reports/` | `swarm` commands | Never by hand | One folder per swarm run (definition, cards, briefs, answers, tally). The command writes only under this tree. Add replies with `swarm save`. |
| `.bmad-plus/nexus/runs/` | `nexus` commands | Never by hand | The authoritative state of durable task runs. A `.bmad-plus/orchestrator-state.yaml` may sit beside it as a navigation summary only. |
| `backups/` | Backup Manager (Backup pack) | Yes | Timestamped ZIP archives of the project. The Backup pack excludes this folder from its own archives. |
| `~/.bmad-plus/brain/` | `install` with the Memory pack (when no other brain is found), `scan` | Yes | Outside the project, in your home folder: the global brain shared by all your projects. Never touched by `uninstall`. |

<a id="git"></a>
## What to put under version control

`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.

<a id="uninstall"></a>
## What uninstall removes and keeps

**Effect of uninstall**

| Removed | Kept |
| --- | --- |
| 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**

```text
$ npx bmad-plus uninstall --yes --directory .\demo-app
T   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

<a id="examples"></a>
## Example

<a id="example-cli-layout-clean-up-safely"></a>
### 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**

```text
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.

**See also**

- [The configuration file](https://bmad-plus.rochetta.fr/docs/reference/config-yaml/)
- [Adapters](https://bmad-plus.rochetta.fr/docs/reference/adapters/)
- [Install, update, uninstall](https://bmad-plus.rochetta.fr/docs/guides/install-lifecycle/)
- [uninstall](https://bmad-plus.rochetta.fr/docs/reference/cli-uninstall/)
- [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Reference](https://bmad-plus.rochetta.fr/docs/reference/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)