# bmad-plus swarm

> Repartir, preparar briefs, comprobar, archivar y contar un enjambre de subagentes con presupuesto: panel, jurado o dispersión. Opciones, aprobación con código 2, honestidad, salida real y errores.

Canonical: https://bmad-plus.rochetta.fr/es/docs/reference/cli-swarm/
Language: es
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

Documentación de BMAD+ › [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/) › 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.

<a id="synopsis"></a>
## Sinopsis

**En el terminal de tu proyecto**

```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]
```

**Opciones de bmad-plus swarm**

| Opción | Argumento | Por defecto | Qué hace |
| --- | --- | --- | --- |
| `<action>` | `init`, `briefs`, `check`, `save`, `tally`, `inspect`, `plan` | obligatorio | El paso que se ejecuta. |
| `[run]`, `[unit]` | id de run, id de unidad | ninguno | Id de run como `buyer-panel-20261018-oqu7` (todas las acciones salvo `init`); id de unidad como `B002` (solo `save`). |
| `-d, --directory <path>` | ruta | carpeta actual | Carpeta del proyecto. |
| `--definition <file>` | ruta | ninguno | Definición del enjambre, JSON relativo al proyecto. Solo `init`; obligatorio. |
| `--profile <file>` | ruta | ninguno | Perfil del panel, JSON relativo al proyecto. `init`; obligatorio en un panel, rechazado en los demás tipos. |
| `--units <file>` | ruta | ninguno | Unidades de la dispersión, JSON relativo al proyecto. `init`; obligatorio en una dispersión, rechazado en los demás tipos. |
| `--context <name=file>` | NOMBRE=ARCHIVO | ninguno | Archivo de contexto incluido tal cual en cada brief. Repetible. Cada nombre que declara la definición es obligatorio; un nombre no declarado se rechaza. |
| `--n <count>` | entero de 1 a 1000 | ninguno | Número de unidades que repartir en un panel. Rechazado en un jurado o una dispersión. |
| `--seed <number>` | entero de 0 a 2147483647 | se sortea una vez y se guarda | Semilla del reparto. Solo panel. Mismo perfil, mismo `--n`, misma semilla: mismas fichas. |
| `--approved` | ninguno | desactivado | Registra que una persona aceptó superar el presupuesto. No lo pases nunca por tu cuenta. |
| `--wave <count>` | entero de 1 a 1000 | oleada configurada (10) | Subagentes lanzados a la vez. Solo `briefs`. |
| `--input <file>` | ruta | ninguno | Respuesta que un subagente imprimió. Solo `save`; obligatorio; fuera de `.bmad-plus/`; máximo 1 MiB. |
| `--out <file>` | ruta | dentro del run | Archivo de salida de `tally` y `plan`. Debe estar bajo `.bmad-plus/swarm/` (ver Lecturas, escrituras y límites). |
| `--json` | ninguno | desactivado | Salida legible por máquinas, con `schemaVersion: 1` y un campo `status`. |

<a id="kinds"></a>
## Los tres tipos de enjambre

**Tipos, fijados por el archivo de definición**

| Tipo | Las unidades vienen de | Uso típico | Recuento |
| --- | --- | --- | --- |
| `panel` | Un perfil: dimensiones con proporciones, repartidas por cuotas exactas y con semilla (`--profile`, `--n`, `--seed`). | Compradores, lectores o usuarios simulados que leen un discurso comercial. | Tasa por grupo, recuentos, citas, números. |
| `jury` | La propia definición: unidades listadas una a una, cada una con un `lens`. | Una lectura adversaria de un discurso, una página o un plan. | Recuentos y citas por óptica. |
| `fanout` | Un archivo de unidades (`--units`): cada unidad tiene su propio `scope` de escritura, disjunto de los demás. | Páginas por redactar, módulos por documentar: trabajo independiente en paralelo. | Tasa y números; exportable como plan Nexus duradero con `plan`. |

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.

<a id="budget"></a>
## 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.

**El bloque swarm de _bmad/config.yaml**

