# Tutoriel : d’une idée à un essaim > Un parcours complet en sorties réelles : installer, Atelier demande d’abord, brief, panel simulé sous budget, décompte honnête, désinstallation avec mémoire conservée. Canonical: https://bmad-plus.rochetta.fr/fr/docs/guides/idea-to-swarm/ Language: fr BMAD+ version: 0.23.1 Documentation reviewed: 2026-10-19 Author: Laurent Rochetta License: MIT Documentation BMAD+ › [Guides](https://bmad-plus.rochetta.fr/fr/docs/guides/) › Tutoriel : d’une idée à un essaim Ce tutoriel suit une petite idée de la première question au dernier fichier. Le scénario : un bar à café nommé Orbit veut une landing page dont l’unique tâche est d’amener un nouveau visiteur à ouvrir une carte de fidélité. Vous allez laisser Atelier (l’agent de design) vous interroger avant qu’il touche à quoi que ce soit, tester l’argumentaire du bar sur un panel d’acheteurs simulés, lire le résultat sans vous raconter d’histoires, puis retirer BMAD+ en gardant la mémoire de votre projet. Chaque bloc de terminal ci-dessous est une sortie réelle. > **Remarque · Ce qui est réel et ce qui ne l’est pas** Les commandes et leurs sorties sont réelles (BMAD+ 0.23.0, exécuté sur un serveur de test dans un projet jetable). Aucun modèle n’a tourné. Là où un sous-agent écrirait une réponse, le tutoriel en écrit cinq à la main et le dit ; les citations du décompte sont donc du texte de démonstration, pas des paroles d’acheteurs. Le bar est inventé, et son argumentaire et son profil sont les fixtures de test du dépôt BMAD+. ## Étape 1. Installer core et design (et memory) Core apporte les quatre agents et les compétences d’intake, d’essaim et de recette. Design apporte Atelier et son intake. Le pack Memory est ajouté pour qu’il y ait quelque chose à garder à la fin du tutoriel. Le pack Design prend ses trois compétences dans le paquet `design-skill` à l’installation ; cette étape a donc besoin d’accéder aux paquets dont dépend BMAD+, comme tout lancement de `npx bmad-plus`. **Installation et diagnostic** ```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 # Une seule fois, pour que les commandes `npx --no-install` ci-dessous trouvent une copie locale (npm affiche son propre résumé, non reproduit ici). Sans elle, elles s’arrêtent avec « 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 # Extrait. Le cerveau global a été créé dans un dossier personnel jetable car aucun cerveau n’existait sur cette machine. ``` Sortie capturée lors d’une exécution réelle. Source: Rejoué sur un serveur de test le 2026-10-18 avec la source 0.23.0 (tools/cli/bmad-plus-cli.js) dans un projet Git jetable ## Étape 2. Laisser Atelier demander d’abord Dans la conversation de votre outil IA, tapez `/design read`. Atelier ne se met pas à concevoir : il exécute l’intake du pack Design. Derrière la conversation, il appelle `bmad-plus intake plan`, vous pose le premier lot (six questions au plus, les trois indispensables d’abord), puis enregistre vos réponses. Vous répondez avec vos mots ; la transcription ci-dessous montre les commandes que l’assistant exécute pour vous. ### Lancer le design read À utiliser avec le pack Design installé, dans la conversation de votre outil IA. **Dans votre assistant IA** ```text /design read pour la page d’accueil d’Orbit, un bar à café. Je répondrai avec mes mots, quelques questions à la fois. ``` **Ce que vous devriez obtenir** Atelier pose le premier lot de questions de l’intake `design-read` : de quelle surface il s’agit, qui l’utilise et dans quelle situation, et l’unique tâche que la page doit accomplir, puis les éléments de marque, le design system et la famille esthétique. Il enregistre ce que vous dites comme `answered` dans `_bmad-output/design/intake.json` dès que vous répondez, propose des valeurs par défaut quand il le peut et attend. Aucun brief n’est encore produit et rien n’est encore conçu. **Ce que l’assistant exécute pendant que vous répondez** ```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 # Code de sortie 2. La liste « Ask next » (six questions) suit dans la sortie réelle. $ 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. ``` Sortie capturée lors d’une exécution réelle. Source: Rejoué sur un serveur de test le 2026-10-18 avec la source 0.23.0 (tools/cli/bmad-plus-cli.js) dans un projet Git jetable ## Étape 3. Lire le brief avant que rien ne soit construit Ouvrez `_bmad-output/design/brief.md`. C’est le contrat pour la suite du travail ; vérifiez donc trois choses. D’abord, les trois indispensables disent ce que vous vouliez dire. Ensuite, les réponses marquées « proposed default, not confirmed by the user » (ici le design system `none` et la famille esthétique `none`) sont des propositions acceptables et non des faits que vous avez donnés. Enfin, la liste « Open questions » en bas : ici `variance` est inconnue, et `density`, `stack`, `accessibility_target`, `languages` et `required_states` n’ont pas encore été demandées. Atelier fixe un réglage resté ouvert d’après la surface et note qu’il l’a déduit ; il lit la stack dans le dépôt. Si une réponse manquante compte pour vous (les langues de la page, par exemple), donnez-la maintenant avec un autre `intake record`. ## Étape 4. Construire à partir du brief Demandez maintenant la construction. Atelier ouvre sa compétence `design`, dont la première étape est satisfaite par le brief (elle ne pose pas deux fois les mêmes questions), et construit la landing page dans la stack lue dans le dépôt. Selon les règles du pack Design, le livrable garde le statut de chaque réponse là où elle a servi (un défaut ou une déduction est signalé), porte les indispensables inconnus avec leur risque dans son premier paragraphe, et se termine par la liste de contrôle de livraison de la compétence, de sorte que « prêt » ou « pas prêt » vienne de la liste et non de l’allure de la page. Ce tutoriel ne reproduit pas ce livrable : ce n’est pas une sortie de CLI et aucun modèle n’a tourné. ### Construire la page à partir du brief enregistré À utiliser une fois le brief rédigé et lu. **Dans votre assistant IA** ```text /design build landing — utilise _bmad-output/design/brief.md comme brief et ne me repose pas ses questions. Montre-moi les réglages que tu as déduits et pourquoi, signale chaque endroit où un défaut proposé ou une déduction a servi, et termine par la liste de contrôle de livraison et son verdict. ``` **Ce que vous devriez obtenir** La page dans votre stack, un court compte rendu des réglages déduits, des défauts signalés et des questions ouvertes avec leurs risques, et le verdict de la liste de contrôle cité en dernier. Les preuves du rapport sont étiquetées `tool` (une commande a tourné et sa sortie est citée) ou `inspection` (lu face à la liste). ## Étape 5. Tester l’argumentaire sur un panel La page dit ce que le bar propose ; l’offre passe-t-elle ? Un panel d’acheteurs simulés lit l’argumentaire de deux phrases et remplit un formulaire fixe. Il vous faut les quatre fichiers d’un panel (définition, profil, gabarit de brief, et l’argumentaire comme fichier de contexte). Ici ce sont les fixtures de test de BMAD+, copiées sous `swarm/` ; leur contenu complet est imprimé dans [les fichiers d’exemple de la page CLI sur les essaims](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-swarm/#sample-files). Demandez 30 unités. Le budget est de 26 : la première tentative s’arrête donc et demande votre approbation. **Refusé au-dessus du budget, puis approuvé avec la même graine** ```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. # Code de sortie 2. On vous pose une phrase : « Ce panel demande 30 sous-agents ; le budget est de 26. On lance ? » Vous dites oui. $ 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 autres unités en trois vagues ... 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. ``` Sortie capturée lors d’une exécution réelle. Source: Rejoué sur un serveur de test le 2026-10-18 avec la source 0.23.0 (tools/cli/bmad-plus-cli.js) dans un projet Git jetable C’est ici que votre assistant lance un sous-agent par brief, vague après vague, avec la seule consigne de lire son brief et de le suivre à la lettre. Cette partie relève de votre outil IA et n’est pas reproduite ici. Pour la démonstration, cinq réponses ont été écrites à la main dans `answers/` (quatre en fichiers, une classée via `save` à partir d’une réponse avec une phrase autour du JSON), et une sixième réponse avec `"buys": "maybe"` a été refusée. **Les six réponses de la démonstration (écrites à la main, comme l’indique le texte ci-dessus)** ```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." } ``` ### Lancer le panel et rendre compte honnêtement À utiliser avec les fichiers du panel en place. L’assistant doit demander avant de dépasser le budget et ne doit répondre à la place d’aucune unité. **Dans votre assistant IA** ```text Lance l’essaim buyer-panel avec swarm/buyer-panel.json, swarm/profile.json et swarm/pitch.md comme argumentaire, 30 unités, graine 7. Demande-moi avant de dépasser le budget. Lance une vague de sous-agents à la fois, chacun ayant pour seule consigne de lire son brief et de le suivre. N’écris, ne corrige et n’invente aucune réponse. Quand le décompte est écrit, rapporte d’abord la mention de transparence, puis le nombre de réponses valides sur 30, le taux d’achat avec son dénominateur par segment et par comportement, les codes de raison et les premières citations, et nomme les unités qui n’ont pas répondu. ``` **Ce que vous devriez obtenir** Le refus avec le code de sortie 2 et la question d’une phrase, puis trois vagues de 10, un `check` qui liste les unités manquantes éventuelles, et un compte rendu qui s’ouvre par « Simulated units are not people. Read rates as an upper bound and confirm with real ones. », suivi de chiffres accompagnés de leurs dénominateurs. Les unités sans réponse sont nommées, pas écartées en silence. ## Étape 6. Lire le décompte sans se raconter d’histoires **check, tally et inspect après cinq réponses valides** ```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 à B030 de même. Code de sortie 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. ``` Sortie capturée lors d’une exécution réelle. Source: Rejoué sur un serveur de test le 2026-10-18 avec la source 0.23.0 (tools/cli/bmad-plus-cli.js) dans un projet Git jetable **tally.md, début et section du taux (fichier écrit par la commande ci-dessus)** ```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. Lisez la première ligne : la mention de transparence. Ce sont des unités simulées, pas des clients. 2. Lisez le dénominateur avant le taux : « 3 sur 5 » n’est pas « 60 pour cent de votre marché », et seulement 5 unités sur 30 ont compté ici. Dans une exécution réelle, un grand nombre d’unités manquantes est lui-même un constat (un sous-agent qui n’a pas suivi son brief), pas du bruit. 3. Un groupe sans réponse valide affiche `n/a`. Il n’affiche pas 0. 4. Les taux sont une borne haute à confirmer auprès de vraies personnes. Servez-vous du panel pour repérer quelle objection apparaît et où, puis interrogez de vrais clients là-dessus. 5. Les citations de cette démonstration sont écrites à la main. Dans une exécution réelle, ce sont mot pour mot ce qu’une unité simulée a écrit, attribué à son id d’unité. Ne les présentez jamais comme des témoignages. ## Étape 7. Comparer un second argumentaire avec les mêmes acheteurs Modifiez une copie de l’argumentaire, puis relancez `init` avec le même profil, `--n 30` et `--seed 7`, en ne changeant que `--context pitch=...`. L’id d’exécution est nouveau, les fiches sont les mêmes. Ici l’argumentaire est resté inchangé pour prouver le point : les deux fichiers `cards.json` sont identiques à l’octet près, donc toute différence que vous verrez ensuite entre deux décomptes vient du seul argumentaire. **Même graine, mêmes fiches** ```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 ``` Sortie capturée lors d’une exécution réelle. Source: Rejoué sur un serveur de test le 2026-10-18 avec la source 0.23.0 (tools/cli/bmad-plus-cli.js) dans un projet Git jetable ## Étape 8. Noter ce que vous avez décidé La décision qui a compté ici (la page a une seule tâche, l’ouverture de la carte de fidélité) a sa place dans la mémoire du projet pour que la session de demain ne la redécouvre pas. Demandez à Zecher de la consigner dans `decisions.md` et d’écrire une passation de session. La commande de journal enregistre l’événement pour un rappel ultérieur. **Consigner un événement, puis le rappeler** ```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 # Extrait. La seconde correspondance est une entrée de décision ajoutée à la main à decisions.md, au format du gabarit installé. ``` Sortie capturée lors d’une exécution réelle. Source: Rejoué sur un serveur de test le 2026-10-18 avec la source 0.23.0 (tools/cli/bmad-plus-cli.js) dans un projet Git jetable ## Étape 9. Désinstaller en gardant la mémoire La désinstallation ne retire que les fichiers dont BMAD+ est propriétaire, c’est-à-dire identiques à l’octet près à ce qu’il a livré, et les adaptateurs qu’il a écrits, plus le manifeste. Elle garde la mémoire de votre projet, vos réglages et tout ce qui est inconnu ou modifié. L’état d’exécution des essaims, l’intake de design et le brief restent aussi, parce que c’est votre travail. `--yes` est requis sans terminal. **Désinstaller, puis ce qui reste** ```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 # Extrait : vos propres fichiers (README.md, swarm/, swarm-inbox/) et les dossiers vides sont omis. `AGENTS.md`, `CLAUDE.md`, `.agents/skills/` et le manifeste ont disparu. ``` Sortie capturée lors d’une exécution réelle. Source: Rejoué sur un serveur de test le 2026-10-18 avec la source 0.23.0 (tools/cli/bmad-plus-cli.js) dans un projet Git jetable ### Clore la session et garder l’essentiel À utiliser à la fin du tutoriel, avant de désinstaller, avec le pack Memory installé. **Dans votre assistant IA** ```text Zecher, clos cette session. Consigne dans decisions.md la décision que la landing page a une seule tâche (l’ouverture de la carte de fidélité) avec sa justification, ajoute une leçon sur la lecture du décompte du panel avec son dénominateur, et écris une passation dans sessions/. Note l’id d’exécution du panel et la graine. Dates en AAAA-MM-JJ, n’archive rien. ``` **Ce que vous devriez obtenir** Une entrée de décision datée, une leçon, une passation dans `.agents/memory/sessions/` et un `context.md` mis à jour. La désinstallation n’écrase jamais les fichiers de mémoire : la session suivante, avec ou sans BMAD+ installé, peut donc partir d’eux. ## Récapitulatif **Les neuf étapes** | Étape | Vous faites | Vous obtenez | | --- | --- | --- | | 1 | `install --packs core,design,memory` ; `doctor` | Agents, compétences, adaptateurs, un diagnostic propre | | 2 | `/design read` et répondre | Des réponses avec un statut chacune | | 3 | Lire `brief.md` | Un contrat que vous avez vérifié : défauts et inconnus visibles | | 4 | `/design build landing` | Une page qui cite son propre verdict de liste de contrôle | | 5 | `swarm init` (approuver), `briefs`, lancer les vagues | Un panel sous budget, avec un refus auquel vous avez répondu | | 6 | `check`, `tally` | Des taux avec dénominateurs, des citations, la mention de transparence en premier | | 7 | `init` de nouveau, même graine | Les mêmes acheteurs pour un avant et un après | | 8 | Zecher, `mem write` | Une décision, une leçon et une passation sur disque | | 9 | `uninstall --yes` | BMAD+ retiré, votre travail et votre mémoire conservés | **Voir aussi** - [L’intake en détail](https://bmad-plus.rochetta.fr/fr/docs/concepts/intake/) - [Les essaims en détail](https://bmad-plus.rochetta.fr/fr/docs/concepts/swarm/) - [La mémoire en détail](https://bmad-plus.rochetta.fr/fr/docs/concepts/how-memory-works/) - [Le pack Design](https://bmad-plus.rochetta.fr/fr/docs/packs/design/) - [Installer, mettre à jour, désinstaller](https://bmad-plus.rochetta.fr/fr/docs/guides/install-lifecycle/) [Documentation BMAD+](https://bmad-plus.rochetta.fr/fr/docs/) · [Guides](https://bmad-plus.rochetta.fr/fr/docs/guides/) [Code sur GitHub](https://github.com/lrochetta/BMAD-PLUS)