Intake: preguntar primero, actuar después

Un intake es la lista de preguntas que un pack necesita ver respondidas antes de ponerse a trabajar. Sin él, un agente que recibe una petición escasa rellena los huecos con suposiciones y lo descubres en el entregable. Con él, el agente hace unas pocas preguntas cada vez, en tu idioma, registra cada respuesta con su estado y produce un brief que pasa a ser el contrato de cuanto haga después el pack. Lee esta página si usas un pack que incluye un intake (en 0.23.0, el pack Design) o si quieres dar uno a tu propio pack.

Por qué preguntar primero#

Un pack actúa con lo que sabe. Diseñar una pantalla para «un panel» sin saber quién lo usa, en qué dispositivo y para qué tarea produce una plantilla genérica que no le sirve a nadie. El coste de la respuesta que falta no se ve hasta que el trabajo está hecho. El intake adelanta ese coste: cada pregunta dice si el pack puede empezar sin ella, qué propone si te da igual y qué sale mal si no lo sabes.

Intervienen tres archivos. El intake (intake.yaml) viene con el pack. El archivo de respuestas es JSON y solo lo escribe bmad-plus intake record. El brief es Markdown y solo lo escribe bmad-plus intake render. Quien pregunta es tu asistente; el comando nunca pregunta nada ni llama a ningún modelo.

Cada respuesta tiene un estado#

El pack está listo cuando cada pregunta imprescindible (must-have) está respondida o marcada como desconocida con su riesgo. «Listo» no significa que los riesgos hayan desaparecido: el brief los lista bajo «Open questions», y se espera que un entregable construido sobre un must-have desconocido repita el riesgo en su primer párrafo. Un valor que elegiste tú se registra con --set aunque coincida con el valor por defecto; --default solo sirve para decir «acepto lo que propones».

El archivo intake.yaml, campo a campo#

El validador es estricto: un campo desconocido, un tipo erróneo o una regla rota es un error, nunca se ignora en silencio. El mismo validador se ejecuta cuando llamas a bmad-plus intake check y cuando se construye el propio BMAD+.

El ciclo: plan, pregunta, registro, redacción#

1. 01

   Planificar

   El comando lista las preguntas siguientes: primero las imprescindibles, luego las demás en el orden del archivo, como máximo max_per_message. Sale con 0 cuando está listo y con 2 mientras quede abierto un must-have.

   En la terminal del proyecto

   npx bmad-plus intake plan --intake FILE --answers FILE

2. 02

   Preguntar

   El asistente hace esas preguntas en un solo mensaje, en tu idioma, con las opciones o los límites, y propone el valor por defecto cuando lo hay. No rellena el mensaje ni vuelve a preguntar lo que ya está registrado.

3. 03

   Registrar

   Cada respuesta se comprueba según el tipo y los límites de la pregunta y se rechaza si no encaja (no se escribe nada). UNKNOWN registra el riesgo; --default registra la propuesta. Una pregunta solo puede fijarse una vez por llamada.

   En la terminal del proyecto

   npx bmad-plus intake record --intake FILE --answers FILE --set id=VALUE --default other_id

4. 04

   Repetir hasta que esté listo

   Vuelve a planificar. Cuando dice ready, se deja de preguntar aunque queden preguntas opcionales: el asistente nombra las que siguen abiertas y avanza, salvo que quieras continuar.

5. 05

   Redactar el brief

   El brief lista cada sección y cada respuesta con su estado, y después las preguntas abiertas con sus riesgos. Es la entrada del siguiente paso del pack.

   En la terminal del proyecto

   npx bmad-plus intake render --intake FILE --answers FILE --out brief.md

Un ejemplo completo: el design read del pack Design#

El único intake que se entrega en 0.23.0 pertenece al pack Design. Atelier, su agente, lo ejecuta antes de cualquier trabajo de diseño (/design read). Tiene 13 preguntas en 5 secciones, 3 de ellas imprescindibles: la superficie, la audiencia y la tarea que debe cumplir la página. Los tres ajustes (variance, motion, density) y el stack no llevan valor por defecto a propósito: un ajuste que dejas abierto lo fija Atelier a partir de la superficie, y el brief anota que fue inferido.

Esta es una ejecución real de la CLI 0.23.0 sobre este intake (un panel para contables, con las respuestas escritas en francés). Primero la validez, luego el plan con su código de salida 2, después tres respuestas y por último el brief.

