scasella/claude-dynamic-workflows-codex

Workflows de Codex

Ejecuta un script de workflow dinámico de Claude Code contra un Servidor de App Codex local. La superficie de autoría es idéntica a los workflows dinámicos nativos — export const meta más un cuerpo que usa agent(), parallel(), pipeline(), phase(), log(), args, budget, workflow() — pero cada llamada a agent() se ejecuta como un hilo+turno de Codex (GPT) en lugar de un subagente de Claude.

Solo invocación manual. Claude no activa automáticamente esta habilidad (disable-model-invocation: true); solo se ejecuta cuando el usuario escribe /codex-workflows o pide explícitamente un workflow de Codex. Una vez invocada, sigue el bucle a continuación — el trabajo se ejecuta en agentes Codex/GPT. Si el usuario realmente quería subagentes de Claude, díselo y dirígelo a la herramienta nativa Workflow.

RUNNER a continuación significa el directorio del runner empaquetado: runner/ relativo al directorio base de esta habilidad (se muestra cuando la habilidad se carga). Para una instalación clásica de directorio de habilidades, eso es ~/.claude/skills/codex-workflows/runner — las rutas literales en los ejemplos a continuación lo asumen; sustituye tu directorio base si esta habilidad está instalada como plugin. No tiene dependencias, Node ≥ 18.

Modo de intención aproximada por defecto

Una o dos frases aproximadas son suficientes. No necesitas proporcionar a esta habilidad una especificación completamente elaborada — describe lo que quieres (ej. /codex-workflows Refuerza este objetivo antes de ejecutarlo) y la habilidad lo compila en un arnés operativo por sí misma: clasifica el trabajo, elige la escala viable más pequeña, un arquetipo y un patrón de arnés, construye un contrato de tarea, compone fases, asigna personas, aplica los estándares de calidad/epistémicos, escribe el script, elige configuraciones de ejecución seguras y lo ejecuta — indicando sus suposiciones a medida que avanza.

Reglas de operación en este modo:

• La intención aproximada es el contrato. Haz suposiciones razonables para cualquier cosa que no esté especificada y decláralas; no interrogues al usuario con preguntas de seguimiento.
• Elige el arnés útil más pequeño, no el más grande posible (ver la Regla anti-sobreconstrucción).
• No emitas un prompt gigante para que el usuario lo pegue de vuelta. Compila y procede a escribir/ejecutar. (La única excepción es el modo prompt-only — ver Detección de modo).
• Esto reemplaza cualquier "metaprompt" externo: la expansión ahora ocurre dentro de la habilidad. Toda la sección Compilando intención aproximada en un workflow a continuación es ese compilador.

Lista de verificación de ejecución por defecto

Cada ejecución, en orden (las secciones a continuación expanden cada paso):

1. Pre-vuelo Codex una vez (handshake.js); anota el modelo frontier más reciente.
2. Compila la intención aproximada: clasifica el trabajo → escala → arquetipo → patrón (nombra el modo de fallo que previene) → contrato de tarea. Indica tus suposiciones.
3. Escribe el script en el repositorio (./<nombre>.workflow.js).
4. Configuraciones: --frontier · esfuerzo por escala (--effort medium para un quick_harness, --auto-effort para standard/deep) · --sandbox read-only a menos que deba escribir · un --budget acotado · esquemas estrictos (additionalProperties:false).
5. Midelo — ejecuta --plan primero para cualquier workflow costoso o complejo.
6. Ejecuta en el runner de Codex (nunca la herramienta nativa Workflow).
7. Presenta — mapa ASCII en línea + destacados de summarize-run; cita las rutas del script, diario, visor, informe y resumen de ejecución (ver Comportamiento de salida).

Detección de modo

Lee el modo de la redacción del usuario, luego compórtate en consecuencia:

