Patrones de composición
Un patrón de composición es una forma probada de combinar skills dentro de un plan. Hay siete. Cada uno resuelve un tipo de coordinación distinto: encadenar, paralelizar, derivar, validar, revisar, repetir y compartir contexto.
Esta guía explica cada patrón, cómo se escribe en un plan del engine y en qué planes reales se usa. La definición conceptual completa está en ARCHITECTURE.md (sección 3) del repo crowdar-qa-skills.
Resumen
| # | Patrón | Para qué | Cómo se escribe en el engine |
|---|---|---|---|
| 3.1 | Sequential Pipeline | Encadenar skills, cada una con la salida de la anterior | Pasos en orden + ${...} |
| 3.2 | Fan-out / Fan-in | Ejecutar varias skills (o la misma sobre varios datos) al mismo tiempo | for_each o parallel |
| 3.3 | Router / Dispatcher | Elegir qué camino seguir según el input | Modelo 2 (entre planes) o when (dentro del plan) |
| 3.4 | Validator / Guard | Validar antes de pasar al siguiente paso | guard y stop_unless |
| 3.5 | Reviewer | Que otra skill, con contexto limpio, revise el resultado | Un paso revisor + stop_unless |
| 3.6 | Loop con criterio de salida | Repetir hasta cumplir un objetivo | Dentro de la skill, con tope de iteraciones |
| 3.7 | Chain-of-Skills con contexto compartido | Que un paso use datos de varios pasos anteriores | output_to + ${...} sobre el contexto append-only |
3.1 Sequential Pipeline
Qué es: skill A → skill B → skill C. Cada una toma la salida de la anterior.
Cuándo: cuando hay una dependencia lineal: no se puede planificar sin haber leído la historia, ni generar tests sin el plan.
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.description}
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
guard: true
- skill: lippia-neo-generate-test-suite
tools: [file]
input:
manual_execution_report_path: "execution/${user_story.us_id}/${user_story.us_id}-scripted-execution-report.json"
output_to: new_tests
A tener en cuenta:
- Usá
guard: trueen cada paso cuya salida consuma el siguiente: si un paso devuelve algo mal formado, es mejor cortar ahí que arrastrar el error. - Las salidas tienen que ser datos estructurados (lo garantiza el
output_schemade cada skill), no texto libre.
En planes reales: todos. feature-new-end-to-end (pasos 1 a 6), qa-bug-fix-verification (1 a 4), ui-selector-repair (1 a 3).
3.2 Fan-out / Fan-in
Qué es: se lanzan varias ejecuciones al mismo tiempo y después se juntan los resultados. Hay dos variantes:
Variante A — la misma skill sobre una lista (for_each)
steps:
- skill: lippia-neo-create-test-plan
for_each: ${input.user_stories} # una lista
tools: [file]
input:
user_story: ${item} # el elemento actual
output_to: test_plans # queda una lista, en el mismo orden
continue_on_error: true # si una falla, siguen las demás
Si input.user_stories tiene tres historias, la skill se ejecuta tres veces en paralelo y test_plans queda como una lista con los tres resultados (null en la posición de una que falló, si hay continue_on_error).
Variante B — skills distintas al mismo tiempo (parallel)
steps:
- parallel:
- skill: lippia-neo-find-existing-tests
tools: [file]
input:
source_summary: ${bug_summary}
output_to: coverage
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${bug_summary.related_user_story}
output_to: related_story
continue_on_error: false
- skill: lippia-neo-review-test-coverage # fan-in: usa las dos salidas
tools: [file]
input:
existing_tests: ${coverage.existing_tests}
related_us_summary: ${related_story}
output_to: coverage_review
A tener en cuenta:
- El engine hace como máximo 5 ejecuciones a la vez. Si la lista tiene 50 elementos, los procesa de a 5, para no saturar los límites de uso del proveedor de IA.
- Los sub-pasos de un
parallelno pueden leer la salida de otro sub-paso del mismo grupo: se ejecutan al mismo tiempo. Solo pueden usar datos de pasos anteriores. - Sin
continue_on_error, si una ejecución falla, falla el paso entero.
En planes reales: ninguno de los planes actuales lo usa todavía. Es el candidato natural para generar planes de prueba de varias historias de una épica, o para ejecutar exploraciones independientes en paralelo.
3.3 Router / Dispatcher
Qué es: algo clasifica el input y lo deriva al camino correcto. El router tiene que informar qué tan seguro está, para poder escalar a un humano cuando duda.
En el engine hay dos niveles:
Nivel 1 — entre planes (Modelo 2)
Lo hace el engine solo, con neo run --input "<texto>": la skill lippia-neo-classify-task elige el plan y el engine escala a un humano si la confianza es menor a 0,7. Ver Modelos de orquestación en el engine.
Nivel 2 — dentro de un plan (when)
Un paso clasifica y devuelve los datos que deciden el camino; los pasos siguientes usan when para ejecutarse solo si les corresponde:
steps:
# El clasificador: decide de dónde sale la historia
- skill: lippia-neo-resolve-user-story-source
tools: [file]
input:
user_story: ${input.description}
output_to: resolved_source
guard: true
# Camino A: solo si es un ticket de Jira. `file` es para que la skill lea su references/jira.md
- skill: lippia-neo-fetch-user-story
when: ${resolved_source.fetch_url_jira}
tools: [jira, file]
input:
story_ref: ${resolved_source.fetch_url_jira}
provider: jira
output_to: jira_fetch
# Camino B: solo si es un work item de Azure DevOps. `file` es para que la skill lea su references/azure-devops.md
- skill: lippia-neo-fetch-user-story
when: ${resolved_source.fetch_url_azure_devops}
tools: [azure-devops, file]
input:
story_ref: ${resolved_source.fetch_url_azure_devops}
provider: azure-devops
output_to: azure_fetch
Los dos caminos usan la misma skill de fetch, con un provider fijo distinto: como skill: no puede ser una referencia, cada rama es un paso propio. Si la historia es un archivo local, ninguno de los dos caminos se ejecuta y el plan sigue con el paso siguiente.
A tener en cuenta:
whenevalúa una referencia, no una expresión:${x.confidence > 0.7}no funciona. La skill clasificadora tiene que devolver directamente el dato que decide (un booleano, una URL o una lista que puede venir vacía).- El nombre de la skill (
skill:) no puede ser una referencia: el engine no soportaskill: ${clasificacion.tipo}. Cada camino posible se escribe como un paso con suwhen.
En planes reales: feature-new-end-to-end (pasos 1a → 1b Jira | 1c Azure DevOps); qa-bug-coverage (el paso 1.5 se ejecuta solo si el bug referencia una historia).
3.4 Validator / Guard
Qué es: un control entre dos pasos, para no pasar downstream algo inválido.
El engine tiene dos controles, que se combinan:
| Control | Valida | Si falla |
|---|---|---|
guard: true |
El formato: que la salida cumpla el output_schema de la skill |
El plan termina en failed |
stop_unless: ${...} |
El contenido: que el dato indique que se puede seguir | El plan termina en stopped (corte previsto, no error) |
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.description}
output_to: user_story
guard: true # formato correcto
stop_unless: ${user_story.can_continue} # la historia tiene lo mínimo para seguir
- skill: lippia-neo-create-test-plan
tools: [file]
input:
us_id: ${user_story.us_id}
user_story: ${user_story.summary}
output_to: test_plan
guard: true
stop_unless: ${test_plan.scenarios} # sin escenarios, no tiene sentido explorar
También se puede poner una skill validadora como paso propio, entre el productor y el consumidor, y cortar con su resultado:
- skill: validar-gherkin # skill validadora (ejemplo)
input:
draft: ${draft}
output_to: validation
guard: true
stop_unless: ${validation.valid}
A tener en cuenta:
- Los errores de una skill validadora tienen que ser accionables ("línea 5: Given sin Then"), no genéricos.
- Si la validación se reintenta, siempre con un tope de intentos.
En planes reales: todos usan guard. stop_unless aparece en feature-new-end-to-end (pasos 1d y 2), qa-bug-coverage (paso 4: corta si el bug no se reproduce) y qa-bug-fix-verification (paso 2: corta si no hay tests que cubran el bug).
3.5 Reviewer (revisión con contexto limpio)
Qué es: una variante del validador donde el control lo hace otra skill con juicio de IA, en lugar de reglas. La clave es que el revisor tenga contexto limpio: el que produjo el resultado tiende a defenderlo.
En el engine, cada paso es una invocación independiente que solo ve lo que recibe en su input. Un paso revisor tiene contexto limpio por diseño. Además, conviene usar un modelo distinto al del productor:
steps:
- skill: lippia-neo-create-test-plan
tools: [file]
input:
user_story: ${user_story.summary}
output_to: test_plan
guard: true
- skill: revisar-plan-de-pruebas # skill revisora (ejemplo)
model: anthropic/claude-sonnet-4-5 # otro modelo que el productor
input:
user_story: ${user_story.summary} # solo lo necesario para juzgar
test_plan: ${test_plan}
output_to: plan_review
guard: true
stop_unless: ${plan_review.approved}
A tener en cuenta:
- Pasale al revisor solo lo que necesita para juzgar, no el historial del productor.
- No es un mecanismo propio del engine: se arma con un paso más,
modelystop_unless. Requiere que exista la skill revisora con unoutput_schemaque devuelva el veredicto.
En planes reales: ninguno de los planes actuales lo usa todavía.
3.6 Loop con criterio de salida
Qué es: repetir algo hasta cumplir un objetivo (por ejemplo, que todos los tests pasen), con un tope de vueltas y detección de estancamiento.
En el engine, el ciclo vive dentro de la skill, no en el plan. El plan solo le da el presupuesto:
- skill: lippia-neo-run-and-heal
tools: [file, shell]
loop:
max_iterations: 100 # presupuesto del agente: cuántas veces puede usar herramientas
input:
config:
max_iterations: 3 # tope del ciclo: ejecutar → reparar → ejecutar
run_label: post-fix
output_to: heal_summary
guard: true
lippia-neo-run-and-heal ejecuta la suite, repara lo que falla y vuelve a ejecutar, hasta que todo pase, se llegue al tope o detecte que dejó de mejorar. Su salida dice cómo terminó (por ejemplo green, plateau_abort o max_iter_abort), y el paso siguiente puede usar ese dato.
A tener en cuenta:
- El tope de iteraciones no es opcional: sin él, un ciclo puede no terminar nunca y consumir créditos sin límite.
- Hay que detectar el estancamiento: si dos vueltas seguidas no mejoran, conviene salir y escalar.
- El engine no tiene un loop "evaluador" genérico a nivel de plan; si lo necesitás, el ciclo va dentro de una skill.
En planes reales: feature-new-end-to-end (paso 5), qa-bug-fix-verification (paso 3) y ui-selector-repair (paso 3), siempre a través de lippia-neo-run-and-heal.
3.7 Chain-of-Skills con contexto compartido
Qué es: varias skills trabajan sobre un mismo contexto, cada una le agrega información, y un paso puede leer datos de cualquier paso anterior, no solo del último.
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.description}
output_to: user_story
- skill: lippia-neo-run-manual-testing
tools: [browser, file]
input:
test_plan_path: "test-plans/${user_story.us_id}-test-plan.md"
output_to: exploration
- skill: lippia-neo-run-and-heal
tools: [file, shell]
input:
config:
run_label: feature-e2e
output_to: heal_summary
- skill: lippia-neo-write-test-report
tools: [file]
input: # lee de tres pasos distintos
us_id: ${user_story.us_id}
manual_results: ${exploration}
automation_results:
- label: feature-e2e
run: ${heal_summary}
output_to: report
A tener en cuenta:
- El contexto es append-only: cada
output_toagrega una clave nueva y reusar una clave ya escrita corta el plan. Así cada dato tiene un único origen. - Todo lo que se escribe en el contexto queda en la auditoría (
audit.db, tablacontext): el historial del contexto es el historial de la ejecución.
En planes reales: feature-new-end-to-end (el paso 6 lee los pasos 1d, 3 y 5), qa-bug-coverage (el paso 5 lee los pasos 2, 3 y 4) y qa-bug-fix-verification (el paso 4 lee los pasos 1 y 3).
Qué patrón usar
flowchart TD
A{¿Las skills son<br/>independientes entre sí?} -- Sí --> B{¿Hay que juntar<br/>los resultados?}
B -- Sí --> FO[3.2 Fan-out / Fan-in]
B -- No --> SEP[Planes o pasos separados]
A -- No --> C{¿La dependencia<br/>es lineal?}
C -- Sí --> D{¿La salida puede<br/>ser inválida?}
D -- Sí --> SV[3.1 Sequential + 3.4 Guard<br/>o 3.5 Reviewer]
D -- No --> S[3.1 Sequential]
C -- No --> E{¿Hay un criterio<br/>de salida claro?}
E -- Sí --> L[3.6 Loop con criterio]
E -- No --> CH[3.7 Contexto compartido]
Y si el camino depende del input (Jira o Azure, hay tests o no los hay), sumá un 3.3 Router con when.
Ejemplo real completo: feature-new-end-to-end
El plan que se ejecuta hoy en el CI con el label feature combina cinco de los siete patrones:
| Paso | Skill | Patrones |
|---|---|---|
| 1a | lippia-neo-resolve-user-story-source |
3.1, 3.3 (clasifica el origen), 3.4 |
| 1b | lippia-neo-fetch-user-story (provider: jira) |
3.3 (when: solo Jira), 3.4 |
| 1c | lippia-neo-fetch-user-story (provider: azure-devops) |
3.3 (when: solo Azure DevOps), 3.4 |
| 1d | lippia-neo-read-user-story |
3.1, 3.4 (stop_unless: can_continue) |
| 2 | lippia-neo-create-test-plan |
3.1, 3.4 (stop_unless: scenarios) |
| 3 | lippia-neo-run-manual-testing |
3.1, 3.4 |
| 4 | lippia-neo-generate-test-suite |
3.1, 3.4 |
| 5 | lippia-neo-run-and-heal |
3.1, 3.4, 3.6 (ciclo ejecutar → reparar) |
| 6 | lippia-neo-write-test-report |
3.4, 3.7 (lee 1d, 3 y 5) |
El YAML completo está en plans/feature-new-end-to-end.yaml del repo crowdar-engine-mvp, comentado paso por paso.