The seven AI tools BMAD+ prepares: the file written for each, how a tool is detected, the shared AGENTS.md spine, and how installs and updates protect instructions you wrote yourself.
Each AI assistant looks for its instructions in a different file. An adapter is that file: a short generated document that tells one assistant about the agents, skills and rules BMAD+ installed. Install writes one adapter per tool you use, plus a common spine, AGENTS.md, so that every assistant sees the same roster and the same rules. This page is for anyone choosing --tools, or wondering what BMAD+ will do to an instruction file that already exists.
Loads CLAUDE.md from the project root by itself; activate an agent by saying its name.
gemini-cli
Gemini CLI
GEMINI.md
.gemini
Loads GEMINI.md from the project root by itself.
antigravity
Antigravity
GEMINI.md (shared with Gemini CLI)
.gemini/antigravity
Reads the same file; the note adds a concurrency rule: coordinate with other agentic tools and never edit the same files at the same time.
cursor
Cursor
.cursor/rules/bmad-plus.mdc
.cursor
A rule with alwaysApply: true in its header, so Cursor always loads it; the spine stays the source of truth.
codex-cli
Codex CLI
.codex/AGENTS.md
.codex
Follows the open AGENTS.md convention; the file relays to the root spine, which is better read directly when both exist.
opencode
OpenCode
.opencode/AGENTS.md
.opencode
Same as Codex CLI.
aider
Aider
CONVENTIONS.md
.aider.conf.yml
Aider does not load convention files by itself: add read: CONVENTIONS.md to .aider.conf.yml, or run /read CONVENTIONS.md in the session.
Gemini CLI and Antigravity point at the same GEMINI.md. When both are selected, one file is written and it is titled for both. Detection is a simple check that the marker exists in the project folder; it says nothing about whether the tool is installed on the machine.
Tools whose marker is found are selected. If none is found, the wizard asks which tools you use.
nothing, with --yes
Detected tools only. With none detected, no adapter is written and the installer says: No AI tool detected; no instruction adapter written. Re-run with --tools <ids> or --tools all to add one.
--tools claude-code,cursor
Exactly these. The list is comma separated.
--tools all
All seven.
--tools none (or skip)
No adapter is written and existing instruction files are left alone. The agents and skills are still installed.
an unknown id
The command stops before writing anything: “Unknown tool ID(s): … Available: claude-code, gemini-cli, antigravity, cursor, codex-cli, opencode, aider, all, none.”
Running install again keeps the tools this installation already owns, whatever you pass now, unless you pass --tools none. So adding a tool never drops another one.
A real install that prepares Claude Code
$ npx bmad-plus install --yes --lang fr --packs core,design --tools claude-code --directory .\demo-app• IDE détectés: Claude Codeo ✅ 5 agents, 9 skills, 4 fichiers copiéso ✅ 1 IDE configuré(s)
AGENTS.md is the spine. It is written whenever at least one tool is selected, and it carries everything: the project context, the roster of agents (with the skills each one drives), the skills folder and auto-activation file, your name and language, the update instructions, the registry facts (pack and agent counts, data-handling flows, cohabitation notes) and the key chat commands. The memory rules (the four guardrails and the four .agents/memory files) are added only when the Memory pack is installed. Each tool file starts with a link to the spine and the tool note from the table, then repeats the same sections, because many tools load only their own file.
Two lines of a generated AGENTS.md
$ Select-String -Path .\demo-app\AGENTS.md -Pattern 'Atelier','Cohabitation'demo-app\AGENTS.md:22:- **Atelier** (Design Engine) — Senior product designer and design engineer: surfaces, tokens, accessibility, audits, redesigns (Design) — drives: design, design-review, redesigndemo-app\AGENTS.md:54:- Cohabitation (Design): Overlaps Sentinel's UX-review role and Dev Studio's Rachel (UX Designer); when this pack is installed its rules govern visual design and accessibility, and the others hand those over.# Long lines were wrapped by the terminal in the recorded run; they are shown joined here.
Output captured from a real run. Source: Captured during the 0.23.0 acceptance run, 2026-10-18 (step 3; Select-String on the AGENTS.md of the demo-app folder)
Every generated file carries the markers AUTO-GENERATED by tools/build/generate-adapters.js — DO NOT EDIT. and BMAD+ installed project configuration. These markers are how BMAD+ later recognises a file as its own. The Cursor rule starts with its YAML header (description, alwaysApply: true), so the markers come right after it.
Install records a fingerprint of each adapter it writes (the file’s content hash, line endings normalised). That fingerprint, kept in the install manifest, is how BMAD+ tells its own untouched file from one you edited.
Preserved and listed as a conflict (reason local-instructions).
written by you, without BMAD+ markers (interactive run)
Preserved, with the same warning.
Preserved, even with --yes.
written by you, without BMAD+ markers, with install --yes
Copied to <file>.bak first, then replaced. An existing .bak is never overwritten: the next copy is .bak.1, then .bak.2.
—
left by an older BMAD+ installer
Backed up to .bak, then refreshed: <file>: backed up to <file>.bak before refreshing.
Same: backed up, then migrated.
the generated file of a BMAD+ source checkout (generator marker, no install marker)
Preserved, with a hint on how to compare it with the package defaults.
Preserved, reason repository-adopted.
Warning·install --yes replaces an instruction file you wrote
Unattended installs cannot ask, so they make a .bak copy and write the BMAD+ version. If your own CLAUDE.md matters, either run install interactively once, or pass --tools none and merge the generated content yourself. update never does this: it always preserves a file it does not own.
doctor reports the state of each adapter as Instruction file: <state>. with the states unchanged (pass), modified, unowned or adopted (warnings), and missing or unreadable (errors). uninstall removes an adapter only when it still carries the install marker and its content hash matches the recorded one; a file you edited stays.
It is text for the assistant to read. BMAD+ installs no hook and no extension in any of these tools: the registry records the integration as host-managed, with lifecycle events not integrated.
It is model-agnostic by contract: Claude, GPT, Gemini and local models are all supported, because the content is plain instructions.
It does not make the assistant run bmad-help, autopilot or parallel: those are phrases you say in the chat.
It tells the assistant to check for a new release once per session with npx --no-install bmad-plus update-check --json, and to apply one only as your update policy allows. That form runs only a local copy: add it once with npm install --save-dev bmad-plus, or use npx bmad-plus update-check --json.
Add Cursor to a project that already uses Claude Code#
BMAD+ is installed with claude-code. A colleague works in Cursor and needs the same agents.
In your AI assistant
Add Cursor to this project’s BMAD+ install without touching the Claude Code setup: run `npx bmad-plus install --yes --tools cursor`, then tell me which files changed.
What you should get--yes is needed when the assistant runs the command, because without a terminal the installer refuses to start; a run in your own terminal would first ask for the language, the packs and your name. The installer keeps claude-code (tools already owned are retained) and writes .cursor/rules/bmad-plus.mdc with alwaysApply: true and a link back to AGENTS.md. CLAUDE.md and AGENTS.md are rewritten only if their generated content differs; a copy you edited is preserved with the “existing project instructions preserved” warning. The manifest now lists both tools.
You appended team conventions at the bottom of the generated CLAUDE.md, then a new BMAD+ version comes out.
In your AI assistant
Update BMAD+ in this project with `npx bmad-plus update --latest --yes`, and list every file the update preserved instead of replacing.
What you should get The plan prints “CLAUDE.md: preserved (local-instructions).” and the receipt records it as a conflict; the update then finishes with “applied partially.” Your additions are untouched. To adopt the new generated text, merge by hand or restore the original and edit again.