Cómo ejecutarlo
El engine tiene cuatro comandos. Los dos primeros son los que vas a usar casi siempre:
| Comando | Para qué |
|---|---|
neo run <plan.yaml> |
Modelo 4: ejecutar un plan que ya elegiste |
neo run --input "<texto>" |
Modelo 2: que el engine elija el plan a partir de un pedido en texto libre |
neo event |
En el CI: convertir el evento del MR/PR en el input del plan |
neo report |
En el CI: comentar el resultado de la ejecución en el MR/PR |
neo matrix |
Comparar una skill entre varios modelos de IA (control de calidad de las skills) |
1. neo run — Modelo 4 (plan fijo)
neo run plans/feature-new-end-to-end.yaml \
--input-file input.json \
--workspace ../mi-proyecto \
--out result.json
El input es un JSON con las claves que pide el plan en required_keys. Para feature-new-end-to-end:
{ "description": "user-stories/US-010.md" }
También se puede pasar en línea con --data:
neo run plans/ui-selector-repair.yaml --workspace . \
--data '{"commit_id":"commit-1","code_diff_path":"diffs/PR-1.diff"}'
PowerShell
Si generás el input.json con Out-File -Encoding utf8, PowerShell le agrega una marca invisible (BOM) al principio. El engine la tolera: no hace falta convertir el archivo.
2. neo run --input — Modelo 2 (el engine elige el plan)
neo run --input "retesteá el flujo de pago, algo cambió ahí" \
--plans-dir plans \
--workspace ../mi-proyecto
El engine junta todos los planes de --plans-dir, le pide a la skill clasificadora que elija uno y lo ejecuta. Si la confianza es menor a 0,7, no ejecuta nada: escala a un humano. El detalle está en Modelos de orquestación en el engine.
Para pasar un archivo como pedido:
neo run --input "$(cat pedido.txt)" --plans-dir plans --workspace .
3. Opciones de neo run
| Opción | Modelo | Qué hace | Default |
|---|---|---|---|
<plan.yaml> |
M4 | El plan a ejecutar | — |
--input-file <json> |
M4 | Archivo JSON con el input del plan | — |
--data '<json>' |
M4 | Input del plan en línea | — |
--input "<texto>" |
M2 | Pedido en texto libre a clasificar | — |
--plans-dir <dir> |
M2 | Carpeta con los planes candidatos | plans |
--overlay-dir <dir> |
M2 | Carpeta con planes que reemplazan a los de --plans-dir con el mismo nombre |
— |
--threshold <n> |
M2 | Confianza mínima para ejecutar sin humano | 0.7 |
--workspace <dir> |
Ambos | Carpeta del repositorio de pruebas. Las skills solo pueden escribir ahí | Carpeta actual |
--out <json> |
Ambos | Guarda todo lo que produjo cada paso en un JSON | — |
--model <modelo> |
Ambos | Reemplaza el modelo del plan (o el del clasificador en M2) | El del plan |
--stack <framework/ci> |
Ambos | Reemplaza lo que dice qa-stack.yaml, por ejemplo playwright/github o solo lippia |
— |
--db <archivo> |
Ambos | Base de auditoría | audit.db |
4. Qué devuelve
4.1 Por pantalla
Al terminar, el engine imprime una línea de resumen:
run feature-new-end-to-end-3f9a1c2e: success (cost $0.4182, steps 8, cached False)
Mientras se ejecuta, además, imprime cada paso con su input y su estado ([step 2] lippia-neo-create-test-plan status=success ...).
4.2 Los estados posibles
| Estado | Qué pasó |
|---|---|
success |
Todos los pasos ejecutaron (o se saltearon por su when) |
stopped |
Un paso con stop_unless cortó el plan a propósito. Es un corte normal, no un error |
failed |
Un paso con guard: true devolvió algo que no cumple su schema |
error |
Algo se rompió: una referencia mal escrita, una skill que no existe, un error de red |
4.3 Códigos de salida
Importan en el CI, porque deciden si el job queda verde o rojo:
| Código | Cuándo |
|---|---|
0 |
success o stopped |
1 |
failed, error, o un problema de configuración (plan inválido, skill inexistente) |
2 |
Solo Modelo 2: la confianza fue baja y se escaló a un humano. No se ejecutó nada |
4.4 Archivos
| Archivo | Qué tiene |
|---|---|
result.json (con --out) |
Todo lo que escribió cada paso, bajo su output_to. Es lo que lee neo report |
audit.db |
La auditoría completa en SQLite: ejecuciones, pasos, modelo usado, tokens, costo, duración y cada dato del contexto |
| Los artefactos de las skills | Planes de prueba, tests, reportes y screenshots, en las carpetas que define qa-stack.yaml dentro del --workspace |
Para revisar la auditoría, cualquier visor de SQLite sirve. Las tablas son runs, steps y context.
5. neo event y neo report — en el CI
Estos dos comandos son la frontera con la plataforma de CI. El plan nunca sabe si se está ejecutando en GitLab o en GitHub:
neo event → neo run → neo report
(lee el MR/PR) (agnóstico) (comenta el resultado)
5.1 neo event
Lee las variables que inyecta la plataforma y escribe un JSON con siempre las mismas claves:
neo event --provider gitlab --out input.json
{
"event": "merge_request",
"project": "grupo/mi-proyecto",
"commit_sha": "a1b2c3...",
"branch": "feature/carrito",
"pr_id": "42",
"title": "Agregar producto al carrito",
"description": "user-stories/US-010.md",
"source_branch": "feature/carrito",
"target_branch": "develop",
"labels": ["feature"]
}
El plan las lee como ${input.description}, ${input.labels}, etc.
5.2 neo report
Toma el result.json y publica la clave summary como comentario en el MR/PR:
neo report --provider gitlab --result result.json
| Opción | Qué hace | Default |
|---|---|---|
--provider |
gitlab o github |
gitlab |
--result |
El JSON que dejó neo run --out |
— |
--summary-key |
Qué clave del resultado publicar | summary |
En GitLab necesita CROWDAR_CI_TOKEN con permiso api: el token por defecto del job no puede comentar MRs.
Reportar aunque falle
En el pipeline conviene capturar el código de salida de neo run, ejecutar neo report igual y recién después salir con ese código. Así el MR recibe el comentario pase o falle. Los templates de lippia-neo-ci-bootstrap ya lo hacen así.
6. neo matrix — control de calidad de una skill
Ejecuta una skill contra un caso de referencia ("golden") en varios modelos a la vez, valida cada salida y muestra una grilla:
neo matrix lippia-neo-create-test-plan --golden golden \
--models anthropic/claude-haiku-4-5-20251001,openai/gpt-4o-mini
PASS anthropic/claude-haiku-4-5-20251001 cost=$0.0123 ...
FAIL openai/gpt-4o-mini cost=$0.0041 missing required key 'scenarios'
matrix lippia-neo-create-test-plan: DRIFT DETECTED (1/2 cells, $0.0164)
Sale con código 1 si alguna celda falla. Sirve para detectar que un cambio en una skill rompió su comportamiento en algún proveedor. Los casos de referencia viven en la carpeta golden/ del repo del engine, una subcarpeta por skill.
7. Problemas comunes (y qué hacer)
| Lo que ves | Por qué pasa | Qué hacer |
|---|---|---|
cached True y el plan no hizo nada |
El mismo plan con exactamente el mismo input ya terminó bien antes (idempotencia) | Cambiá el input, usá otra base con --db otra.db, o borrá audit.db |
UnresolvedRefError: ... required input(s) reference keys nothing wrote |
Un ${...} del plan apunta a un dato que nadie escribió, y la skill lo necesita sí o sí |
Revisá que el input tenga esa clave (--data / --input-file) o corregí la referencia en el plan |
cannot read skill file: .../SKILL.md |
El engine no encuentra la skill en la carpeta de skills | Revisá CROWDAR_SKILLS_DIR, o el campo stack: del plan, que tiene prioridad |
ignoring unknown tools: ... en el log |
El paso pide una herramienta que no está en qa-stack.yaml (mcp_servers) ni la provee el adapter |
Agregá el servidor en mcp_servers con ese mismo nombre, o corregí el nombre en el plan |
| Falla al traer un ticket de Jira o Azure DevOps | Faltan las variables de entorno del MCP | Ver Requisitos e instalación |
escalated to human (código 2) |
En el Modelo 2, la confianza fue menor al umbral, o el pedido no traía los datos que necesita el plan | Reformulá el pedido con más detalle, o ejecutá el plan directo con el Modelo 4 |
Forbidden control character detected in headers |
Una API key con caracteres raros, en una versión vieja del engine | Actualizá el engine; las versiones actuales limpian la key solas |
En el CI, neo report falla con 401/403 |
CROWDAR_CI_TOKEN no tiene permiso api |
Generá un project/group access token con scope api |