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.

What to version and what to keep local#

Conventions worth agreeing on#

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.

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

$ 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"}

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

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.

Onboarding a colleague#

1. 01

   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.

   In your project terminal

   npx bmad-plus@0.23.1 install --packs core,memory --tools claude-code
   npx bmad-plus@0.23.1 doctor

2. 02

   Add your own tool

   Install with your tool id; the existing files are kept and your adapter is added.

   In your project terminal

   npx bmad-plus@0.23.1 install --packs core,memory --tools cursor

3. 03

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

   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.

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.

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.