| name | dynamic-workflows |
| description | Orquestá manualmente tareas multiagente con los gates y patrones de Ultracode en Claude Code o Pi. |
| disable-model-invocation | true |
dynamic-workflows
Primero decidí si conviene orquestar, después diseñá el workflow y recién entonces ejecutalo. Este skill es
autocontenido y dual-platform: los conceptos (cuándo orquestar, primitivas, prompting, seguridad) se comparten; la
API concreta cambia entre Claude Code (Anthropic) y pi (un runtime que corre sobre Anthropic o OpenAI/Codex).
En Referencia de plataforma está la tool, los helpers y la forma de invocación de cada uno.
En 30 segundos
ultracode orquesta tareas multiagente cuando inline no alcanza (exhaustividad, confianza o escala). Primero gates;
después primitiva o patrón; al final la tool de tu plataforma. Ejemplo mínimo en pi:
dynamic_workflow({ action: "start", name: "task-slug", input: { request: "…" }, concurrency: 4 });
Glosario de nombres (producto vs skill vs tool):
docs/handbooks/glosario-skills.md. Para criterio de delegación (inline
vs orquestar), deferí a ai-assisted-engineering; este skill gobierna el cómo una vez decidido orquestar. Detalle
operativo (fan-out, model tiers, catálogo completo): reference/operational-notes.md.
El catálogo del lado de Claude vive en reference/catalog-prose.es.md (fuente canónica en español);
npm run sync:scaffold-catalog propaga snapshots a reference/scaffold-catalog.md y .claude/workflows/README.md para
el detalle completo por workflow.
Cuándo orquestar (gates, en orden)
Para casi todo, una sola llamada a un agente le gana a un workflow. Recorré estos gates en orden; la mayoría de las
tareas terminan temprano.
- Contract Gate. Ejecutá PHASE 0 y routeá desde su
contrato inspeccionable, no desde el pedido original.
- Trivial. Si es conversacional, de un paso o de apenas unas tool calls → hacelo directo. Un workflow consume
muchas model calls; no pagues ese costo por una edición rápida, un lookup o un cambio en un solo archivo.
- Scout inline primero. Si una tarea podría ser grande, sondéala barato en el turno actual (
git ls-files, leer
el diff, grep/glob, listar candidatos). Eso revela la work-list real y su tamaño. Necesitás entender la forma antes
del orchestration step, no antes de la task.
- Orquestá solo por una razón real. Después del scout, armá un workflow solo si vale una de estas razones:
Exhaustiveness (muchos ítems independientes para cubrir en paralelo), Confidence (alto riesgo; perspectivas
independientes + verificación adversarial antes de commitear) o Scale (más de una ventana de contexto:
auditorías repo-wide, migraciones grandes, sweeps amplios con artifacts). Si ninguna aplica, quedate con un solo
agente.
Escalá el esfuerzo al pedido
| Pedido | Forma |
|---|
| "find some bugs", "quick read" | scout → fan-out chico (~3-5 finders) → síntesis liviana |
| "review this plan", "is this safe" | pocos reviewers con perspectivas diversas → synthesis-as-judge |
| "audit thoroughly", "be exhaustive" | pool más grande → chequeo adversarial por finding → judge → repetir mientras aparezcan findings nuevos |
Dimensionar el fan-out (concurrency y budget de agentes)
No tomes los defaults bajos como techo. Subí el fan-out para ramas read-only e independientes; mantenelo bajo con side
effects, modelos caros o dependencias secuenciales. Logueá con log() todo cap, sample o clamp. Presupuestá el peor
caso cuando el fan-out dependa de resultados (jurados por finding). Para scopes grandes, evitá schema estricto y
timeouts default (~10 min) sin ajustar — ver
notas operativas.
Lectura de archivos grandes
Seguí como default la guía repo-wide de AGENTS.md / CLAUDE.md. En prompts de workflows, no les pidas a los workers
que "read every file fully" sobre scopes grandes; deciles que primero hagan scout, que paginen archivos grandes con
Read offset/limit cuando haga falta, que superpongan ventanas de código, achiquen ventanas densas y reporten la
cobertura parcial de forma explícita. Para inputs enormes, partí chunks semánticos en agents()/pipeline() o elegí
map-reduce en vez de incrustar un archivo gigante en un prompt.
Elegir una primitiva
Elegí por dependencia de datos, no por estética. Resumen:
| Necesidad | Primitiva |
|---|
| Un paso independiente por ítem | agents(items, { concurrency }) |
| Stages dependientes por ítem, sin merge global | pipeline(items, ...stages) — default |
| Un paso necesita TODOS los resultados a la vez | parallel([...]) — solo para barreras reales |
| Sub-workflow reutilizable | workflow(name, args) |
| Primera respuesta buena; cancelar el resto | race(thunks, { accept? }) — solo pi |
| Decisión humana a mitad de corrida | ask(question, opts?) — solo pi |
Runtime note: race/ask viven en el runtime pi de dynamic_workflow; no asumas que existen en Workflow de
Claude Code.
Settle semantics: ramas fallidas → null; filtrá nulls y log() cuántas fallaron.
Referencia completa de globals y gotchas: reference/primitives/README.md y
globals en notas operativas.
Model y effort por llamada
model (capacidad por token) y effort (budget de razonamiento) son dos diales independientes. Seteá ambos
explícitamente en cada nodo con fan-out; no acoples "modelo barato" con "pensamiento barato". Pisos orientativos:
| Tipo de trabajo | Piso model | Piso effort |
|---|
| Extracción mecánica, verificada downstream | haiku | low |
| Scout que rankea work-list | haiku | low–medium |
| Review read-only por ítem | sonnet | medium |
| Worker que muta el árbol | sonnet | medium–high |
| Judge / synthesis FINAL | opus | high |
Tablas de tiers, providers pi (Anthropic/Codex), post-mortem #47 y reglas de cache key:
notas operativas · model/effort.
Seguridad y prompting (resumen)
Fenceá datos no confiables (pedido, archivos, salida de otros agentes) con delimitadores infalsificables; combiná con
tools read-only y judges conservadores. Usá evidence contracts (NO_FINDINGS, INSUFFICIENT_EVIDENCE),
synthesis-as-judge y prefijos estables para prompt-cache. Detalle: notas operativas.
Catálogo de patrones
25 scaffolds en extensions/pandi-dynamic-workflows/scaffolds/; en pi:
dynamic_workflow action=scaffold name=<pattern>. Tabla por familia y mapeo research→scaffold:
notas operativas · catálogo. Vista rápida:
reference/scaffold-catalog.md y
docs/handbooks/workflow-catalog.md.
PHASE 0 — contract-gate (siempre, para corridas sustantivas)
-
En Pi, corré el scaffold canónico contract-gate sobre el pedido bruto; la extensión lo usa como workflow read-only.
Cierre: el scaffold devolvió un contrato con tarea, success criteria, supuestos, non-goals, verificación y
blockers explícitos.
-
Si necesita aclaración → devolvé las preguntas bloqueantes a la persona usuaria y STOP.
Cierre: la corrida quedó detenida con sólo las preguntas que impiden routing o implementación.
-
Si se puede avanzar → usá el prompt reescrito como handoff durable hacia router / workflow-factory / el workflow
elegido.
Cierre: el handoff conserva el contrato reescrito y nombra el destino seleccionado.
-
Propagá el resource plan del gate ({ tier, models, efforts }) al budget de la corrida aguas abajo.
Cierre: el workflow downstream recibe y refleja tier, models y efforts del gate.
Referencia de plataforma
Claude Code: tool Workflow; globals agent, parallel, pipeline, workflow, phase, log, args; budget en
args vía helper local node(role) o inline; catálogo ~/.claude/workflows/; depth 1. Invoke mínimo:
Workflow({ name: "router", args: { request: "the task", model: "sonnet", effort: "medium" } });
Obligatorio en Claude: render HTML pre-launch + open, lanzar sin aprobación, re-render con --run al terminar.
Detalle: notas operativas · plataforma.
pi: tool dynamic_workflow; mismos globals de composición más race, ask, bash, filesystem y artifacts; budget
por llamada + personas agentType; depth 2 (→3); resume journaled. Invoke mínimo:
dynamic_workflow({ action: 'start', name: 'task-slug', input: {…}, concurrency: 8, maxAgents: 40 })
Monitor sin polling (completion notice del harness); reporte final con /workflow report o
dynamic_workflow action="report". Comandos: /dynamic-workflow, /ultracode, /deep-research,
/workflow view|runs|resume, /workflows, /workflow patterns|graph.
Chuleta
| Aspecto | Claude Code (Anthropic) | pi (Anthropic o Codex) |
|---|
| Tool | Workflow | dynamic_workflow |
| Script API | helper globals (agent, parallel, …) | los mismos helper globals (agent, parallel, …) |
| Budget knobs | model · effort (low…max) | model/provider · effort (off|minimal|low|medium|high|xhigh; max→xhigh) |
| Models | haiku/sonnet/opus/fable | ids de Anthropic O openai-codex/gpt-5.x |
| Per-role | helper node(role) / inline / models+efforts | por llamada + personas agentType |
| Catalog | ~/.claude/workflows/ + README (desde catalog-prose.es.md) | dynamic_workflow action=scaffold |
| Depth | 1 | 2 (→3) |
| Preview / results | HTML pre-launch + open, luego re-render con --run al terminar (ambos obligatorios) | /workflow graph, dashboard /workflows, HTML final --run latest |
Crear un workflow nuevo
Basá todo workflow nuevo en el scaffold existente más cercano; nunca reinventes. Preferí workflow-factory
antes que hand-roll. Convenciones: meta.basedOn con procedencia de scaffolds; parseá args defensivamente;
model/effort explícitos por nodo; loops acotados + log(); settle semantics, evidence contracts y fences. En
Claude: renderizá + abrí HTML y lanzá directo. Detalle en
notas operativas · plataforma.
