0xVoidw/subagent-allocator

Distribuidor de Subagentes

Transforma um plan.md em uma tabela de alocação executável: quem faz o quê, qual modelo usar, qual intensidade de esforço (effort) definir e como escalar em caso de falha.

O princípio para economizar créditos é simples: a maior parte do trabalho em um plano envolve ler arquivos, pesquisar código, executar testes e modificar código seguindo especificações – tudo isso não precisa do modelo mais caro. Modelos caros devem ser usados apenas onde há necessidade de julgamento real. Esta skill separa esses dois tipos de tarefas.

Entrada

1. Caminho do plan.md. Se não for fornecido, procura por plan.md / PLAN.md / PLANS.md no diretório atual. Se não encontrar, pergunta.
2. Plataforma alvo: claude (Claude Code), codex (OpenAI Codex) ou both. Se não for especificada, tenta detectar pelo ambiente de execução atual; se não conseguir detectar, pergunta uma vez.
3. Viés (opcional): economia, equilibrado (padrão) ou robusto. Afeta apenas o passo 4 quando houver dúvida sobre qual direção seguir.

Após determinar a plataforma, lê o arquivo de referência correspondente, que contém os nomes específicos dos modelos, proporções de preço e níveis de effort para aquela plataforma:

• Claude → references/claude.md
• Codex → references/codex.md
• both → lê ambos, exibe as duas configurações lado a lado na saída

Os nomes e preços dos modelos podem ficar desatualizados. O arquivo de referência é a única fonte de verdade; não preencha nomes de modelo de memória.

Fluxo

1. Ler o plano e dividir em unidades de tarefa

Mantenha a divisão de etapas do próprio plan.md, ajustando apenas em dois casos:

• Separar: uma etapa que contenha simultaneamente "muita leitura/pesquisa" e "tomada de decisão/modificação de código". Separe a parte de leitura para um subagente barato, que retorna apenas um resumo.
• Agrupar: várias etapas pequenas consecutivas que modificam os mesmos arquivos e precisam do mesmo contexto. Combine-as em uma única tarefa para evitar recarregar o contexto.

Não divida excessivamente. Cada subagente tem um custo de inicialização (relocar o contexto, escrever instruções de transição). Tarefas que podem ser concluídas em alguns minutos devem ser executadas diretamente pelo agente principal, marcadas no documento como "execução direta pelo agente principal".

2. Atribuir cinco marcadores a cada tarefa

Marcador	Pergunta a ser feita	Valores
Clareza	A especificação já está definida, basta seguir?	Clara / Parcial / Aberta
Custo do erro	Erros são fáceis de detectar e reverter?	Baixo / Médio / Alto
Verificável	Existem testes, build, lint, scripts que avaliam automaticamente?	Sim / Pode-se adicionar / Não
Volume de leitura	Quanto material precisa ser lido antes de agir?	Pouco / Muito
Abrangência	A mudança é local ou afeta múltiplos módulos/arquitetura?	Local / Entre módulos / Arquitetural

Se o plan.md não deixar algo claro, julgue pelo cenário mais provável e registre na coluna "Suposições" da saída. Não pare para perguntar item por item.

3. Mapear para quatro níveis

Os modelos específicos de cada plataforma estão nos arquivos de referência; aqui definimos apenas os níveis:

Nível	Usado para	Tarefas típicas
T0 Leve	Clara + Baixo custo + Resultado facilmente verificável	Procurar arquivos, ler logs, executar testes e relatar, classificar, extrair, resumir
T1 Padrão	Clara + Local + Verificável	Implementar funcionalidades conforme especificação, corrigir bugs identificados, escrever testes, documentação, reproduzir UI
T2 Principal	Parcialmente clara, ou entre módulos, ou requer diagnóstico	Funcionalidades multiarquivo, depurar bugs de causa desconhecida, revisão de código, integrar resultados de subagentes
T3 Flagship	Aberta + Arquitetural, ou erro de alto custo e sem verificação automática	Decisões arquiteturais, planos de refatoração de grande escala, compensações entre múltiplas restrições conflitantes, coordenar múltiplos subagentes

Ordem de julgamento: comece presumindo T1, depois veja se há razão para descer ou subir.

• Razões para descer para T0: a tarefa é essencialmente "encontrar e relatar", sem produzir código a ser mesclado.
• Razões para subir para T2: a clareza não é "clara", ou a abrangência não é "local".
• Razões para subir para T3: deve atender simultaneamente a "aberta ou arquitetural" E "erro custa caro". Se apenas um dos dois, use T2 com effort alto.

Em um plano normal, geralmente há de 0 a 2 tarefas T3. Se metade das tarefas for T3, volte e revise a divisão; provavelmente você está agrupando "leitura" e "julgamento" juntos.

4. Definir intensidade de esforço (effort)

Effort é um ajuste mais fino do que trocar de modelo; ajuste-o primeiro.

• Sempre comece com o valor padrão inicial do respectivo nível no arquivo de referência.
• Verificável = Sim: mantenha o valor inicial, ou até reduza um nível. Quando o modelo pode executar autoverificação (testes), o ganho de effort alto é pequeno.
• Verificável = Não E custo do erro ≥ Médio: aumente um nível.
• Há alguém esperando resultado em tempo real: reduza um nível, priorize velocidade.
• Viés = economia: quando em dúvida, escolha o menor valor; robusto: escolha o maior.

Acima de high, aumentar o effort geralmente custa quase o mesmo que trocar para o modelo do nível superior com effort baixo. Portanto, a escada de escalonamento é:

