Swarms of sub-agents

A swarm is many sub-agents doing the same kind of work once each: thirty simulated buyers reading a pitch, three jurors reading it through one lens each, one writer per page of a site. The moderator is your assistant; it never does a unit’s work. bmad-plus swarm is the bookkeeper: it validates the files, deals the units, writes one brief per sub-agent, checks every answer file and counts only the valid ones. It never calls a model, never opens a network connection and never starts a process. This page is for anyone who wants to test a message, a page or a plan against many readers, or to split repeated work across sub-agents under a budget.

When to use a swarm#

A panel and a jury run as session sub-agents: your assistant launches them, waits, and reads their files. A fanout can run the same way, or be exported with swarm plan as a durable Nexus plan when the work must survive the session, needs an independent check per unit, or edits the repository.

When not to use one#

• When you can ask real people. A swarm rehearses; it does not measure.
• For two or three tasks. Ask the agent directly, or use Nexus parallel.
• For work where one result depends on another. Units are independent by construction.
• To generate paid media. Image, video and audio generation is never covered by the budget: the assistant asks every time.

In 0.23.0 no pack ships a swarm definition: the runtime and the moderator skill are Core, and the definitions used on this page are test fixtures in the BMAD+ repository (tests/fixtures/swarm/). A pack, or you, supply the definition. These files are not in the npm package, so this page prints each one in full: you can create them as they are.

The flow, end to end#

definition + profile|list|units + context
        |
      init ---- over budget? exit 2 "needs approval": ask a human, re-run with --approved
        |
   cards.json  (frozen)
        |
     briefs ---- one brief per unit, in waves
        |
  one sub-agent per brief  ->  answers/<unit>.json
        |
      check ---- missing / invalid, with reasons
        |  (second chance once; save files a printed reply)
      tally ---- tally.json + tally.md, disclosure first

1. 01

   init

   Validates the definition, the profile or units file, the context files and the brief template; deals or lists the cards; applies the budget. A panel needs --n (1 to 1000); the seed is drawn and recorded when you do not give one. A run larger than the budget stops here with exit code 2.

   In your project terminal

   npx bmad-plus swarm init --definition swarm/buyer-panel.json --profile swarm/profile.json --context pitch=swarm/pitch.md --n 30 --seed 7

2. 02

   briefs

   Renders one brief per unit that has no valid answer yet, from the frozen template, the card and the frozen contexts, and prints the waves (10 units per wave unless --wave says otherwise) with the brief path of each unit.

   In your project terminal

   npx bmad-plus swarm briefs RUN

3. 03

   Launch a wave

   Your assistant starts one sub-agent per brief with exactly one instruction: read the brief and follow it exactly; it is the whole instruction. It does not summarise the brief, add context or merge two units into one sub-agent. It waits for the whole wave before the next.

4. 04

   check

   Lists every unit whose answer is missing or invalid, with the reason. Exit code 0 when all units are valid, 1 otherwise.

   In your project terminal

   npx bmad-plus swarm check RUN

5. 05

   Second chance, once

   Run briefs again (it only renders units without a valid answer) and relaunch those units. A unit that printed its answer instead of writing it is filed with save RUN UNIT --input FILE, where the file holds that unit’s reply verbatim. A unit still missing after the second wave stays missing.

   In your project terminal

   npx bmad-plus swarm save RUN B005 --input swarm-inbox/B005.txt

6. 06

   tally

   Counts valid answers only and writes tally.json and tally.md. Units without a valid answer are listed as skipped and counted in the denominator line. The disclosure is the first line of tally.md.

   In your project terminal

   npx bmad-plus swarm tally RUN

7. 07

   plan (fanout only)

   Instead of running the sub-agents inside the session, exports the fanout as a Nexus plan. See the Nexus page.

   In your project terminal

   npx bmad-plus swarm plan RUN --out .bmad-plus/swarm/reports/RUN/plan.json

swarm inspect RUN prints the state of a run (units, briefed, valid, invalid, missing) at any time and writes nothing. Exit codes: 0 done, 2 needs-approval (a human must say yes first), 1 incomplete or error. With --json, every answer carries schemaVersion: 1 and a status.

