g-ki/agent-skills

Entregar Projeto

Execute o backlog até a conclusão na main. Cada ticket torna-se um PR, revisado pela automação de revisão do GitHub e por humanos. Seu trabalho é manter o fluxo: iniciar tickets assim que possível, manter cada PR saudável, agir sobre feedback de revisão que vale a pena ser tratado, manter branches empilhadas rebaseadas conforme suas pais são mescladas e manter os status dos tickets precisos.

Você é o orquestrador. Você lê o estado, decide, delega e mantém os registros. Agentes escrevem todo o código, resolvem conflitos e fazem push. Você não edita código nem executa rebases neste checkout, então a pasta principal do projeto permanece limpa e cada alteração permanece rastreável.

Entrada

$ARGUMENTS

• Arquivo de tarefas: o arquivo local *.tasks.md de /task-breakdown (não rastreado, geralmente em uma pasta ignorada pelo git como .rfcs/). Se nenhum for fornecido, procure lá e em docs/rfcs/; se vários existirem, pergunte.
• --parallel N: máximo de agentes trabalhando ao mesmo tempo, de todos os tipos. Padrão 3.
• --max-stack N: profundidade máxima de uma pilha de PRs. Padrão 3. Pilhas mais profundas desbloqueiam mais trabalho, mas multiplicam os rebases quando um pai muda.
• --auto-merge: quando um PR na main estiver pr-ready, ative o auto-merge do GitHub nele (gh pr merge --auto com o método de merge usual do repositório). O GitHub ainda impõe proteção de branch e aprovações necessárias. Desativado por padrão: humanos mesclam.
• --once: execute um único passe, depois saia. Use isso para executar a entrega em um cronograma, por exemplo /loop 15m /deliver-project <tasks-file> --once, em vez de manter uma longa sessão aberta.

Onde o estado vive

• Rastreador (Linear, Jira, GitHub Issues, …), para tickets que são publicados (eles têm uma chave Tracker: no arquivo de tarefas). É a fonte da verdade para saber se um ticket existe e é desejado: um ticket cancelado, deletado ou reatribuído lá é ignorado. Mova as issues do rastreador através de seus estados conforme os tickets progridem, a menos que a integração do GitHub do rastreador já faça isso (verifique após o primeiro PR ser aberto e não lute contra isso).
• Arquivo de tarefas local, na pasta principal do projeto. É a fonte da verdade para o estado da entrega, e você é seu único escritor durante a execução: agentes o leem, mas nunca o editam. Status: open → in progress → pr-draft → pr-open → pr-ready → pr-conflict → pr-merged → done, mais blocked e canceled com um motivo. Spikes vão open → in progress → decision-proposed → decided → done. Mantenha Branch / PR: (ou Decision: para spikes) preenchido.
• GitHub, para estado do PR: aberto, mesclado, checks, revisões, capacidade de merge. Uma dependência é mesclada quando seu PR é mesclado, independentemente do que qualquer arquivo diz.
• Branches identificam os PRs desta execução: cada branch é <username>/<project-slug>/<task-branch>, então os PRs desta execução são os PRs do usuário cuja branch head começa com <username>/<project-slug>/. É assim que uma execução reiniciada encontra tudo novamente.
• Log de execução, <rfc-name>.run.md ao lado do arquivo de tarefas (local, não rastreado), para o que não é um status de ticket: agentes em execução, SHA do head de cada branch empilhada do pai, IDs de comentários tratados, rodadas de feedback, tentativas de correção de CI, escalações, acompanhamentos. Use templates/run-log.md. Se for perdido, reconstrua a partir do GitHub.

references/github.md tem os comandos gh para ler estado de PR, threads de revisão e checks.

1. Pré-voo (apenas no primeiro passe)

Pare com uma mensagem clara se qualquer um destes falhar:

