Saltar a contenido

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-input tiene 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:

  1. Busca una entrada con ese mismo nombre en mcp_servers de qa-stack.yaml.
  2. Si no la encuentra, busca en lo que declara el adapter de la skill (adapter.yaml, sección provides:).
  3. 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