| Clave | Por defecto | Valores admitidos | Efecto |
| --- | --- | --- | --- |
| `budget` | 26 | entero de 1 a 1000 | Subagentes que un run puede usar antes de que el anfitrión deba preguntarte. |
| `wave` | 10 | entero de 1 a 1000 | Subagentes lanzados a la vez; `briefs` agrupa las unidades pendientes en oleadas de este tamaño (se puede cambiar con `--wave`). |
| `media_credits` | `ask` | exactamente `ask` | La generación de pago de imágenes, vídeo o audio nunca está cubierta por un presupuesto: el anfitrión pregunta antes de cada run así. |

> **Advertencia · La aprobación es de una persona** `--approved` se guarda en el run como `approval: user`. La habilidad swarm solo lo permite tras un sí humano, sea cual sea el número de unidades. Un run nunca se aprueba por el propio criterio del asistente.

<a id="actions"></a>
## Las siete acciones

**Qué lee y escribe cada acción**

| Acción | Lee | Escribe | Salida |
| --- | --- | --- | --- |
| `init` | Definición, plantilla, perfil o unidades, contextos, `_bmad/config.yaml`. | El árbol del run (entradas congeladas y `run.json`). | 0 listo, 2 requiere aprobación, 1 rechazado. |
| `briefs RUN` | El árbol del run y las respuestas. | Un brief por cada unidad sin respuesta válida; la carpeta `answers/`. | 0, o 2 si el run requiere aprobación. |
| `check RUN` | El árbol del run y las respuestas. | Nada. | 0 completo, 1 incompleto. |
| `save RUN UNIT --input F` | El árbol del run y el archivo de respuesta. | `answers/<unit>.json`. | 0 archivada, 1 rechazada. |
| `tally RUN [--out F]` | El árbol del run y las respuestas. | `tally.json` y `tally.md` (o `--out`). | 0, o 2 si el run requiere aprobación. |
| `inspect RUN` | El árbol del run, respuestas, briefs. | Nada. | 0. |
| `plan RUN [--out F]` | El árbol del run (solo dispersión). | Todos los briefs, `checks/`, `nexus-plan.json` (o `--out`). | 0 planificado, 2 requiere aprobación, 1 no es una dispersión. |

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.

<a id="run-tree"></a>
## El árbol de un run

**Creado en tu proyecto por init**

```text
.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>/`.

<a id="honesty"></a>
## 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.

<a id="reads-writes"></a>
## 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`.

<a id="exit-codes"></a>
## Códigos de salida

**Códigos de salida de bmad-plus swarm**

| Código | Significado |
| --- | --- |
| 0 | La acción tuvo éxito; en `check`, cada unidad tiene una respuesta válida. |
| 1 | `check` encontró unidades que faltan o inválidas (estado `incomplete`), o cualquier error (se muestra como `Swarm: <message>`). |
| 2 | Estado `needs-approval`: el run tiene más unidades que el presupuesto y no hay `--approved`. Pregunta a una persona y vuelve a ejecutar `init --approved --seed <seed>`. `briefs`, `save`, `tally` y `plan` sobre ese run también salen con 2 y no escriben nada. |

<a id="sample-files"></a>
## 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.

**swarm/buyer-panel.json, la definición del panel**

```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, el perfil del que se reparten las 30 fichas de compradores**

```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, el texto que leen los compradores**

```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, la plantilla de brief (cada marcador entre llaves dobles se rellena por unidad)**

```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, una respuesta válida para la unidad 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, una respuesta que el validador rechaza (buys debe ser true o false)**

```json
{ "id": "B002", "buys": "maybe", "reason_code": "price", "reason": "Too steep for a drink." }
```

**swarm/units.json, las tres páginas del ejemplo de dispersión**

```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, la definición de la dispersión**

```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, la plantilla de brief de la dispersión**

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

<a id="real-output"></a>
## 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.