The budget, the waves and the approval#

Three keys in the swarm block of _bmad/config.yaml set the limits. The installer writes the block with its defaults; a project updated from an earlier version has no block and gets the same defaults.

When n is larger than the budget and --approved is absent, init creates the run with the status needs-approval, exits with 2 and writes no brief. The assistant asks you one sentence with the number ("This panel needs 30 sub-agents; the budget is 26. Run it?"). Only after your yes does it re-run init with --approved and the same seed. It never passes --approved on its own judgement. The refused run is terminal: later commands on it answer needs-approval and write nothing.

$ npx bmad-plus swarm init --definition swarm/buyer-panel.json --profile swarm/profile.json --context pitch=swarm/pitch.md --n 30 --seed 7
buyer-panel-20261019-g1i9: 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. No brief was written.
$ npx 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-20261019-vqkf: panel of 30 units, budget 26, approval user.
Seed 7 (same seed, same cards).
Next: bmad-plus swarm briefs buyer-panel-20261019-vqkf

The four files, field by field#

The runtime refuses an unknown field, a wrong type and a bound breach; it never guesses. Every path is project-relative with / separators. The brief template path is relative to the definition file.

1. The definition (JSON)#

2. The profile (panel only)#

Card fields are the dimension names, their range names, the top-level range names, the pool names and the notes. Names must be distinct, and id, scope and lens are reserved. Names of people are not dealt: a brief that wants one draws it from a pool the pack supplies.

3. The units file (fanout only)#

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

• id: 1 to 64 lowercase letters, digits, _ or -. It becomes a Nexus task id.
• scope: one path or a list of up to 20, portable and project-relative, never .git or .bmad-plus. Scopes are pairwise disjoint: no scope may contain another.
• Every other field must be a text, number or boolean; it becomes a card field available as {{card.field}} in the brief.

The definition that goes with this units file has no profile; init takes the units with --units, for instance npx bmad-plus swarm init --definition swarm/page-fanout.json --units swarm/units.json. This is the definition of the site-pages fanout used in the example at the end of this page, followed by its brief template.

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

4. The brief template (Markdown) and the contexts#

Deterministic dealing and seeds#

The same profile, the same --n and the same --seed always give the same cards. Each dimension is distributed by exact quota (largest remainder, ties by declaration order): with shares of 0.45, 0.40 and 0.15, twenty cards hold 9, 8 and 3 units of those values whatever the seed. The column of values is then shuffled by a generator based on SHA-256, and card k takes position k of every column; ranges and pool entries follow, in order. The seed (0 to 2147483647) is recorded in run.json.

This is what makes a before and after comparison honest. To test two versions of a pitch, run the same profile with the same --n and --seed and change only the context file: the buyers are the same, so the only thing that changed is the pitch. Unit ids are the prefix plus the position padded to at least three digits (B001, B030, B1000).

Refused replies and what is never done#

An answer counts only if answers/<unit>.json is a regular file, parses as a JSON object, carries id equal to the unit id and every required field, declares no unknown field and satisfies every type and bound. check reports a unit as missing (no file) or invalid (with the reasons). save applies the same rules to the first balanced JSON object found in a printed reply, and refuses when none is found, when it fails validation (a wrong id included), when the unit already has a valid answer and on a run that still needs approval. A refused reply changes nothing on disk.

$ npx bmad-plus swarm save buyer-panel-20261019-2ftt B005 --input swarm-inbox/B005.txt
buyer-panel-20261019-2ftt: answer of B005 filed at /work/demo/app/.bmad-plus/swarm/runs/buyer-panel-20261019-2ftt/answers/B005.json
$ npx bmad-plus swarm save buyer-panel-20261019-2ftt B006 --input swarm-inbox/B006.txt
Swarm: Reply of unit B006 refused: field "buys" must be true or false.
# The first file holds a sentence followed by a valid JSON object; the second holds an object whose buys field is the text "maybe". Exit codes 0 and 1.

