agent-coordinator

Usado em projetos onde um agente de codificação separado (ex: Antigravity/Gemini, Codex, outro Claude) faz a pesquisa e a codificação pesada, e ao iniciar um novo projeto com um, adicionar um a um projeto existente, importar resultados de pesquisa, lançar uma versão ou perguntar sobre o status do projeto. Claude configura o projeto, escreve os prompts do agente, revisa seus branches, mergeia e cria tags.

O que é agent-coordinator?

O Agent Coordinator é uma habilidade especializada do Claude que atua como o 'cérebro' em um fluxo de trabalho de desenvolvimento de software dividido. Ele permite que desenvolvedores e agentes de IA colaborem de forma eficiente, com o Claude focado em planejamento, revisão e coordenação, enquanto agentes de codificação dedicados (como Cursor, Codex ou Claude Code) lidam com pesquisas, correções de bugs e codificação em massa. O usuário atua como testador, e o repositório serve como a memória persistente do projeto. A habilidade fornece um conjunto completo de modos operacionais: iniciar novos projetos (Kickoff), adotar projetos existentes (Adopt), fazer importação de pesquisas, cortar releases, obter status do projeto e continuar o trabalho de uma sessão anterior. Ela inclui templates e scripts para gerenciamento de milestones, escrita de prompts, revisão de relatórios, verificação de segurança e manutenção de uma base de conhecimento centralizada. O Agent Coordinator suporta diversas plataformas de agentes de codificação, permitindo que o usuário especifique qual agente usar, e sua configuração se adapta às ferramentas instaladas. A habilidade promove um fluxo de trabalho disciplinado, com o Claude revisando o trabalho do agente de codificação antes de qualquer merge, garantindo assim a qualidade e a consistência do projeto.

Funciona com✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/Trooper-code/Trooper-s-Coordinator-Skills/tree/HEAD/skills/agent-coordinator

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Coordenador de agente (Claude como o cérebro)

Divida o trabalho por força e custo:

  • Claude = o cérebro. Planeja marcos, escreve os prompts do agente, revisa seu trabalho, mergeia e cria tags.
  • Agente de codificação = as mãos. Faz a pesquisa, rastreamento, investigações, grandes correções e código em massa.
  • O usuário = o testador. Executa a build em sua máquina real e relata o que vê.
  • O repositório = a memória. Tudo o que é aprendido vive em documentos commitados, não em nenhum chat.

Claude economiza seus tokens para julgamento. Ele não inicia novas investigações ou faz grandes correções de bugs por conta própria — essas vão para o agente como um prompt.

Modelos e scripts para cada arquivo abaixo: a pasta templates/ desta habilidade (incluída nos zips de release), ou templates/ em https://github.com/Trooper-code/Trooper-s-Coordinator-Skills. Detalhes para alguns modos estão na pasta reference/ desta habilidade; leia esse arquivo quando o modo for acionado.

Onde os scripts residem. Um projeto mantém seus scripts de verificação em scripts/ na raiz do repositório, ou em docs/scripts/. Sempre procure em ambos (detect-mode.py informa qual). Cada caminho scripts/... nesta habilidade significa a pasta que o projeto usa. Novos projetos recebem scripts/ a menos que o usuário peça docs/scripts/. Nunca mova os scripts existentes de um projeto.

Escolha o modo

O usuário diz / o repositório temModo
"status", "onde estamos"Status (abaixo)
"release v…", "cortar uma release", "criar tag para isto"Release: siga reference/release.md
"importar pesquisa", resultados de deep-research coladosImportação de pesquisa: siga reference/research-import.md
repositório tem docs/HANDOFF.mdContinuar: leia HANDOFF.md, o quadro de status e os documentos para os quais ele aponta, depois faça sua "Primeira coisa a fazer"
repositório tem código ou documentos, sem HANDOFF.mdAdotar (abaixo)
repositório vazio (ou apenas README/LICENSE/.gitignore)Iniciar (abaixo)

Se você puder executar comandos, python templates/scripts/detect-mode.py <repo> decide os três últimos e lista os arquivos de fluxo de trabalho que o repositório tem e está faltando.

Status

Para "Usar agent-coordinator. Status." ou "onde estamos em ?". Barato de propósito:

  • Leia apenas docs/MILESTONES.md e docs/HANDOFF.md (e git log --oneline -5 se você tiver o repositório).
  • Responda em cerca de cinco linhas: marco atual e seu estado, o que está em andamento e quem o possui, o último resultado testado, o próximo passo e qualquer coisa aguardando o usuário.
  • Não revise, teste ou abra outros arquivos a menos que seja solicitado.

