bmad-plus swarm

Un enjambre son muchos subagentes que hacen cada uno una vez el mismo tipo de trabajo: treinta compradores simulados que leen un discurso comercial, tres jurados con una óptica cada uno, un redactor por página. bmad-plus swarm lleva la contabilidad de todo eso. Reparte las unidades, escribe un brief por subagente, comprueba cada archivo de respuesta, archiva una respuesta que un subagente solo imprimió y cuenta las respuestas válidas. Nunca llama a un modelo, no abre ninguna conexión de red ni lanza ningún proceso: tu asistente (el asistente anfitrión) lanza los subagentes y el comando solo lee y escribe archivos bajo .bmad-plus/swarm/. Úsalo cuando se pida un panel, un jurado o un reparto en unidades independientes. La versión 0.23.0 no incluye ninguna definición de enjambre en sus packs; la definición la aportas tú o un pack.

Sinopsis#

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]

Los tres tipos de enjambre#

Un panel y un jurado se ejecutan como subagentes de sesión: el anfitrión los lanza, espera y luego lee sus archivos. Una dispersión puede ejecutarse igual, o exportarse con plan cuando el trabajo debe sobrevivir a la sesión, necesita una comprobación independiente por unidad o edita el repositorio (ver bmad-plus nexus). El archivo de definición (JSON) nombra el tipo, la plantilla del brief, los campos de respuesta (boolean, integer, number, string, enum, list), el recuento y una frase de disclosure de 1 a 500 caracteres.

Presupuesto, oleadas y aprobación#

Tres ajustes del bloque swarm de _bmad/config.yaml acotan un run. Un archivo o un bloque ausente significa los valores por defecto de abajo; cualquier otro valor se rechaza. init compara el número de unidades con el presupuesto: un run mayor se crea en estado needs-approval, no escribe ningún brief y termina con el código 2. Entonces el asistente debe preguntarte, en una frase con el número, y solo tras un sí volver a ejecutar init con --approved y la semilla que mostró el rechazo.

Las siete acciones#

Orden habitual: init, luego briefs; el anfitrión lanza un subagente por brief con exactamente la instrucción «Read the brief and follow it exactly; it is your whole instruction», y después check. Ejecuta briefs una vez más para dar una segunda oportunidad a las unidades que faltan (solo renderiza las unidades sin respuesta válida), archiva con save cualquier respuesta impresa y luego tally. Una unidad que sigue faltando tras la segunda oleada sigue faltando y se nombra en el recuento. inspect resume un run en cualquier momento sin escribir nada.

El árbol de un run#

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

El sufijo de 4 caracteres es aleatorio y nunca se reutiliza una carpeta existente. Las entradas se congelan en init: editar después un contexto o la definición no cambia nada para ese run. Estados: needs-approval (terminal), ready, briefed, tallied. Un recuento se puede repetir, y briefs también tras un recuento. Los informes pedidos con --out van bajo .bmad-plus/swarm/reports/<run id>/.

Reglas de honestidad#

• Las unidades simuladas no son personas. El recuento empieza con el aviso de transparencia (disclosure) de la definición, antes de cualquier cifra. Las tasas de un panel son una cota superior que hay que confirmar con personas reales, nunca una medición.
• Las citas son simuladas: preséntalas como lo que escribió una unidad simulada, nunca como un testimonio o una entrevista.
• El moderador nunca responde por una unidad: ni archivo de respuesta escrito a mano ni «arreglar» una respuesta inválida. save solo extrae y valida lo que un subagente imprimió.
• Los briefs nunca se editan. Un cambio va en la plantilla o en la definición, y luego en un run nuevo.
• Misma semilla, mismas fichas: una comparación antes/después de dos discursos repite el mismo perfil con el mismo --n y la misma --seed, de modo que solo cambia el contexto.
• El runtime no filtra nada: los valores de las fichas, las entradas de las bolsas y los archivos de contexto llegan palabra por palabra al subagente. Lee un contexto antes de pasarlo; se copia en cada brief, con secretos e instrucciones incluidos.
• Una respuesta válida es una respuesta bien formada. Nada prueba que un subagente leyó su brief ni que dijo la verdad.

Lecturas, escrituras y límites#

• Solo escribe bajo .bmad-plus/swarm/. --out en tally y plan debe quedarse en .bmad-plus/swarm/reports/<run id>/ o en el árbol propio del run, nunca sobre answers/, briefs/, context/, checks/, run.json, cards.json, definition.json, template.md, nexus-plan.json, tally.json ni tally.md.
• Cada ruta que nombras (--definition, --profile, --units, --context, --input) es relativa al proyecto con /; se rechazan rutas absolutas, barras invertidas, .., .git y todo lo que pase por un enlace simbólico. Esos archivos no pueden venir de .bmad-plus/.
• Límites: de 1 a 1000 unidades por run; presupuesto y oleada de 1 a 1000; semilla de 0 a 2147483647; entradas de 16 MiB como máximo; respuesta impresa para save de 1 MiB como máximo; 50 campos de respuesta como máximo; 20 contextos por definición como máximo; 5 campos groupBy como máximo.
• Los ids de unidad son letras, dígitos, _ o - (hasta 64 caracteres; en minúsculas en una dispersión). Los ids de un panel repartido son el prefijo más la posición rellena hasta al menos tres dígitos (B001).
• Los archivos se escriben mediante un archivo temporal y se renombran. Sin red, sin proceso hijo, sin eval.

Códigos de salida#

Los archivos de ejemplo#

Las transcripciones y los ejemplos de abajo usan los archivos impresos aquí. Están en el repositorio, bajo tests/fixtures/swarm/, y no forman parte del paquete npm, así que se dan completos: créalos bajo swarm/ en tu proyecto y los comandos reproducen las transcripciones, salvo los ids de run (una fecha y un sufijo aleatorio). Los seis primeros pertenecen al panel de compradores; los tres últimos, al ejemplo de dispersión del final de la página.

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

Salida real#

Estas transcripciones proceden de la receta de aceptación humana de 0.23.0: un panel de 30 compradores simulados en una aplicación de demostración, frente al presupuesto por defecto de 26. Se han quitado las líneas npm notice y el prompt del shell. La definición (swarm/buyer-panel.json) y el perfil son los fixtures de prueba del repositorio, copiados a la aplicación de demostración.

$ 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
# Las oleadas 2 (B011 a B020) y 3 (B021 a B030) siguen con el mismo formato; aquí se omiten.
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 a B030 se listan igual (27 líneas más).
$ 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.

Cómo leerlo: el primer init creó un run rechazado (...-ungp) y nada más; el aprobado es otro run (...-oqu7) con su propio sufijo aleatorio. Solo había respondido B001, así que el recuento honesto cuenta 1 unidad y nombra 29 omitidas; el aviso de transparencia va primero, y es también la primera línea de tally.md. La respuesta rechazada no escribió nada para B002.

Errores y qué hacer#

Ejemplos#

Lanza el panel de compradores de swarm/buyer-panel.json con el perfil swarm/profile.json y mi discurso en swarm/pitch.md. Usa 30 compradores simulados y la semilla 7.

Lanza el panel de compradores sobre swarm/pitch-v1.md y luego otra vez sobre swarm/pitch-v2.md, con el mismo perfil, 24 compradores y la semilla 7. Compara los dos recuentos.

Redacta las tres páginas listadas en swarm/units.json con un subagente por página, usando swarm/page-fanout.json. Expórtalo como plan Nexus para que cada página se verifique antes de que la acepte.