bmad-plus 0.22.0 → 0.23.0

package/src/bmad-plus/skills/bmad-plus-swarm/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: bmad-plus-swarm
+description: Moderate a swarm of sub-agents under a budget — simulated buyers dealt from a profile, a jury of lenses, or one worker per page — each reading one brief and writing one validated answer that `bmad-plus swarm` tallies with its disclosure first. Use when a pack declares a swarm, when someone asks for a panel, a jury, a simulated audience, a before/after read of a pitch, or when independent units of work should be fanned out to parallel sub-agents.
+---
+
+# Moderating a swarm
+
+## Overview
+
+A swarm is many sub-agents doing the same kind of work once each: a hundred simulated buyers
+reading a pitch, five jurors holding one lens each, one writer per page. The moderator (you)
+never does the units' work. The runtime (`bmad-plus swarm`) never calls a model. Between the two
+sits a file protocol: a **card** per unit, frozen at init; a **brief** rendered from the card; an
+**answer** the sub-agent writes as JSON and the runtime validates; a **tally** over valid answers
+only, with a disclosure sentence on its first line.
+
+```
+definition + profile|list|units ─► init ─► cards.json ─► briefs ─► one sub-agent per brief
+                                                                      │
+      tally.md ◄── tally ◄── check (missing / invalid) ◄── answers/<unit>.json ◄──┘
+```
+
+Read `ref/definition.md` for the four file contracts with one example each.
+
+## The four kinds
+
+| Kind | Units come from | Typical use | Tally |
+|---|---|---|---|
+| `panel` | dealt from a **profile** by exact quotas, seeded | simulated buyers, readers, users | rate by group, counts, quotes, numbers |
+| `jury` | **listed** in the definition, one `lens` each | adversarial read of a pitch, a page, a plan | counts and quotes per lens |
+| `fanout` | **supplied** at init, one disjoint write `scope` each | pages to write, scenes to render, modules to document | rate and numbers; exportable as a Nexus plan |
+
+A `panel` and a `jury` run as **session sub-agents**: you launch them, wait for them, read 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 (each unit then owns an exclusive write scope and Nexus verifies its answer file).
+
+## The budget
+
+`_bmad/config.yaml` holds `swarm.budget` (default 26 sub-agents per run), `swarm.wave` (default 10
+launched together) and `swarm.media_credits: ask`. An absent block means these defaults.
+
+- `init` refuses a run larger than the budget with status `needs-approval` and exit code 2. It
+  writes no brief. **Ask the user**, in one sentence with the number: "This panel needs 100
+  sub-agents; the budget is 26. Run it?" Only after a human yes, re-run `init` with `--approved`
+  and the seed the refusal printed. Never pass `--approved` on your own judgement.
+- Paid generation (images, video, audio) is **never** covered by a budget: ask before each run
+  that would spend credits, whatever `budget` says.
+- Launch one wave at a time; wait for the whole wave before the next. The wave size is the
+  configured one unless `briefs --wave N` says otherwise.
+
+## Protocol
+
+1. **Load the definition** the pack ships next to the agent that moderates it, and the inputs it
+   needs: a profile (panel), nothing more (jury), or a units file you write from the request
+   (fanout). Every path is project-relative with `/`.
+2. **Init.** `bmad-plus swarm init --definition FILE [--profile FILE | --units FILE]
+   [--context NAME=FILE]... [--n N] [--seed N] --json`. A panel needs `--n`; the seed is drawn and
+   recorded when absent. Keep the printed `run` id and `seed`.
+3. **Approval** when exit code 2: ask, then re-run `init --approved --seed <seed>`.
+4. **Briefs.** `bmad-plus swarm briefs RUN --json` prints the waves, each unit with the absolute
+   path of its brief and of the answer it must write.
+5. **Launch a wave**: one sub-agent per brief, with exactly this instruction and nothing else:
+   *"Read `<brief path>` and follow it exactly; it is your whole instruction."* Do not summarise
+   the brief, do not add context, do not merge two units into one sub-agent.
+6. **Wait for the wave**, then `bmad-plus swarm check RUN --json`. It lists every unit whose
+   answer is missing or invalid, with the reason.
+7. **Second chance, once.** Re-run `briefs` (it only renders units without a valid answer) and
+   launch the listed units again. A unit that printed its answer instead of writing it is filed
+   with `bmad-plus swarm save RUN UNIT --input FILE`, where FILE holds that unit's reply verbatim.
+   A unit still missing after the second wave stays missing.
+8. **Tally.** `bmad-plus swarm tally RUN --json` writes `tally.json` and `tally.md`. Report from
+   the tally, never from your memory of the replies.
+9. **Fanout as a plan** instead of steps 4–8: `bmad-plus swarm plan RUN --json`, then
+   `bmad-plus nexus create --plan <file>` and the Nexus protocol (`start`, `record`, `verify`,
+   `accept`) for each task.
+
+## Rules that do not bend
+
+- **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. `save` extracts and validates; it is
+  not a way around a missing unit. The tally counts the units that answered and names the rest.
+- **Never edit a brief.** Briefs are rendered from the template and the card; a change belongs in
+  the template or the definition, then a new run.
+- **Disclosure, once and first.** Simulated units are not people. The tally starts with the
+  pack's disclosure sentence; repeat it once in your report, before any figure. Rates from a
+  panel are an upper bound to confirm with real people, never a measurement.
+- **Quotes are simulated.** Present a quote as what a simulated unit wrote, never as a testimonial,
+  a customer voice or a user interview.
+- **Same seed, same cards.** A before/after comparison of two pitches re-runs the same profile
+  with the same `--n` and `--seed`, so the only thing that changed is the context.
+- **The runtime filters nothing.** Card values, pool entries, listed unit fields and context
+  files reach the sub-agent word for word; a pool entry that reads like an instruction lands in
+  the brief as one. The pack owns its pools, its unit fields and its templates; you own the
+  contexts you pass. Read a context before passing it, and never pass a file you have not read:
+  it is included verbatim in every brief, secrets and instructions alike.
+- **Replies are filed from outside the state tree.** `save --input` takes a project file the
+  host wrote (for instance `swarm-inbox/<unit>.txt`), never a path under `.bmad-plus/`.
+
+## What the runtime guarantees, and what it does not
+
+The runtime validates every input, deals by exact quota, writes atomically, caps inputs at
+16 MiB, refuses paths that traverse, are absolute, follow a link or reach `.git`, and never
+writes outside `.bmad-plus/swarm/`. It does not prove a sub-agent read its brief, stayed inside
+its card, or wrote anything true. A valid answer is a well-formed one. Quality is your reading of
+the tally and the user's judgement, not a status code.
+
+## Invocation
+
+```
+bmad-plus-swarm
+```
+
+Or through the Orchestrator's Parallel Supervisor role when a pack declares a swarm or a panel is
+requested (`role-triggers.yaml`: `swarm_declared`, `panel_requested`).

