A complete walk-through with real output: install, let Atelier ask first, record a brief, run a simulated buyer panel under a budget, read the honest tally, then uninstall and keep memory.
This tutorial follows one small idea from the first question to the last file. The scenario: a coffee bar called Orbit wants a landing page whose one job is to get a first-time visitor to open a loyalty card. You will let Atelier (the design agent) interview you before it touches anything, test the bar’s pitch on a panel of simulated buyers, read the result without fooling yourself, and then remove BMAD+ while keeping your project memory. Every terminal block below is a real output.
Note· What is real and what is not
The commands and their output are real (BMAD+ 0.23.0, run on a test server in a throwaway project). No model ran. Where a sub-agent would write an answer, the tutorial writes five answers by hand and says so; the quotes in the tally are therefore demonstration text, not buyers’ words. The coffee bar is invented, and its pitch and profile are the test fixtures of the BMAD+ repository.
Core brings the four agents and the intake, swarm and acceptance skills. Design brings Atelier and its intake. The Memory pack is added so that there is something to keep at the end of the tutorial. The Design pack takes its three skills from the design-skill package at install time, so this step needs access to the packages BMAD+ depends on, as any npx bmad-plus run does.
Install and health check
$ npx bmad-plus install --yes --lang en --packs core,design,memory --tools claude-code◆ Selected packs: ⚙️ Core, 🧠 Memory, 🎨 Design● 🧠 Global brain created: /work/demo/home/.bmad-plus/brain◇ ✅ 6 agents, 9 skills, 5 files copied◇ ✅ 1 IDE(s) configured│ 🎨 Design: "/design read" → Atelier interviews you, then builds└ BMAD+ is ready! Talk to Atlas to get started 🚀$ npm install --save-dev bmad-plus# Once, so that the `npx --no-install` commands below find a local copy (npm prints its own summary, not reproduced here). Without it they stop with “npx canceled due to missing packages and no YES option”.$ npx --no-install bmad-plus doctor│ 98/98 checks passed│ 0 error(s), 0 warning(s)│ Ownership inventory: complete# Excerpt. The global brain was created in a throwaway home folder because no brain existed on that machine.
npx bmad-plus install --yes --lang en --packs core,design,memory --tools claude-code
npm install --save-dev bmad-plus
npx --no-install bmad-plus doctor
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
In your AI tool’s chat, type /design read. Atelier will not start designing: it runs the Design pack’s intake. Behind the conversation it calls bmad-plus intake plan, asks you the first batch (at most six questions, the three must-haves first), then records your answers. You answer in your own words; the transcript below shows the commands the assistant runs for you.
Use with the Design pack installed, in the chat of your AI tool.
In your AI assistant
/design read for the landing page of Orbit, a coffee bar. I will answer in my own words, a few questions at a time.
What you should get Atelier asks the first batch of questions of the design-read intake: which surface this is, who uses it and in what situation, and the one job the page must get done, then brand assets, design system and aesthetic family. It records what you say as answered in _bmad-output/design/intake.json as soon as you answer, proposes defaults where it can and waits. No brief is rendered and nothing is designed yet.
What the assistant runs while you answer
$ npx --no-install bmad-plus intake check .agents/skills/pack-design/intake.yaml.agents/skills/pack-design/intake.yaml: valid intake design-read (design), 13 questions, 3 must-have.$ npx --no-install bmad-plus intake plan --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.jsondesign-read (design): not ready — 0 answered, 0 defaulted, 0 unknown, 13 not asked yet.Must-haves still open: surface_kind, audience, job# Exit code 2. The "Ask next" list (six questions) follows in the real output.$ npx --no-install bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set surface_kind=landing --set "audience=Urban professionals who buy coffee most days; on a phone, on the way to work, a few seconds of attention" --set "job=Get a first-time visitor to open a loyalty card; success is the sign-up button being tapped"Recorded surface_kind, audience, job in _bmad-output/design/intake.json.design-read (design): ready — 3 answered, 0 defaulted, 0 unknown, 10 not asked yet.$ npx --no-install bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set brand_assets=partial --default design_system --default aesthetic_family --set motion=3 --set variance=UNKNOWNRecorded brand_assets, motion, variance, design_system, aesthetic_family in _bmad-output/design/intake.json.design-read (design): ready — 5 answered, 2 defaulted, 1 unknown, 5 not asked yet.Unknown: variance$ npx --no-install bmad-plus intake render --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --out _bmad-output/design/brief.mdBrief written to _bmad-output/design/brief.md (3043 bytes); the intake is ready.
npx --no-install bmad-plus intake check .agents/skills/pack-design/intake.yaml
npx --no-install bmad-plus intake plan --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json
npx --no-install bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set surface_kind=landing --set "audience=Urban professionals who buy coffee most days; on a phone, on the way to work, a few seconds of attention" --set "job=Get a first-time visitor to open a loyalty card; success is the sign-up button being tapped"
npx --no-install bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set brand_assets=partial --default design_system --default aesthetic_family --set motion=3 --set variance=UNKNOWN
npx --no-install bmad-plus intake render --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --out _bmad-output/design/brief.md
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
Open _bmad-output/design/brief.md. It is the contract for the rest of the work, so check three things. First, the three must-haves say what you meant. Second, the answers marked "proposed default, not confirmed by the user" (here the design system none and the aesthetic family none) are acceptable proposals and not facts you gave. Third, the "Open questions" list at the bottom: here variance is unknown, and density, stack, accessibility_target, languages and required_states were not asked yet. Atelier sets an open dial from the surface and records that it inferred it; it reads the stack from the repository. If a missing answer matters to you (the languages of the page, say), answer it now with another intake record.
Now ask for the build. Atelier opens its design skill, whose first step is satisfied by the brief (it does not ask the same questions twice), and builds the landing page in the stack it read from the repository. By the Design pack’s rules, the deliverable keeps the status of each answer where it was used (a default or an inference is flagged), carries the unknown must-haves with their risk in its opening paragraph, and ends with the skill’s delivery checklist, so that "ready" or "not ready" comes from the checklist and not from how the page looks. This tutorial does not reproduce that deliverable: it is not a CLI output and no model ran.
Use after the brief is rendered and you have read it.
In your AI assistant
/design build landing — use _bmad-output/design/brief.md as the brief and do not ask me its questions again. Show me the dials you inferred and why, flag every place where a proposed default or an inference was used, and end with the delivery checklist and its verdict.
What you should get The page in your stack, a short account of the inferred dials, the flagged defaults and the open questions with their risks, and the checklist verdict quoted last. Evidence in the report is labelled tool (a command ran and its output is quoted) or inspection (read against the checklist).
The page says what the bar offers; does the offer land? A panel of simulated buyers reads the two-sentence pitch and answers a fixed form. You need the four files of a panel (definition, profile, brief template, and the pitch as a context file). Here they are the BMAD+ test fixtures, copied under swarm/; their full content is printed in the sample files of the swarm CLI page. Ask for 30 units. The budget is 26, so the first attempt stops and asks for your approval.
Refused over budget, then approved with the same seed
$ npx --no-install bmad-plus swarm init --definition swarm/buyer-panel.json --profile swarm/profile.json --context pitch=swarm/pitch.md --n 30 --seed 7buyer-panel-20261018-ghku: needs approval. The run needs 30 sub-agents and the budget is 26: ask the user, then re-run init with --approved --seed 7.# Exit code 2. You are asked one sentence: "This panel needs 30 sub-agents; the budget is 26. Run it?" You say yes.$ npx --no-install bmad-plus swarm init --definition swarm/buyer-panel.json --profile swarm/profile.json --context pitch=swarm/pitch.md --n 30 --seed 7 --approvedbuyer-panel-20261018-nhq4: panel of 30 units, budget 26, approval user.Seed 7 (same seed, same cards).Next: bmad-plus swarm briefs buyer-panel-20261018-nhq4$ npx --no-install bmad-plus swarm briefs buyer-panel-20261018-nhq4buyer-panel-20261018-nhq4: 30 of 30 units need a sub-agent, in waves of 10.Wave 1: B001 /work/demo/app/.bmad-plus/swarm/runs/buyer-panel-20261018-nhq4/briefs/B001.md# ... 29 more units in three waves ...Each sub-agent: Read the brief and follow it exactly; it is your whole instruction.Disclosure: Simulated units are not people. Read rates as an upper bound and confirm with real ones.
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
This is where your assistant launches one sub-agent per brief, wave by wave, with the single instruction to read its brief and follow it exactly. That part belongs to your AI tool and is not reproduced here. For the demonstration, five answers were written by hand into answers/ (four as files, one filed through save from a reply with a sentence around the JSON), and a sixth reply with "buys": "maybe" was refused.
The six replies of the demonstration (hand-written, as the text above says)
# .bmad-plus/swarm/runs/<run id>/answers/B001.json
{ "id": "B001", "buys": false, "reason_code": "price", "reason": "Four twenty is steep for a drink I can get closer to home." }
# .../answers/B002.json
{ "id": "B002", "buys": true, "reason_code": "habit", "reason": "The free tenth drink and the remembered order fit my routine.", "price_floor": 3.5 }
# .../answers/B003.json
{ "id": "B003", "buys": true, "reason_code": "habit", "reason": "I pass the street every morning and order the same thing.", "visits_per_week": 5 }
# .../answers/B004.json
{ "id": "B004", "buys": false, "reason_code": "other", "reason": "I do not know the brand yet." }
# swarm/reply-b005.txt, filed with: swarm save <run id> B005 --input swarm/reply-b005.txt
Here is my answer as the buyer in my card:
{ "id": "B005", "buys": true, "reason_code": "need", "reason": "A quick stop two streets from the station is what my mornings need." }
# swarm/reply-b006.txt, refused by swarm save: field "buys" must be true or false
{ "id": "B006", "buys": "maybe", "reason_code": "price", "reason": "Not sure." }
Use with the panel files in place. The assistant must ask before exceeding the budget, and must not answer for any unit.
In your AI assistant
Run the buyer-panel swarm with swarm/buyer-panel.json, swarm/profile.json and swarm/pitch.md as the pitch, 30 units, seed 7. Ask me before going over the budget. Launch one wave of sub-agents at a time, each told only to read its brief and follow it. Do not write, fix or invent any answer. When the tally is written, report the disclosure first, then the number of valid answers out of 30, the buy rate with its denominator by segment and by behaviour, the reason codes and the first quotes, and name the units that did not answer.
What you should get The refusal at exit code 2 and the one-sentence question, then three waves of 10, a check that lists any missing unit, and a report that opens with "Simulated units are not people. Read rates as an upper bound and confirm with real ones." followed by figures that carry their denominators. Units that did not answer are named, not silently dropped.
$ npx --no-install bmad-plus swarm check buyer-panel-20261018-nhq4buyer-panel-20261018-nhq4: 5 of 30 valid answers. B006 missing: no answer file# ... B007 to B030 likewise. Exit code 1.$ npx --no-install bmad-plus swarm tally buyer-panel-20261018-nhq4/work/demo/app/.bmad-plus/swarm/runs/buyer-panel-20261018-nhq4/tally.md5 of 30 units counted; 25 skipped.Disclosure: Simulated units are not people. Read rates as an upper bound and confirm with real ones.
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
tally.md, opening and rate section (a file written by the command above)
> Simulated units are not people. Read rates as an upper bound and confirm with real ones.
# Simulated buyers see the pitch (run buyer-panel-20261018-nhq4)
5 of 30 units gave a valid answer; 25 skipped: B006 (no answer file), B007 (no answer file), ...
## Rate: buys
| group | yes | of | rate |
|---|---|---|---|
| all | 3 | 5 | 60.0% |
| segment = mid career | 2 | 4 | 50.0% |
| segment = high earner | 1 | 1 | 100.0% |
| segment = early career | 0 | 0 | n/a |
| behaviour = occasional | 1 | 3 | 33.3% |
| behaviour = daily regular | 2 | 2 | 100.0% |
| behaviour = explorer | 0 | 0 | n/a |
Read the first line: the disclosure. These are simulated units, not customers.
Read the denominator before the rate: "3 of 5" is not "60 percent of your market", and only 5 of 30 units counted here. In a real run, a large number of missing units is itself a finding (a sub-agent that did not follow its brief), not noise.
A group with no valid answer shows n/a. It does not show 0.
The rates are an upper bound to confirm with real people. Use the panel to find which objection shows up and where, then ask real customers about that.
The quotes in this demonstration are hand-written. In a real run they are what a simulated unit wrote, verbatim, attributed to its unit id. Never present them as testimonials.
Step 7. Compare a second pitch with the same buyers#
Edit a copy of the pitch, then run init again with the same profile, --n 30 and --seed 7, changing only --context pitch=.... The run id is new, the cards are the same. Here the pitch was left unchanged just to prove the point: the two cards.json files are byte for byte identical, so any difference you later see between two tallies comes from the pitch alone.
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
The decision that mattered here (the page has one job, the loyalty card sign-up) belongs in project memory so that tomorrow’s session does not rediscover it. Ask Zecher to log it in decisions.md and to write a session handoff. The journal command records the event for later recall.
Journal an event, then recall it
$ npx --no-install bmad-plus mem write --agent atelier --cli claude-code --task "Design read for the Orbit landing page: one job, the loyalty card sign-up" --outcome success --ci passmem write: event 4d5cbf08d26e appended (2026-10-18T20:19:27.139Z)$ npx --no-install bmad-plus mem recall "loyalty card sign-up"mem recall: 2 match(es) for "loyalty card sign-up" (scope: project) 1. [0.707] event journal.ndjson#4d5cbf08d26e 2. [0.507] note decisions.md § 2026-10-18 — The landing page has one job, the loyalty card sign-up# Excerpt. The second match is a decision entry added to decisions.md by hand, in the format of the installed template.
npx --no-install bmad-plus mem write --agent atelier --cli claude-code --task "Design read for the Orbit landing page: one job, the loyalty card sign-up" --outcome success --ci pass
npx --no-install bmad-plus mem recall "loyalty card sign-up"
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
Uninstall removes only the files BMAD+ owns, that is files byte-identical to what it shipped, and the adapters it wrote, plus the manifest. It keeps your project memory, your settings and everything unknown or modified. The run state of swarms, the design intake and the brief stay too, because they are your work. --yes is required without a terminal.
Uninstall, then what is left
$ npx --no-install bmad-plus uninstall --yes● BMAD+ v0.23.0 (installed 2026-10-18)● Selected packs: core, memory, design◇ ✅ BMAD+ removed (120 items)└ Project memory, settings, and unknown or modified files have been preserved.$ find . -path ./.git -prune -o -path "./.bmad-plus/swarm/runs/*" -prune -o -print | sort./.agents/memory/.brain-link./.agents/memory/context.md./.agents/memory/decisions.md./.agents/memory/lessons.md./.agents/memory/patterns.md./.agents/memory/sessions./.bmad/memory/journal.ndjson./.bmad-plus/swarm/runs./_bmad-output/design/brief.md./_bmad-output/design/intake.json./_bmad/config.yaml# Excerpt: your own files (README.md, swarm/, swarm-inbox/) and empty folders are left out. `AGENTS.md`, `CLAUDE.md`, `.agents/skills/` and the manifest are gone.
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
Use at the end of the tutorial, before uninstalling, with the Memory pack installed.
In your AI assistant
Zecher, close this session. Log the decision that the landing page has one job (the loyalty card sign-up) in decisions.md with its rationale, add a lesson about reading the panel tally with its denominator, and write a handoff in sessions/. Record the panel run id and seed. Keep dates as YYYY-MM-DD and archive nothing.
What you should get A dated decision entry, a lesson, a handoff in .agents/memory/sessions/ and an updated context.md. Memory files are never overwritten by uninstall, so the next session, with or without BMAD+ installed, can start from them.