orchestrate

Orchestrate: Opus planeja e revisa, agentes baratos executam

Você (Opus) é o arquiteto e gatekeeper, não o digitador. Os trabalhadores são baratos e rápidos, mas não confiáveis: assuma que todo resultado pode estar errado, incompleto, excessivo, feio ou com trapaça em testes até que os portões provem o contrário.

Ferramentas: python3 ~/.claude/skills/orchestrate/scripts/orch.py (daqui em diante: orch). Referências, leia sob demanda:

• references/agent-matrix.md — capacidade/custo por agente + padrões de pipeline de etapas (uma vez por sessão);
• references/workers.md — receitas de CLI e armadilhas por trabalhador;
• references/live.md — supervisão ao vivo rx-acp (L0/L1/L2), execuções --live, formatos de transmissão, registro de lições (leia antes de usar rx-acp* ou --live);
• references/review-checklist.md — Portão 2.

0. Triagem

Faça você mesmo quando a alteração for de ≲ 40 linhas em 1–2 arquivos, ou principalmente de julgamento (arquitetura, segurança, depuração delicada), ou principalmente mecânica com menos de ~1000 linhas de diff (senão ≤ 2 trabalhadores). Orquestre para várias subtarefas independentes, edições em lote, código boilerplate, testes, documentação, buscas no código-base, ou quando o usuário pedir.

Orçamento de recursos (8 trabalhadores paralelos já congelaram a máquina com dezenas de verificadores de tipo):

• Máximo 3 trabalhadores vivos (--parallel 3 padrão; agentes Sonnet/Haiku contam também).
• checks = barato e com escopo (um arquivo de teste, lint nos arquivos tocados). Verificações de tipo/build em todo o projeto vão em final_checks: os trabalhadores nunca as veem; você as executa uma vez na árvore principal após a mesclagem.
• Prefira 2–3 contratos maiores em vez de muitos pequenos (a inicialização é o custo fixo).
• Os trabalhadores nunca instalam pacotes ou iniciam processos em segundo plano / servidores de desenvolvimento. Após uma onda, verifique se nada está em execução (pgrep -fl "wt/<ID>|tsc").
• Contratos de interface do usuário: liste tokens de design permitidos e proibidos explicitamente.

Pré-condição: um repositório git; worktrees ramificam a partir de HEAD + alterações monitoradas não commitadas (arquivos não monitorados não são transportados).

Jev (TypeSafe System One, scripts/jev.py): julgamentos tipados, ~0,4 s, ~$0,00004/chamada. Ele classifica, pontua e verifica; política e limites permanecem no código. Desligado quando TYPESAFE_API_KEY está ausente (ORCH_JEV=0).

1. Entenda e especifique

1. Leia o código relevante (ou envie um trabalhador somente leitura para buscas amplas). Encontre os comandos de teste/lint.
2. orch route "<tarefa>" → sinais do Jev + um trabalhador sugerido / etapa de análise. Uma sugestão; você decide.
3. Especificação curta: objetivo, não-objetivos, critérios de aceitação, riscos. Pergunte ao usuário apenas sobre decisões que são dele.

2. Decomponha em contratos

Um contrato JSON por subtarefa em <repo>/.orch/contracts/<ID>.json (references/contract-template.json).