Iniciar (novo projeto)

Exemplo: /agent-coordinator Iniciar um novo projeto: <nome>. Repositório: <url ou pasta>. Objetivo: <...>. Agente de codificação: <...>.

  1. Obter acesso. Peça o repositório (link do GitHub ou pasta local) se você não o tiver. Em uma pasta local, peça também permissão para excluir (o git cria e remove arquivos .lock).
  2. Escopo. Se o objetivo for realmente incerto, faça 1-3 perguntas precisas: como é "pronto", qual agente de codificação e quais de suas ferramentas o usuário tem, e restrições rígidas (plataforma, linguagem, o que nunca deve ser commitado). Caso contrário, comece.
  3. Estruturar a memória (não sobrescreva arquivos que já existem):
    • AGENTS.md, com a seção específica do agente preenchida (veja "O arquivo de regras do agente").
    • docs/MILESTONES.md, docs/HANDOFF.md (com Versões das ferramentas), docs/DECISIONS.md, docs/research/INDEX.md, docs/prompts/, docs/reports/TEMPLATE.md, CHANGELOG.md.
    • scripts/ (ou docs/scripts/, se o usuário preferir): os scripts de verificação (veja reference/scripts.md).
    • Segurança e releases: templates/hooks/pre-commit copiado para scripts/hooks/pre-commit (os hooks em si não são commitados, então o usuário o instala uma vez com cp scripts/hooks/pre-commit .git/hooks/pre-commit, ou o caminho docs/scripts/...), mais .github/workflows/checks.yml e .github/workflows/release.yml. O hook e os workflows encontram os scripts em qualquer uma das pastas.
  4. Escreva o primeiro prompt para M1 em docs/prompts/M1-<slug>.md e execute check-prompt.py nele. Se M1 for puramente pesquisa, o trabalho do agente é preencher docs/research/, não escrever código.
  5. Commite a estruturação com uma mensagem clara.
  6. Responda brevemente: a lista de marcos, a instrução de uma linha para colar no agente, o comando de instalação do hook e "diga-me quando estiver pronto; seu relatório estará em docs/reports/ em seu branch".

Adotar (projeto existente)

Exemplo: /agent-coordinator Adotar meu projeto existente. Repositório: <url ou pasta>. Agente de codificação: <...>.

Aprenda o que o projeto já sabe, planeje a partir disso e adicione apenas os documentos que estão faltando. A varredura é ler documentos e a estrutura do repositório, não investigar código: qualquer coisa que precise de rastreamento vai para o agente.

  1. Obter acesso, como na inicialização.
  2. Varrer (orçamento: cerca de 15-20 chamadas de ferramenta; detect-mode.py faz o inventário em uma). Leia, não rastreie:
    • layout de alto nível, arquivos de build e configuração de teste (linguagem, como constrói e testa, quais versões de ferramentas);
    • README, tudo em docs/, RESEARCH.md, NOTES.md, TODO.md, ROADMAP.md, CHANGELOG.md;
    • arquivos de regras de agente existentes (AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/, .agents/rules/);
    • ambos scripts/ e docs/scripts/: quais scripts de verificação o projeto já tem e onde;
    • git log --oneline -30, branches e tags: o que foi feito por último, o que está meio pronto;
    • comentários TODO/FIXME, se for barato listar (git grep -n "TODO\|FIXME").
  3. Inventariar. Mapeie o que existe nos arquivos do fluxo de trabalho. Reutilize o que faz o trabalho: vincule um roadmap existente de MILESTONES.md, mantenha os documentos de pesquisa existentes onde estão e indexe-os, e adicione seções ausentes a um arquivo de regras existente em vez de substituí-lo. Crie apenas o que está faltando. Nunca sobrescreva, mova ou renomeie os arquivos do usuário.
  4. Rotule o que aprendeu. Fatos de documentos ou comentários existentes são não verificados até serem testados. Anote contradições entre documentos e código como lacunas. Registre escolhas passadas que você pode ver (uma biblioteca escolhida, um formato selecionado) em DECISIONS.md apenas se os documentos disserem o porquê; caso contrário, liste-as como perguntas em aberto.
  5. Execute check-safe-to-publish.py em todo o repositório. Se algo for sinalizado, avise o usuário primeiro: remover um arquivo commitado do histórico é uma decisão dele.
  6. Planeje com antecedência: termine branches meio prontos, corrija testes com falha, feche TODOs, preencha lacunas de pesquisa. Marcos com critérios de conclusão em docs/MILESTONES.md. Decisões de julgamento reais (reescrever vs. corrigir, qual funcionalidade primeiro) → faça 1-3 perguntas precisas antes de se comprometer com o plano.
  7. Primeiro prompt. Grandes partes do código não documentadas → M0: levantamento (o agente as mapeia em docs/research/ e no índice, cada alegação citada e rotulada). Caso contrário, M1.
  8. Escreva docs/HANDOFF.md, execute check-handoff.py e commite os novos documentos em um único commit (ex.: "Adicionar documentos do coordenador"), mantendo as terminações de linha de cada arquivo existente.
  9. Responda brevemente: o que aprendeu, arquivos criados ou estendidos, o plano, qualquer coisa que precise da decisão do usuário e a linha única para colar no agente.

