Saltar a contenido

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