# BMAD+ documentation — Get started, examples and release notes
> Install BMAD+, start your first agent workflow, try practical prompts and keep your project current. Step-by-step guides and verified published release notes.
Canonical: https://bmad-plus.rochetta.fr/docs/
Language: en
BMAD+ version: 0.13.0
Documentation reviewed: 2026-09-09
Author: Laurent Rochetta
License: MIT
From installation to your first workflow.
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.
- [Get started, step by step](#start)
- [Examples to build on](#examples)
- [Check and apply updates](#updates)
- [What’s new](#news)
- [Release history](#changelog)
- [When something is unclear](#help)
## Get started, step by step
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.
### 1. Open your project folder
Use a terminal in the repository you want to work on, then check your Node.js version. Keep your usual version control workflow.
**In your project terminal**
```sh
node --version
```
The command should report v20 or newer. Install or update Node.js separately if needed.
### 2. Install BMAD+ and choose your tools
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.
**In your project terminal**
```sh
npx bmad-plus@0.13.0 install
```
The installer creates the agent instructions, shared project spine and selected tool adapters. Optional packs may need additional runtimes or API access.
### 3. Start a session in that same folder
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.
**In your AI assistant**
```text
bmad-help
```
There is no extra BMAD+ initialization command after installation. bmad-help is a message to the assistant, not a terminal command.
### 4. Give one role a concrete task
Describe your goal, constraints and expected result. For a new idea, start with Atlas. For an existing code change, start with Forge.
**In your AI assistant**
```text
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.
### 5. Review the result and preserve context
Ask Sentinel to check the change against its acceptance criteria. Ask for test evidence and a short handoff so the next session can continue.
**In your AI assistant**
```text
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.
## Examples to build on
Replace the project details with your own. These are conversation starters, with a clear output to review.
### Turn an idea into a first release
Use after you have described the users and the problem.
**In your AI assistant**
```text
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.
### Fix a bug in an existing project
Include the failing behavior, steps to reproduce and any relevant error output.
**In your AI assistant**
```text
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.
### Coordinate independent work
Use when your host supports parallel agents and the tasks do not write to the same files.
**In your AI assistant**
```text
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.
### Resume without losing decisions
Use at the start of a later session in the same project.
**In your AI assistant**
```text
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.
## Check and apply updates
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.
### Check the published version
Compare the installed release with npm. The result includes installedVersion, latestVersion, status, updateAvailable and canAutoApply.
**In your project terminal**
```sh
npx --no-install bmad-plus update-check --refresh --json
```
### If the CLI is unavailable or the installation is older
This 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.
**In your project terminal**
```sh
npx bmad-plus@0.13.0 update-check --refresh --json
```
### Review and apply an available update
This command checks npm again and asks for confirmation of the exact target version. Review the report, including any preserved custom files.
**In your project terminal**
```sh
npx --no-install bmad-plus update --latest
```
### Migrating from 0.12.2 or earlier
Use the versioned CLI once. This confirmed migration backs up existing replacements because older installations do not have complete ownership hashes.
**In your project terminal**
```sh
npx --yes bmad-plus@0.13.0 update --yes
```
- Notification is the default. A version check does not enable automatic updates. Offline, stale or unavailable registry results mean the latest version is unknown.
- Updates preserve identified customizations. The report may describe a partial application when local files are retained; the installed version alone does not prove every file matches the release.
- After a successful update, ask the assistant to reread AGENTS.md and the relevant skills, or start a fresh session.
- BMAD+ package updates and BMAD-METHOD source synchronization are separate. These commands update BMAD+; they do not merge upstream source into your project.
### Optional: authorize a bounded automatic-update policy
Enable 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.
**In your project terminal**
```sh
npx --no-install bmad-plus update-policy --mode auto --range "^0.13.0"
```
**In your project terminal**
```sh
npx --no-install bmad-plus update-policy --mode notify
```
### Recovery after an update
Update 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.
**In your project terminal**
```sh
npx --no-install bmad-plus update --restore RECEIPT_ID --yes
```
## What’s new
The 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 — Updates that respect your project
2026-09-08
Discover published releases, control automatic-update policy and preserve customized agent files.
## Release history
Selected 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 — Updates that respect your project
2026-09-08
Discover published releases, control automatic-update policy and preserve customized agent files.
- Update checks provide JSON output, refresh and offline modes, with notification as the default.
- Managed-file hashes, backups and update receipts protect identified customizations and support restoration.
- The installer delivers the shared agent spine and seven adapters from the same definitions.
- Uninstall preserves project memory, settings and modified content whose safe removal cannot be established.
[Published package · v0.13.0](https://www.npmjs.com/package/bmad-plus/v/0.13.0)
### v0.12.2 — SEO tools delivered with the pack
2026-07-17
The SEO package includes the Python scripts and requirements needed by its documented workflow.
- The SEO toolkit ships in the npm package and is copied into installed projects.
- SEO Scout, SEO Chief and SEO Judge can be selected through their activation triggers.
- Crawler redirects are checked at each hop, and CLI and Python security checks were expanded.
[Published package · v0.12.2](https://www.npmjs.com/package/bmad-plus/v/0.12.2)
### v0.12.1 — More consistent project memory
2026-07-12
Project memory better recognizes an existing shared brain and records the selected link.
- Brain discovery honors configured and nearby portfolio locations before global fallbacks.
- Memory initialization and project indexing were corrected to avoid creating unrelated duplicate entries.
- Adapter drift checks and installation lockfile validation were strengthened.
[Published package · v0.12.1](https://www.npmjs.com/package/bmad-plus/v/0.12.1)
[All published versions on npm](https://www.npmjs.com/package/bmad-plus?activeTab=versions)
## When something is unclear
### The assistant cannot see my agents. What should I check?
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.
### Should I type autopilot or parallel in the terminal?
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.
### The version check says unknown or offline. Am I up to date?
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.