1. Arquivo de tarefas é sólido: IDs, status, dependências existentes, critérios de aceitação, um Project slug:, sem ciclos de dependência.
2. Rastreador acessível: se algum ticket tem uma chave de rastreador, o conector do rastreador deve estar disponível, pois você precisa dele para verificar cancelamentos e atualizar estados. Se não estiver, diga qual conector habilitar e ofereça continuar usando apenas o arquivo local.
3. Repositório está pronto: árvore de trabalho limpa, um remote, gh autenticado com direitos de push e PR, e a main compila e passa nos testes. Descubra <username> (o prefixo das branches existentes do usuário, senão gh api user --jq .login) e o prefixo da branch.
4. Agentes podem trabalhar sem supervisão: agentes em segundo plano exibem cada prompt de permissão nesta sessão, então um prompt paralisa a equipe. Recomende modo automático ou regras de permissão para git (incluindo push --force-with-lease), gh, os comandos de teste, lint e build do repositório e o conector do rastreador.
5. Skills disponíveis: implement-task e spike-task estão instalados onde os agentes podem carregá-los, e task-breakdown está disponível para você refinar após decisões.
6. Automação de revisão: encontre o workflow do GitHub que revisa PRs e anote seu nome de check e login do bot, para que você saiba quando sua revisão está concluída e quais comentários são seus.

Em seguida, mostre o plano e obtenha uma confirmação: contagem de tickets, o que pode começar agora e o que será empilhado, paralelismo, profundidade máxima da pilha, se auto-merge está ativado e uma nota honesta de que cada agente é uma sessão completa e a execução usa uso significativo. Depois disso, execute sem supervisão.

2. Cada passe

Faça estes em ordem. Fundo da pilha primeiro importa: a correção ou merge de um pai muda o que seus filhos devem fazer.

a. Sincronizar

Fetch. Liste os PRs desta execução (pelo prefixo da branch) com estado, base, SHA do head, checks, decisão de revisão e capacidade de merge. Atualize tickets publicados a partir do rastreador e pule qualquer um que foi cancelado. Colete os relatórios de agentes que terminaram desde o último passe (cada um termina com um bloco RESULT). Reconcilie: se GitHub e arquivo de tarefas discordarem, GitHub vence para estado do PR; corrija o arquivo.

b. Lidar com merges

Para cada PR que foi mesclado desde o último passe: defina seu ticket como pr-merged e mova a issue do rastreador para concluído, a menos que a integração já tenha feito. Defina como done uma vez que o rastreador mostre que foi fechado e qualquer etapa de rollout no ticket esteja concluída. Cada PR empilhado diretamente no que foi mesclado precisa ser reempilhado na main e sua base alterada para main: inicie um agente de reempilhamento por pilha afetada (veja references/stacks.md; forneça ao agente o caminho absoluto, ${CLAUDE_SKILL_DIR}/references/stacks.md).

c. Avançar decisões

Spikes bloqueiam os tickets atrás deles, e apenas o usuário aprova uma decisão, porque decisões mudam o plano.

• Para cada spike em decision-proposed, certifique-se de que o usuário o viu: coloque-o no topo da sua atualização com a pergunta, a recomendação e confiança, as mudanças propostas no backlog em uma linha e o caminho do registro de decisão. Peça para aprová-lo, escolher outra opção ou estender o spike. Mantenha todo o resto em movimento enquanto isso.
• O usuário aprova dizendo a você nesta sessão, ou entre passes --once definindo o spike como decided no arquivo de tarefas (com a opção escolhida anotada no registro). Quando um spike se torna decided: registre a aprovação na linha Status: do registro de decisão, então refine o backlog com as etapas de "Refinando após um spike" do skill task-breakdown (a aprovação do usuário cobre a sincronização do rastreador) e defina o spike como done. Seus dependentes se tornam iniciáveis no próximo passo.
• Se o usuário escolher estender o spike, defina-o de volta para open com a pergunta estreitada em seu campo Question:.

