bmad-plus swarm

Un essaim, ce sont de nombreux sous-agents qui font chacun une fois le même type de travail : trente acheteurs simulés qui lisent un argumentaire, trois jurés qui tiennent chacun un angle, un rédacteur par page. bmad-plus swarm tient la comptabilité autour de cela. Il tire les unités, écrit un brief par sous-agent, vérifie chaque fichier de réponse, classe une réponse qu’un sous-agent s’est contenté d’afficher et compte les réponses valides. Il n’appelle jamais de modèle, n’ouvre aucune connexion réseau et ne lance aucun processus : votre assistant (l’assistant hôte) lance les sous-agents, la commande ne fait que lire et écrire des fichiers sous .bmad-plus/swarm/. À utiliser quand on demande un panel, un jury ou un éclatement en unités indépendantes. La version 0.23.0 ne livre aucune définition d’essaim dans ses packs ; c’est vous ou un pack qui fournit le fichier de définition.

Synopsis#

npx bmad-plus swarm init --definition FILE [--profile FILE | --units FILE] [--context NAME=FILE]... [--n N] [--seed N] [--approved]
npx bmad-plus swarm briefs RUN [--wave N]
npx bmad-plus swarm check RUN
npx bmad-plus swarm save RUN UNIT --input FILE
npx bmad-plus swarm tally RUN [--out FILE]
npx bmad-plus swarm inspect RUN
npx bmad-plus swarm plan RUN [--out FILE]

Les trois types d’essaim#

Un panel et un jury tournent comme des sous-agents de session : l’hôte les lance, attend, puis lit leurs fichiers. Un fanout peut tourner de la même façon, ou être exporté avec plan quand le travail doit survivre à la session, exige un contrôle indépendant par unité ou modifie le dépôt (voir bmad-plus nexus). Le fichier de définition (JSON) nomme le type, le gabarit de brief, les champs de réponse (boolean, integer, number, string, enum, list), le décompte et une phrase de disclosure de 1 à 500 caractères.

Budget, vagues et approbation#

Trois réglages du bloc swarm de _bmad/config.yaml bornent une exécution. Un fichier ou un bloc absent signifie les valeurs par défaut ci-dessous ; toute autre valeur est refusée. init compare le nombre d’unités au budget : une exécution plus grand est créé à l’état needs-approval, n’écrit aucun brief et se termine par le code 2. L’assistant doit alors vous demander, en une phrase chiffrée, et seulement après un oui relancer init avec --approved et la graine affichée par le refus.

Les sept actions#

Ordre habituel : init, puis briefs, l’hôte lance un sous-agent par brief avec exactement la consigne « Read the brief and follow it exactly; it is your whole instruction », puis check. Relancez briefs une fois pour donner une seconde chance aux unités manquantes (il ne rend que les unités sans réponse valide), classez avec save toute réponse affichée, puis tally. Une unité toujours manquante après la seconde vague reste manquante et est nommée dans le décompte. inspect résume une exécution à tout moment sans rien écrire.

L’arborescence d’une exécution#

.bmad-plus/swarm/runs/<definition-id>-<yyyymmdd>-<4 chars>/
  run.json            inputs hashes, n, seed, wave, budget, approval, status
  definition.json     the normalized definition, frozen
  template.md         the brief template, frozen
  cards.json          the dealt or listed units
  context/<name>.md   each context file, frozen
  briefs/<unit>.md    written by briefs (and plan)
  answers/<unit>.json written by the sub-agent, or filed by save
  tally.json, tally.md
  checks/answer.cjs, checks/swarm-validate.cjs, nexus-plan.json   (fanout, written by plan)

Le suffixe de 4 caractères est aléatoire et un dossier existant n’est jamais réutilisé. Les entrées sont figées à init : modifier ensuite un contexte ou la définition ne change rien pour cette exécution. États : needs-approval (terminal), ready, briefed, tallied. Un décompte peut être relancé, et briefs peut l’être après un décompte. Les rapports demandés avec --out vont sous .bmad-plus/swarm/reports/<run id>/.

