Anatomía de un plan
Un plan es un archivo YAML que describe un flujo de trabajo: qué skills se ejecutan, en qué orden, con qué datos y qué pasa si algo sale mal. El engine lo lee, lo valida y lo ejecuta. Esta guía es la referencia completa del formato.
1. Un plan mínimo
name: leer-y-planificar
description: Lee una historia de usuario y genera su plan de pruebas.
default_model: anthropic/claude-haiku-4-5-20251001
required_keys:
- user_story_path: Path local al .md de la historia de usuario.
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.user_story_path}
output_to: user_story
guard: true
- skill: lippia-neo-create-test-plan
tools: [file]
input:
us_id: ${user_story.us_id}
user_story: ${user_story.summary}
output_to: test_plan
Se ejecuta con:
neo run plans/leer-y-planificar.yaml --workspace . \
--data '{"user_story_path":"user-stories/US-010.md"}'
2. Campos del plan
| Campo | Obligatorio | Qué es |
|---|---|---|
name |
Sí | Identificador del plan. En el Modelo 2 es lo que devuelve el clasificador, y lo que reemplaza un overlay |
description |
No (sí para M2) | Qué hace el plan y cuándo corresponde. Es lo único que ve el clasificador del Modelo 2 |
version |
No | Versión del plan. Default 0.1.0 |
default_model |
Sí | Modelo de IA para todos los pasos, en formato proveedor/modelo (por ejemplo openai/gpt-5.4) |
stack |
No | Carpeta de las skills. Si está, tiene prioridad sobre CROWDAR_SKILLS_DIR. Conviene no usarlo: un path fijo solo funciona con los repos clonados en esa ubicación |
required_keys |
No | Los datos que el plan necesita recibir como input (ver punto 4) |
steps |
Sí (al menos uno) | La lista de pasos |
3. Campos de cada paso
Cada paso es o bien una skill (skill:) o bien un grupo de pasos en paralelo (parallel:), nunca las dos cosas.
| Campo | Qué hace | Ejemplo |
|---|---|---|
skill |
La skill a ejecutar (el nombre de su carpeta) | lippia-neo-create-test-plan |
input |
Los datos que recibe la skill. Pueden ser fijos o referencias ${...} |
us_id: ${user_story.us_id} |
output_to |
Bajo qué nombre se guarda lo que devuelve, para que lo lean los pasos siguientes | test_plan |
tools |
Las herramientas que puede usar la skill mientras trabaja (ver punto 6). Si hay al menos una, la skill se ejecuta como agente | [file, browser] |
model |
Modelo para este paso solamente, en lugar de default_model |
anthropic/claude-sonnet-4-5 |
loop.max_iterations |
Cuántas vueltas de herramientas puede dar el agente en este paso. Default 8 |
max_iterations: 100 |
guard |
Si es true y la salida no cumple el schema de la skill, el plan termina con estado failed |
true |
when |
El paso se ejecuta solo si esta referencia tiene un valor "verdadero" | ${resolved_source.fetch_url_jira} |
stop_unless |
Después del paso, si esta referencia es "falsa", el plan se detiene con estado stopped |
${user_story.can_continue} |
for_each |
Ejecuta la skill una vez por cada elemento de una lista, en paralelo | ${historias} |
parallel |
Una lista de pasos que se ejecutan al mismo tiempo | ver Patrones |
continue_on_error |
En for_each o parallel: si un elemento falla, sigue con los demás |
true |
3.1 guard vs. stop_unless
Los dos cortan el plan, pero por motivos distintos:
guard: true |
stop_unless: ${...} |
|
|---|---|---|
| Qué controla | Que la salida tenga el formato correcto (schema) | Que el contenido permita seguir |
| Cuándo corta | La skill devolvió algo mal formado | La skill devolvió algo válido, pero que indica que no tiene sentido seguir (por ejemplo, la historia no tiene criterios de aceptación) |
| Estado final | failed (código 1) |
stopped (código 0) |
| Es un error | Sí | No: es un corte previsto |
Sin guard, una salida inválida sigue de largo
Si un paso no tiene guard: true y la skill devuelve algo que no cumple su schema, el paso queda marcado como inválido en la auditoría, pero el plan continúa. Poné guard: true en todo paso cuya salida usen los pasos siguientes.
3.2 loop.max_iterations no es "repetir la skill"
loop.max_iterations es el presupuesto de vueltas del agente dentro de un mismo paso: cuántas veces puede usar herramientas (leer un archivo, hacer clic, ejecutar un comando) antes de que el engine lo corte. No repite la skill entera.
Si la skill tiene su propio ciclo (por ejemplo, lippia-neo-run-and-heal ejecuta la suite, repara y vuelve a ejecutar), ese ciclo se configura en el input de la skill, no en loop:
- skill: lippia-neo-run-and-heal
tools: [file, shell]
loop:
max_iterations: 100 # presupuesto del agente (engine)
input:
config:
max_iterations: 3 # ciclos ejecutar → reparar → ejecutar (skill)
4. required_keys
Lista los datos que el plan necesita recibir. Cada entrada puede ser solo el nombre, o el nombre con una descripción:
required_keys:
- identifier # solo el nombre
- bug_report: > # nombre + descripción
Referencia al bug: path local, URL de ticket (Jira/Azure DevOps),
o el reporte completo como texto.
- En el Modelo 4 documentan qué hay que pasar en
--data/--input-file. - En el Modelo 2 son lo que
lippia-neo-build-plan-inputtiene que extraer del pedido. La descripción es lo que le explica qué buscar: sin ella, la skill solo tiene el nombre de la clave. Si falta alguna, el engine escala a un humano.
La descripción es dato, no comentario
Escribila como clave: descripción, no como comentario YAML (# ...). Los comentarios se pierden al leer el archivo y nunca llegan al engine.
5. Referencias ${...}
Una referencia lee un dato del contexto del plan: el input inicial o lo que escribió un paso anterior con output_to.
| Referencia | Qué lee |
|---|---|
${input.description} |
La clave description del input del plan |
${user_story} |
Todo lo que escribió el paso con output_to: user_story |
${user_story.us_id} |
Un campo puntual de esa salida (se puede bajar varios niveles con puntos) |
${item} |
Dentro de un for_each: el elemento actual de la lista |
5.1 Cómo se resuelven
| Caso | Resultado |
|---|---|
El valor es solo la referencia: user_story: ${user_story} |
Se pasa el dato tal cual, con su tipo (objeto, lista, número) |
La referencia está dentro de un texto: "test-plans/${user_story.us_id}-test-plan.md" |
Se reemplaza como texto: "test-plans/US-010-test-plan.md" |
La referencia apunta a algo que nadie escribió, y la skill lo necesita (required_keys de la skill) |
El plan aborta en ese paso con UnresolvedRefError |
| La referencia apunta a algo que nadie escribió, pero el dato es opcional | Se pasa vacío (null, o "" dentro de un texto) y se registra un aviso |
Que un dato "no exista" es distinto de que exista con valor null: si un paso escribió null, la referencia se resuelve sin error.
5.2 when y stop_unless evalúan una referencia, no una expresión
when y stop_unless aceptan una referencia simple y miran si su valor es "verdadero". No aceptan comparaciones:
when: ${matched.has_matches} # bien
when: ${repair.repaired_tests} # bien: una lista vacía es "falsa"
when: ${classification.confidence > 0.7} # NO funciona: el engine no evalúa expresiones
Se consideran "falsos": false, null, 0, "", una lista vacía y un objeto vacío. Si necesitás una condición, la skill anterior tiene que devolver el booleano ya calculado.
5.3 El contexto es append-only
Cada output_to agrega una clave nueva. Escribir dos veces la misma clave es un error: el plan se corta. Esto garantiza que cada dato tenga un único origen y que la auditoría muestre exactamente qué paso escribió qué.
6. Herramientas (tools)
| Herramienta | Qué le permite a la skill | De dónde sale |
|---|---|---|
file |
Leer, listar y escribir archivos. Escribe solo dentro del --workspace; puede leer también la carpeta de skills |
Del engine |
shell |
Ejecutar comandos en la terminal, dentro del --workspace, con un límite de 120 segundos por comando |
Del engine |
browser |
Navegar la app: abrir páginas, hacer clic, sacar screenshots | Del adapter del framework (por ejemplo, el de Playwright lanza el MCP oficial de Playwright) |
jira, azure-devops, github, gitlab |
Leer tickets, crear bugs, etc. | De la sección mcp_servers de qa-stack.yaml |
Cómo resuelve el engine una herramienta que no es file ni shell:
- Busca una entrada con ese mismo nombre en
mcp_serversdeqa-stack.yaml. - Si no la encuentra, busca en lo que declara el adapter de la skill (
adapter.yaml, secciónprovides:). - Si tampoco, la ignora y deja un aviso en el log (
ignoring unknown tools). El paso sigue, pero sin esa herramienta.
El nombre tiene que coincidir exactamente
Si el plan pide tools: [atlassian] pero qa-stack.yaml declara mcp_servers.jira, el engine no los relaciona: la skill se ejecuta sin acceso a Jira. Usá en el plan los mismos nombres que en mcp_servers.
Cada servidor MCP se lanza al empezar el paso y se cierra al terminarlo, siempre con la carpeta del --workspace como directorio de trabajo.
7. Lo que el engine le agrega a cada skill
Además de lo que escribís en input, el engine le pasa a la skill, sin que lo pidas:
| Dato | Cuándo | Para qué |
|---|---|---|
adapter |
Si la skill tiene adapters y hay qa-stack.yaml |
La ruta e instrucciones del adapter del framework o CI del proyecto |
skill |
Si la skill tiene carpeta references/ |
La ruta absoluta de la skill y la lista de sus referencias, para que pueda leerlas |
8. Validación
El engine valida el plan antes de ejecutar el primer paso. Si algo no cumple el formato, no ejecuta nada y avisa:
error: invalid plan plans/mi-plan.yaml:
steps.0: a step needs either 'skill' or 'parallel' (exactly one)
Errores de formato frecuentes:
| Error | Causa |
|---|---|
a step needs either 'skill' or 'parallel' (exactly one) |
Un paso tiene las dos cosas, o ninguna |
'for_each' applies to a skill step, not a 'parallel' group |
Se combinó for_each con parallel |
a required_keys entry must be a bare key name, or a single key_name: description mapping |
Una entrada de required_keys tiene más de una clave |
Field required en default_model o name |
Falta un campo obligatorio del plan |