The honesty rules#

• Never answer for a unit: not by writing an answer file, not by "fixing" an invalid one, not by filing with save something a sub-agent did not print.
• Never edit a brief. A change belongs in the template or the definition, then in a new run.
• The disclosure comes once and first: the tally starts with it, and the assistant repeats it once in its report, before any figure.
• Rates are an upper bound to confirm with real people. Quotes are what a simulated unit wrote.
• The seed travels with the result: same seed, same cards, so a comparison is a comparison.
• A valid answer is a well-formed one. Nothing proves that a sub-agent read its brief, stayed in its card or wrote the truth; quality is your reading of the tally.
• Replies are filed from outside the state tree: save --input takes a project file the host wrote (for instance in swarm-inbox/), never a path under .bmad-plus/.

A worked buyer panel#

The scenario: a coffee bar called Orbit wants to know how an urban professional reacts to its pitch. The files below are the test fixtures of the BMAD+ repository, used here unchanged: the definition, the profile and the brief template. The pitch itself is two sentences.

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

# 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}}

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.

Seed 7 and 30 units deal this first card (from cards.json). The brief the sub-agent receives is the template with this card, the pitch and the answer path filled in.

{
  "id": "B001",
  "segment": "mid career",
  "income": 114720,
  "behaviour": "occasional",
  "behaviour_note": "a treat, not a routine",
  "age": 32,
  "walk_minutes": 8.99,
  "objection": "I do not know the brand",
  "habit": "you order the same thing every day"
}

In the transcript below, the assistant would launch 30 sub-agents in three waves. To show the files, the tool and the tally without any model, five of the answers were written by hand for this demonstration (four as files, one through save), and a sixth reply was refused. So the tally counts 5 of 30 units and names the 25 others. The quotes below are therefore not what a model wrote either: they are demonstration text.

answers/B001.json    { "id": "B001", "buys": true, "reason_code": "habit", "reason": "The bar keeps my usual order under my name, so I would stop at a tenth coffee for free.", "price_floor": 3.8 }
answers/B002.json    { "id": "B002", "buys": false, "reason_code": "price", "reason": "A flat white at 4.20 is more than my usual place, and it is closer.", "price_floor": 3.2 }
answers/B003.json    { "id": "B003", "buys": true, "reason_code": "need", "reason": "Opening at seven fits my route to the station, and I order the same drink every morning.", "price_floor": 4.5 }
answers/B004.json    { "id": "B004", "buys": false, "reason_code": "trust", "reason": "I do not know the brand and nothing in the pitch tells me why I should switch.", "price_floor": 3.5 }
swarm-inbox/B005.txt Here is my answer as a buyer.
                     { "id": "B005", "buys": true, "reason_code": "habit", "reason": "Same drink, same place, most mornings: the loyalty card would pay for itself.", "price_floor": 4.2 }
swarm-inbox/B006.txt { "id": "B006", "buys": "maybe", "reason_code": "other", "reason": "I could go either way." }

$ npx bmad-plus swarm briefs buyer-panel-20261019-2ftt
buyer-panel-20261019-2ftt: 30 of 30 units need a sub-agent, in waves of 10.
Wave 1:
  B001  /work/demo/app/.bmad-plus/swarm/runs/buyer-panel-20261019-2ftt/briefs/B001.md
  B002  /work/demo/app/.bmad-plus/swarm/runs/buyer-panel-20261019-2ftt/briefs/B002.md
# ... units B003 to B010, then waves 2 and 3 (B011 to B030) ...
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.
# Four answer files (B001 to B004) are now written by hand into answers/.
$ npx bmad-plus swarm check buyer-panel-20261019-2ftt
buyer-panel-20261019-2ftt: 4 of 30 valid answers.
  B005  missing: no answer file
  B006  missing: no answer file
