scasella/claude-dynamic-workflows-codex

Workflows Codex

Executa um script de workflow dinâmico do Claude Code em um Servidor de Aplicação Codex local. A superfície de autoria é idêntica aos workflows dinâmicos nativos — export const meta mais um corpo usando agent(), parallel(), pipeline(), phase(), log(), args, budget, workflow() — mas cada chamada agent() executa como uma thread+turno Codex (GPT) em vez de um subagente Claude.

Invocação manual apenas. Claude não aciona esta skill automaticamente (disable-model-invocation: true); ela executa somente quando o usuário digita /codex-workflows ou pede explicitamente um workflow Codex. Uma vez invocada, siga o loop abaixo — o trabalho é executado em agentes Codex/GPT. Se o usuário queria subagentes Claude, informe e aponte para a ferramenta Workflow nativa.

RUNNER abaixo significa o diretório runner incluído: **runner/ relativo ao diretório base desta skill (mostrado quando a skill carrega). Para uma instalação skills-dir clássica, isso é ~/.claude/skills/codex-workflows/runner — os caminhos literais nos exemplos abaixo assumem isso; substitua pelo seu diretório base se a skill estiver instalada como plugin. É Node ≥ 18 livre de dependências.

Modo de intenção aproximada padrão

Uma ou duas frases aproximadas é suficiente. Você não precisa fornecer a esta skill uma especificação totalmente elaborada — descreva o que você quer (ex.: /codex-workflows Reforce esta meta antes de eu executá-la) e a skill compila isso em um harness operacional: classifica o trabalho, escolhe a menor escala viável, um arquétipo e um padrão de harness, constrói um contrato de tarefa, compõe fases, atribui personas, aplica os padrões de qualidade/epistemologia, cria o script, escolhe configurações seguras de execução e o executa — declarando suas premissas à medida que avança.

Regras operacionais neste modo:

• A intenção aproximada é o contrato. Faça premissas razoáveis para qualquer coisa não especificada e declare-as; não interrogue o usuário com perguntas de acompanhamento.
• Escolha o menor harness útil, não o maior possível (veja a Regra anti-superdimensionamento).
• Não emita um prompt gigante para o usuário colar de volta. Compile e prossiga para autoria/execução. (A única exceção é o modo prompt-only — veja Detecção de modo.)
• Isso substitui qualquer "metaprompt" externo: a expansão agora acontece dentro da skill. Toda a seção Compilando intenção aproximada em um workflow abaixo é esse compilador.

Lista de verificação de execução padrão

Cada execução, em ordem (as seções abaixo expandem cada passo):

1. Pré-voo Codex uma vez (handshake.js); anote o modelo frontier mais recente.
2. Compile a intenção aproximada: classifique o trabalho → escala → arquétipo → padrão (nomeie o modo de falha que ele previne) → contrato de tarefa. Declare suas premissas.
3. Crie o script no repositório (./<nome>.workflow.js).
4. Configurações: --frontier · esforço por escala (--effort medium para um quick_harness, --auto-effort para standard/deep) · --sandbox read-only a menos que precise escrever · um --budget limitado · esquemas estritos (additionalProperties:false).
5. Dimensione — execute --plan primeiro para qualquer workflow caro ou complexo.
6. Execute no runner Codex (nunca na ferramenta Workflow nativa).
7. Apresente — mapa ASCII inline + destaques de summarize-run; cite o script, diário, visualizador, relatório e caminhos do resumo da execução (veja Comportamento de saída).

Detecção de modo

Leia o modo a partir da frase do usuário, então comporte-se de acordo:

Modo	Gatilho	Comportamento
padrão (intenção aproximada)	1–2 frases aproximadas	Compilar internamente → criar → executar. Declarar premissas.
--multi (frota)	a flag --multi, ou "frota" / "vários workflows de uma vez"	Compilar um plano de frota (2–4 workflows variantes concorrentes, similares e/ou diversos), lançá-los em segundo plano e supervisionar: consultar fleet status, responder a gates, direcionar, encerrar, bifurcar, então sintetizar. Veja Modo frota.
prompt-only	"prompt-only", "apenas a invocação", "não execute"	Emitir uma invocação/especificação /codex-workflows completa (a estrutura A–L abaixo) e PARAR — não criar ou executar.
write-only	"escreva mas não execute", "apenas crie"	Criar o script do workflow, imprimir seu caminho, parar antes de executar.
run-existing	um caminho de script ou nome de workflow salvo é fornecido	Pular compilação; executar aquele script/nome através do runner.
quick	"rápido", "pequeno", "barato"	Enviesar para um quick_harness (2–5 agentes).
deep	"profundo", "minucioso", "exaustivo"	Permitir um deep_harness maior; justificar o tamanho.
no-write	"não escreva arquivos", "apenas me diga"	Retornar apenas JSON/Markdown final; nenhum arquivo de relatório/fonte; --sandbox read-only.