Règles d’honnêteté#

• Des unités simulées ne sont pas des personnes. Le décompte s’ouvre sur la mention de transparence (disclosure) de la définition, avant tout chiffre. Les taux d’un panel sont une borne haute à confirmer avec de vraies personnes, jamais une mesure.
• Les citations sont simulées : présentez-les comme ce qu’a écrit une unité simulée, jamais comme un témoignage ou un entretien.
• Le modérateur ne répond jamais à la place d’une unité : pas de fichier de réponse écrit à la main, pas de « correction » d’une réponse invalide. save se contente d’extraire et de valider ce qu’un sous-agent a affiché.
• Les briefs ne sont jamais modifiés. Un changement va dans le gabarit ou la définition, puis dans une nouvelle exécution.
• Même graine, mêmes cartes : une comparaison avant/après de deux argumentaires relance le même profil avec le même --n et la même --seed, de sorte que seul le contexte a changé.
• Le runtime ne filtre rien : valeurs des cartes, entrées des réservoirs et fichiers de contexte arrivent mot pour mot au sous-agent. Lisez un contexte avant de le passer ; il est copié dans chaque brief, secrets et consignes compris.
• Une réponse valide est une réponse bien formée. Rien ne prouve qu’un sous-agent a lu son brief ni qu’il a dit vrai.

Lectures, écritures et limites#

• N’écrit que sous .bmad-plus/swarm/. --out pour tally et plan doit rester dans .bmad-plus/swarm/reports/<run id>/ ou dans l’arborescence de l’exécution, jamais par-dessus answers/, briefs/, context/, checks/, run.json, cards.json, definition.json, template.md, nexus-plan.json, tally.json ou tally.md.
• Chaque chemin que vous nommez (--definition, --profile, --units, --context, --input) est relatif au projet avec des / ; chemins absolus, antislashs, .., .git et tout passage par un lien symbolique sont refusés. Ces fichiers ne peuvent pas venir de .bmad-plus/.
• Limites : 1 à 1000 unités par exécution ; budget et vague de 1 à 1000 ; graine de 0 à 2147483647 ; entrées de 16 Mio au plus ; réponse affichée pour save de 1 Mio au plus ; 50 champs de réponse au plus ; 20 contextes par définition au plus ; 5 champs groupBy au plus.
• Les ids d’unité sont des lettres, chiffres, _ ou - (64 caractères au plus ; en minuscules pour un fanout). Les ids d’un panel tiré sont le préfixe plus la position complétée à au moins trois chiffres (B001).
• Les fichiers sont écrits via un fichier temporaire puis renommés. Aucun réseau, aucun processus enfant, aucun eval.

Codes de sortie#

Les fichiers d’exemple#

Les transcriptions et les exemples ci-dessous utilisent les fichiers imprimés ici. Ils se trouvent dans le dépôt, sous tests/fixtures/swarm/, et ne font pas partie du paquet npm : ils sont donc donnés en entier. Créez-les sous swarm/ dans votre projet et les commandes reproduisent les transcriptions, à l’exception des identifiants d’exécution (une date et un suffixe aléatoire). Les six premiers appartiennent au panel d’acheteurs ; les trois derniers appartiennent à l’exemple de fanout en fin de page.

{
  "schemaVersion": 1,
  "id": "buyer-panel",
  "kind": "panel",
  "pack": "marketfit",
  "title": "Simulated buyers see the pitch",
  "units": { "source": "profile", "idPrefix": "B" },
  "brief": { "template": "briefs/buyer.md", "context": ["pitch"] },
  "answer": {
    "required": ["id", "buys", "reason_code", "reason"],
    "fields": {
      "buys": { "type": "boolean" },
      "reason_code": { "type": "enum", "values": ["price", "habit", "need", "trust", "other"] },
      "reason": { "type": "string", "max": 600 },
      "price_floor": { "type": "number", "min": 0 },
      "visits_per_week": { "type": "integer", "min": 0, "max": 14 },
      "would_tell": { "type": "list", "maxItems": 3 }
    }
  },
  "tally": {
    "rate": "buys",
    "groupBy": ["segment", "behaviour"],
    "counts": ["reason_code"],
    "quotes": { "reason": 2 },
    "numbers": ["price_floor"]
  },
  "disclosure": "Simulated units are not people. Read rates as an upper bound and confirm with real ones."
}