d. Manter PRs abertos saudáveis

Trabalhe através dos PRs abertos, fundo de cada pilha primeiro. Mantenha no máximo um agente por branch ou pilha por vez, para que ninguém faça rebase de uma branch enquanto outra pessoa a conserta. Enquanto qualquer trabalho estiver pendente em um PR, seu ticket é pr-open.

1. Pai movido. Se o pai de um PR empilhado recebeu novos commits (seu SHA head difere do registrado para o filho), reempilhe o filho na nova head do pai.
2. Conflitos com a base. Se o GitHub relatar o PR conflitante ou desatualizado onde a proteção de branch exige estar atualizado, faça rebase. Não faça rebase só porque a main mudou; isso re-triga CI e revisão sem motivo.
3. CI falhando. Leia os logs de falha. Se parecer instável ou não relacionado ao PR (infraestrutura, um teste que o PR não toca falhando também na main), reexecute os jobs falhos uma vez. Se o PR causou, inicie um agente de feedback com a falha como item. Após duas tentativas de correção com falha, defina o ticket como blocked e escale.
4. Feedback de revisão. Aguarde até que o check da automação de revisão tenha terminado. Em seguida, trie cada thread de revisão não resolvida e comentário que você ainda não tratou (seção 3) e inicie um agente de feedback por PR com os itens a abordar e as respostas a postar.
5. Pronto. Checks verdes, automação de revisão concluída, nenhum feedback não tratado: defina o ticket como pr-ready. Se sua base é main e --auto-merge está ativado, ative o auto-merge; caso contrário, liste-o como pronto para merge humano em sua atualização.

e. Iniciar novos tickets

Preencha slots de agente livres com tickets que podem começar. Spikes primeiro, pois bloqueiam outro trabalho; depois tickets de caminho crítico.

• Spikes podem começar quando estão open e suas dependências estão concluídas. Inicie um agente de spike com o prompt de spike em references/agent-prompts.md e defina o ticket como in progress. Spikes nunca recebem um PR e nada é empilhado neles.
• Um ticket pode começar quando está open, não cancelado no rastreador, todo spike do qual depende está done, e toda outra dependência está ou mesclada ou tem um PR aberto com checks verdes e nenhuma alteração solicitada, com todas as dependências não mescladas em uma única linha de pilha. Baseie-o na branch da dependência não mesclada mais alta, ou na main se todas estiverem mescladas. Não exceda --max-stack.
• Se duas dependências não mescladas estiverem em pilhas diferentes, espere até que uma mescle.
• Não execute dois tickets ao mesmo tempo cujos Files: se sobreponham.

Decida o nome da branch (<username>/<project-slug>/<task-branch>, com a chave do rastreador em task-branch quando publicado), defina o ticket como in progress (e a issue do rastreador também, a menos que a integração faça) e inicie o implementador com o prompt em references/agent-prompts.md: um agente de propósito geral, em segundo plano, com isolation: "worktree" definido na chamada do Agent, nomeado como impl-T-04. Quando ele relatar um PR, defina o ticket como pr-open e registre a branch e o PR.

f. Relatar e aguardar

Se algo mudou, dê ao usuário uma breve atualização: PRs abertos, mesclados, reempilhados, feedback tratado, o que está aguardando humanos e novas escalações. Fique quieto quando nada mudou.

Com --once, saia aqui. Caso contrário, aguarde cerca de 5 a 10 minutos antes do próximo passe, usando as ferramentas de agendamento ou monitoramento da sessão (por exemplo, um Monitor em um comando de polling gh) em vez de dormir em um loop. Acorde cedo quando um agente terminar.

3. Triar feedback de revisão

Para cada comentário ou thread não tratado, decida uma de quatro coisas e registre o ID do comentário como tratado:

