Every key of _bmad/config.yaml: execution mode, the four checkpoints, the uat block and the swarm budget. Defaults, who reads each key, and what changing it does.
_bmad/config.yaml is the one file where a project tells BMAD+ how to behave: which language to use, whether agents run one at a time or under the Nexus orchestrator, where the agents must stop and wait for you, how human acceptance recipes are handled, and how many sub-agents a swarm may use. bmad-plus install creates it; you may edit it by hand. This page lists every key it writes.
Note· Who reads this file
The command line itself reads only a few values: the swarm block (validated by bmad-plus swarm), five text keys used by bmad-plus studio, and communication_language for the language of an acceptance page built by bmad-plus uat. Everything else is read by the agents: their skill instructions tell them to open this file and follow it. That is why a changed checkpoint takes effect the next time an agent starts a pipeline, with no command to run.
The file after install --yes --lang fr in a folder named demo-app, replayed with the 0.23.0 package. The writer quotes string values with single quotes, and user_name falls back to your system user name, then to Developer
The values for user_name, communication_language and project_name come from the wizard or the folder; the rest are the defaults shown. uat.environment holds name: "TEST" and the address when you typed a test environment URL in the wizard.
wizard answer, else your system user name, else Developer
CLI (studio) and agents
The name agents use to greet you. Must be a non-empty text for studio.
communication_language
--lang language name, else your system locale if supported, else English
CLI (studio, uat) and agents
Language agents answer in. uat build opens the acceptance page in it.
document_output_language
same as communication_language
CLI (studio) and agents
Language of the documents agents write (briefs, PRD, reports).
output_folder
_bmad-output
CLI (studio) and agents
Where agents put their deliverables. For studio, the path must be relative to the project.
project_name
name of the project folder
CLI (studio) and agents
The project name used in documents.
execution_mode
manual
Agents, through their skill instructions
manual: you call the agents. autopilot: Nexus runs Discovery, Build and Ship. hybrid: autopilot with frequent checkpoints. Set at install with --mode.
auto_role_activation
true
Agents, through their skill instructions
true: an agent may switch role when the context calls for it, after announcing it. false: roles change only when you ask.
parallel_execution
true
Agents, through their skill instructions
true: the Parallel Supervisor may run independent tasks side by side. false: sequential only.
checkpoints.discovery
require_approval
Agents, through their skill instructions
Stop after the product brief, PRD and UX review.
checkpoints.architecture
require_approval
Agents, through their skill instructions
Stop after the architecture, before any code.
checkpoints.story
require_approval; notify_only when installed with --mode autopilot
Agents, through their skill instructions
Applied after each completed story.
checkpoints.delivery
require_approval
Agents, through their skill instructions
Applied at the final delivery. With uat.mode: gate, it also waits for a passing uat gate.
uat.mode
advisory
Agents, through their skill instructions
advisory: build and offer the acceptance page, never block. gate: the delivery waits for a passing gate. off: no recipe, and the delivery report says so. A missing uat block means advisory.
uat.granularity
delivery
Agents, through their skill instructions
delivery: one recipe per delivery. story: the page is built and delivered immediately, story by story.
uat.environment
name and url empty, or TEST and your URL
Agents, through their skill instructions
The test environment the recipe is played on.
uat.page_budget
max_steps: 15, max_minutes: 30
Agents, through their skill instructions
Size target for a recipe page: at most this many steps and minutes for the tester.
uat.dir
_bmad-output/uat
Documentation of the location; bmad-plus uat takes it from --dir
Folder of the recipe specs, pages, results and triage. Its default is the same value.
swarm.budget
26
CLI (swarm) and agents
How many sub-agents one swarm run may use before the host must ask you. Integer from 1 to 1000.
swarm.wave
10
CLI (swarm) and agents
How many sub-agents are launched together. Integer from 1 to 1000.
swarm.media_credits
ask
CLI (swarm) and agents
The only accepted value is ask: paid image, video or audio generation is never covered by a budget, the assistant asks every time.
A checkpoint is a place in the autopilot pipeline where the orchestrator either stops, tells you and moves on, or just moves on. Each of the four keys takes one of three values.
Checkpoint values
Value
Behaviour
require_approval
Stop. Present a reviewable checkpoint and wait. If an earlier authorisation of yours already covers the concrete next action, it is not asked again. An outside notification needs a configured channel and your authorisation.
notify_only
Report progress in the session and continue.
auto
Continue automatically and log it for the audit trail.
Note· Installing with --mode autopilot
The only checkpoint that depends on the mode at install time is story: it is written as notify_only for autopilot and as require_approval otherwise. Later edits of execution_mode do not rewrite the checkpoints; change them yourself.
You trust the pipeline up to the finished build and want to approve only what ships.
In your AI assistant
In _bmad/config.yaml, set execution_mode to autopilot, set the discovery, architecture and story checkpoints to notify_only and keep delivery on require_approval. Then show me the edited block.
What you should get The assistant edits the file so that it reads execution_mode: autopilot and the checkpoints discovery, architecture and story are notify_only, delivery is require_approval. At the next autopilot, Nexus reports at the first three points and keeps going, and stops at delivery with a checkpoint to review.
The swarm block is the one part the CLI enforces. A missing block, or a missing key, means the defaults: 26 sub-agents per run, 10 per wave. When bmad-plus swarm init is asked for more units than swarm.budget and --approved is absent, it writes nothing and exits with code 2, so a human decides. Paid media generation is outside any budget.
A panel of 30 simulated buyers was refused with “needs approval” because the budget is 26, and you decide to accept panels up to 50 without asking each time.
In your AI assistant
In _bmad/config.yaml set swarm.budget to 50 and leave wave and media_credits as they are. Then re-run the same swarm init without --approved.
What you should get Because 30 is no longer above the budget, init does not stop with exit code 2: it creates the run and prints the panel line (for example “panel of 30 units, budget 50”). A request for 60 units would still be refused until you pass --approved.
Existing keys win: running install again never overwrites a value you changed.
Missing keys are added with their defaults, including missing keys inside a block such as uat or swarm. This is how a project installed with an older version gains the newer blocks.
Answers you give explicitly replace the stored value: the wizard fields (name, communication language, execution mode), --mode, and a test environment URL.
When anything changes, the file is rewritten by a YAML writer under the header “BMAD+ Project Configuration”. Comments you added by hand are not kept in that case.
If the file is not a YAML mapping, install leaves it untouched and warns: “_bmad/config.yaml could not be parsed; it was left unchanged.”
uninstall keeps this file, because it holds your settings.
_bmad/config.yaml: swarm.budget must be an integer from 1 to 1000.
budget (or wave, same message with its name) is not a whole number in range.
Write a plain integer, for example budget: 50.
_bmad/config.yaml: swarm.media_credits must be "ask".
Any other value was written.
Set media_credits: "ask" or delete the line.
_bmad/config.yaml: swarm has an unknown key "<name>".
A key other than budget, wave, media_credits is in the block.
Remove it or fix the spelling.
_bmad/config.yaml is not valid YAML: …
The file cannot be parsed.
Fix the indentation or quoting shown in the message.
_bmad/config.yaml: user_name must be a nonempty string
studio requires its five text keys (user_name, communication_language, document_output_language, output_folder, project_name) to be non-empty strings when present.
Give the key a text value or delete it to fall back to the default.