{
  "schemaVersion": 1,
  "subject": "Orbit espresso bar",
  "target": "Urban professionals who buy coffee most days",
  "dimensions": [
    {
      "name": "segment",
      "values": [
        { "value": "early career", "share": 0.45, "ranges": { "income": [38000, 85000] } },
        { "value": "mid career", "share": 0.4, "ranges": { "income": [85000, 150000] } },
        { "value": "high earner", "share": 0.15, "ranges": { "income": [150000, 210000] } }
      ]
    },
    {
      "name": "behaviour",
      "values": [
        { "value": "daily regular", "share": 0.2, "note": "same drink, same place, most mornings" },
        { "value": "explorer", "share": 0.5 },
        { "value": "occasional", "share": 0.3, "note": "a treat, not a routine" }
      ]
    }
  ],
  "ranges": { "age": [24, 38], "walk_minutes": [1.5, 12] },
  "pools": {
    "objection": ["too steep for a drink", "my place is closer", "I do not know the brand"],
    "habit": ["you pass the street on the way to work", "you order the same thing every day"]
  }
}

Orbit opens at 7, two streets from the station. A flat white is 4.20, the loyalty card gives
the tenth one free, and the bar keeps your usual order under your name.

# You are unit {{unit.id}} of run {{run.id}}

You are one simulated buyer. Stay inside this card for the whole task.

- Segment: {{card.segment}}, income {{card.income}}
- Behaviour: {{card.behaviour}} ({{card.behaviour_note}})
- Age {{card.age}}, {{card.walk_minutes}} minutes on foot from the bar
- Your first objection: {{card.objection}}
- Your habit: {{card.habit}}

## The pitch

{{context.pitch}}

## Your answer

Write a JSON object to `{{answer.path}}` with the fields `id` (exactly "{{unit.id}}"), `buys`,
`reason_code` (price, habit, need, trust or other), `reason` (your own words, 600 characters at
most) and, when you have one, `price_floor`.

{{disclosure}}

{ "id": "B001", "buys": true, "reason_code": "habit", "reason": "The loyalty card and my usual order under my name suit my mornings." }

{ "id": "B002", "buys": "maybe", "reason_code": "price", "reason": "Too steep for a drink." }

{
  "schemaVersion": 1,
  "units": [
    { "id": "about", "scope": "site/about", "title": "About us", "tone": "warm" },
    { "id": "pricing", "scope": ["site/pricing", "site/data/prices.json"], "title": "Pricing", "tone": "plain" },
    { "id": "contact", "scope": "site/contact", "title": "Contact", "tone": "short" }
  ]
}

{
  "schemaVersion": 1,
  "id": "site-pages",
  "kind": "fanout",
  "title": "One sub-agent per page of the site",
  "units": { "source": "input" },
  "brief": { "template": "briefs/page.md", "context": [] },
  "answer": {
    "required": ["id", "done", "words"],
    "fields": {
      "done": { "type": "boolean" },
      "words": { "type": "integer", "min": 0 },
      "note": { "type": "string", "max": 200 }
    }
  },
  "tally": { "rate": "done", "numbers": ["words"] },
  "disclosure": "Each page was written by a separate sub-agent from the same brief; read them together before publishing."
}

# Page {{unit.id}}

Write the page "{{card.title}}" under `{{card.scope}}`, {{card.tone}} in tone. Touch nothing
outside that folder.

When the page is written, write a JSON object to `{{answer.path}}` with `id` ("{{unit.id}}"),
`done`, `words` (the word count) and an optional `note`.

