# bmad-plus swarm
> Einen Schwarm von Sub-Agenten im Budget austeilen, briefen, prüfen, ablegen und auszählen: Panel, Jury oder Fanout. Optionen, Laufbaum, Freigabe bei Code 2, Ehrlichkeitsregeln, echte Ausgabe, Fehler.
Canonical: https://bmad-plus.rochetta.fr/de/docs/reference/cli-swarm/
Language: de
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT
BMAD+ Dokumentation › [Referenz](https://bmad-plus.rochetta.fr/de/docs/reference/) › 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
**Im Terminal deines Projekts**
```sh
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]
```
**Optionen von bmad-plus swarm**
| Option | Argument | Standard | Wirkung |
| --- | --- | --- | --- |
| `` | `init`, `briefs`, `check`, `save`, `tally`, `inspect`, `plan` | Pflicht | Der auszuführende Schritt. |
| `[run]`, `[unit]` | Lauf-ID, Einheiten-ID | keine | Lauf-ID wie `buyer-panel-20261018-oqu7` (jede Aktion außer `init`); Einheiten-ID wie `B002` (nur `save`). |
| `-d, --directory ` | Pfad | aktuelles Verzeichnis | Projektverzeichnis. |
| `--definition ` | Pfad | keiner | Schwarm-Definition, projektrelatives JSON. Nur `init`; Pflicht. |
| `--profile ` | Pfad | keiner | Panel-Profil, projektrelatives JSON. `init`; Pflicht bei einem Panel, bei anderen Arten abgelehnt. |
| `--units ` | Pfad | keiner | Fanout-Einheiten, projektrelatives JSON. `init`; Pflicht bei einem Fanout, bei anderen Arten abgelehnt. |
| `--context ` | NAME=DATEI | keiner | Kontextdatei, unverändert in jedes Briefing übernommen. Wiederholbar. Jeder in der Definition deklarierte Name ist Pflicht; ein nicht deklarierter Name wird abgelehnt. |
| `--n ` | ganze Zahl 1 bis 1000 | keiner | Anzahl der auszuteilenden Einheiten bei einem Panel. Bei Jury oder Fanout abgelehnt. |
| `--seed ` | ganze Zahl 0 bis 2147483647 | einmal gezogen, dann gespeichert | Seed der Austeilung. Nur Panel. Gleiches Profil, gleiches `--n`, gleicher Seed: gleiche Karten. |
| `--approved` | keiner | aus | Hält fest, dass ein Mensch der Überschreitung des Budgets zugestimmt hat. Nie auf eigene Faust setzen. |
| `--wave ` | ganze Zahl 1 bis 1000 | konfigurierte Welle (10) | Gleichzeitig gestartete Sub-Agenten. Nur `briefs`. |
| `--input ` | Pfad | keiner | Antwort, die ein Sub-Agent ausgegeben hat. Nur `save`; Pflicht; außerhalb von `.bmad-plus/`; höchstens 1 MiB. |
| `--out ` | Pfad | im Lauf | Ausgabedatei für `tally` und `plan`. Muss unter `.bmad-plus/swarm/` liegen (siehe Lesen, Schreiben und Grenzen). |
| `--json` | keiner | aus | Maschinenlesbare Ausgabe mit `schemaVersion: 1` und einem Feld `status`. |
## Die drei Schwarmarten
**Arten, festgelegt durch die Definitionsdatei**
| Art | Die Einheiten stammen aus | Typischer Einsatz | Auszählung |
| --- | --- | --- | --- |
| `panel` | Ein Profil: Dimensionen mit Anteilen, nach exakter Quote und mit Seed ausgeteilt (`--profile`, `--n`, `--seed`). | Simulierte Käufer, Leser oder Nutzer, die einen Pitch lesen. | Quote je Gruppe, Zählungen, Zitate, Zahlen. |
| `jury` | Die Definition selbst: einzeln aufgelistete Einheiten mit je einer `lens`. | Eine kritische Gegenlesung eines Pitches, einer Seite oder eines Plans. | Zählungen und Zitate je Linse. |
| `fanout` | Eine Einheiten-Datei (`--units`): Jede Einheit hat einen eigenen, disjunkten Schreib-`scope`. | Zu schreibende Seiten, zu dokumentierende Module: unabhängige Arbeit parallel. | Quote und Zahlen; mit `plan` als dauerhafter Nexus-Plan exportierbar. |
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.
**Der Block swarm in _bmad/config.yaml**
| Schlüssel | Standard | Erlaubt | Wirkung |
| --- | --- | --- | --- |
| `budget` | 26 | ganze Zahl 1 bis 1000 | Sub-Agenten, die ein Lauf nutzen darf, bevor der Host dich fragen muss. |
| `wave` | 10 | ganze Zahl 1 bis 1000 | Gleichzeitig gestartete Sub-Agenten; `briefs` gruppiert die offenen Einheiten in Wellen dieser Größe (mit `--wave` überschreibbar). |
| `media_credits` | `ask` | genau `ask` | Bezahlte Bild-, Video- oder Audiogenerierung ist nie durch ein Budget gedeckt: Der Host fragt vor jedem solchen Lauf. |
> **Warnung · Die Freigabe gehört einem Menschen** `--approved` wird im Lauf als `approval: user` gespeichert. Der Swarm-Skill erlaubt es nur nach einem menschlichen Ja, egal wie viele Einheiten es sind. Ein Lauf wird nie nach dem eigenen Ermessen des Assistenten freigegeben.
## Die sieben Aktionen
**Was jede Aktion liest und schreibt**
| Aktion | Liest | Schreibt | Exit |
| --- | --- | --- | --- |
| `init` | Definition, Vorlage, Profil oder Einheiten, Kontexte, `_bmad/config.yaml`. | Den Laufbaum (eingefrorene Eingaben und `run.json`). | 0 bereit, 2 Freigabe nötig, 1 abgelehnt. |
| `briefs RUN` | Den Laufbaum und die Antworten. | Ein Briefing für jede Einheit ohne gültige Antwort; das Verzeichnis `answers/`. | 0, oder 2 wenn der Lauf eine Freigabe braucht. |
| `check RUN` | Den Laufbaum und die Antworten. | Nichts. | 0 vollständig, 1 unvollständig. |
| `save RUN UNIT --input F` | Den Laufbaum und die Antwortdatei. | `answers/.json`. | 0 abgelegt, 1 abgelehnt. |
| `tally RUN [--out F]` | Den Laufbaum und die Antworten. | `tally.json` und `tally.md` (oder `--out`). | 0, oder 2 wenn der Lauf eine Freigabe braucht. |
| `inspect RUN` | Den Laufbaum, Antworten, Briefings. | Nichts. | 0. |
| `plan RUN [--out F]` | Den Laufbaum (nur Fanout). | Alle Briefings, `checks/`, `nexus-plan.json` (oder `--out`). | 0 geplant, 2 Freigabe nötig, 1 kein Fanout. |
Ü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
**Von init in deinem Projekt angelegt**
```text
.bmad-plus/swarm/runs/--<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/.md each context file, frozen
briefs/.md written by briefs (and plan)
answers/.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//`.
## 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//` 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
**Exit-Codes von bmad-plus swarm**
| Code | Bedeutung |
| --- | --- |
| 0 | Die Aktion war erfolgreich; bei `check` hat jede Einheit eine gültige Antwort. |
| 1 | `check` fand fehlende oder ungültige Einheiten (Status `incomplete`) oder irgendein Fehler (ausgegeben als `Swarm: `). |
| 2 | Status `needs-approval`: Der Lauf hat mehr Einheiten als das Budget und kein `--approved`. Eine Person fragen, dann `init --approved --seed ` erneut ausführen. `briefs`, `save`, `tally` und `plan` auf einem solchen Lauf enden ebenfalls mit 2 und schreiben nichts. |
## 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.
**swarm/buyer-panel.json, die Definition des Panels**
```json
{
"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."
}
```
**swarm/profile.json, das Profil, aus dem die 30 Käuferkarten verteilt werden**
```json
{
"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"]
}
}
```
**swarm/pitch.md, der Text, den die Käufer lesen**
```md
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.
```
**swarm/briefs/buyer.md, die Briefing-Vorlage (jeder Platzhalter in doppelten geschweiften Klammern wird pro Einheit gefüllt)**
```md
# 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}}
```
**swarm/reply-ok.json, eine gültige Antwort für die Einheit B001**
```json
{ "id": "B001", "buys": true, "reason_code": "habit", "reason": "The loyalty card and my usual order under my name suit my mornings." }
```
**swarm/reply-bad.txt, eine Antwort, die der Validator ablehnt (buys muss true oder false sein)**
```json
{ "id": "B002", "buys": "maybe", "reason_code": "price", "reason": "Too steep for a drink." }
```
**swarm/units.json, die drei Seiten des Fanout-Beispiels**
```json
{
"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" }
]
}
```
**swarm/page-fanout.json, die Fanout-Definition**
```json
{
"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."
}
```
**swarm/briefs/page.md, die Briefing-Vorlage des Fanouts**
```md
# 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.
**30 Einheiten gegen ein Budget von 26: abgelehnt (Exit-Code 2)**
```text
$ 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.
```
Ausgabe eines echten Laufs. Quelle: Aufgezeichnet im Abnahmelauf der 0.23.0 am 2026-10-18 (Schritt 6)
**Nach einem menschlichen Ja: --approved mit demselben Seed**
```text
$ 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
```
Ausgabe eines echten Laufs. Quelle: Aufgezeichnet im Abnahmelauf der 0.23.0 am 2026-10-18 (Schritt 6)
**Briefings, in Wellen zu 10**
```text
$ 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.
```
Ausgabe eines echten Laufs. Quelle: Aufgezeichnet im Abnahmelauf der 0.23.0 am 2026-10-18 (Schritt 6; Wellen 2 und 3 gekürzt)
**Eine gültige Antwort, eine abgelehnte Antwort, die Auszählung**
```text
$ 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.
```
Ausgabe eines echten Laufs. Quelle: Aufgezeichnet im Abnahmelauf der 0.23.0 am 2026-10-18 (Schritt 6; die 27 weiteren fehlenden Zeilen von check sind gekürzt; der erste Befehl (Ablage von B001) wurde danach mit demselben Paket nachgespielt; der Offenlegungshinweis (Disclosure) ist der, den derselbe Lauf aus den Briefings ausgab)
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
**Meldungen von bmad-plus swarm**
| Meldung | Ursache | Was tun |
| --- | --- | --- |
| `: needs approval. The run needs N sub-agents and the budget is B: ask the user, then re-run init with --approved --seed S.` (Code 2) | Mehr Einheiten als `swarm.budget` und kein `--approved`. | Eine Person in einem Satz mit der Zahl fragen. Nach einem Ja `init` mit `--approved --seed S` erneut ausführen. Oder `--n` senken beziehungsweise `swarm.budget` in `_bmad/config.yaml` erhöhen. |
| `Swarm: Use swarm init --definition FILE [--profile FILE \| --units FILE] …` | Unbekannte Aktion, oder Lauf-ID beziehungsweise Einheiten-ID fehlt oder steht an der falschen Stelle. | Syntax prüfen: `save` nimmt Lauf und Einheit, die übrigen Aktionen nach `init` nur einen Lauf. |
| `Swarm: init needs --definition FILE.` | `init` ohne Definition. | `--definition` angeben. |
| `Swarm: A panel needs --profile FILE.` / `A panel needs --n, the number of units to deal.` / `A panel takes --profile, not --units.` | Panel ohne seine Eingaben gestartet. | `--profile` und `--n` ergänzen; `--units` nicht angeben. |
| `Swarm: Only a panel takes --profile.` / `A jury has as many units as it lists; --n does not apply.` / `A seed only applies to a dealt panel.` / `A fanout needs --units FILE.` | Optionen, die nicht zur Art in der Definition passen. | Option entfernen oder die richtige Definition verwenden. |
| `Swarm: The definition needs --context NAME=FILE.` / `Context "x" is not declared by the definition.` / `A context is written NAME=FILE: …` | Ein deklarierter Kontext fehlt, ein überzähliger wurde übergeben, oder die Form ist falsch. | Genau die in der Definition deklarierten Kontexte übergeben, als `--context name=path`. |
| `Swarm: _bmad/config.yaml: swarm.media_credits must be "ask".` / `…swarm.budget must be an integer from 1 to 1000.` / `…swarm has an unknown key "x".` | Der Block `swarm` enthält einen Wert oder Schlüssel, den die Laufzeit ablehnt. | Block korrigieren oder löschen, um die Standardwerte (26, 10, `ask`) zu erhalten. |
| `Swarm: Definition does not exist: …` / `…is not valid JSON: …` / `…exceeds N bytes` / `…is not a regular file` | Die Eingabedatei fehlt, ist fehlerhaft, zu groß oder keine Datei. | Pfad oder JSON korrigieren. |
| `Swarm: … may not reach .git` / `… may not come from the BMAD+ state tree` / `… refused: … (…)` | Der Pfad zeigt in `.git`, nach `.bmad-plus/`, aus dem Projekt hinaus oder über einen Link. | Einen projektrelativen Pfad mit `/` außerhalb von `.bmad-plus/` verwenden. |
| `Swarm: Tally groupBy field "f" is absent from unit U.` | Einer Karte fehlt ein Feld, nach dem die Auszählung gruppiert. | Das Feld in Profil, Liste oder Einheiten-Datei ergänzen oder aus `tally.groupBy` streichen. |
| `Swarm: A run id reads --<4 characters>.` / `Run record is not usable: …` | Falsche Lauf-ID oder beschädigter Laufbaum. | Die von `init` ausgegebene ID kopieren; wurde der Baum bearbeitet, einen neuen Lauf beginnen. |
| `Swarm: Reply of unit U refused: …` / `No JSON object found in the reply filed for unit U.` | Die ausgegebene Antwort enthält kein JSON-Objekt oder verletzt den Antwortvertrag (falscher Typ, fehlendes Feld, falsche ID). | Es wurde nichts geschrieben. Den Sub-Agenten erneut fragen (`briefs` erneut ausführen) oder die Einheit fehlen lassen. Die Antwort nicht selbst schreiben. |
| `Swarm: Unit U already has a valid answer; it is kept.` / `Unknown unit U in run R.` | `save` bei einer bereits beantworteten oder im Lauf nicht vorhandenen Einheit. | Mit `check` sehen, welche Einheiten offen sind. |
| `Swarm: save needs --input FILE, the reply the sub-agent printed.` | `save` ohne `--input`. | Die Antwort in eine Projektdatei außerhalb von `.bmad-plus/` legen und angeben. |
| `Swarm: --out must stay under … or …` / `--out may not write inside …` / `--out may not replace the run file …` | `--out` zeigt dorthin, wo `tally` oder `plan` nicht schreiben dürfen. | Einen Pfad unter `.bmad-plus/swarm/reports//` verwenden. |
| `Swarm: Only a fanout exports a Nexus plan; run R is a panel.` | `plan` bei einem Panel oder einer Jury. | `plan` nur mit einem Fanout verwenden. |
## Beispiele
### Ein Panel simulierter Käufer im Budget
Du hast eine Schwarm-Definition, ein Profil und eine Pitch-Datei. Das Standardbudget liegt bei 26 Sub-Agenten; du verlangst 30.
**In deinem KI-Assistenten**
```text
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.
```
**Das solltest du erhalten** Der Assistent führt `swarm init` aus. Dreißig Einheiten übersteigen das Budget von 26, also endet der Befehl mit Code 2 und schreibt kein Briefing; der Assistent sagt dir „30 Sub-Agenten bei einem Budget von 26“ und fragt nach. Nach deinem Ja führt er `init` erneut mit `--approved --seed 7` aus, erhält eine Lauf-ID, führt `briefs` aus (drei Wellen zu 10), startet je Briefing einen Sub-Agenten mit der festen Anweisung, führt dann `check` aus, gibt fehlenden Einheiten eine zweite Chance und schließt mit `tally`. Sein Bericht beginnt mit dem Offenlegungshinweis, nennt, wie viele Einheiten gezählt und wie viele übersprungen wurden, und stellt Quoten als Obergrenze dar.
### Zwei Fassungen eines Pitches vergleichen
Dasselbe Panel, zweimal mit demselben Seed ausgeführt, unterscheidet sich nur in der Pitch-Datei.
**In deinem KI-Assistenten**
```text
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.
```
**Das solltest du erhalten** Vierundzwanzig Einheiten passen in das Standardbudget von 26, daher braucht keines der beiden `init` eine Freigabe. Da Profil, `--n` und `--seed` identisch sind, teilen beide Läufe dieselben 24 Karten aus; nur `{{context.pitch}}` unterscheidet sich in den Briefings. Jeder Lauf hat eigene ID und `tally.md`. Der Vergleich wird als Differenz zweier simulierter Obergrenzen berichtet, mit dem Disclosure zuerst, nicht als gemessene Änderung der Conversion.
### Ein Autor pro Seite, von Nexus geprüft
Eine Fanout-Definition und eine Einheiten-Datei geben jeder Seite einen eigenen Schreibbereich. Die Arbeit soll die Sitzung überdauern, daher wird sie als dauerhafter Plan exportiert.
**In deinem KI-Assistenten**
```text
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.
```
**Das solltest du erhalten** Der Assistent führt `swarm init` mit `--definition` und `--units` aus, dann `swarm plan RUN`. Der Plan hat eine Aufgabe je Einheit: ihren Bereich plus ihre Antwortdatei, ihr Briefing und die eingefrorenen Dateien als Ressourcen, eine Prüfung `node checks/answer.cjs --unit=`, `maxAttempts` 2 und `maxParallel` gleich der konfigurierten Welle, gedeckelt bei 32. `plan` gibt den Planpfad und `Next: bmad-plus nexus create --plan ` aus. Von dort an startet, prüft und akzeptiert Nexus jede Aufgabe; eine Einheit mit fehlerhafter Antwortdatei besteht ihre Prüfung nicht und wird wiederholt, nicht akzeptiert.
**Siehe auch**
- [bmad-plus nexus: einen exportierten Fanout-Plan ausführen](https://bmad-plus.rochetta.fr/de/docs/reference/cli-nexus/)
- [bmad-plus intake: die Fragen vor einem Schwarm](https://bmad-plus.rochetta.fr/de/docs/reference/cli-intake/)
- [config.yaml: der Block swarm](https://bmad-plus.rochetta.fr/de/docs/reference/config-yaml/#swarm-block)
- [Projektstruktur: .bmad-plus/swarm/](https://bmad-plus.rochetta.fr/de/docs/reference/project-layout/)
- [Fehlerbehebung](https://bmad-plus.rochetta.fr/de/docs/faq/troubleshooting/)
[BMAD+ Dokumentation](https://bmad-plus.rochetta.fr/de/docs/) · [Referenz](https://bmad-plus.rochetta.fr/de/docs/reference/)
[Quellcode auf GitHub](https://github.com/lrochetta/BMAD-PLUS)