bmad-plus swarm

Ein Schwarm besteht aus vielen Sub-Agenten, die jeweils einmal dieselbe Art Arbeit tun: dreißig simulierte Käufer lesen einen Pitch, drei Juroren halten je eine Linse, ein Autor pro Seite. bmad-plus swarm ist die Buchführung darum herum. Es teilt die Einheiten aus, schreibt pro Sub-Agent ein Briefing, prüft jede Antwortdatei, legt eine Antwort ab, die ein Sub-Agent nur ausgegeben hat, und zählt die gültigen Antworten. Es ruft nie ein Modell auf, öffnet keine Netzverbindung und startet keinen Prozess: Dein Assistent (der Host-Assistent) startet die Sub-Agenten, der Befehl liest und schreibt nur Dateien unter .bmad-plus/swarm/. Nutze ihn, wenn ein Panel, eine Jury oder eine Auffächerung unabhängiger Einheiten gewünscht ist. 0.23.0 liefert in keinem Pack eine Schwarm-Definition mit; die Definitionsdatei stellst du oder ein Pack bereit.

Syntax#

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]

Die drei Schwarmarten#

Ein Panel und eine Jury laufen als Sitzungs-Sub-Agenten: Der Host startet sie, wartet und liest dann ihre Dateien. Ein Fanout kann ebenso laufen oder mit plan exportiert werden, wenn die Arbeit die Sitzung überdauern soll, eine unabhängige Prüfung je Einheit braucht oder das Repository ändert (siehe bmad-plus nexus). Die Definitionsdatei (JSON) benennt die Art, die Briefing-Vorlage, die Antwortfelder (boolean, integer, number, string, enum, list), die Auszählung und einen disclosure-Satz von 1 bis 500 Zeichen.

Budget, Wellen und Freigabe#

Drei Einstellungen im Block swarm von _bmad/config.yaml begrenzen einen Lauf. Fehlt die Datei oder der Block, gelten die Standardwerte unten; jeder andere Wert wird abgelehnt. init vergleicht die Zahl der Einheiten mit dem Budget: Ein größerer Lauf wird im Zustand needs-approval angelegt, schreibt kein Briefing und endet mit Code 2. Der Assistent muss dich dann in einem Satz mit der Zahl fragen und erst nach einem Ja init mit --approved und dem im Abbruch genannten Seed erneut ausführen.

Die sieben Aktionen#

Übliche Reihenfolge: init, dann briefs; der Host startet je Briefing einen Sub-Agenten mit genau der Anweisung „Read the brief and follow it exactly; it is your whole instruction“, danach check. Führe briefs ein weiteres Mal aus, um fehlenden Einheiten eine zweite Chance zu geben (es rendert nur Einheiten ohne gültige Antwort), lege jede ausgegebene Antwort mit save ab, dann tally. Eine Einheit, die nach der zweiten Welle noch fehlt, bleibt fehlend und wird in der Auszählung genannt. inspect fasst einen Lauf jederzeit zusammen, ohne zu schreiben.

Der Laufbaum#

.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)

Das 4-Zeichen-Suffix ist zufällig, und ein vorhandenes Verzeichnis wird nie wiederverwendet. Eingaben werden bei init eingefroren: Eine spätere Änderung an einem Kontext oder der Definition ändert für diesen Lauf nichts. Zustände: needs-approval (endgültig), ready, briefed, tallied. Eine Auszählung lässt sich wiederholen, ebenso briefs nach einer Auszählung. Mit --out angeforderte Berichte liegen unter .bmad-plus/swarm/reports/<run id>/.

Ehrlichkeitsregeln#

• Simulierte Einheiten sind keine Menschen. Die Auszählung beginnt mit dem Offenlegungshinweis (disclosure) der Definition, vor jeder Zahl. Quoten eines Panels sind eine Obergrenze, die mit echten Menschen zu bestätigen ist, nie eine Messung.
• Zitate sind simuliert: Gib sie als das wieder, was eine simulierte Einheit geschrieben hat, nie als Zeugnis oder Interview.
• Der Moderator antwortet nie für eine Einheit: keine handgeschriebene Antwortdatei, kein „Reparieren“ einer ungültigen. save extrahiert und prüft nur, was ein Sub-Agent ausgegeben hat.
• Briefings werden nie bearbeitet. Eine Änderung gehört in Vorlage oder Definition und dann in einen neuen Lauf.
• Gleicher Seed, gleiche Karten: Ein Vorher-nachher-Vergleich zweier Pitches wiederholt dasselbe Profil mit demselben --n und --seed, sodass sich nur der Kontext ändert.
• Die Laufzeit filtert nichts: Kartenwerte, Pool-Einträge und Kontextdateien erreichen den Sub-Agenten wortgleich. Lies einen Kontext, bevor du ihn übergibst; er wird in jedes Briefing kopiert, samt Geheimnissen und Anweisungen.
• Eine gültige Antwort ist eine wohlgeformte Antwort. Nichts beweist, dass ein Sub-Agent sein Briefing gelesen oder die Wahrheit gesagt hat.