# ... and so on up to B030. Exit code 1.
$ npx bmad-plus swarm tally buyer-panel-20261019-2ftt
/work/demo/app/.bmad-plus/swarm/runs/buyer-panel-20261019-2ftt/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.
$ npx bmad-plus swarm inspect buyer-panel-20261019-2ftt
buyer-panel-20261019-2ftt: tallied (panel, approved by the user)
units 30, briefed 30, valid 5, invalid 0, missing 25
Disclosure: Simulated units are not people. Read rates as an upper bound and confirm with real ones.

> Simulated units are not people. Read rates as an upper bound and confirm with real ones.

# Simulated buyers see the pitch (run buyer-panel-20261019-2ftt)

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 |

How to read it: the rate comes with its denominator ("3 of 5", and 5 of 30 units counted), not as a percentage alone. A group with no valid answer shows n/a, not 0. The same run also writes counts per reason code, the first two quotes per group verbatim, and the median, mean, minimum and maximum of price_floor. Re-run init with the same profile, --n 30 and --seed 7 against a second pitch to compare: the file cards.json of the two runs is byte for byte identical (cmp reports no difference between them).

The acceptance steps, replayed: 1 valid answer out of 30#

The acceptance recipe of 0.23.0 includes a swarm step in an empty project, carried out by a person: no sub-agent runs, the tester acts as one unit, files a valid answer for B001 and tries a bad one. The tool counts exactly that, and says so. Below is the same sequence replayed with the 0.23.0 CLI (the 30 paths of briefs are shortened).

$ npx 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-20261019-9da2: panel of 30 units, budget 26, approval user.
Seed 7 (same seed, same cards).
Next: bmad-plus swarm briefs buyer-panel-20261019-9da2
$ npx bmad-plus swarm briefs buyer-panel-20261019-9da2
buyer-panel-20261019-9da2: 30 of 30 units need a sub-agent, in waves of 10.
Wave 1:
# ... one line per unit with the brief path, 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.
# The tester writes one valid answer by hand: answers/B001.json.
$ npx bmad-plus swarm check buyer-panel-20261019-9da2
buyer-panel-20261019-9da2: 1 of 30 valid answers.
  B002  missing: no answer file
# ... B003 to B030 likewise.
$ npx bmad-plus swarm save buyer-panel-20261019-9da2 B002 --input swarm/reply-bad.txt
Swarm: Reply of unit B002 refused: field "buys" must be true or false.
# swarm/reply-bad.txt holds an object whose buys field is the text "maybe". Exit code 1.
$ npx bmad-plus swarm tally buyer-panel-20261019-9da2
/work/demo/app/.bmad-plus/swarm/runs/buyer-panel-20261019-9da2/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.
$ head -n 3 .bmad-plus/swarm/runs/buyer-panel-20261019-9da2/tally.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-20261019-9da2)

A jury: three lenses on the same pitch#

A jury needs no profile, no --n and no seed: its units are listed in the definition, one lens each. This one (swarm/pitch-jury.json, printed below with its template) reads the same pitch through price, trust and habit. The third juror carries its own id (J-habit); the first two get J001 and J002 from the prefix. Its answer has only three fields: a verdict, the weakest claim and up to two fixes, and its tally counts verdicts and keeps the first three quotes.

{
  "schemaVersion": 1,
  "id": "pitch-jury",
  "kind": "jury",
  "title": "Three lenses on the pitch",
  "units": {
    "source": "list",
    "idPrefix": "J",
    "list": [
      { "lens": "price", "stance": "Every claim is a cost the buyer pays." },
      { "lens": "trust", "stance": "Who vouches for this, and why believe them?" },
      { "id": "J-habit", "lens": "habit", "stance": "What has to change in a normal morning?" }
    ]
  },
  "brief": { "template": "briefs/juror.md", "context": ["pitch"] },
  "answer": {
    "required": ["id", "verdict", "weakest_claim"],
    "fields": {
      "verdict": { "type": "enum", "values": ["convincing", "unclear", "weak"] },
      "weakest_claim": { "type": "string", "min": 5, "max": 300 },
      "fixes": { "type": "list", "maxItems": 2 }
    }
  },
  "tally": { "counts": ["verdict"], "quotes": { "weakest_claim": 3 } },
  "disclosure": "A simulated jury is a rehearsal, not a review by the people it imitates."
}