1. Primeiro, adicione meios de verificação (forneça um comando de teste ou verificação executável)
2. Aumente o effort em um nível, no máximo até high
3. Troque para o modelo do nível superior, com o menor effort inicial desse nível

O T0 do Codex é uma exceção: com effort alto, o custo-benefício ainda é excelente; veja references/codex.md para detalhes.

5. Proteção de qualidade

Economizar créditos não pode custar retrabalho. Retrabalho é mais caro do que usar o modelo correto desde o início. As medidas a seguir garantem que a qualidade não seja perceptivelmente reduzida:

• Cada tarefa deve ter um critério de conclusão. Se puder ser escrito como comando (ex.: pytest tests/x, npm run build), escreva como comando. Tarefas sem critério de conclusão claro sobem um nível.
• Modificação de código e julgamentos críticos permanecem acima de T1. T0 apenas lê ou escreve coisas que não vão para o branch principal (relatórios, listas).
• Após a conclusão por um modelo barato, um modelo do nível superior revisa o diff. Revisar diff consome poucos tokens (apenas as partes alteradas), mas detecta a maioria dos problemas. Liste isso como uma tarefa de revisão independente no final de cada fase.
• Subagentes retornam apenas conclusões. Na descrição da função, defina o formato e o limite de tamanho do retorno (ex.: "resumo de no máximo 200 caracteres + lista de caminhos de arquivos relevantes") para evitar que saídas longas encham o contexto do agente principal.

6. Ordenar execução

• Tarefas sem dependências mútuas devem ser marcadas como paralelizáveis.
• Sempre que possível, agrupe tarefas que usam o mesmo modelo, trocando de modelo nos pontos de transição naturais entre fases. Trocar de modelo com frequência no meio do caminho perde o cache, efetivamente pagando novamente pelo contexto.
• Observações específicas da plataforma (pertencimento de cache, limite de aumento de preço para contexto longo, etc.) estão nos arquivos de referência. Quando aplicáveis, inclua na seção "Observações" da saída.

Saída

Escreva plan.dispatch.md no mesmo diretório do plan.md, usando a seguinte estrutura. Se houver muitas tarefas, mantenha a tabela completa; os cartões de função são escritos apenas para tarefas de subagentes.

# Alocação de Subagentes: <Nome do plano>

Fonte: <Caminho do plan.md>　Plataforma: <claude / codex / both>　Viés: <economia / equilibrado / robusto>

## Visão Geral

| # | Tarefa | Executor | Nível | Modelo | effort | Dependências | Paralelizável |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | … | Investigador | T0 | … | … | Nenhuma | Com 2 |

Distribuição de níveis: T0 ×n, T1 ×n, T2 ×n, T3 ×n
Agente principal: <Modelo> / <effort>, responsável por <coordenação, integração, validação final etc.>

## Fases de Execução

### Fase 1: <Nome> (Modelo: …)
- Tarefas 1, 2 em paralelo
- Revisão ao final da fase: <Quem revisa, o que revisa>

## Cartões de Função

### Tarefa 1: <Nome>
- **Função**: <Descrição em uma frase, ex.: "Investigador somente leitura: localizar todas as ocorrências da interface antiga">
- **Modelo / effort**: … / …
- **Objetivo**: …
- **Entrada**: <Arquivos, diretórios, mensagens de erro a serem lidos>
- **Restrições**: <O que não pode modificar, normas a seguir>
- **Critério de conclusão**: <Comando ou estado verificável>
- **Formato de retorno**: <Conteúdo e limite de tamanho>
- **Escada de escalonamento**: Adicionar verificação → aumentar effort para … → trocar modelo para … / …
- **Justificativa da escolha**: <Uma frase, correspondente aos cinco marcadores>

## Suposições e Observações
- <Pontos em que o plan.md não esclareceu e que foram inferidos por esta skill>
- <Armadilhas de custo relacionadas à plataforma>

## Economia Estimada
Em relação à configuração padrão "tudo com modelo principal": estimativa aproximada, ex.: "Cerca de metade das tarefas reduzidas para T0/T1, com custo unitário de 1/2 a 1/20 do original."

Os quatro campos "Objetivo, Entrada, Restrições, Critério de conclusão" do cartão de função são o prompt que pode ser colado diretamente para o subagente. Escreva-os de forma que possam ser compreendidos de forma independente, pois o subagente não verá o restante do plan.md.

"Economia Estimada" deve fornecer apenas a ordem de grandeza e a justificativa, sem inventar porcentagens exatas. O consumo real depende da tarefa em si; sugira ao usuário que compare com as estatísticas de uso após a execução e ajuste conforme necessário.

Exemplo

Dado o seguinte passo no plan.md:

3. Substituir todas as ocorrências de oldLogger por newLogger em utils/. Observação: alguns locais passam um formatador personalizado.

Processamento: este passo mistura "encontrar todas as ocorrências" (muita leitura, somente leitura) e "substituir e tratar exceções de formatador" (requer modificação de código, com casos especiais que exigem julgamento). Divida em duas tarefas:

#	Tarefa	Executor	Nível	effort	Justificativa
3a	Listar todas as ocorrências de oldLogger, destacando as que possuem formatador personalizado	Investigador	T0	Inicial	Somente leitura; se algo for perdido, será detectado pelo grep da tarefa 3b
3b	Substituir conforme a lista, adaptando os casos especiais de formatador um a um	Implementador	T1	Inicial	Especificação clara; critério de conclusão: grep -r oldLogger utils/ vazio e testes aprovados

Se não houver testes cobrindo o comportamento do formatador, o effort da tarefa 3b deve ser aumentado em um nível, e isso deve ser registrado em "Suposições e Observações".