Lesen, Schreiben und Grenzen#

• Schreibt nur unter .bmad-plus/swarm/. --out bei tally und plan muss in .bmad-plus/swarm/reports/<run id>/ oder im eigenen Baum des Laufs bleiben, nie über answers/, briefs/, context/, checks/, run.json, cards.json, definition.json, template.md, nexus-plan.json, tally.json oder tally.md.
• Jeder Pfad, den du nennst (--definition, --profile, --units, --context, --input), ist projektrelativ mit /; absolute Pfade, Backslashes, .., .git und alles über einen Symlink werden abgelehnt. Diese Dateien dürfen nicht aus .bmad-plus/ stammen.
• Grenzen: 1 bis 1000 Einheiten je Lauf; Budget und Welle 1 bis 1000; Seed 0 bis 2147483647; Eingaben höchstens 16 MiB; eine ausgegebene Antwort für save höchstens 1 MiB; höchstens 50 Antwortfelder; höchstens 20 Kontexte je Definition; höchstens 5 groupBy-Felder.
• Einheiten-IDs bestehen aus Buchstaben, Ziffern, _ oder - (bis 64 Zeichen; bei einem Fanout klein geschrieben). IDs eines ausgeteilten Panels sind das Präfix plus die auf mindestens drei Stellen aufgefüllte Position (B001).
• Dateien werden über eine temporäre Datei geschrieben und umbenannt. Kein Netzwerk, kein Kindprozess, kein eval.

Exit-Codes#

Die Beispieldateien#

Die Mitschriften und Beispiele unten verwenden die hier abgedruckten Dateien. Sie liegen im Repository unter tests/fixtures/swarm/ und gehören nicht zum npm-Paket, daher stehen sie vollständig hier: Lege sie unter swarm/ in deinem Projekt an, dann reproduzieren die Befehle die Mitschriften, abgesehen von den Lauf-IDs (ein Datum und ein zufälliges Suffix). Die ersten sechs gehören zum Käufer-Panel, die letzten drei zum Fanout-Beispiel am Ende der Seite.

{
  "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}}

Echte Ausgabe#

Diese Mitschnitte stammen aus dem menschlichen Abnahmelauf von 0.23.0: ein Panel aus 30 simulierten Käufern in einer Demo-App, gegen das Standardbudget von 26. Die npm notice-Zeilen und der Shell-Prompt sind entfernt. Definition (swarm/buyer-panel.json) und Profil sind die Test-Fixtures des Repositorys, in die Demo-App kopiert.

$ 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
# Die Wellen 2 (B011 bis B020) und 3 (B021 bis B030) folgen im selben Format; sie sind hier ausgelassen.
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 bis B030 sind genauso aufgeführt (27 weitere Zeilen).
$ 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.

So liest du es: Das erste init hat einen abgelehnten Lauf (...-ungp) angelegt und sonst nichts; der freigegebene ist ein anderer Lauf (...-oqu7) mit eigenem Zufallssuffix. Nur B001 hatte geantwortet, daher zählt die ehrliche Auszählung 1 Einheit und nennt 29 übersprungene; der Offenlegungshinweis steht zuerst und ist auch die erste Zeile von tally.md. Die abgelehnte Antwort hat für B002 nichts geschrieben.

Fehler und was zu tun ist#

Beispiele#

Starte das Käufer-Panel aus swarm/buyer-panel.json mit dem Profil swarm/profile.json und meinem Pitch in swarm/pitch.md. Nimm 30 simulierte Käufer und Seed 7.

Starte das Käufer-Panel mit swarm/pitch-v1.md und danach noch einmal mit swarm/pitch-v2.md, mit demselben Profil, 24 Käufern und Seed 7. Vergleiche die beiden Auszählungen.

Schreibe die drei Seiten aus swarm/units.json mit einem Sub-Agenten pro Seite, mit swarm/page-fanout.json. Exportiere es als Nexus-Plan, damit jede Seite geprüft ist, bevor ich sie annehme.