# Your first hour with BMAD+ > A newcomer path from an empty terminal to a reviewed first result: install, check, talk to your first agent, review, keep context, stay up to date. Each step with the real command and what to expect. Canonical: https://bmad-plus.rochetta.fr/docs/guides/first-hour/ Language: en BMAD+ version: 0.23.1 Documentation reviewed: 2026-10-19 Author: Laurent Rochetta License: MIT BMAD+ documentation › [Guides](https://bmad-plus.rochetta.fr/docs/guides/) › Your first hour with BMAD+ This page takes you from nothing to a first result you have reviewed yourself, in an order that works. You need a project folder, Node.js 20 or newer, and an AI coding tool you already use (Claude Code, Gemini CLI, Cursor, Codex CLI and others). BMAD+ supplies the instructions, roles and workflows; your tool supplies the model and the permissions to edit files and run commands. Nothing here needs an account with BMAD+, an API key of its own or a background service. Video: [BMAD+ in brief](https://bmad-plus.rochetta.fr/media/overview-en.mp4) — What BMAD+ installs, how a pack asks before it acts, how a swarm is counted honestly, and the ten packs. [Captions (WebVTT)](https://bmad-plus.rochetta.fr/media/overview-en.vtt) Transcript: > BMAD+ installs roles, workflows and shared context into the AI coding tool you already use. It starts by asking: a pack declares the questions it needs answered before it acts. You answer a few at a time, and what you do not know is recorded as unknown, with its risk. Then Nexus can run a swarm of sub-agents, within a budget you set. Each one reads a brief and writes an answer, and only valid answers are counted. The tally on screen is demo data, and it says plainly that simulated units are not people. For planned work, Nexus requires independent checks before it accepts a result. Core's four roles, nine optional packs, and adapters for seven AI coding tools. Install it with one npx command from your project folder. Described transcript: - **0:00** On screen: Dark blue haze fills the screen. The title “BMAD+ 0.23.0” sits in the centre, and a warm light slowly grows behind it. Narration: BMAD+ installs roles, workflows and shared context into the AI coding tool you already use. - **0:09** On screen: A single amber point of light in a dark teal cloud, with faint rays spreading from it. The caption at the bottom reads “Ask first”. Narration: It starts by asking: a pack declares the questions it needs answered before it acts. - **0:19** On screen: A terminal window titled “~/app”. A command is typed: bmad-plus intake record, pointing at the Design pack’s intake.yaml and an answers file, with three answers (surface_kind=dashboard; audience=“Accountants in a practice, on a desktop, at month end”; job=UNKNOWN) and a default for design_system. The output reads “Recorded surface_kind, audience, job, design_system”, then “design-read (design): ready — 2 answered, 1 defaulted, 1 unknown, 9 not asked yet.” and a list of the next questions, each tagged with its type (choice, number or text): brand_assets, aesthetic_family, variance, motion, density and stack. The view zooms in on the last line, where “Unknown: job” is outlined: “risk: There is no goal to review against, so hierarchy and the primary action cannot be judged, only decorated.” Narration: You answer a few at a time, and what you do not know is recorded as unknown, with its risk. - **0:27** On screen: Amber particles fly outward from a bright centre and form a widening ring against a dark purple background. The caption reads “A swarm, within a budget”. Narration: Then Nexus can run a swarm of sub-agents, within a budget you set. - **0:33** On screen: Two terminal panes side by side. On the left, bmad-plus swarm tally buyer-panel-20261018-zho8 is typed. It prints the path of a tally.md file, “8 of 40 units counted; 32 skipped.” and a line that starts with “Disclosure:”: “Simulated units are not people. Read rates as an upper bound and confirm with real ones.” The right pane opens tally.md. Its heading, outlined in orange, reads “Simulated buyers see the pitch (run buyer-panel-20261018-zho8)”, followed by “8 of 40 units gave a valid answer; 32 skipped” and a “Rate: buys” table (the row “all” reads 4 yes of 8, 50.0%). The pane scrolls through short quoted replies grouped by segment and behaviour, then stops on “Numbers: price_floor”: a table with the columns group, count, median, mean, min and max, whose first row, “all”, reads 8, 3.65, 3.7, 3 and 4.5. Narration: Each one reads a brief and writes an answer, and only valid answers are counted. The tally on screen is demo data, and it says plainly that simulated units are not people. - **0:48** On screen: A tangled knot of thin amber lines straightens, line by line, into a square grid with a bright point at its centre. The caption reads “Independent checks before acceptance”. Narration: For planned work, Nexus requires independent checks before it accepts a result. - **0:54** On screen: Tall, dark, glassy slabs stand in a row, lit from the side by a warm glow. The caption reads “10 packs · 7 adapters”. Narration: Core's four roles, nine optional packs, and adapters for seven AI coding tools. - **1:04** On screen: A terminal. The command npx bmad-plus install --lang en --packs core,design --tools claude-code is typed. The installer’s lines appear: “BMAD+ Installer v0.23.0”, “Installing to: /home/dev/app”, “Selected packs: Core, Design”, “Detected IDEs: Claude Code”, a first-name prompt (Developer), the communication language (English), a prompt for a test environment URL, and the execution mode, with Manual, Autopilot and Hybrid offered and “Manual — You call agents yourself” kept. The view zooms in on two green checks: “5 agents, 9 skills, 4 files copied”, with “files copied” outlined in orange, and “1 IDE(s) configured”. Narration: Install it with one npx command from your project folder. - **1:12** On screen: A dim blue-black sky with a faint band of light at the horizon. The address “bmad-plus.rochetta.fr” fades in, in orange, and fades out. > **Tip · Two kinds of instruction** Commands that start with `npx bmad-plus` go in a terminal. Sentences such as `bmad-help`, `autopilot`, `parallel` or "Atlas, ..." go in the chat of your AI tool. Typing `autopilot` in a terminal does nothing useful. ## Part 1. Install 1. **Open a terminal in your project and check Node.js** Use the repository you want to work on. The command should print v20 or higher; install or update Node.js separately if it does not. ```sh node --version ``` 2. **Run the installer** The interactive wizard asks for your language, the packs, the tools (if none is detected), your name, your communication language, a test-environment URL for acceptance recipes (optional) and the execution mode. Core is always installed. The tools are detected from folders such as `.claude/` or `.cursor/`. ```sh npx bmad-plus@0.23.1 install ``` 3. **Or install without questions** For a script or a first try, give everything on the command line. `--yes` skips the wizard (English by default unless you pass `--lang`); `--tools` takes ids such as `claude-code`, `gemini-cli`, `antigravity`, `cursor`, `codex-cli`, `opencode`, `aider`, or `all` or `none`. ```sh npx bmad-plus@0.23.1 install --yes --packs core --tools claude-code ``` The installer ends with a short guide of who to talk to and a line such as "BMAD+ is ready! Talk to Atlas to get started". With an unknown pack or tool id it stops and prints the valid ids; without a terminal and without `--yes` it refuses to run. **What the install leaves in a Git project** ```text $ npx bmad-plus install --yes --lang en --packs core --tools claude-code $ git status --short ?? .agents/ ?? AGENTS.md ?? CLAUDE.md ?? _bmad/ $ ls .agents/skills agent-architect-dev agent-orchestrator agent-quality agent-strategist bmad-plus-autopilot bmad-plus-intake bmad-plus-parallel bmad-plus-swarm bmad-plus-sync bmad-plus-uat # Four new paths, nothing in your source tree. Decide with your team whether to commit them or ignore them; either way, `_bmad/.bmad-plus-install.json` records which files BMAD+ owns. ``` Output captured from a real run. Source: Replayed on a test server on 2026-10-18 with the 0.23.0 source (tools/cli/bmad-plus-cli.js) in a throwaway Git project ## Part 2. Check and wake up your assistant 1. **Add the package to the project (once)** The installer does not put `bmad-plus` in your project’s `node_modules`, and the `npx --no-install` commands used from here on run only a local copy: without it they stop with `npx canceled due to missing packages and no YES option`. This adds a dev dependency to `package.json`. Skip the step if you prefer to type `npx bmad-plus ` instead, which downloads the package when needed. Without a local copy, the update check that the generated `CLAUDE.md` and `AGENTS.md` ask your assistant to run is simply skipped. ```sh npm install --save-dev bmad-plus ``` 2. **Run the health check** `doctor` is read-only: it never changes the project and never contacts npm. It ends with a line like "98/98 checks passed" and "0 error(s)" and exits 1 if there is any error. ```sh npx --no-install bmad-plus doctor ``` 3. **Open your AI tool in the same folder** Start a new session (or restart the tool) so that it loads its adapter file and `AGENTS.md`. There is no extra BMAD+ initialisation command. 4. **Ask it what it knows** In the chat, not in the terminal. If it lists Atlas, Forge, Sentinel and Nexus, your tool has read the instructions. If not, check that the tool is open in the installed project, that you chose its adapter, and that `AGENTS.md` and `.agents/skills/` exist. ```sh bmad-help ``` ## Part 3. A first task Pick the smallest real thing you need. The four Core agents cover most starts: Atlas for ideas and requirements, Forge for architecture and code, Sentinel for review and tests, Nexus for plans and coordination. A good prompt gives the goal, the constraints and the output you want to review. ### Start from an idea Use when there is no code yet, or when you want to write down the problem before changing anything. **In your AI assistant** ```text Atlas, I want a small tool that lets our support team triage incoming issues. Ask me about the users and their daily workflow, then write a product brief with the first useful workflow and acceptance criteria I can check. Keep it to one page. ``` **What you should get** Atlas may first show its menu and wait: answer with your request, or with the menu code `CB` (create a product brief). It then asks questions and writes the brief under `_bmad-output/`; the skill chooses the file name, so read the path it reports. Read the brief as you would read a colleague’s draft: the acceptance criteria should be checkable, and anything you did not say should be marked as an assumption. ### Make a small change in existing code Use for a bounded change. "Quick dev" is Forge’s minimum-ceremony path; it keeps the proportionate checks and skips the full pipeline. **In your AI assistant** ```text Forge, quick dev: add a loading state to the invoice list. Show me which files you will touch before you edit, change only those, run the existing tests that cover them and tell me exactly what you ran and what passed. ``` **What you should get** A short list of files, a small diff, and a report of the checks that really ran. If the tests could not run in the assistant’s environment, the report says so instead of claiming success. ## Part 4. Have it reviewed Ask Sentinel, a different role, to check what Forge produced against the acceptance criteria. If the BMAD+ command line is available, the review can be sealed so that its verdict follows from coverage and not from tone: it lists the files it must read, quotes the code of every finding and ends with one of `incomplete`, `findings` or `clean`. The code review page explains the three words. ### Ask Sentinel for an honest review Use right after a change, before you commit. **In your AI assistant** ```text Sentinel, review this change against the acceptance criteria in the brief. Check the success path and the main failure paths. If the BMAD+ CLI is available, seal the scope with bmad-plus review scope first-change --workspace, quote the code of every finding, account for every selected file and report what bmad-plus review gate answers. Say what you could not check. ``` **What you should get** A review in `_bmad-output/review/first-change/` ending with a verdict. `incomplete` means some file was not accounted for; `findings` lists what to fix, each with the quoted code; `clean` means no open finding within a fully covered scope, which is not a proof that the code is correct. ## Part 5. Keep what you learned A new session starts with nothing. Without the Memory pack, ask the assistant for a short handoff note that you save in the project: what was done and verified, what is pending, the decisions and the next step. With the Memory pack, Zecher does this and keeps decisions, lessons and handoffs in `.agents/memory/`. You can add the pack later: running the installer again with `--packs core,memory` only adds what is missing and keeps your configuration. **In your project terminal, to add the Memory pack later** ```sh npx bmad-plus install --packs core,memory ``` ### End the session with a handoff Use at the end of a working session, with the Memory pack installed. Without the pack, drop the name “Zecher” and ask your assistant, then save the note yourself. **In your AI assistant** ```text Zecher, write a handoff for the next session. Separate what is implemented, what is tested, what is only planned, the decisions we made and why, the open questions, and the exact first step to take next. Dates in YYYY-MM-DD. Do not include secrets. ``` **What you should get** A dated note (with the Memory pack, `.agents/memory/sessions/YYYY-MM-DD-.md` and an updated `context.md`) that a cold session can read in under a minute and trust, because it separates done from planned. ## Part 6. Stay up to date, safely By default BMAD+ only notifies. `update-check` reports the installed and the published versions without changing anything, and offline it says unknown rather than guessing. `update-policy` shows or sets whether updates are `off`, `notify` (the default) or `auto` (which needs an explicit version range). `update` with no option says "Nothing to update" when the installed version equals the package that runs it; `update --latest` looks at npm. **Reading the update state, offline** ```text $ npx --no-install bmad-plus update-check --offline Installed: 0.23.0; running: 0.23.0; channel latest: unknown unknown: offline $ npx --no-install bmad-plus update-policy Update policy: notify; channel=latest; range=none; prereleases=false $ npx --no-install bmad-plus update ● Installed: v0.23.0 -> Executing package: v0.23.0 ◆ The installed version matches this executing package. Use --latest to check the registry. └ Nothing to update. ``` Output captured from a real run. Source: Replayed on a test server on 2026-10-18 with the 0.23.0 source (tools/cli/bmad-plus-cli.js) in a throwaway Git project When an update does apply, files you edited are kept and reported, a receipt and backups are written under `.bmad/updates/`, and `update --restore --yes` takes it back. The team guide and the install lifecycle page cover the details. ## Where next **Pick the next page by what you want to do** | You want to | Read | | --- | --- | | Understand what BMAD+ does and does not do | How BMAD+ works | | Automate a whole project, or run tasks in parallel | Nexus, autopilot and parallel work | | Let a pack ask you the right questions first | Intake: ask first, then act | | Test a pitch or a page against many simulated readers | Swarms of sub-agents | | Walk through a complete example from idea to tally | Tutorial: from an idea to a swarm | | Copy prompts for every pack | Recipes cookbook | | Know what leaves your machine | Data handling | | Share one setup across a team | Using BMAD+ in a team | | Fix a problem | Troubleshooting and the FAQ | **See also** - [How BMAD+ works](https://bmad-plus.rochetta.fr/docs/concepts/how-bmad-plus-works/) - [Tutorial: from an idea to a swarm](https://bmad-plus.rochetta.fr/docs/guides/idea-to-swarm/) - [Recipes cookbook](https://bmad-plus.rochetta.fr/docs/guides/recipes-cookbook/) - [Using BMAD+ in a team](https://bmad-plus.rochetta.fr/docs/guides/for-teams/) - [FAQ](https://bmad-plus.rochetta.fr/docs/faq/faq/) - [Troubleshooting](https://bmad-plus.rochetta.fr/docs/faq/troubleshooting/) [BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Guides](https://bmad-plus.rochetta.fr/docs/guides/) [Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)