Duas regras de precedência: se o usuário fornecer um caminho de script ou nome salvo, execute-o (não recompile). Se o usuário fornecer uma especificação detalhada, honre-a como escrita mas aplique ainda os padrões de segurança e execução abaixo. Caso contrário, é intenção aproximada → compile.

No modo prompt-only, a invocação que você emite segue a mesma estrutura A–L que a skill constrói internamente: A nome · B propósito · C contrato de tarefa · D entradas / reconstrução de contexto · E fases · F personas · G padrões anti-wrapper · H saídas · I configurações de execução · J segurança / epistemologia · K formato da resposta final · L produtização. Então pare — não execute.

O loop

No modo de intenção aproximada padrão, execute os passos 1–2 silenciosamente e declare suas premissas antes de criar. A mecânica abaixo — handshake, comando de execução, mapa inline — permanece inalterada; os passos 2 e 4 são onde a intenção aproximada é compilada.

1. Pré-voo — uma vez por sessão, ou sempre que uma execução falhar ao conectar, confirme que o Codex está acessível e autenticado:

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

   Ele imprime state: ready e os modelos disponíveis. Se falhar, diga ao usuário para executar codex login (o runner precisa de um CLI codex logado no PATH). Dessa lista, anote o modelo frontier mais recente — o mais novo modelo principal geral (não uma variante -mini/-spark; model/list o sinaliza isDefault e sua descrição o chama de mais forte). A série GPT-5.6 Codex é Sol (principal), Terra (equilibrada) e Luna (eficiente); hoje o frontier é gpt-5.6-sol. Cada agente na execução o usa (veja Modelo).

2. Compile a intenção aproximada em um workflow (veja Compilando intenção aproximada em um workflow): classifique o trabalho → escolha a escala → escolha o arquétipo → escolha o padrão e nomeie o modo de falha que ele previne → construa o contrato de tarefa → compor as fases → atribua as personas → aplique os padrões. Declare as premissas resultantes ao usuário antes de criar.

3. Crie um script de workflow a partir dessa compilação (veja Criação). Escreva-o no projeto do usuário para que ele possa ler e reexecutar — ./<nome>.workflow.js, ou workflows/<nome>.workflow.js / examples/harness-zoo/<nome>/ para um harness reutilizável. Scripts são JavaScript puro usando apenas os globais injetados (sem importações).

4. Escolha configurações de execução (veja Padrões de execução): --frontier, a flag de esforço para a escala escolhida (--auto-effort para um harness standard/deep, --effort medium para um quick), um sandbox somente leitura a menos que a execução precise escrever, e um --budget limitado. Para um workflow caro ou complexo, --plan primeiro — uma execução a seco sem tokens que conta agentes por fase/esforço e estima um --budget.

5. Execute — sempre passe --frontier, mais a flag de esforço para a escala escolhida: --auto-effort para um harness standard/deep (ele escala o esforço de cada agente para a largura paralela de sua camada, então gates de síntese/juiz solitários pensam mais), ou --effort medium para um harness quick (veja Esforço). --frontier fixa cada agente no modelo frontier mais recente (veja Modelo):

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

   O progresso flui em stderr; o valor de retorno do workflow é impresso como JSON em stdout. Capture stdout para o resultado (… 1>/tmp/result.json) quando for grande. Para assistir a execução ao vivo, adicione --tui (mapa ASCII ao vivo em uma nova janela de terminal) e/ou --gui (visualizador HTML ao vivo no navegador) — veja Execução → Monitoramento ao vivo.