O arquivo de regras do agente (AGENTS.md)

Regras permanentes residem em AGENTS.md na raiz do repositório, para que os prompts carreguem apenas o que é específico para sua tarefa. Ele contém regras sempre/nunca, as regras de versões de ferramentas e carimbo, as condições de parada, o formato do relatório e uma seção específica do agente.

Restrições específicas do agente são obrigatórias. Sempre que o usuário nomear seu agente de codificação (inicialização, adoção ou uma troca), preencha ## Restrições específicas do agente: <agente>:

  • Comece pelo perfil em templates/agents/ (Antigravity, Codex, Claude Code, Cursor, genérico). Mantenha seus rótulos de confirmado/não verificado.
  • Pergunte quais ferramentas o usuário tem instaladas e remova as que ele não possui.
  • Como ele carrega regras. Se o perfil disser que o agente lê outro arquivo, crie o ponteiro que ele descreve. Se não tiver certeza, diga isso e mantenha AGENTS.md primeiro em "Leia primeiro" em cada prompt.
  • Limites de permissão para ferramentas de alto privilégio e peculiaridades conhecidas.
  • Quando o usuário ou o agente corrigir um fato do perfil, corrija-o em AGENTS.md e sugira corrigir o perfil compartilhado upstream também.

Marcos e branches

  • Divida o trabalho do tamanho de um marco em marcos. Cada um recebe seu próprio branch de funcionalidade.
  • O agente nunca mergeia. Claude revisa o branch, depois mergeia e cria uma tag (ex.: m5-p4a) assim que o usuário o testar e funcionar.
  • Acompanhe o status em docs/MILESTONES.md (marcos, registro de progresso datado, próximo passo "Next" atual).

Escrevendo um prompt

Prompts vão em docs/prompts/<MILESTONE>-<slug>.md, commitados, autocontidos (o agente não tem nenhum contexto deste chat). Seções, como em templates/PROMPT.md:

  1. Leia primeiro: AGENTS.md primeiro; depois docs/research/INDEX.md e as seções que esta tarefa precisa; quaisquer entradas de DECISIONS.md que ele toca.
  2. Objetivo: uma ou duas frases.
  3. Branch: o nome e de qual tag ramificar.
  4. Fatos conhecidos: caminhos exatos, endereços, deslocamentos, valores; cada um confirmado ou não verificado, com evidência.
  5. Tarefas: numeradas. Se check-research.py encontrou fatos comprovados em versões de ferramentas mais antigas das quais esta tarefa depende, re-verificá-los é uma tarefa.
  6. Ferramentas: as ferramentas do agente que se encaixam nesta tarefa e por quê.
  7. Restrições específicas da tarefa: apenas o que AGENTS.md já não diz.
  8. Pare e relate se: as condições de parada do AGENTS.md, mais quaisquer para esta tarefa.
  9. Verificações de aceitação: quais testes devem passar; cada alegação cita sua evidência.
  10. Relatório: docs/reports/<MILESTONE>-<slug>.md, commitado no branch.

Execute check-prompt.py nele, corrija o que ele relatar e dê ao usuário uma instrução de uma linha para o agente, ex.: "Leia e siga docs/prompts/M5-p4b-save-format.md."

Nomeando ferramentas. Habilidades de processo (ex.: superpoderes: depuração-sistemática, desenvolvimento-orientado-por-testes, verificação-antes-da-conclusão); kits de ferramentas de análise ou engenharia reversa (suas alegações precisam de prova por emulação, um teste ou uma execução real; mantenha recursos de alto privilégio somente leitura nos arquivos do usuário); modos multiagente "swarm" apenas para tarefas grandes que se dividem em partes independentes — um prompt swarm descreve a parte de cada trabalhador, arquivos e critérios de conclusão, e diz que os verificadores executam os testes do repositório.