Modo	Disparador	Comportamiento
por defecto (intención aproximada)	1–2 frases aproximadas	Compila internamente → escribe → ejecuta. Indica suposiciones.
--multi (flota)	el flag --multi, o "flota" / "varios workflows a la vez"	Compila un plan de flota (2–4 workflows variantes concurrentes, similares y/o diversas), lánzalos en segundo plano y supervisa: consulta fleet status, responde puertas, dirije, mata, bifurca, luego sintetiza. Ver Modo flota.
prompt-only	"solo prompt", "solo la invocación", "no lo ejecutes"	Emite una invocación/especificación /codex-workflows completa (la estructura A–L a continuación) y DETENTE — no escribas ni ejecutes.
write-only	"escríbelo pero no lo ejecutes", "solo autoría"	Escribe el script del workflow, imprime su ruta, detente antes de ejecutar.
run-existing	una ruta de script o nombre de workflow guardado	Omite la compilación; ejecuta ese script/nombre a través del runner.
quick	"rápido", "pequeño", "barato"	Sesga hacia un quick_harness (2–5 agentes).
deep	"profundo", "exhaustivo", "minucioso"	Permite un deep_harness más grande; justifica el tamaño.
no-write	"no escribas archivos", "solo dímelo"	Devuelve solo JSON/Markdown final; sin archivos de informe/fuente; --sandbox read-only.

Dos reglas de precedencia: si el usuario da una ruta de script o nombre guardado, ejecútalo (no recompiles). Si el usuario da una especificación detallada, respétala tal como está escrita pero aplica los valores predeterminados de seguridad y ejecución a continuación. De lo contrario, es intención aproximada → compila.

En el modo prompt-only, la invocación que emites sigue la misma estructura A–L que la habilidad construye internamente: A nombre · B propósito · C contrato de tarea · D entradas / reconstrucción de contexto · E fases · F personas · G estándares anti-wrapper · H salidas · I configuraciones de ejecución · J seguridad / epistémica · K formato de respuesta final · L productización. Luego detente — no ejecutes.

El bucle

En el modo de intención aproximada por defecto, haz los pasos 1–2 en silencio e indica tus suposiciones antes de escribir. La mecánica a continuación — apretón de manos, el comando de ejecución, el mapa en línea — no cambian; los pasos 2 y 4 son donde la intención aproximada se compila.

1. Pre-vuelo — una vez por sesión, o cada vez que una ejecución falla al conectar, confirma que Codex es accesible y está autenticado:

   node ~/.claude/skills/codex-workflows/runner/test/handshake.js
   

   Imprime state: ready y los modelos disponibles. Si falla, dile al usuario que ejecute codex login (el runner necesita un codex CLI autenticado en PATH). De esa lista, anota el modelo frontier más reciente — el modelo general insignia más nuevo (no una variante -mini/-spark; model/list lo marca isDefault y su descripción lo llama el más potente). La serie GPT-5.6 Codex es Sol (insignia), Terra (equilibrado) y Luna (eficiente); hoy el frontier es gpt-5.6-sol. Cada agente en la ejecución lo usa (ver Modelo).

2. Compila la intención aproximada en un workflow (ver Compilando intención aproximada en un workflow): clasifica el trabajo → elige la escala → elige el arquetipo → elige el patrón y nombra el modo de fallo que previene → construye el contrato de tarea → compone las fases → asigna las personas → aplica los estándares. Indica las suposiciones resultantes al usuario antes de escribir.

3. Escribe un script de workflow a partir de esa compilación (ver Autoría). Escríbelo en el proyecto del usuario para que pueda leerlo y volver a ejecutarlo — ./<nombre>.workflow.js, o workflows/<nombre>.workflow.js / examples/harness-zoo/<nombre>/ para un arnés reutilizable. Los scripts son JavaScript plano que usa solo los globales inyectados (sin imports).

