# Tutorial: from an idea to a swarm > 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. Canonical: https://bmad-plus.rochetta.fr/docs/guides/idea-to-swarm/ 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/) › Tutorial: from an idea to a swarm 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. ## Step 1. Install core and design (and memory) 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** ```text $ 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. ``` 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 ## Step 2. Let Atelier ask first 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. ### Start the design read Use with the Design pack installed, in the chat of your AI tool. **In your AI assistant** ```text /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** ```text $ 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.json design-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=UNKNOWN Recorded 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.md Brief written to _bmad-output/design/brief.md (3043 bytes); the intake is ready. ``` 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 ## Step 3. Read the brief before anything is built 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`. ## Step 4. Build from the brief 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. ### Build the page from the recorded brief Use after the brief is rendered and you have read it. **In your AI assistant** ```text /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). ## Step 5. Test the pitch on a panel 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](https://bmad-plus.rochetta.fr/docs/reference/cli-swarm/#sample-files). 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** ```text $ 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 buyer-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 --approved buyer-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-nhq4 buyer-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)** ```text # .bmad-plus/swarm/runs//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 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." } ``` ### Run the panel and report honestly 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** ```text 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. ## Step 6. Read the tally without fooling yourself **check, tally and inspect after five valid answers** ```text $ npx --no-install bmad-plus swarm check buyer-panel-20261018-nhq4 buyer-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.md 5 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)** ```md > 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 | ``` 1. Read the first line: the disclosure. These are simulated units, not customers. 2. 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. 3. A group with no valid answer shows `n/a`. It does not show 0. 4. 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. 5. 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. **Same seed, same cards** ```text $ 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 --approved buyer-panel-20261018-5ucw: panel of 30 units, budget 26, approval user. Seed 7 (same seed, same cards). Next: bmad-plus swarm briefs buyer-panel-20261018-5ucw $ cmp .bmad-plus/swarm/runs/buyer-panel-20261018-nhq4/cards.json .bmad-plus/swarm/runs/buyer-panel-20261018-5ucw/cards.json && echo identical identical ``` 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 ## Step 8. Write down what you decided 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** ```text $ 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 mem 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. ``` 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 ## Step 9. Uninstall and keep your memory 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** ```text $ 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 ### Close the session and keep what matters Use at the end of the tutorial, before uninstalling, with the Memory pack installed. **In your AI assistant** ```text 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. ## Recap **The nine steps** | Step | You do | You get | | --- | --- | --- | | 1 | `install --packs core,design,memory`; `doctor` | Agents, skills, adapters, a clean health check | | 2 | `/design read` and answer | Answers with a status each | | 3 | Read `brief.md` | A contract you checked: defaults and unknowns visible | | 4 | `/design build landing` | A page that quotes its own checklist verdict | | 5 | `swarm init` (approve), `briefs`, launch waves | A panel run under a budget, with a refusal you answered | | 6 | `check`, `tally` | Rates with denominators, quotes, a disclosure first | | 7 | `init` again, same seed | The same buyers for a before and after | | 8 | Zecher, `mem write` | A decision, a lesson and a handoff on disk | | 9 | `uninstall --yes` | BMAD+ removed, your work and memory kept | **See also** - [Intake in depth](https://bmad-plus.rochetta.fr/docs/concepts/intake/) - [Swarms in depth](https://bmad-plus.rochetta.fr/docs/concepts/swarm/) - [Memory in depth](https://bmad-plus.rochetta.fr/docs/concepts/how-memory-works/) - [The Design pack](https://bmad-plus.rochetta.fr/docs/packs/design/) - [Install, update, uninstall](https://bmad-plus.rochetta.fr/docs/guides/install-lifecycle/) [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)