How BMAD+ works

This page explains the machinery in one pass, for anyone who wants to know what happens after npx bmad-plus install before trusting it with a project. BMAD+ is not a program that runs your agents. It is a set of files (instructions, roles, workflows) plus a small command-line tool that keeps records. Your AI coding tool, called the host in these pages, reads the files and does the work with its own model and permissions.

Host-managed execution#

The registry states it as a contract: execution: host-managed, lifecycle_events: not-integrated. In practice this means four things. The host supplies the model, so BMAD+ holds no API key and calls no model. The host supplies the permissions, so a file edit or a shell command is allowed or refused by your tool, not by BMAD+. The host supplies any parallel sub-agents. And nothing runs in the background: there is no daemon, no scheduler and no telemetry.

The vocabulary#

What the installer writes#

Installation copies files into your project and records what it copied. It does not touch your source code, and it does not start anything. The only write outside the project is the global brain of the Memory pack, in your home folder (row ~/.bmad-plus/brain/). The table lists the locations; the later rows appear only when you use the matching feature.

$ npx bmad-plus install --yes --lang en --packs core,design,memory --tools claude-code
●  Selected packs: ⚙️ Core, 🧠 Memory, 🎨 Design
●  Detected IDEs: Claude Code
●  🧠 Global brain created: /home/dev/.bmad-plus/brain
◇  ✅ 6 agents, 9 skills, 5 files copied
◇  ✅ 1 IDE(s) configured
└  BMAD+ is ready! Talk to Atlas to get started 🚀
$ npx bmad-plus doctor
│  98/98 checks passed
│  0 error(s), 0 warning(s)
│  Installed: v0.23.0 | Executing CLI: v0.23.0
│  Ownership inventory: complete
│  Integrations use host-managed execution; host capabilities were not probed.
# Excerpt: the installer guide box and the empty lines were left out, and the home folder is shortened. The counts depend on the packs you choose. The brain line appears only when the Memory pack finds no existing brain.

What runs where#

From a sentence to files#

1. 01

   You write to your host

   You address an agent by name in the chat of your AI tool, in your language.

   In your project terminal

   Atlas, help me define a small invoicing app for freelancers.

2. 02

   The host loads the instructions

   The host reads its adapter file, which points to AGENTS.md. The spine names Atlas and the folder of its SKILL.md. Reading that file is what turns a general assistant into the persona.

3. 03

   The settings are read, then Atlas waits

   The agent reads _bmad/config.yaml (your language, the execution mode, the checkpoint behaviour), greets you and shows its menu of capabilities (for example CB for a product brief, MR for market research). Atlas waits for your choice: a number, a code or a phrase that matches one.

4. 04

   A role is chosen

   Atlas has two roles, Analyst (research, discovery) and Product Manager (planning, product briefs, PRD). A keyword such as "market" or "PRD", or a situation such as a new project, switches the role, and the agent says so. The execution mode and the checkpoints then decide whether it stops and asks or goes on.

5. 05

   A deliverable is written

   Once you have chosen, for example CB to create a product brief, the host writes the result to the project with its own permissions, normally in the output folder (_bmad-output/ by default). You review it like any other file.

6. 06

   The CLI keeps the books when needed

   For intake, swarms, reviews or acceptance, the agent calls bmad-plus to validate, count or seal evidence. The CLI answers with files and exit codes, never with opinions.

How roles switch#

The rules live in .agents/data/role-triggers.yaml. Each agent can switch role on three levels, and it announces the change so that you can refuse it.

The announcement reads like "I’m switching to QA mode - financial calculations detected. Say ’skip’ to stay in current mode." Setting auto_role_activation: false in _bmad/config.yaml turns the automatic switching off; you can still ask for a role by name.

Settings and execution modes#

The installer writes _bmad/config.yaml once and keeps your edits on later installs. execution_mode is manual by default: you call each agent yourself. autopilot lets Nexus run the whole pipeline; hybrid is autopilot with frequent checkpoints. Each checkpoint (discovery, architecture, story, delivery) is require_approval, notify_only or auto.

execution_mode: 'manual'
auto_role_activation: true
parallel_execution: true
checkpoints:
  discovery: 'require_approval'
  architecture: 'require_approval'
  story: 'require_approval'
  delivery: 'require_approval'
uat:
  mode: 'advisory'
swarm:
  budget: 26
  wave: 10
  media_credits: 'ask'

Generated files and your edits#

The spine and the adapters are generated from registry.yaml in the BMAD+ source repository, so counts and rosters cannot drift from the declarations. In your project you can still add your own rules to an adapter. The installer records a SHA-256 hash for every file it writes; an adapter or a skill whose hash no longer matches is treated as yours and is preserved by updates and by uninstall.

What BMAD+ deliberately does not do#

• No model runtime: it calls no LLM API, holds no API key for one and runs no agent loop of its own.
• No background process: no daemon, no scheduler, no telemetry exporter, no silent self-update.
• No review engine that guesses: findings the code cannot anchor are reported as such, never repositioned by a model.
• No automatic fix from a review: a review grants no write permission, and human acceptance stays the release gate.
• No IDE extension and no posting to GitHub, GitLab or other forges.