$ npx bmad-plus intake check .agents/skills/pack-design/intake.yaml
.agents/skills/pack-design/intake.yaml: valid intake design-read (design), 13 questions, 3 must-have.
$ npx bmad-plus intake plan --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json
design-read (design): not ready — 0 answered, 0 defaulted, 0 unknown, 13 not asked yet.
Must-haves still open: surface_kind, audience, job
Ask next (at most 6 per message):
  - surface_kind [choice] Which surface is this? A marketing landing page, a dashboard, a data table, a form, an auth or onboarding flow, a mobile screen, an email, a chat or AI surface, a checkout, a settings page, or something else? (must-have; choices: landing, dashboard, table, form, auth, onboarding, mobile, email, ai-chat, checkout, settings, other)
  - audience [text] Who uses it, and in what situation (device, time pressure, expertise, frequency)? (must-have)
  - job [text] What is the one job this page must get done, and how will you know it did? (must-have)
# En la salida real siguen tres preguntas opcionales más (brand_assets, design_system, aesthetic_family). El código de salida es 2: no está listo.
$ npx bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set surface_kind=dashboard --set "audience=Comptables en cabinet, sur ordinateur, en fin de mois" --set "job=Repérer les factures en retard et relancer en un clic"
Recorded surface_kind, audience, job in _bmad-output/design/intake.json.
design-read (design): ready — 3 answered, 0 defaulted, 0 unknown, 10 not asked yet.
$ npx bmad-plus intake render --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --out _bmad-output/design/brief.md
Brief written to _bmad-output/design/brief.md (3022 bytes); the intake is ready.
$ head -n 3 _bmad-output/design/brief.md
# Design read
<!-- owned by bmad-plus intake design-read; written by bmad-plus intake render, do not edit -->

# La lista «Ask next» que record imprime después de cada lote se omite aquí. El último comando muestra las tres primeras líneas del brief.

La segunda transcripción continúa con otro escenario (una landing page para una cafetería) y muestra los otros dos estados: un valor por defecto aceptado con --default, un valor elegido con --set y un ajuste marcado como desconocido. Fíjate en que el plan sigue en «ready» con un ajuste desconocido porque no es un must-have, y en que el brief siguiente refleja el estado de cada respuesta.

$ npx bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set surface_kind=landing --set "audience=Urban professionals who buy coffee most days; on a phone, on the way to work, a few seconds of attention" --set "job=Get a first-time visitor to open a loyalty card; success is the sign-up button being tapped"
Recorded surface_kind, audience, job in _bmad-output/design/intake.json.
design-read (design): ready — 3 answered, 0 defaulted, 0 unknown, 10 not asked yet.
$ npx bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set brand_assets=partial --default design_system --default aesthetic_family --set motion=3 --set variance=UNKNOWN
Recorded brand_assets, motion, variance, design_system, aesthetic_family in _bmad-output/design/intake.json.
design-read (design): ready — 5 answered, 2 defaulted, 1 unknown, 5 not asked yet.
Unknown: variance
$ npx bmad-plus intake render --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --out _bmad-output/design/brief.md
Brief written to _bmad-output/design/brief.md (3043 bytes); the intake is ready.
# Se omiten las listas «Ask next» que imprime record.

# Design read
<!-- owned by bmad-plus intake design-read; written by bmad-plus intake render, do not edit -->

Intake `design-read` of pack `design` — 5 answered, 2 defaulted, 1 unknown, 5 not asked yet. Ready.

## Who and why

### audience (must-have)

Who uses it, and in what situation (device, time pressure, expertise, frequency)?

Answer:
    Urban professionals who buy coffee most days; on a phone, on the way to work, a few seconds of attention
Feeds: brief.md#audience

### design_system

Is a design system or component library already in use?

Answer (proposed default, not confirmed by the user):
    none
Feeds: brief.md#design-system

### variance

Layout variance, from 1 (symmetric and safe) to 10 (asymmetric and bold)? Leave it open and Atelier sets it from the surface.

Answer: unknown
Feeds: brief.md#dials

## Open questions

- variance: unknown
- density: not asked yet
- stack: not asked yet
- accessibility_target: not asked yet
- languages: not asked yet
- required_states: not asked yet

Atelier construye entonces a partir de este brief. Las reglas que sigue vienen del pack Design: una respuesta conserva su estado en todos los entregables (un valor por defecto o una inferencia se señala donde se usó, un must-have desconocido viaja con su riesgo), y un ajuste que se dejó abierto se fija según la superficie y se anota como inferido.