{{disclosure}}

Sortie réelle#

Ces transcriptions viennent de la recette humaine de 0.23.0 : un panel de 30 acheteurs simulés dans une application de démonstration, face au budget par défaut de 26. Les lignes npm notice et l’invite du shell sont retirées. La définition (swarm/buyer-panel.json) et le profil sont les fixtures de test du dépôt, copiées dans l’application de démonstration.

$ npx bmad-plus swarm init --definition swarm/buyer-panel.json --profile swarm/profile.json --context pitch=swarm/pitch.md --n 30 --seed 7 --directory .\demo-app
buyer-panel-20261018-ungp: needs approval. The run needs 30 sub-agents and the budget is 26: ask the user, then re-run init with --approved --seed 7.

$ npx bmad-plus swarm init --definition swarm/buyer-panel.json --profile swarm/profile.json --context pitch=swarm/pitch.md --n 30 --seed 7 --approved --directory .\demo-app
buyer-panel-20261018-oqu7: panel of 30 units, budget 26, approval user.
Seed 7 (same seed, same cards).
Next: bmad-plus swarm briefs buyer-panel-20261018-oqu7

$ npx bmad-plus swarm briefs buyer-panel-20261018-oqu7 --directory .\demo-app
buyer-panel-20261018-oqu7: 30 of 30 units need a sub-agent, in waves of 10.
Wave 1:
  B001  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B001.md
  B002  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B002.md
  B003  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B003.md
  B004  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B004.md
  B005  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B005.md
  B006  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B006.md
  B007  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B007.md
  B008  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B008.md
  B009  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B009.md
  B010  C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\briefs\B010.md
# Les vagues 2 (B011 à B020) et 3 (B021 à B030) suivent au même format ; elles sont omises ici.
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.

$ npx bmad-plus swarm save buyer-panel-20261018-oqu7 B001 --input swarm/reply-ok.json --directory .\demo-app
buyer-panel-20261018-oqu7: answer of B001 filed at C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\answers\B001.json
$ npx bmad-plus swarm check buyer-panel-20261018-oqu7 --directory .\demo-app
buyer-panel-20261018-oqu7: 1 of 30 valid answers.
  B002  missing: no answer file
  B003  missing: no answer file
# B004 à B030 sont listées de la même façon (27 lignes de plus).
$ npx bmad-plus swarm save buyer-panel-20261018-oqu7 B002 --input swarm/reply-bad.txt --directory .\demo-app
Swarm: Reply of unit B002 refused: field "buys" must be true or false.
$ npx bmad-plus swarm tally buyer-panel-20261018-oqu7 --directory .\demo-app
C:\Users\you\demo-app\.bmad-plus\swarm\runs\buyer-panel-20261018-oqu7\tally.md
1 of 30 units counted; 29 skipped.
Disclosure: Simulated units are not people. Read rates as an upper bound and confirm with real ones.

Comment le lire : le premier init a créé une exécution refusée (...-ungp) et rien d’autre ; l’exécution approuvée est une autre exécution (...-oqu7) avec son propre suffixe aléatoire. Seule B001 avait répondu : le décompte honnête compte 1 unité et nomme 29 unités ignorées ; la mention de transparence vient en premier, et c’est aussi la première ligne de tally.md. La réponse refusée n’a rien écrit pour B002.

Erreurs et que faire#

Exemples#

Lance le panel d’acheteurs de swarm/buyer-panel.json avec le profil swarm/profile.json et mon argumentaire dans swarm/pitch.md. Prends 30 acheteurs simulés et la graine 7.

Lance le panel d’acheteurs sur swarm/pitch-v1.md, puis à nouveau sur swarm/pitch-v2.md, avec le même profil, 24 acheteurs et la graine 7. Compare les deux décomptes.

Rédige les trois pages listées dans swarm/units.json avec un sous-agent par page, avec swarm/page-fanout.json. Exporte-le en plan Nexus pour que chaque page soit vérifiée avant que je l’accepte.