4. Elige configuraciones de ejecución (ver Valores predeterminados de ejecución): --frontier, el flag de esfuerzo para la escala elegida (--auto-effort para un arnés estándar/profundo, --effort medium para uno rápido), un sandbox de solo lectura a menos que la ejecución deba escribir, y un --budget acotado. Para un workflow costoso o complejo, --plan primero — una ejecución en seco sin tokens que cuenta agentes por fase/esfuerzo y estima un --budget.

5. Ejecútalo — siempre pasa --frontier, más el flag de esfuerzo para la escala elegida: --auto-effort para un arnés estándar/profundo (escala el esfuerzo de cada agente al ancho paralelo de su capa, por lo que las puertas de síntesis/juez solitarias piensan más), o --effort medium para un arnés rápido (ver Esfuerzo). --frontier fija cada agente al modelo frontier más reciente (ver Modelo):

   node ~/.claude/skills/codex-workflows/runner/bin/run-workflow.js <script.js> --frontier --auto-effort [otros flags]
   #   quick_harness:  … <script.js> --frontier --effort medium [otros flags]
   

   El progreso se transmite por stderr; el valor de retorno del workflow se imprime como JSON en stdout. Captura stdout para el resultado (… 1>/tmp/result.json) cuando es grande. Para ver la ejecución en vivo, añade --tui (mapa ASCII en vivo en una nueva ventana de terminal) y/o --gui (visor HTML en vivo en el navegador) — ver Ejecución → Monitoreo en vivo.