Lanza el intake de diseño antes de construir nada. Usa bmad-plus intake plan para ver qué sigue abierto, hazme como máximo seis preguntas cada vez en mi idioma empezando por las imprescindibles, propón los valores por defecto, registra lo que no sé con su riesgo y luego redacta el brief y enséñamelo antes de empezar.

Escribir el intake de tu propio pack#

Cualquier archivo de tu proyecto puede ser un intake: bmad-plus intake check|plan|record|render aceptan rutas simples relativas al proyecto. El ejemplo siguiente es un pack inventado llamado releasekit. Tiene dos must-have con un riesgo cada uno, un valor por defecto honesto (la audiencia es «both» salvo indicación en contra), un número acotado y una lista libre.

schema_version: 1
id: release-notes
pack: releasekit
title: Release notes brief
language: user
max_per_message: 4
sections:
  - id: release
    title: The release
    questions:
      - id: version
        ask: Which version is being released?
        kind: text
        must_have: true
        feeds: [brief.md#release]
        risk_if_unknown: The notes cannot say what changed in which version.
      - id: audience
        ask: Who reads the notes?
        kind: choice
        choices: [developers, end-users, both]
        default: both
        feeds: [brief.md#audience]
  - id: content
    title: What goes in
    questions:
      - id: breaking_changes
        ask: Is anything breaking for existing users?
        kind: boolean
        must_have: true
        risk_if_unknown: A breaking change ships without a migration note.
      - id: highlights
        ask: What are the highlights, one per item?
        kind: list
      - id: max_words
        ask: How long may the notes be?
        kind: number
        min: 50
        max: 2000
        default: 300

Valida primero. El archivo siguiente está roto a propósito (un must-have con valor por defecto y sin riesgo, una elección con un solo valor); el validador informa de los tres problemas a la vez. Después el terminal valida el archivo correcto y recorre el ciclo con él.

schema_version: 1
id: broken-demo
pack: releasekit
title: A deliberately broken intake
sections:
  - id: release
    title: The release
    questions:
      - id: version
        ask: Which version is being released?
        kind: text
        must_have: true
        default: "1.0.0"
      - id: audience
        ask: Who reads the notes?
        kind: choice
        choices: [everyone]

$ npx bmad-plus intake check intake/broken.yaml
intake/broken.yaml: not a valid intake
  - sections[0].questions[0]: a must-have question needs "risk_if_unknown"
  - sections[0].questions[0]: a must-have question takes no "default"; the user answers it
  - sections[0].questions[1]: a choice needs at least two distinct non-empty "choices"
# Código de salida 1.
$ npx bmad-plus intake check intake/release-notes.yaml
intake/release-notes.yaml: valid intake release-notes (releasekit), 5 questions, 2 must-have.
$ npx bmad-plus intake plan --intake intake/release-notes.yaml --answers notes/answers.json
release-notes (releasekit): not ready — 0 answered, 0 defaulted, 0 unknown, 5 not asked yet.
Must-haves still open: version, breaking_changes
Ask next (at most 4 per message):
  - version [text] Which version is being released? (must-have)
  - breaking_changes [boolean] Is anything breaking for existing users? (must-have)
  - audience [choice] Who reads the notes? (choices: developers, end-users, both; default: "both")
  - highlights [list] What are the highlights, one per item?
$ npx bmad-plus intake record --intake intake/release-notes.yaml --answers notes/answers.json --set version=UNKNOWN --set breaking_changes=yes --default audience --set "highlights=faster install, new swarm command"
Recorded version, breaking_changes, highlights, audience in notes/answers.json.
release-notes (releasekit): ready — 2 answered, 1 defaulted, 1 unknown, 1 not asked yet.
Ask next (at most 4 per message):
  - max_words [number] How long may the notes be? (default: 300)
Unknown: version — risk: The notes cannot say what changed in which version.
$ npx bmad-plus intake record --intake intake/release-notes.yaml --answers notes/answers.json --set max_words=40
Intake: max_words: value must be at least 50
$ npx bmad-plus intake record --intake intake/release-notes.yaml --answers notes/answers.json --set max_words=250
Recorded max_words in notes/answers.json.
release-notes (releasekit): ready — 3 answered, 1 defaulted, 1 unknown, 0 not asked yet.
Unknown: version — risk: The notes cannot say what changed in which version.
$ npx bmad-plus intake render --intake intake/release-notes.yaml --answers notes/answers.json --out notes/brief.md
Brief written to notes/brief.md (921 bytes); the intake is ready.

# Release notes brief
<!-- owned by bmad-plus intake release-notes; written by bmad-plus intake render, do not edit -->

Intake `release-notes` of pack `releasekit` — 3 answered, 1 defaulted, 1 unknown, 0 not asked yet. Ready.

## The release

### version (must-have)

Which version is being released?

Answer: unknown — risk: The notes cannot say what changed in which version.
Feeds: brief.md#release

### audience

Who reads the notes?

Answer (proposed default, not confirmed by the user):
    both
Feeds: brief.md#audience

## What goes in

### breaking_changes (must-have)

Is anything breaking for existing users?

Answer:
    yes

### highlights

What are the highlights, one per item?

Answer:
    faster install
    new swarm command

### max_words

How long may the notes be?

Answer:
    250

## Open questions

- version (must-have): unknown — risk: The notes cannot say what changed in which version.

Escribir preguntas que se ganen su sitio#

• Haz imprescindible una pregunta solo si el pack de verdad no puede hacer nada útil sin ella. La frase de riesgo es la prueba: si no sabes decir qué sale mal, no es un must-have.
• Da un valor por defecto solo cuando sea honesto, es decir, cuando la mayoría de la gente lo elegiría y equivocarse cuesta poco. Un valor por defecto aparece en el brief como propuesta, así que nunca pasa por palabra del usuario.
• Prefiere un choice al texto libre cuando la respuesta guía una decisión del pack: el valor se puede comprobar y el brief sigue siendo comparable de una ejecución a otra.
• Acota los números con min y max: un valor rechazado se detecta en record, no se descubre en el entregable.
• Mantén max_per_message bajo (de 3 a 6). Un formulario largo se responde mal y se lee por encima.
• Usa feeds para decir qué artefacto moldea cada respuesta. No cuesta nada y permite a quien revisa remontarse de una decisión a una pregunta.
• Escribe ask en el lenguaje llano que usarías con un cliente. El asistente la traduce para el usuario cuando language es user; no escribas varios idiomas en un mismo archivo.

Dónde vive el archivo#

En un proyecto, pon el archivo donde quieras y pásalo con --intake; hay que decirle al asistente dónde está (una línea en tu adaptador o en la habilidad que dirige el trabajo). Para integrarlo en un pack del repositorio fuente de BMAD+, añade intake: intake.yaml al pack en registry.yaml (la ruta es relativa a la carpeta del pack): entonces el build lo valida, el instalador lo copia y bmad-plus doctor lo exige. El registro es un archivo del repositorio fuente; no se instala en tu proyecto. Consulta la página del registro.

Escribe un archivo de intake en intake/release-notes.yaml con las preguntas que siempre olvidamos antes de redactar notas de versión: la versión, si algo rompe compatibilidad, quién lee las notas, los puntos destacados y un límite de longitud. Haz imprescindibles solo la versión y la pregunta sobre cambios que rompen, cada una con el riesgo si queda desconocida. Pon valor por defecto solo donde sea honesto. Luego ejecuta bmad-plus intake check sobre él y corrige todos los problemas que informe antes de enseñarme el archivo.

Seguridad y límites#

• Las respuestas solo se escriben con record y el brief solo con render. No edites ninguno a mano.
• render solo sobrescribe un brief si el archivo empieza con la marca de propiedad del mismo intake (línea 2). Nunca reemplaza un brief que no escribió. record solo sobrescribe un archivo de respuestas del mismo intake.
• Ninguno de los dos comandos escribe bajo .git/, _bmad/, .bmad-plus/ o node_modules/, ni a través de un enlace simbólico.
• Lo que escribiste se imprime como bloque con sangría bajo Answer:, de modo que un valor nunca puede convertirse en un encabezado o un elemento de lista del brief.
• Si el archivo de intake cambia después de registrar respuestas, plan informa de la discrepancia. record --reset vuelve a empezar el archivo de respuestas, vacío, para el mismo id de intake; nunca reinicia un archivo que pertenece a otro intake.
• El pack no debe iniciar su pipeline ni un enjambre mientras un must-have no esté respondido ni marcado como desconocido. Los comandos no lo comprueban por sí mismos: es una instrucción de las habilidades autopilot y Nexus, que piden al asistente ejecutar primero el intake de cada pack implicado, en Discovery.
• El runtime no pregunta nada, no inventa nada y no llama a ningún modelo. Un valor rechazado no cambia nada en el disco.