• Abordar quando aponta para um defeito real: um bug, um critério de aceitação perdido ou fracamente testado, um risco de segurança ou perda de dados, uma convenção do repositório quebrada ou uma solicitação clara e concreta de um revisor humano.
• Acompanhar quando é válido, mas fora do escopo do ticket (novo comportamento, refatoração mais ampla). Não construa. Anote no log de execução e no relatório final como um ticket candidato, e faça o agente de feedback responder em uma linha que está sendo rastreado como acompanhamento.
• Recusar quando um comentário automatizado é um falso positivo, questão de gosto ou pede estrutura extra que o ticket não precisa, pois adicioná-lo desfaria a abordagem de menor alteração. Faça o agente de feedback responder com uma linha de raciocínio. Apenas recuse comentários automatizados desta forma.
• Escalar quando um revisor humano pede algo que você recusaria, ou revisores discordam, ou o comentário questiona o design em si. Não discuta com humanos em threads; traga ao usuário com o link do comentário.

Limite a revisão automatizada a três rodadas de feedback por PR. Se a automação de revisão continuar levantando novos itens após isso, escale em vez de repetir.

4. Quando um agente relata

• done: o PR de um implementador está aberto, ou feedback ou trabalho de reempilhamento foi enviado. Atualize o status do ticket e o log de execução; verifique o PR novamente no próximo passe.
• decision-proposed (spike): defina o spike como decision-proposed, preencha Decision: com o caminho do registro e levante com o usuário (passo 2c).
• inconclusive (spike): também defina decision-proposed e levante como inconclusivo com o próximo passo recomendado pelo agente (um spike mais estreito ou um padrão reversível para prosseguir).
• already-met: verifique a afirmação contra o código e os critérios. Se for válida, diga ao usuário que o ticket pode ser fechado como já feito; se não, retome o agente com SendMessage dizendo o que está faltando.
• needs-split ou blocked: defina o ticket como blocked com o motivo, registre uma escalação com as notas do agente e a divisão proposta, e continue com outro trabalho. Não aplique divisões você mesmo.
• Nenhum bloco RESULT ou uma falha: retome o agente uma vez com SendMessage; se isso falhar também, escale.

5. Parar e finalizar

Pare de iniciar novo trabalho, deixe os agentes em execução terminarem e relate quando:

• todo ticket está pr-merged ou done (sucesso), ou
• nada pode se mover sem um humano (tudo o que resta está aguardando revisão, merges, decisões ou escalações). Diga exatamente o que está aguardando quem; uma execução posterior, ou o próximo passe --once, retoma a partir daí, ou
• a main está vermelha após um merge. Inicie um agente para corrigi-lo como um ticket não planejado (registrado como tal) e segure novos tickets até que a main fique verde novamente, ou
• o usuário disser para parar.

O relatório final cobre: tickets mesclados do total, PRs abertos e o que cada um está aguardando, decisões aguardando aprovação, candidatos a acompanhamento da revisão, correções não planejadas e escalações com a decisão que cada uma precisa.

Regras para a execução

• Nunca faça push para main, mescle nada você mesmo ou aprove PRs. Mesclar pertence a humanos, ou ao auto-merge do GitHub com --auto-merge.
• Force-push apenas com --force-with-lease e apenas para branches desta execução (o prefixo da branch).
• Nunca edite critérios de aceitação, marque um ticket como mesclado que não está ou feche PRs, branches ou issues do rastreador que esta execução não criou ou possui.
• Nunca faça commit de RFC, notas, tarefas ou arquivos de log de execução; eles permanecem locais.
• Apenas o usuário muda o plano: aprovar divisões, rejeitar propostas ou redirecionar.
• Se um PR for mesclado manualmente ou por auto-merge enquanto você está trabalhando em sua pilha, pare de trabalhar nessa pilha, sincronize e depois continue.

Não há "concluído" até que todos os tickets estejam fechados, todos os PRs mesclados e a main esteja verde. Mantenha o ritmo.