BMAD+ · Documentation
What BMAD+ is, what each pack and agent does, every command and file, and step-by-step guides. Start with the quick guide below or pick a topic.
What BMAD+ is and the ideas behind it: agents, skills, packs and memory, and how they fit together.
7 pages
What each pack adds, who needs it and how to install it.
11 pages
Each agent in detail: its role, when to call it and the skills it brings.
2 pages
Every command, option, file and setting, with exact syntax.
22 pages
Step-by-step walkthroughs for common jobs, from installation to updates.
6 pages
What stays on your machine, what can leave it and how to check it.
2 pages
Short answers to what newcomers ask, and what to do when something fails.
3 pages
Start with a small task in your own project. This guide shows what to run in the terminal, what to ask your AI assistant and how to keep BMAD+ up to date.
You need Node.js 20 or newer and an AI coding tool you already use. BMAD+ supplies project instructions, roles and workflows; your tool supplies the model and execution permissions.
Use a terminal in the repository you want to work on, then check your Node.js version. Keep your usual version control workflow.
node --versionThe command should report v20 or newer. Install or update Node.js separately if needed.
Run the installer. Select the adapters for the AI tools you use and the packs your project needs. Core contains Atlas, Forge, Sentinel and Nexus.
npx bmad-plus@0.23.1 installThe installer creates the agent instructions, shared project spine and selected tool adapters. Optional packs may need additional runtimes or API access.
Open or restart your AI coding assistant in this project so it can load its adapter and AGENTS.md. Ask it to show the installed agents and workflows.
bmad-helpThere is no extra BMAD+ initialization command after installation. bmad-help is a message to the assistant, not a terminal command.
Describe your goal, constraints and expected result. For a new idea, start with Atlas. For an existing code change, start with Forge.
Atlas, help me define a small invoicing app for freelancers. Ask about the users, identify the first useful workflow and write a brief with acceptance criteria.Review the brief before asking Forge to implement one story. A clear deliverable makes progress easier to verify.
Ask Sentinel to check the change against its acceptance criteria. Ask for test evidence and a short handoff so the next session can continue.
Sentinel, review this change against the acceptance criteria. Check the main success and failure paths, report remaining issues and summarize what the next session needs to know. If the BMAD+ CLI is available, seal the scope with bmad-plus review scope, apply the rules in its checklist, quote the code of every finding, account for every selected file, then report what bmad-plus review gate answers.Read the changes and test results. The assistant follows the permissions and capabilities of its host tool.
Replace the project details with your own. These are conversation starters, with a clear output to review.
Use after you have described the users and the problem.
Nexus, plan the first usable release of my appointment-booking app. Have Atlas define scope, Forge propose the smallest implementation and Sentinel define acceptance checks. List dependencies and stop at the plan review before implementation.Expected result: a prioritized plan with a small first story and explicit review points.
Include the failing behavior, steps to reproduce and any relevant error output.
Forge, investigate why saving an edited invoice creates a duplicate. Reproduce the issue, trace the cause and propose the smallest fix. Add a regression check for the real failure, then ask Sentinel to review the affected flow.Expected result: a reproduced failure, a focused fix and evidence that the regression is covered.
Use with the optional Design pack installed. Atelier asks its questions first, then follows checkable rules.
Atelier, run the design read for the invoice list of my app, build the screen, and end with the pre-flight verdict.Expected result: the recorded design read, the screen with every state covered, and the pre-flight verdict quoted as the last line.
Use at the start of a later session in the same project; no optional pack is required.
Read AGENTS.md and the available project memory. Summarize the last verified state, open decisions and the next unfinished task. Distinguish released features from local candidates, and automated checks from human acceptance. Check that the notes still match the code before continuing.Expected result: a short, evidence-based restart. Project notes are useful context and still need to be checked against the current work.
Use when your host supports parallel agents and the tasks do not write to the same files.
Nexus, split the approved work into independent tasks. Give each role a scope, owned files and a definition of done. Use parallel agents only if this host supports them; otherwise run the tasks sequentially. Integrate the results and have Sentinel check the whole user flow.Expected result: bounded assignments, explicit dependencies and one integrated review. Parallel execution comes from the host tool.
Use when a version reaches your test environment and someone must check it on screen.
Sentinel, write the acceptance recipe for this delivery on our test environment. One step per gesture, one verifiable fact per line, on-screen labels quoted from the code, and mark the steps that write for real. Build the page, then tell me the link, how long it takes and what I must not skip. Use disposable test data when possible, name the exact folder and files each command changes, and keep automated evidence separate from the person’s answers. Before handing the page over, build it with uat build, check the guarantees it lists, play the essential pass yourself in a real browser — start, tick, type a remark, reload, everything back — and tell me which checks ran.Expected result: a page a non-technical person can play, and a run the agent reads back to classify every failure before anything is fixed.
Use before ending a session, with the optional Memory pack installed.
Zecher, update this project’s memory from the changes and checks we actually completed. Separate implemented, tested, published and still pending work. Record decisions and useful evidence, archive superseded notes without deleting them, and write a short prompt for the next session. Keep project memory local and exclude secrets.Expected result: a concise current context, a dated session handoff and a restart prompt that identifies the next unfinished task.
Use when a person has completed or stopped an acceptance run.
Sentinel, read the latest acceptance run and compare its fingerprint with the current recipe. Ask what actually happened when answers and evidence disagree. Classify failures before proposing fixes, verify writing steps read-only, and distinguish human observations, automated checks and any explicit risk decision by its named owner. Never mark an unperformed step as passed.Expected result: a clear verdict, evidence for confirmed writes and a short list of checks still requiring action.
Run these commands from the installed project. The checks below use an already available CLI. If npx --no-install cannot find it, use the explicit versioned command shown below.
Compare the installed release with npm. The result includes installedVersion, latestVersion, status, updateAvailable and canAutoApply.
npx --no-install bmad-plus update-check --refresh --jsonThis explicit command downloads the documented CLI and checks your project. On 0.12.2 or earlier, use the migration command in the next paragraph to add update awareness.
npx bmad-plus@0.23.1 update-check --refresh --jsonThis command checks npm again and asks for confirmation of the exact target version. Review the report, including any preserved custom files.
npx --no-install bmad-plus update --latestUse the versioned CLI once. This confirmed migration backs up existing replacements because older installations do not have complete ownership hashes.
npx --yes bmad-plus@0.23.1 update --yesEnable this only when you want the project to apply eligible releases in the stated semantic-version range. The CLI still checks runtime compatibility, file ownership and the policy. Use notify to return to notifications.
npx --no-install bmad-plus update-policy --mode auto --range "^0.23.1"npx --no-install bmad-plus update-policy --mode notifyUpdate receipts and backups live in .bmad/updates/. To restore an update, replace RECEIPT_ID with its actual receipt identifier. Restoration checks the backups and refuses to overwrite subsequent local edits.
npx --no-install bmad-plus update --restore RECEIPT_ID --yesThese notes describe the release verified on npm. The guide, install command and release feed refer to that same publication.
v0.23.1 ·
The documentation site is rebuilt in four languages with seven videos. Several commands now behave exactly as their pages say: refusals read the same everywhere, a workspace review starts from HEAD, and the config file is plain YAML. Installing and updating work as before.
Release historySelected recent releases, dated by their actual npm publication. Summaries describe changes delivered in each release. The package page provides the wider version history.
v0.23.1 ·
The documentation site is rebuilt in four languages with seven videos. Several commands now behave exactly as their pages say: refusals read the same everywhere, a workspace review starts from HEAD, and the config file is plain YAML. Installing and updating work as before.
v0.23.0 ·
A pack now declares the questions it needs answered before it acts, and Nexus can run a swarm of sub-agents, a simulated panel or a jury, within a budget you set. Atelier, the design engine, joins as the tenth pack. Installing and updating work as before.
v0.22.0 ·
BMAD+ now declares every way it sends data or starts a process, and its CI refuses anything undeclared. The recipe page and the SEO report load nothing from other sites, OSINT calls are HTTPS-only, and Shield gains an evidence-bound assurance case and an AI processing register. Nothing changes in how you install or update.
Confirm that the assistant is open in the installed project, that you selected its adapter and that AGENTS.md and .agents/skills/ exist. Start a fresh session and ask it to read those instructions. Each host has its own rules for loading project instructions.
No. bmad-help, autopilot and parallel are conversation instructions for your AI assistant. Terminal commands start with the BMAD+ CLI, as shown in the terminal examples above.
That result does not establish the latest published version. Continue your project work and repeat the check when registry access is available. An unavailable check does not authorize changing the update policy.