package/src/bmad-plus/skills/bmad-plus-swarm/ref/definition.md

@@ -0,0 +1,188 @@
+# Swarm file contracts
+
+Four files, all JSON except the brief template. The runtime refuses an unknown field, a wrong
+type or a bound breach; it never guesses. Every path is project-relative with `/` separators.
+
+## 1. Definition
+
+One per swarm, shipped by the pack next to the agent that moderates it. The template path is
+relative to the definition file.
+
+```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 }
+    }
+  },
+  "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."
+}
+```
+
+| Field | Rule |
+|---|---|
+| `id` | 1–64 lowercase letters, digits or `-`; it opens the run id |
+| `kind` / `units.source` | `panel`/`profile`, `jury`/`list`, `fanout`/`input` — the pair must match |
+| `units.idPrefix` | 1–4 letters; required for a panel, optional for a jury whose entries lack an `id`, absent for a fanout |
+| `units.list` | jury only: 1–1000 entries, each with a `lens` string and any other string, number or boolean fields; an optional `id` |
+| `pack` | optional pack id, recorded in the run |
+| `brief.template` | plain relative path, no `.` or `..` parts |
+| `brief.context` | names of context files the moderator passes at init; each is required |
+| `answer.fields` | at most 50; `id` is implicit and always required |
+| field types | `boolean`; `integer` and `number` with optional `min`/`max`; `string` with `min`/`max` length (default 0–4000, ceiling 20000); `enum` with 1–50 distinct `values`; `list` of nonempty strings with `maxItems` (default 50, ceiling 200) |
+| `tally.rate` | a boolean field |
+| `tally.groupBy` | up to 5 card fields; every card must carry them |
+| `tally.counts` | enum fields |
+| `tally.quotes` | string field → quotes kept per group (1–10) |
+| `tally.numbers` | integer or number fields |
+| `disclosure` | 1–500 characters, printed first in every tally |
+
+## 2. Profile (panel)
+
+```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] },
+  "pools": { "objection": ["too steep for a drink", "my place is closer"] }
+}
+```
+
+- 1–10 dimensions, each with 1–50 values whose shares add up to 1. Each dimension is dealt by
+  exact quota (largest remainder), then shuffled by the seeded generator: 20 cards from the
+  profile above hold 9, 8 and 3 segments whatever the seed.
+- A range on a value is sampled when that value is dealt; every value of a dimension declares the
+  same range names. Top-level ranges are sampled per card. Integer bounds deal integers; other
+  bounds deal numbers with two decimals.
+- One entry of each pool is dealt per card.
+- A value's `note` becomes the card field `<dimension>_note` (empty for values without one).
+- 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 are not dealt. A brief that wants one draws it from a pool the pack supplies.
+
+The dealt card for one unit:
+
+```json
+{ "id": "B007", "segment": "mid career", "income": 97250, "behaviour": "explorer", "behaviour_note": "", "age": 31, "objection": "my place is closer" }
+```
+
+## 3. Units file (fanout)
+
+```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`: 1–64 lowercase letters, digits, `_` or `-` (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 across units (no scope contains another).
+- Other fields are strings, numbers or booleans and become card fields for the brief.
+
+## 4. Brief template
+
+A Markdown file. Placeholders, and nothing else between double braces:
+
+| Placeholder | Renders |
+|---|---|
+| `{{card.<field>}}` | the card field; a list renders comma-separated |
+| `{{context.<name>}}` | the context file passed at init, verbatim and frozen in the run |
+| `{{answer.path}}` | the absolute path of the answer file the sub-agent must write |
+| `{{run.id}}`, `{{unit.id}}` | the run and unit ids |
+| `{{disclosure}}` | the definition's disclosure sentence |
+
+An unknown placeholder, a card field some card lacks or an undeclared context fails `init`.
+Literal `{{` sequences are not allowed in a template. Every value is inserted verbatim: the
+runtime filters no instruction text out of a card, a pool entry or a context, so the pack owns
+what its pools and unit fields say and the moderator reads a context before passing it.
+
+```markdown
+# You are unit {{unit.id}} of run {{run.id}}
+
+Segment: {{card.segment}}, income {{card.income}}. Your first objection: {{card.objection}}.
+
+## The pitch
+
+{{context.pitch}}
+
+Write a JSON object to `{{answer.path}}` with `id` ("{{unit.id}}"), `buys`, `reason_code`
+and `reason`.
+
+{{disclosure}}
+```
+
+## 5. Answer
+
+What the sub-agent writes to `{{answer.path}}`: one JSON object, `id` equal to the unit id,
+every required field present, no field the definition does not declare.
+
+```json
+{ "id": "B007", "buys": false, "reason_code": "price", "reason": "5.40 is a lunch, not a drink.", "price_floor": 3.5 }
+```
+
+`check` reports an answer as `missing` (no file) or `invalid` (unreadable JSON, wrong id, missing
+required field, unknown field, type or bound breach) with the reasons. `save` applies the same
+rules to the first balanced JSON object found in a printed reply.
+
+## 6. Tally
+
+`tally.json` and `tally.md`, over valid answers only. Units without one are listed as skipped and
+counted in the denominator line. Every section has an `all` entry and one entry per `groupBy`
+value.
+
+```json
+{
+  "schemaVersion": 1,
+  "run": "buyer-panel-20261016-k3f9",
+  "disclosure": "Simulated units are not people. ...",
+  "units": { "total": 20, "valid": 19, "skipped": [{ "unit": "B013", "reason": "no answer file" }] },
+  "rate": { "field": "buys", "all": { "yes": 11, "of": 19, "rate": 0.5789 }, "groups": { "segment": { "early career": { "yes": 6, "of": 9, "rate": 0.6667 } } } },
+  "counts": { "reason_code": { "all": { "price": 5, "habit": 7, "need": 4, "trust": 2, "other": 1 }, "groups": {} } },
+  "quotes": { "reason": { "keep": 2, "all": [{ "unit": "B001", "text": "On my way to work." }], "groups": {} } },
+  "numbers": { "price_floor": { "all": { "count": 14, "median": 4, "mean": 4.07, "min": 2.5, "max": 6 }, "groups": {} } }
+}
+```
+
+`tally.md` opens with the disclosure as a quote, then the denominator line, then one section per
+rate, count, quote and number. Quotes are JSON-escaped verbatim, attributed to their unit id.

package/tools/build/adapters.config.js

@@ -84,6 +84,8 @@ const PROJECT_INSTRUCTIONS = [
   '- Installed projects load skills from `.agents/skills/`; in this repository the sources live in `src/bmad-plus/skills/` and `src/bmad-plus/agents/`.',
   '- Each agent has a SKILL.md with capabilities, activation protocol, and role-switching rules.',
   '- Auto-activation triggers: `.agents/data/role-triggers.yaml` (source: `src/bmad-plus/data/role-triggers.yaml`).',
+  '- An agent whose roster line says `drives:` reads the `SKILL.md` of every skill it drives (`.agents/skills/<id>/SKILL.md`) before acting on that skill.',
+  "- The host runs a pack's declared intake (`bmad-plus intake`, skill `bmad-plus-intake`) before that pack's pipeline or swarm starts.",
   '',
   '## Project Structure',
   '',

package/tools/build/generate-adapters.js

@@ -141,8 +141,12 @@ function factsFromDerived(derived, packs = derived.packOrder) {
       categoryAgentCount: pack.categoryAgentCount,
       subAgentCount: pack.subAgentCount,
       workflowCount: pack.workflowCount,
+      pipelineCount: (pack.pipelines || []).length,
+      pipelines: pack.pipelines || [],
       frameworkCount: pack.frameworkCount,
+      usesSkills: pack.usesSkills || [],
       personas: pack.personas,
+      ...(pack.cohabitationWarning ? { cohabitationWarning: pack.cohabitationWarning } : {}),
     };
   });
   return {
@@ -174,6 +178,7 @@ function renderRoster(facts) {
       const identity = persona.alias
         ? '(' + persona.alias + ') — ' + persona.role
         : '(' + persona.role + ')';
+      const drives = [...new Set([...(pack.usesSkills || []), ...(persona.usesSkills || [])])];
       lines.push(
         '- **' +
           persona.name +
@@ -181,7 +186,8 @@ function renderRoster(facts) {
           identity +
           ' — ' +
           persona.description +
-          (pack.required ? '' : ' (' + pack.name + ')')
+          (pack.required ? '' : ' (' + pack.name + ')') +
+          (drives.length ? ' — drives: ' + drives.join(', ') : '')
       );
     }
   }
@@ -214,16 +220,31 @@ function renderFactsSection(facts) {
     if (p.subAgentCount) extras.push(`${p.subAgentCount} sub-agents`);
     if (p.categoryAgentCount) extras.push(`${p.categoryAgentCount} specialized agents`);
     if (p.workflowCount) extras.push(`${p.workflowCount} workflows`);
+    if (p.pipelineCount)
+      extras.push(`${p.pipelineCount} pipeline${p.pipelineCount === 1 ? '' : 's'}`);
     if (p.frameworkCount) extras.push(`${p.frameworkCount} compliance frameworks`);
     const suffix = extras.length > 0 ? ` — ${extras.join(', ')}` : '';
     lines.push(
       `  - ${p.name}${p.required ? ' (required)' : ''}: ${p.agentCount} installer agent${p.agentCount === 1 ? '' : 's'} — ${p.desc}${suffix}`
     );
   }
+  for (const p of facts.packs) {
+    for (const pipeline of p.pipelines) {
+      const steps = pipeline.steps
+        .map((step, index) => `${index + 1}. ${step.workflow ?? step.agent} (${step.gate})`)
+        .join(' → ');
+      lines.push(`- Pipelines (${p.name}): ${pipeline.id} "${pipeline.title}": ${steps}`);
+    }
+  }
   if (facts.dataFlows.length)
     lines.push(
       `- Data handling: no telemetry; ${facts.dataFlows.length} flow${facts.dataFlows.length === 1 ? '' : 's'} can send data off the machine, each under its consent basis: ${facts.dataFlows.map((flow) => `${flow.id} (${flow.consent})`).join(', ')}. What, to whom and when: "Data handling" in the bmad-plus SECURITY.md.`
     );
+  // A pack that overlaps another one says so where every agent reads it, not only in
+  // the install prompt; the line exists only for packs that declare a warning.
+  for (const p of facts.packs) {
+    if (p.cohabitationWarning) lines.push(`- Cohabitation (${p.name}): ${p.cohabitationWarning}`);
+  }
   return lines;
 }
 
@@ -421,6 +442,8 @@ function renderUserSections(derived, { packs, userName = 'Developer', language =
     '- Load skills from `.agents/skills/`.',
     '- Each agent has a SKILL.md with capabilities, activation protocol, and role-switching rules.',
     '- Auto-activation triggers: `.agents/data/role-triggers.yaml`.',
+    '- An agent whose roster line says `drives:` reads the `SKILL.md` of every skill it drives (`.agents/skills/<id>/SKILL.md`) before acting on that skill.',
+    "- The host runs a pack's declared intake (`bmad-plus intake`, skill `bmad-plus-intake`) before that pack's pipeline or swarm starts.",
     '',
     '## Communication',
     '',
@@ -799,6 +822,7 @@ module.exports = {
   TOOL_NOTES,
   validateTargets,
   buildRegistryFacts,
+  factsFromDerived,
   groupAdaptersByFile,
   renderFactsSection,
   renderProjectInstructions,