6. Apresente o resultado ao usuário (veja Comportamento de saída) — resuma-o, mencione o caminho do script e renderize o mapa ASCII da execução inline nesta conversa para que ele veja o grafo de execução nativamente (sem janela para abrir):

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

   (<journal> é o caminho que a execução registrou como ✎ journal: …, padrão .workflow-journal/<nome>.jsonl.) Cole essa saída em sua resposta dentro de um bloco ```text — é o orquestrador → camadas de fase → grade de agentes → DAG de resultados com modelo/esforço/tokens/tempo por agente e um trecho de resultado de uma linha por agente. Sempre use --no-color inline (ANSI bruto renderizaria como lixo no chat). Para monitoramento ao vivo, na sessão, execute o workflow com run_in_background e re-renderize este snapshot algumas vezes enquanto estiver em andamento (agentes executando mostram ⠋ … executando…); para uma janela ao vivo suave em vez disso, adicione --tui/--gui (veja Execução → Monitoramento ao vivo).

   A execução também imprime um resumo de custo/confiabilidade de uma linha quando termina. Para um detalhamento mais completo — tokens por fase, os agentes mais caros/lentos e quaisquer bandeiras vermelhas (muitos nulos, um enorme fan-out não escalonado, custo de esforço padrão) — execute summarize-run no diário e incorpore os destaques em sua resposta (veja Resumir uma execução).

NÃO chame a ferramenta Workflow nativa enquanto usa esta skill. Criar o script e executá-lo através do CLI acima é exatamente o que roteia o trabalho para o Codex; invocar a ferramenta nativa geraria subagentes Claude.

Modo frota (--multi): lançar, supervisionar, direcionar

Quando o usuário passa --multi (ou pede uma frota / vários workflows de uma vez), você é o operador de N execuções concorrentes — não um lançador do tipo "disparar e esquecer". Você compila um plano de frota, lança cada variante em segundo plano, então executa um loop de supervisão: consultar status, responder a gates, direcionar workers desviantes, encerrar becos sem saída, bifurcar leads promissores e sintetizar no final. O humano define a política uma vez (objetivo, orçamento total, tolerância a risco); você faz os julgamentos de meio de execução que as variantes não podem fazer por si mesmas.

1 · Compile o plano de frota

Decomponha a intenção em 2–4 variantes e declare o plano (variantes, em que cada uma aposta, orçamentos por execução) antes de lançar. Dois eixos, livremente misturados:

• Similar — o mesmo harness, fatias diferentes: divida uma grande entrada entre execuções via --args, ou ataque a mesma pergunta a partir de diferentes hipóteses/sementes iniciais. Um script + --args por execução + --run-id (para que os diários não colidam), ou N cópias do script.
• Diversa — formas diferentes de harness apostando em teorias diferentes da tarefa: ex.: uma caça a bugs loop_until_dry vs uma varredura adversarial_verification vs uma investigação sessionful_controller_loop, todas visando o mesmo objetivo. Um script por variante.

Divida o orçamento geral do usuário entre as variantes (o status mostra o gasto de cada execução contra seu teto). Dimensione fan-outs pesados de leitura realisticamente usando as medições existentes do GPT-5.5: um agente cujo trabalho é ler um repositório/corpus custa ~400–600k tokens independentemente de seu nível de esforço — a entrada domina, então --effort low não torna uma varredura barata, e a estimativa do --plan por esforço a subestima (medido: quatro varreduras "low" = 2,1M, 525k cada, vs. uma estimativa de plano de 150k/agente). Em xhigh — que --auto-effort dá a cada turno de worker sessionful (largura 1) — um turno de leitura executa ~1–1,5M (medido: primeiro turno de um worker walkthrough + um direcionamento atingiu um teto de 2,5M). Orçamento ≈ leitores × 500k + turnos de leitura xhigh × 1,2M + não leitores × a estimativa do plano, com margem. Um teto atingido é recuperável (--resume reproduz o prefixo de graça) mas custa um round-trip de supervisão. Aplique a Regra anti-superdimensionamento à frota também: 2 variantes bem diferenciadas vencem 4 redundantes — cada variante deve apostar em algo que as outras não fazem.

2 · Crie para supervisão

Cada variante recebe checkpoints de supervisor — gates human() nas junções onde um julgamento externo pode redirecionar a execução:

const diretiva = await human(
  `Rodada ${round} descobertas: ${resumo}. Diretiva para a próxima rodada?`,
  { id: `rodada${round}`, escolhas: ["continuar", "parar"], padrao: "continuar", timeoutMs: 240000 })
if (diretiva === "parar") break
if (diretiva !== "continuar") await worker.direcionar(diretiva)   // texto livre = uma diretiva

Este é o canal de direcionamento: uma resposta em texto livre é a diretiva, e o script a aplica (session.direcionar(...), re-ajustando a próxima rodada, estreitando o escopo). Coloque gates entre rodadas, antes de fases caras e em incerteza. Os padrões devem ser seguros — uma gate não respondida atinge o tempo limite para seu padrão e a execução degrada sem intervenção, nunca trava. (Isso usa o canal human() registrado no diário, então um --resume reproduz respostas em vez de perguntar novamente.)

3 · Lance — um diretório por frota, cada execução em segundo plano

As variantes compartilham um diretório (é o que fleet status <dir> supervisiona). Lance cada uma com run_in_background, sempre com --interactive (ele habilita o canal de resposta sem cabeça):

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
# mesmo script, fatia diferente → isolar com --run-id:
node …/run-workflow.js hunt.workflow.js --args '{"slice":"auth"}' --run-id auth --interactive …

4 · Supervisione — o loop

Consulte o resumo da frota entre outros trabalhos (e prontamente enquanto gates podem estar pendentes —

…

[truncado para tradução]