Orchestrate

Orchestrate

Use esta skill quando o trabalho pedir coordenacao entre modelos, troca automatica de perfis Claude por cota, ou quando o usuario quiser explicitar o fluxo Claude planeja -> Codex executa -> Claude valida quando vale a pena.

Objetivo canonico

• Claude decide o plano, o risco e se vale chamar outro modelo.
• Codex executa implementacao, automacao e alteracoes de codigo.
• Claude valida apenas quando o risco justificar custo e latencia.

Nao trate esta skill como um "roteador multi-IA generico". O caminho padrao aqui e:

1. classificar a tarefa
2. planejar no Claude
3. executar no Codex quando houver trabalho de implementacao
4. devolver ao Claude um handoff curto
5. validar no Claude apenas se os gatilhos de risco forem atingidos

Como identificar qual IA voce e

Nao tente adivinhar seu nome. Observe as ferramentas que voce tem disponíveis:

| Voce tem esta ferramenta | Voce provavelmente e | Como chamar Claude | |--------------------------|---------------------|--------------------| | Agent tool | Claude Code | Agent tool nativo (nao use subprocess) | | exec/shell sem Agent tool | Codex, Gemini ou Qwen | echo "prompt" \| claude --print |

Chamando cada IA via stdin pipe ou wrapper (sem Agent tool)

# Claude
echo "prompt" | claude --print

# Codex (obrigatorio limpar variaveis OpenRouter)
echo "prompt" | unset OPENAI_BASE_URL && unset OPENAI_API_KEY && codex exec --skip-git-repo-check -

# Qwen
echo "prompt" | qwen

# agy / Antigravity CLI (substituto do Gemini — NAO usar -p direto, stdout vazio fora de TTY)
python scripts/call_agy.py "prompt"        # requer: pip install pywinpty

# Gemini (DEPRECADO — EOL 2026-06-18)
cat > /tmp/prompt.txt ` — se der match, acione validacao.

## Contrato de handoff

Quando o Codex devolver contexto para o Claude, responda **apenas este JSON**:

```json
{
  "status": "OK|ERRO|PARCIAL",
  "task_summary": "o que foi feito em 1-2 frases",
  "changed_files": ["lista/de/arquivos.py"],
  "tests_run": true,
  "risks": ["lista de riscos ou array vazio"],
  "analyst_summary": "observacoes tecnicas relevantes",
  "next_action": "DONE|NEEDS_VALIDATION|NEEDS_RETRY|ESCALATE"
}

NEVER envolva a resposta em blocos markdown (\\\json). Stdout deve comecar com { e terminar com } para permitir parse direto via jq` ou Python.

Wrapper Windows

Sempre que o usuario quiser o fluxo automatizado, prefira os scripts desta skill:

• scripts/claude_codex_orchestrator.py bootstrap-profiles
• scripts/claude_codex_orchestrator.py call-claude
• scripts/claude_codex_orchestrator.py call-codex
• scripts/claude_codex_orchestrator.py route
• scripts/claude_codex_orchestrator.ps1 ...

Esses comandos existem para:

• isolar CLAUDE_CONFIG_DIR por perfil
• preservar autenticacao de mais de uma conta Claude no mesmo usuario do Windows
• detectar erro explicito de cota
• alternar para o proximo perfil Claude
• chamar o Codex pelo .cmd correto no Windows
• devolver um handoff curto e previsivel

Perfis Claude

Perfis vivem fora do repositorio, por padrao em:

• %USERPROFILE%\.claude-profiles\claude-a
• %USERPROFILE%\.claude-profiles\claude-b

Credenciais e estado ficam fora do hub. So compartilhe no bootstrap os assets nao sensiveis, como:

• skills
• plugins
• commands
• settings.json
• trustedFolders.json

Nao copie credenciais entre perfis manualmente.

Sequencia recomendada

1. Se os perfis ainda nao existem, rode bootstrap-profiles.
2. Se a tarefa exigir execucao, use route.
3. Se a tarefa for simples e totalmente analitica, responda no proprio Claude.
4. Para escalar entre IAs, use scripts/run_ai_cli.py --provider X --prompt-file /tmp/prompt.txt.

Quando consultar arquivos auxiliares

• Falha silenciosa ou timeout inesperado: leia calling-conventions.md (kill de arvore de processo no Windows)
• agy sem saida em subprocesso: use python scripts/call_agy.py (ConPTY via pywinpty) — ver calling-conventions.md secao 5
• Rate limit, rc=130 ou resposta vazia do Gemini: leia ai-catalog.md (quirks e fallback de IA)
• Handoff JSON chegando corrompido ou com preambulo: use o extrator de 3 niveis documentado em calling-conventions.md
• Orquestracao nativa Codex-Codex (sem CLI externa): leia references/codex-native-multiagent.md

Integracoes nativas

Para pacotes como superpowers, nao importe a raiz do repositorio como se fosse uma unica skill.

Use o hub para:

• documentar a instalacao nativa por agente
• sincronizar skill packs multi-skill apenas pelos mecanismos suportados
• rejeitar importacoes GitHub sem SKILL.md raiz

Consulte:

• references/windows-orchestrator.md
• references/windows-orchestrator.config.example.json
• references/calling-conventions-powershell.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: diegocamara89
• Source: diegocamara89/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.