Revisando o trabalho do agente

Leia o relatório do branch: git fetch origin <branch> então git show origin/<branch>:docs/reports/<file>. Peça ao usuário para colar um resumo apenas se o relatório não estiver lá.

O agente já errou antes. Verifique, não confie:

  1. check-report.py no relatório. Um relatório que falha volta para o agente, a menos que as lacunas sejam triviais.
  2. Versões de ferramentas no relatório contra docs/HANDOFF.md. Uma incompatibilidade é um bug até ser explicada.
  3. Reexecute seus testes e provas você mesmo.
  4. Verifique pontualmente os endereços, deslocamentos e alegações que ele cita contra os arquivos e logs reais. Verifique se as descobertas confirmadas são carimbadas ([confirmado @ <branch> | ferramenta=versão]) e novas seções estão no índice de pesquisa; execute check-research.py.
  5. Decodifique ou verifique sua saída manualmente.
  6. Liste os resultados como bugs, depois lacunas, depois minúcias.

Regra de orçamento: se verificar uma alegação precisar de novo rastreamento além do que o agente citou (aproximadamente mais de ~10 chamadas de ferramenta), pare. Coloque-o no próximo prompt.

Se o agente parou, não refaça seu trabalho: decida o que ele precisa (acesso, um arquivo, um fato corrigido, uma tarefa menor) e escreva isso no próximo prompt.

Após a revisão:

  • Funciona → dê ao usuário passos de teste exatos (o que fazer, o que eles devem ver). Assim que eles confirmarem, faça o merge, crie a tag, adicione uma linha em ## Unreleased em CHANGELOG.md e registre-o nos documentos.
  • Não funciona → escreva o prompt de acompanhamento com os bugs e lacunas como tarefas.
  • Abandonar após duas rodadas de revisão com falha, ou quando a correção for na direção errada: mantenha o branch (renomeie-o para abandonado/<nome> se o usuário concordar), registre o porquê nos documentos de pesquisa e como uma Lição, mantenha quaisquer descobertas confirmadas e escreva um novo prompt a partir da última tag boa.

Mantendo a memória afiada

  • Decisões. Quando o usuário fizer uma escolha real entre opções (um formato, uma biblioteca, reescrever vs. corrigir), adicione uma entrada a docs/DECISIONS.md: decidido, rejeitado, porquê, revisitar-se. Antes de reabrir uma questão resolvida, leia sua entrada; novos fatos recebem uma nova entrada que substitui a antiga.
  • Índice de pesquisa. Cada tópico de pesquisa tem uma linha em docs/research/INDEX.md apontando para seu arquivo e seção. Consulte lá primeiro; mantenha-o atualizado quando as seções forem movidas.
  • Fatos com ciência de versão. Fatos confirmados carregam um carimbo da tag e versões de ferramentas em que foram comprovados. Sempre que a tabela de Versões de ferramentas mudar, execute check-research.py e coloque a re-verificação dos fatos listados no próximo prompt.
  • Lições se tornam regras. Uma lição que aparece uma segunda vez recebe (x2) em HANDOFF.md, depois se move para AGENTS.md (uma regra para o agente), um script de verificação (se puder ser automatizado) ou o modelo de prompt.
  • Regra de descobertas. Cada descoberta vai para os documentos do repositório na mesma sessão, rotulada como confirmada, não verificada ou errada, com evidência. Corrija alegações antigas que se revelaram erradas. Mantenha as terminações de linha.
  • Seguro para publicar. Nada protegido por direitos autorais ou pessoal é commitado: o hook pre-commit e o CI executam check-safe-to-publish.py. Os usuários fornecem seus próprios arquivos de jogo.

Handoffs de sessão

Combine isso com a habilidade project-handoff. Sugira um handoff no final de cada rodada de revisão ou quando o contexto ficar grande. A rotina de troca:

  1. Claude atualiza docs/HANDOFF.md, executa check-handoff.py e commita.
  2. O usuário executa o que Claude pediu (logs, capturas).
  3. O usuário dá ao agente seu prompt.
  4. Novo chat Claude: cole HANDOFF.md (ou, se o chat puder ler o repositório, "Leia docs/HANDOFF.md e faça sua Primeira coisa a fazer"). O relatório do agente já está em seu branch, então nada mais precisa ser colado.

Habilidades Relacionadas