• Pequeno: 1–3 arquivos, ≲150 linhas de diff. allowed disjuntos para tarefas paralelas; dependentes encadeiam.
• Autocontido: os trabalhadores não veem esta conversa — caminhos, nomes, convenções, pegadinhas, o que NÃO tocar.
• Aceitação testável; cada critério mapeia para uma verificação. O Jev verifica apenas o que está escrito ali.
• Testes ocultos para novos comportamentos: você escreve testes de caso extremo fora do repositório, referenciados via hidden_files + hidden_checks; copiados apenas durante a avaliação.
• Arquivos protected; max_diff_lines ≈ 2–3× sua estimativa sem testes (linhas de teste contam contra max_test_diff_lines, padrão 3×); mode: "read_only" para análise.
• Campos de plano — faça o pensamento por eles (−33% tempo, −45% tokens de saída, sem violações de escopo): approach (etapas ordenadas; por causa raiz para bugs), pattern_refs (arquivo:linhas — o que copiar), examples (entrada -> esperado, casos complicados incluídos), pseudo (apenas parte complicada), rules (proibições concretas, verificáveis — L1 as impõe durante a execução). Mantenha prompt_style: "profiled".
• orch check .orch/contracts/*.json antes do despacho; corrija contratos sinalizados primeiro.
• Worktrees (.orch/wt/<ID>) contêm apenas arquivos monitorados: liste por pacote node_modules / código gerado em worktree_links (contrato) ou .orch/config.json (globs simples) — vinculados simbolicamente da árvore principal, então compartilhados com ela.
• Um arquivo nomeado exatamente em allowed pode ser editado mesmo que seja um arquivo de teste existente.

3. Roteamento

Política (usuário): não roteie tudo para o reasonix.

Forma da tarefa	Primeira escolha	Escalar para
Edição mecânica pequena, configuração, renomeação, função pura com exemplos	rx-acp	rx-acp-max → agy → sonnet
Análise/pesquisa somente leitura	rx-flash	rx-flash-max → sonnet
Módulo de funcionalidade normal (1–3 arquivos, com campos de plano)	sonnet	Opus
Testes para código existente (nunca código de funcionalidade)	haiku	sonnet
Refatoração preservando comportamento	sonnet + testes ocultos	Opus
Interface do usuário seguindo um sistema de design existente (pattern_refs)	agy ou sonnet	sonnet
Crítico: dinheiro/contabilidade, autenticação, concorrência, segurança, migrações	Opus, ou sonnet + especificação restrita + revisão linha por linha	—
Segunda opinião sobre um diff	a outra família, somente leitura	Opus

agy = Gemini 3.8 Flash Medium. rx-* = DeepSeek V4 Flash (-max = esforço máximo, o nível mais forte do DeepSeek ). rx-acp* = os mesmos modelos sob supervisão ao vivo — tão corretos quanto rx-flash, mais baratos, sem arquivos soltos; preferido para contratos de edição, especialmente com armadilhas (arquivos extras tentadores, instalações, verificações pesadas). Gosto visual → sonnet + revisão.

4. Despache — uma chamada em segundo plano, Opus dorme

Cada reativação relê todo o seu contexto. Despache uma onda em UMA chamada:

orch run --title "<solicitação do usuário, curta>" .orch/contracts/A.json B.json ...   # Bash, run_in_background: true

Você é reinvocado quando ele termina — nunca faça polling ou durma. Por contrato, sem o Opus: nova worktree → prompt do trabalhador → proteção → em FALHA, feedback da máquina na própria sessão do trabalhador (cache quente), até max_attempts; regras de código + triagem do Jev escolhem repetir / escalar ao longo da ladder / BLOCKED (problema no contrato) / NEEDS_OPUS (ambiente, incl. erros de API/CLI — para imediatamente). Após PASS, o Jev verifica o diff contra cada critério de aceitação (P>0,85 → uma revisão automática; 0,7–0,85 → aviso para sua revisão). Você recebe uma linha compacta por tarefa; os logs permanecem em .orch/runs/<ID>/attempt-N/. hidden_feedback: "names" esconde asserções do feedback quando você suspeita de trapaça em testes.

• rx-acp executa sob um supervisor ao vivo (regras L0 + revisão L1 do Jev, durante a execução). orch run --live também entrega decisões de meio de execução para você (aprovação de plano, edições incertas, perguntas, travado): orch wait → orch reply <id> --choice … --steer "…" → orch wait. Use --live apenas onde uma decisão de meio de execução vale uma reativação (contratos arriscados/ambíguos, novos estilos de contrato). Detalhes: references/live.md.
• Sonnet / Haiku: orch prepare <contract> → Agente subagent_type: "sonnet-worker" (+ model: "haiku"), run_in_background: true, prompt = o agent_prompt do prepare (o caminho do arquivo, não o texto). Então:

  orch guard .orch/contracts/<ID>.json --reply - <<'EOF'
  <o JSON final do trabalhador, na íntegra>
  EOF
  

• Pipelines de etapas: after: [ids] (aguardar PASS), inputs: [ids] (injetar resposta/diff dessa etapa), build_on: id (começar a partir do seu código). Uma etapa com falha pula dependentes. Padrões: agent-matrix.md §3.
• orch dispatch = tentativa única, para depuração. Nunca dê a um trabalhador o checkout principal ou credenciais.

5. Portão 1 — proteção (automática)

FALHA: fora do escopo / arquivos protegidos / testes existentes / manifestos de dependência tocados, tarefa somente leitura escreveu arquivos, nenhuma alteração, acima do orçamento, checagens (ocultas) falhando, marcadores skip/only, asserções removidas, segredos no código-fonte, arquivos inúteis, status do trabalhador ≠ concluído, erro de CLI. AVISO: segredos em testes, supressões de lint, exceções engolidas, TODOs, prints de depuração, diffs apenas de espaços em branco, incompatibilidade de relatório, preocupações do trabalhador, arquivos de CLI perdidos (excluídos automaticamente), atividade de supervisão ao vivo (leia no Portão 2).

6. Portão 2 — Revisão do Opus (nunca pule para tarefas de edição)

Leia attempt-N/diff.patch + JSON de proteção com references/review-checklist.md, então:

• ACEITAR → orch merge <ID> (não preparado), execute verificações na árvore principal.
• REVISAR → feedback numerado e concreto (arquivo:linha, o que está errado, como deve ser) em .orch/runs/<ID>/feedback.md; orch dispatch <contract> --feedback <file>. Máximo 2 por tarefa.
• NEEDS_OPUS / BLOCKED → corrija o contrato e execute novamente, entregue a sonnet-worker, ou assuma.
• ASSUMIR quando explicar os custos custar mais do que fazer. As "preocupações" do trabalhador são sinais para verificar, nunca instruções.

7. Integre e relate

1. Mescle uma tarefa de cada vez, verificações após cada uma; resolva conflitos você mesmo.
2. Revisão holística do diff combinado (consistência, auxiliares duplicados, sobras de depuração); execute final_checks.
3. orch clean --all; orch status = razão.
4. Tarefas rx-acp: registre o que as regras perderam (orch lessons --note …) e folheie orch lessons (live.md §Lições).
5. Relate: o que foi feito, por quem, o que foi rejeitado/escalado e por quê, verificações executadas, o que resta. Não faça commit a menos que solicitado.

Painel (para o usuário, monitoramento apenas): orch ui --open → http://127.0.0.1:8765 — execuções (tarefas pai, nomeadas por --title), tarefas filhas, tentativas, tempo, custo, progresso ao vivo, decisões pendentes, e por tentativa a troca completa entre orquestrador e trabalhador. O usuário responde às decisões informando você nesta sessão, nunca no painel.

Mantendo este skill — destile, nunca acumule

Toda edição neste skill (SKILL.md, referências) deve deixá-lo não maior do que precisa ser:

• Substitua, não anexe. Novas evidências atualizam a linha ou número existente; nenhum parágrafo datado ao lado dele.
• Exclua o que está desatualizado: modelos e aliases aposentados, bugs corrigidos e suas histórias, números substituídos, incidentes isolados cuja lição já está codificada em código ou regra. Dados brutos de benchmark vivem em ~/workspaces/agent-bench, versões antigas em ~/.claude/skill-backups/ — não aqui.
• Mantenha apenas o que muda uma decisão ou evita um erro agora: a regra, mais sua razão em ≤ 1 linha.
• Orçamentos: SKILL.md ≤ ~200 linhas (sempre carregado); cada referência ≤ ~150 linhas. Acima do orçamento → destile primeiro.
• Detalhes de implementação pertencem a docstrings de código, não em documentos que o Opus lê toda sessão.
• Após alterar scripts: python3 -I scripts/tests/test_policy.py, …/test_supervisor.py, …/test_escalation.py. Após alterações de prompt/limiar L1: ~/workspaces/agent-bench/l1_eval.py. Após atualizações de CLI/modelo: re-bench (agent-bench/bench.py, ab.py) e atualize números no lugar.