BMAD+ · Documentation
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 [email protected] 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.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 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 at the start of a later session in the same project.
Read AGENTS.md and the available project memory. Summarize the last verified state, open decisions and the next unfinished task. 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.
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 [email protected] 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 [email protected] 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.13.0"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 --yesThe latest published release makes updates aware of your project’s local changes. The guide and install command refer to the same release.
v0.13.0 ·
Discover published releases, control automatic-update policy and preserve customized agent files.
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.13.0 ·
Discover published releases, control automatic-update policy and preserve customized agent files.
v0.12.2 ·
The SEO package includes the Python scripts and requirements needed by its documented workflow.
v0.12.1 ·
Project memory better recognizes an existing shared brain and records the selected link.
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.