**30 unidades frente a un presupuesto de 26: rechazado (código de salida 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.
```

Salida capturada de una ejecución real. Fuente: Capturado durante la receta de aceptación de la 0.23.0, el 2026-10-18 (paso 6)

**Tras un sí humano: --approved con la misma semilla**

```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
```

Salida capturada de una ejecución real. Fuente: Capturado durante la receta de aceptación de la 0.23.0, el 2026-10-18 (paso 6)

**Briefs, en oleadas de 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
# 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.
```

Salida capturada de una ejecución real. Fuente: Capturado durante la receta de aceptación de la 0.23.0, el 2026-10-18 (paso 6; oleadas 2 y 3 abreviadas)

**Una respuesta válida, una respuesta rechazada, el recuento**

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

Salida capturada de una ejecución real. Fuente: Capturado durante la receta de aceptación de la 0.23.0, el 2026-10-18 (paso 6; las otras 27 líneas ausentes de check están abreviadas; el primer comando (archivo de B001) se reprodujo después con el mismo paquete; el aviso de transparencia (Disclosure) es el que la misma ejecución imprimió desde los briefs)

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.

<a id="errors"></a>
## Errores y qué hacer

**Mensajes que muestra bmad-plus swarm**

| Mensaje | Causa | Qué hacer |
| --- | --- | --- |
| `<run>: needs approval. The run needs N sub-agents and the budget is B: ask the user, then re-run init with --approved --seed S.` (código 2) | Más unidades que `swarm.budget` y no hay `--approved`. | Pregunta a una persona en una frase con el número. Tras un sí, vuelve a ejecutar `init` con `--approved --seed S`. O baja `--n`, o sube `swarm.budget` en `_bmad/config.yaml`. |
| `Swarm: Use swarm init --definition FILE [--profile FILE \| --units FILE] …` | Acción desconocida, o falta el id de run o de unidad, o está mal colocado. | Revisa la sinopsis: `save` lleva un run y una unidad; las demás acciones tras `init` solo un run. |
| `Swarm: init needs --definition FILE.` | `init` sin definición. | Pasa `--definition`. |
| `Swarm: A panel needs --profile FILE.` / `A panel needs --n, the number of units to deal.` / `A panel takes --profile, not --units.` | Panel lanzado sin sus entradas. | Añade `--profile` y `--n`; no pases `--units`. |
| `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.` | Opciones que no encajan con el tipo que nombra la definición. | Quita la opción o usa la definición correcta. |
| `Swarm: The definition needs --context NAME=FILE.` / `Context "x" is not declared by the definition.` / `A context is written NAME=FILE: …` | Falta un contexto declarado, sobra uno que se pasó, o la forma es incorrecta. | Pasa exactamente los contextos que declara la definición, como `--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".` | El bloque `swarm` contiene un valor o una clave que el runtime rechaza. | Corrige el bloque o bórralo para volver a los valores por defecto (26, 10, `ask`). |
| `Swarm: Definition does not exist: …` / `…is not valid JSON: …` / `…exceeds N bytes` / `…is not a regular file` | El archivo de entrada no existe, está mal formado, es demasiado grande o no es un archivo. | Corrige la ruta o el JSON. |
| `Swarm: … may not reach .git` / `… may not come from the BMAD+ state tree` / `… refused: … (…)` | La ruta apunta a `.git`, a `.bmad-plus/`, sale del proyecto o pasa por un enlace. | Usa una ruta relativa al proyecto con `/`, fuera de `.bmad-plus/`. |
| `Swarm: Tally groupBy field "f" is absent from unit U.` | A una ficha le falta un campo por el que agrupa el recuento. | Añade el campo al perfil, a la lista o al archivo de unidades, o quítalo de `tally.groupBy`. |
| `Swarm: A run id reads <definition>-<yyyymmdd>-<4 characters>.` / `Run record is not usable: …` | Id de run incorrecto o árbol del run dañado. | Copia el id que mostró `init`; si se editó el árbol, empieza un run nuevo. |
| `Swarm: Reply of unit U refused: …` / `No JSON object found in the reply filed for unit U.` | La respuesta impresa no contiene un objeto JSON o incumple el contrato de respuesta (tipo erróneo, campo ausente, id erróneo). | No se escribió nada. Vuelve a pedírselo al subagente (repite `briefs`) o deja la unidad ausente. No escribas tú la respuesta. |
| `Swarm: Unit U already has a valid answer; it is kept.` / `Unknown unit U in run R.` | `save` sobre una unidad ya respondida o que no está en el run. | Usa `check` para ver qué unidades siguen abiertas. |
| `Swarm: save needs --input FILE, the reply the sub-agent printed.` | `save` sin `--input`. | Guarda la respuesta en un archivo del proyecto fuera de `.bmad-plus/` y pásalo. |
| `Swarm: --out must stay under … or …` / `--out may not write inside …` / `--out may not replace the run file …` | `--out` apunta a un sitio donde `tally` o `plan` no pueden escribir. | Usa una ruta bajo `.bmad-plus/swarm/reports/<run id>/`. |
| `Swarm: Only a fanout exports a Nexus plan; run R is a panel.` | `plan` sobre un panel o un jurado. | Usa `plan` solo con una dispersión. |

<a id="examples"></a>
## Ejemplos

<a id="example-cli-swarm-buyer-panel"></a>
### Un panel de compradores simulados dentro de un presupuesto

Tienes una definición de enjambre, un perfil y un archivo con el discurso comercial. El presupuesto por defecto es de 26 subagentes; pides 30.

**En tu asistente de IA**

```text
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.
```

**Lo que deberías obtener** El asistente ejecuta `swarm init`. Treinta unidades superan el presupuesto de 26, así que el comando sale con el código 2 y no escribe ningún brief; el asistente te dice «30 subagentes frente a un presupuesto de 26» y te pregunta. Tras tu sí, vuelve a ejecutar `init` con `--approved --seed 7`, obtiene un id de run, ejecuta `briefs` (tres oleadas de 10), lanza un subagente por brief con la instrucción fija, luego ejecuta `check`, da una segunda oportunidad a las unidades que faltan y termina con `tally`. Su informe empieza con el aviso de transparencia, indica cuántas unidades se contaron y cuántas se omitieron, y presenta las tasas como una cota superior.

<a id="example-cli-swarm-before-after"></a>
### Comparar dos versiones de un discurso comercial

El mismo panel, ejecutado dos veces con la misma semilla, solo se diferencia en el archivo del discurso.

**En tu asistente de IA**

```text
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.
```

**Lo que deberías obtener** Veinticuatro unidades caben en el presupuesto por defecto de 26, así que ningún `init` pide aprobación. Como perfil, `--n` y `--seed` son idénticos, ambos runs reparten las mismas 24 fichas; solo cambia `{{context.pitch}}` en los briefs. Cada run tiene su id y su `tally.md`. La comparación se presenta como la diferencia entre dos cotas superiores simuladas, con el aviso de transparencia primero, no como un cambio de conversión medido.

<a id="example-cli-swarm-fanout-plan"></a>
### Un redactor por página, verificado por Nexus

Una definición de dispersión y un archivo de unidades dan a cada página su propio ámbito de escritura. El trabajo debe sobrevivir a la sesión, así que se exporta como plan duradero.

**En tu asistente de IA**

```text
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.
```

**Lo que deberías obtener** El asistente ejecuta `swarm init` con `--definition` y `--units`, y luego `swarm plan RUN`. El plan tiene una tarea por unidad: su ámbito más su archivo de respuesta, su brief y los archivos congelados como recursos, una comprobación `node checks/answer.cjs --unit=<unit>`, `maxAttempts` 2 y `maxParallel` igual a la oleada configurada con tope de 32. `plan` muestra la ruta del plan y `Next: bmad-plus nexus create --plan <path>`. A partir de ahí Nexus inicia, verifica y acepta cada tarea; una unidad cuyo archivo de respuesta está mal formado falla su comprobación y se reintenta, no se acepta.

**Véase también**

- [bmad-plus nexus: ejecutar un plan de dispersión exportado](https://bmad-plus.rochetta.fr/es/docs/reference/cli-nexus/)
- [bmad-plus intake: las preguntas antes de un enjambre](https://bmad-plus.rochetta.fr/es/docs/reference/cli-intake/)
- [config.yaml: el bloque swarm](https://bmad-plus.rochetta.fr/es/docs/reference/config-yaml/#swarm-block)
- [Estructura del proyecto: .bmad-plus/swarm/](https://bmad-plus.rochetta.fr/es/docs/reference/project-layout/)
- [Resolución de problemas](https://bmad-plus.rochetta.fr/es/docs/faq/troubleshooting/)

[Documentación de BMAD+](https://bmad-plus.rochetta.fr/es/docs/) · [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/)

[Código en GitHub](https://github.com/lrochetta/BMAD-PLUS)