# Juror {{unit.id}}

Lens: {{card.lens}}. Stance: {{card.stance}}

Read the pitch below through that lens only and write a JSON object to `{{answer.path}}` with
`id` ("{{unit.id}}"), `verdict` (convincing, unclear or weak), `weakest_claim` and optional `fixes`.

{{context.pitch}}

{{disclosure}}

{ "id": "J001", "verdict": "unclear", "weakest_claim": "A flat white at 4.20 is stated, but nothing says what it is compared to.", "fixes": ["Compare the price with a nearby chain.", "Show what the loyalty card is worth in euros."] }
{ "id": "J002", "verdict": "weak", "weakest_claim": "No one vouches for the bar: there is no review, no name, no photo.", "fixes": ["Add two customer sentences with a first name."] }
{ "id": "J-habit", "verdict": "convincing", "weakest_claim": "Opening at seven is good; it does not say how long the queue is.", "fixes": ["Say how long a regular order takes."] }

$ npx bmad-plus swarm init --definition swarm/pitch-jury.json --context pitch=swarm/pitch.md
pitch-jury-20261019-3qxm: jury of 3 units, budget 26, approval not-needed.
Units listed, no seed.
Next: bmad-plus swarm briefs pitch-jury-20261019-3qxm
$ npx bmad-plus swarm briefs pitch-jury-20261019-3qxm
pitch-jury-20261019-3qxm: 3 of 3 units need a sub-agent, in waves of 10.
Each sub-agent: Read the brief and follow it exactly; it is your whole instruction.
Disclosure: A simulated jury is a rehearsal, not a review by the people it imitates.
# Three answer files are written by hand into answers/.
$ npx bmad-plus swarm check pitch-jury-20261019-3qxm
pitch-jury-20261019-3qxm: 3 of 3 valid answers.
$ npx bmad-plus swarm tally pitch-jury-20261019-3qxm
3 of 3 units counted; 0 skipped.
Disclosure: A simulated jury is a rehearsal, not a review by the people it imitates.

> A simulated jury is a rehearsal, not a review by the people it imitates.

# Three lenses on the pitch (run pitch-jury-20261019-3qxm)

3 of 3 units gave a valid answer; 0 skipped.

## Counts: verdict

| group | convincing | unclear | weak |
|---|---|---|---|
| all | 1 | 1 | 1 |

## Quotes: weakest_claim (up to 3 per group, verbatim)

**all**
- J001: "A flat white at 4.20 is stated, but nothing says what it is compared to."
- J002: "No one vouches for the bar: there is no review, no name, no photo."
- J-habit: "Opening at seven is good; it does not say how long the queue is."

Panel and jury use cases#

Run the buyer-panel swarm with 30 units and seed 7 on swarm/pitch-v1.md, then again with the same seed and profile on swarm/pitch-v2.md. If a run needs approval, ask me first with the numbers. Launch the sub-agents one wave at a time and never answer for a unit. Report from the two tallies only: the disclosure first, then the buy rate by segment for each pitch with its denominator, the reason codes, and what changed between the two.

Run the pitch-jury swarm on swarm/pitch.md. One sub-agent per juror, each reading its own brief only. Read each context file before passing it. When the tally is written, report the disclosure first, then the verdict counts and the weakest claim quoted per lens, and list the fixes the jurors proposed. Do not write or edit any answer yourself.

Initialise the site-pages fanout from swarm/page-fanout.json and swarm/units.json (about, pricing, contact), export it with swarm plan to .bmad-plus/swarm/reports/RUN/plan.json and create the Nexus run from it. Start one task at a time on this host, let me review the page, then verify and accept it. Do not accept a task whose check fails.

Run tree and limits#

run.json         kind, pack, hashes of every input, 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   rendered by briefs or 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)

Safety boundaries: the runtime has no child process, no network and no eval; every file is written atomically and only under .bmad-plus/swarm/; paths that traverse, are absolute, follow a link or reach .git are refused; inputs are frozen at init, so editing a context afterwards changes nothing for that run.