# Using BMAD+ in a team

> What to commit and what to keep local, which settings to agree on, one adapter per teammate on a shared spine, a safe update policy, CI gates and onboarding.

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

BMAD+ documentation › [Guides](https://bmad-plus.rochetta.fr/docs/guides/) › Using BMAD+ in a team

BMAD+ lives in the project, so a team shares it the way it shares any other part of the repository: by deciding what is versioned, what is configured the same way for everyone and who changes it. This page lists those decisions and the facts that make each one safe: ownership hashes, preserved edits, an update policy per project, adapters generated from one spine. It is for tech leads and for anyone who has to onboard colleagues who use different AI tools. Where a choice is a matter of taste rather than a fact, the text says so.

<a id="what-to-version"></a>
## What to version and what to keep local

**The files BMAD+ creates, and who they belong to**

| Files | Nature | Considerations |
| --- | --- | --- |
| `AGENTS.md`, adapter files, `.agents/skills/`, `.agents/data/` | Generated and copied by the installer; hashed in the manifest. | Committing them gives every teammate the same instructions without running the installer. Not committing them means each person installs the same version. Both work; pick one. |
| `_bmad/config.yaml` | Your settings: language, execution mode, checkpoints, uat, swarm. Written once and merged, never overwritten. | The natural file to share, since it holds the team’s conventions. |
| `_bmad/update-policy.json` | Written by `update-policy` when you change the policy. | Share it if the team wants one policy; it names the allowed version range. |
| `_bmad/review-rules.yaml` and its documents | Project review rules. | Share it: a findings file answers exactly one rule set, so the team should review against the same one. |
| `_bmad/.bmad-plus-install.json` | The manifest: version, packs, tools, a SHA-256 for each installed file. | It must stay consistent with the files it describes, so version it together with them or neither. |
| `.agents/memory/` | Decisions, lessons, patterns, context, handoffs. | Version it if the memory is the team’s. Install and update never overwrite these files. |
| `.agents/memory/.brain-link` | The absolute path of the brain linked on one machine. | Machine-specific: do not share it. |
| `_bmad-output/` | Deliverables: briefs, PRDs, review evidence, acceptance results. | Usually versioned in part: briefs, PRDs, triage and results are evidence worth keeping. |
| `.bmad/`, `.bmad-plus/` | Update cache and receipts, memory journal, swarm and Nexus run state. | Local state. The update lock and receipts concern one checkout. |

<a id="shared-conventions"></a>
## Conventions worth agreeing on

**Settings and their effect on the team**

| Setting | Where | Why agree on it |
| --- | --- | --- |
| Packs | `install --packs` | The packs define which agents exist. `--packs` and `--tools` add to a previous installation, so a pack can be added later without losing anything. |
| `communication_language`, `document_output_language` | `_bmad/config.yaml` | The language agents speak and the language of the deliverables. |
| `execution_mode` | `_bmad/config.yaml` | `manual`, `autopilot` or `hybrid`: how much the team lets Nexus run on its own. |
| `checkpoints` | `_bmad/config.yaml` | Who approves what: `discovery`, `architecture`, `story`, `delivery`, each `require_approval`, `notify_only` or `auto`. |
| `uat.mode` and `uat.environment` | `_bmad/config.yaml` | `advisory`, `gate` or `off`, and the test environment a recipe targets. |
| `swarm.budget` and `swarm.wave` | `_bmad/config.yaml` | How many sub-agents a run may use before someone must say yes (26 and 10 by default). |
| Review rules | `_bmad/review-rules.yaml` | The same rule set for every reviewer, human or agent. |
| Update policy | `_bmad/update-policy.json` | See the next section. |

<a id="adapters"></a>
## One spine, one adapter per teammate

All adapters are generated from the same registry as `AGENTS.md`, so a teammate on Cursor and one on Claude Code get the same roster and rules; only the file format differs. `--tools` takes several ids at once (`--tools claude-code,cursor`), `all`, or `none`. The installer detects tools from their folders (`.claude/`, `.gemini/`, `.cursor/`, `.codex/`, `.opencode/`, `.aider.conf.yml`) when you do not pass `--tools`; `--yes` with no detected tool writes no adapter. A BMAD+ adapter that you edited is preserved. An instruction file you wrote yourself is preserved by an interactive install and by `update`; `install --yes` first copies it to `<file>.bak` and then replaces it. Legacy installer files are backed up as `<file>.bak`.

**Adapters**

| Tool id | File written | Detected from |
| --- | --- | --- |
| `claude-code` | `CLAUDE.md` | a `.claude/` folder |
| `gemini-cli` | `GEMINI.md` | a `.gemini/` folder |
| `antigravity` | `GEMINI.md` (shared with gemini-cli) | a `.gemini/antigravity/` folder |
| `cursor` | `.cursor/rules/bmad-plus.mdc` (always applied) | a `.cursor/` folder |
| `codex-cli` | `.codex/AGENTS.md` | a `.codex/` folder |
| `opencode` | `.opencode/AGENTS.md` | a `.opencode/` folder |
| `aider` | `CONVENTIONS.md`; add `read: CONVENTIONS.md` to `.aider.conf.yml` or run `/read CONVENTIONS.md` in Aider | an `.aider.conf.yml` file |

A teammate who adds a tool later runs the installer again with that tool: the run keeps what is already installed and adds the missing adapter. `--tools none` installs agents, skills and memory without touching any tool configuration, which is the right option for a project whose `CLAUDE.md` or `AGENTS.md` is maintained by hand.

<a id="update-policy"></a>
## A safe update policy

The default is notification: the generated instructions ask the assistant to run `update-check` once per session and to report. Nothing is applied. For a team, the practical pattern is one person (or one CI job) who decides when to move, applies `update`, reviews the report and commits; the others get the result with their next pull. If the team wants updates to flow without a human, `auto` needs an explicit semver range and several guards: the registry result must be fresh, the managed files unchanged, the installation hash inventory complete, the target version exactly the one recorded in the command, and the Node requirement met. Offline, stale or failed lookups never allow an automatic update.

**Reading and setting the policy**

```text
$ npx bmad-plus update-policy
Update policy: notify; channel=latest; range=none; prereleases=false
$ npx bmad-plus update-policy --json
{"policy":{"mode":"notify","channel":"latest","allowedRange":null,"allowPrerelease":false,"registry":"https://registry.npmjs.org/"},"changed":false}
$ npx bmad-plus update-policy --mode auto --range "^0.23.0"
Update policy saved: auto; channel=latest; range=^0.23.0; prereleases=false
$ npx bmad-plus update-policy --mode notify
Update policy saved: notify; channel=latest; range=^0.23.0; prereleases=false
$ npx bmad-plus update-check --offline --json
{"schemaVersion":1,"installedVersion":"0.23.0","runningVersion":"0.23.0","latestVersion":null,"targetVersion":null,"channel":"latest","status":"unknown","checkedAt":null,"source":"none","stale":false,"updateAvailable":null,"releaseEligible":false,"versionEligible":false,"canAutoApply":false,"engineCompatible":null,"engines":{},"reason":"offline"}
```

Output captured from a real run. Source: Replayed on a test server on 2026-10-18 with the 0.23.0 source (tools/cli/bmad-plus-cli.js) in a throwaway Git project

- `off` stops every lookup. `notify` (default) reports. `auto` needs `--range`; add `--allow-prerelease` or `--stable-only` to control prereleases. The registry is fixed to `https://registry.npmjs.org/`.
- An update preserves files changed since their recorded hash and reports them; a conflict blocks the automatic path. Files a new version no longer ships are removed after a restorable backup. Each applied update writes `.bmad/updates/<receipt-id>/` with `receipt.json` and `backups/`; `update --restore <receipt-id> --yes` returns to it and refuses to overwrite later local edits.
- An installation older than 0.13 (without file hashes) cannot be updated automatically; one explicit migration, `npx --yes bmad-plus@0.23.1 update --yes`, backs up what it replaces.
- `install` never changes the installed version: a downgrade is refused and an upgrade goes through `update`. If two teammates installed different versions, the one with the older version runs `update`.
- A lock `.bmad/update.lock` protects the project during an update (considered stale after 60 minutes or when its owner is dead); `doctor` reports a lock that is not its own.

<a id="ci-and-gates"></a>
## CI and gates

BMAD+ installs no Git hook and no lifecycle hook in your project, because an instruction can be skipped. What a team can enforce, it enforces with its own CI, using exit codes that are designed for it.

**Checks a team can wire into CI**

| Check | Command | Fails when |
| --- | --- | --- |
| Installation integrity | `bmad-plus doctor --json` | Exit 1 on any error (a missing required file, for instance). Modified files are warnings. |
| Update awareness | `bmad-plus update-check --json` | Exit 1 for an invalid runtime, installation or policy; an unreachable registry is `unknown`, not a failure. |
| Review gate on pull requests | The recipes of `docs/recipes/ci-review/` | The review is incomplete (exit 2) or has open findings (exit 1). |
| A release has an accepted human run | `uat-release-gate.mjs` from the uat skill | No finished run, another revision, an unclassified failure, an unconfirmed write (exits 1 to 3; 4 means the gate could not run). |
| A version has a recipe at all | `uat-spec-present.mjs` | No recipe names the version in `package.json`. |
| A team intake file is valid | `bmad-plus intake check FILE` | Exit 1 with every problem listed. |
| Shield evidence | `bmad-plus assurance verify` and `ai-register check` | `assurance verify` exits 1 when a claim is unsupported; `ai-register check` only warns. |

<a id="onboarding"></a>
## Onboarding a colleague

1. **Pull the repository and check the installation** If the generated files are committed, `doctor` already works. If not, run the installer with the team’s pack list, then `doctor`.

   ```sh
   npx bmad-plus@0.23.1 install --packs core,memory --tools claude-code
   npx bmad-plus@0.23.1 doctor
   ```
2. **Add your own tool** Install with your tool id; the existing files are kept and your adapter is added.

   ```sh
   npx bmad-plus@0.23.1 install --packs core,memory --tools cursor
   ```
3. **Read the spine, then ask the assistant** Open `AGENTS.md` for the roster and the team’s rules, then type `bmad-help` in the chat. Read the settings in `_bmad/config.yaml` so you know which checkpoints will stop and ask you.
4. **Link the memory to your machine** With the Memory pack, install detects a brain on your machine (`BMAD_PLUS_BRAIN`, a `_brain/` folder in a parent directory, `~/.bmad-plus/brain/`, then a non-empty `~/.claude/memory/`) and records it in `.agents/memory/.brain-link`. That file is yours alone; the project memory files around it are the team’s.

<a id="governance"></a>
## Governance notes for teams

- Approvals: if the team wants a person to approve architecture and delivery, keep `require_approval` on those checkpoints. Autopilot with `auto` everywhere is a deliberate choice, not a default.
- Budget: a swarm larger than `swarm.budget` is refused until a human says yes; paid media generation is asked for every time. Nobody should pass `--approved` on behalf of someone else.
- OSINT: researching a named person requires a recorded purpose and legal basis, per run. In a team this means a person who owns that decision. See the trust page.
- Shield: the reports are AI-generated and carry a "not legal advice" marking; a compliance decision stays with a qualified person.
- Secrets: API keys belong in the environment of each person or of CI, never in the repository. The review redaction floor and the acceptance-note redaction mask common credential shapes; they do not replace not committing secrets.
- Ownership: every file BMAD+ wrote is hashed. A file a teammate edited is kept by update and uninstall and reported by `doctor` as modified (a warning), so local customisation is visible, not silently overwritten.

<a id="example-team-conventions-review"></a>
### Audit the team’s BMAD+ conventions

Use when a new tech lead takes over, or before onboarding a colleague. The assistant only reads; nothing is changed.

**In your AI assistant**

```text
Read _bmad/config.yaml, _bmad/update-policy.json if it exists, _bmad/review-rules.yaml if it exists and the manifest _bmad/.bmad-plus-install.json. Summarise in a table: installed version, packs, tools, execution mode, each checkpoint behaviour, uat mode, swarm budget, update policy mode and range. Then list what a new teammate would need to do to get the same setup, and flag any setting that looks inconsistent with the others. Change nothing.
```

**What you should get** A table of the real values read from the files, an onboarding list (install with the same packs, add your tool, read the spine) and a short list of inconsistencies, for example `execution_mode: autopilot` with every checkpoint on `auto`. No file is modified.

**See also**

- [Your first hour with BMAD+](https://bmad-plus.rochetta.fr/docs/guides/first-hour/)
- [Install, update, uninstall](https://bmad-plus.rochetta.fr/docs/guides/install-lifecycle/)
- [Reference: config.yaml](https://bmad-plus.rochetta.fr/docs/reference/config-yaml/)
- [Reference: adapters](https://bmad-plus.rochetta.fr/docs/reference/adapters/)
- [Trust and ownership](https://bmad-plus.rochetta.fr/docs/security/trust-and-ownership/)
- [Data handling](https://bmad-plus.rochetta.fr/docs/security/data-handling/)

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

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