6. Presenta el resultado al usuario (ver Comportamiento de salida) — resúmelo, menciona la ruta del script y renderiza el mapa ASCII de la ejecución en línea en esta conversación para que vean el grafo de ejecución de forma nativa (sin ventana que abrir):

   node ~/.claude/skills/codex-workflows/runner/bin/map-run.js --journal <journal> --no-color
   

   (<journal> es la ruta que la ejecución registró como ✎ journal: …, por defecto .workflow-journal/<nombre>.jsonl.) Pega esa salida en tu respuesta dentro de un bloque ```text — es el orquestador → capas de fase → cuadrícula de agentes → DAG de resultados con modelo/esfuerzo/tokens/tiempo por agente y un fragmento de resultado de una línea por agente. Siempre usa --no-color en línea (el ANSI sin procesar se renderizaría como basura en el chat). Para monitoreo en vivo, dentro de la sesión, ejecuta el workflow con run_in_background y vuelve a renderizar esta instantánea varias veces mientras está en vuelo (los agentes en ejecución se muestran como ⠋ … ejecutando…); para una ventana en vivo suave en su lugar, añade --tui/--gui (ver Ejecución → Monitoreo en vivo).

   La ejecución también imprime un resumen de costo/fiabilidad de una línea cuando termina. Para un desglose más completo — tokens por fase, los agentes más costosos/lentos y cualquier bandera roja (muchos nulos, un abanico enorme no escalonado, costo de esfuerzo predeterminado) — ejecuta summarize-run en el diario y pliega los aspectos destacados en tu respuesta (ver Resumir una ejecución).

NO llames a la herramienta nativa Workflow mientras usas esta habilidad. Escribir el script y ejecutarlo a través de la CLI anterior es exactamente lo que enruta el trabajo a Codex; invocar la herramienta nativa generaría subagentes de Claude en su lugar.

Modo flota (--multi): lanzar, supervisar, dirigir

Cuando el usuario pasa --multi (o pide una flota / varios workflows a la vez), eres el operador de N ejecuciones concurrentes — no un lanzador de "disparar y olvidar". Compilas un plan de flota, lanzas cada variante en segundo plano, luego ejecutas un bucle de supervisión: consulta estado, responde puertas, dirige trabajadores a la deriva, mata callejones sin salida, bifurca leads prometedores y sintetiza al final. El humano establece la política una vez (objetivo, presupuesto total, tolerancia al riesgo); tú tomas las decisiones de juicio a medio camino que las variantes no pueden tomar por sí mismas.

1 · Compila el plan de flota

Descompón la intención en 2–4 variantes e indica el plan (variantes, qué apuesta cada una, presupuestos por ejecución) antes de lanzar. Dos ejes, libremente mezclados:

• Similares — el mismo arnés, diferentes porciones: divide una entrada grande entre ejecuciones mediante --args, o ataca la misma pregunta desde diferentes hipótesis iniciales/semillas. Un script + --args por ejecución + --run-id (para que los diarios no colisionen), o N copias del script.
• Diversas — formas de arnés diferentes que apuestan por diferentes teorías de la tarea: ej. una caza de errores loop_until_dry vs un barrido adversarial_verification vs una investigación sessionful_controller_loop, todas apuntando al mismo objetivo. Un script por variante.

Divide el presupuesto general del usuario entre las variantes (el estado muestra el gasto de cada ejecución contra su techo). Dimensiona los abanicos de lectura de forma realista usando las mediciones existentes de GPT-5.5: un agente cuyo trabajo es leer un repositorio/corpus cuesta ~400–600k tokens independientemente de su nivel de esfuerzo — la entrada domina, por lo que --effort low no hace que un barrido sea barato, y la estimación por esfuerzo de --plan lo subestima (medido: cuatro barridos "low" = 2.1M, 525k cada uno, vs una estimación de plan de 150k/agente). En xhigh — que --auto-effort da a cada turno de trabajador con sesión (ancho 1) — un turno de lectura se ejecuta en ~1–1.5M (medido: el primer turno de un trabajador de recorrido + una dirección activó un techo de 2.5M). Presupuesto ≈ lectores × 500k + turnos de lectura xhigh × 1.2M + no lectores × la estimación del plan, con margen. Un techo activado es recuperable (--resume reproduce el prefijo gratis) pero cuesta un viaje de ida y vuelta de supervisión. Aplica la Regla anti-sobreconstrucción también a la flota: 2 variantes bien diferenciadas son mejores que 4 redundantes — cada variante debe apostar por algo que las otras no.

2 · Escribe para supervisión

Cada variante obtiene puntos de control de supervisor — puertas human() en las coyunturas donde un juicio externo puede redirigir la ejecución:

const directive = await human(
  `Hallazgos de la Ronda ${round}: ${summary}. ¿Directiva para la siguiente ronda?`,
  { id: `round${round}`, choices: ["continue", "stop"], default: "continue", timeoutMs: 240_000 })
if (directive === "stop") break
if (directive !== "continue") await worker.steer(directive)   // texto libre = una dirección

Este es el canal de dirección: una respuesta de texto libre es la directiva, y el script la aplica (session.steer(...), reorientando la siguiente ronda, estrechando el alcance). Coloca puertas entre rondas, antes de fases costosas y en caso de incertidumbre. Los valores predeterminados deben ser seguros: una puerta no respondida agota su tiempo de espera y la ejecución se degrada sin intervención, nunca se cuelga. (Esto usa el canal human() registrado en el diario, por lo que un --resume reproduce las respuestas en lugar de volver a preguntar.)

3 · Lanza — un directorio por flota, cada ejecución en segundo plano

Las variantes comparten un directorio (eso es lo que supervisa fleet status <dir>). Lanza cada una con run_in_background, siempre con --interactive (que habilita el canal de respuestas sin interfaz gráfica):

node ~/.claude/skills/codex-workflows/runner/bin/run-workflow.js hunt-orm.workflow.js \
  --frontier --auto-effort --interactive --budget 1500000 1>hunt-orm.result.json
# mismo script, porción diferente → aísla con --run-id:
node …/run-workflow.js hunt.workflow.js --args '{"slice":"auth"}' --run-id auth --interactive …

4 · Supervisa — el bucle

Consulta el resumen de la flota entre otras tareas (y rápidamente mientras las puertas pueden estar pendientes):

— [truncado por brevedad para la traducción]