merge

Visão geral do merge skill

Para que serve o merge skill

O merge skill é uma skill de workflow do AgentHub para aplicar o resultado do agente vencedor em uma branch base do Git depois de uma sessão de codificação multiagente. Ele foi criado para o comando /hub:merge e se concentra em uma tarefa prática: fazer merge do vencedor selecionado, preservar as tentativas perdedoras para inspeção posterior, limpar os worktrees da sessão e escrever um resumo pós-merge.

Melhor encaixe em Git Workflows

Use este merge skill quando seu repositório segue o padrão do AgentHub com IDs de sessão, branches de agentes, rankings de avaliação e worktrees temporários. Ele é mais útil depois de /hub:eval, quando você já sabe qual agente produziu a melhor solução e quer um Git Workflow repetível em vez de fazer manualmente checkout de branches, merge, marcação dos perdedores com tags e remoção de worktrees.

O que o diferencia de um prompt genérico de merge

Um prompt genérico poderia dizer “faça merge da melhor branch”, mas esta skill codifica uma convenção operacional específica: usar o agente mais bem ranqueado, a menos que --agent seja informado; fazer merge com --no-ff; arquivar branches não vencedoras com tags hub/archive/...; excluir suas referências de branch; e gerar .agenthub/board/results/merge-summary.md. Essa estrutura reduz a ambiguidade durante a limpeza, que costuma ser o ponto em que sessões Git multiagente ficam confusas.

Observações antes da instalação

A skill pressupõe que seu projeto já tenha branches no estilo AgentHub, como hub/{session-id}/{agent-id}/attempt-1, e saída de avaliação capaz de identificar um vencedor. Se sua equipe não usa AgentHub, o guia de merge ainda pode servir como modelo para uma limpeza estruturada, mas precisará ser adaptado antes de ser usado com segurança.

Como usar o merge skill

Instalação do merge e arquivos para inspecionar primeiro

Instale a skill a partir do repositório de skills no GitHub com:

npx skills add alirezarezvani/claude-skills --skill merge

Depois, inspecione o código-fonte em:

engineering/agenthub/skills/merge/SKILL.md

Esta skill parece ser autocontida em SKILL.md; não há pastas complementares visíveis como rules/, resources/ ou scripts/ na prévia do diretório da skill. Como as instruções upstream mencionam session_manager.py, verifique onde esse script existe na sua configuração local do AgentHub antes de confiar na limpeza automatizada.

Uso básico do merge

Chamadas típicas são:

/hub:merge
/hub:merge 20260317-143022
/hub:merge 20260317-143022 --agent agent-2

Use /hub:merge quando a sessão avaliada mais recente for o alvo. Informe um ID de sessão quando houver várias sessões do AgentHub. Adicione --agent apenas quando você quiser sobrescrever intencionalmente o resultado mais bem ranqueado de /hub:eval, por exemplo quando a maior pontuação deixou passar um requisito de segurança, compatibilidade ou produto identificado na revisão humana.

Entradas de que a skill precisa

Para um uso confiável do merge, o agente precisa de:

• A branch base de destino, normalmente a branch na qual você quer aplicar o trabalho vencedor.
• O ID da sessão do AgentHub, a menos que a sessão mais recente seja inequívoca.
• Um vencedor, vindo do ranking de avaliação mais recente ou de --agent.
• Referências de branch existentes no formato esperado: hub/{session-id}/{agent-id}/attempt-1.
• Permissão para executar operações Git que criam commits de merge, tags e exclusões de branches.

Um prompt mais forte seria: “Run /hub:merge 20260317-143022 --agent agent-2 into main. Before merging, confirm the working tree is clean, show the winning branch ref, tag losing branches for archive, and write the merge summary.” Isso dá à skill contexto operacional suficiente para evitar suposições.

Workflow prático antes e depois da execução

Antes de chamar o merge, execute git status, confirme que você não está carregando alterações locais não relacionadas e revise o diff vencedor. Depois do merge, confira a mensagem do commit de merge, confirme que as tags de arquivamento foram criadas e verifique se .agenthub/board/results/merge-summary.md reflete a sessão, a tarefa e o vencedor. Se aparecerem conflitos, resolva-os como conflitos Git normais; a skill fornece estrutura de workflow, não substitui revisão de código.

FAQ do merge skill

O merge é apenas para AgentHub?

Sim, na prática. O merge skill foi escrito em torno das convenções de nomenclatura, avaliação e limpeza do AgentHub. Ele pode inspirar um Git Workflow manual para outros experimentos com múltiplas branches, mas o uso direto espera branches de sessão do AgentHub e metadados de resultado.

O merge escolhe automaticamente o melhor código?

Ele escolhe o --agent que você especificar ou, caso contrário, o agente mais bem ranqueado no /hub:eval mais recente. Isso significa que a qualidade do merge depende da qualidade da avaliação anterior. Se seus critérios de avaliação estavam incompletos, revise manualmente o vencedor antes de fazer o merge.

O que acontece com as branches perdedoras?

O workflow previsto arquiva cada branch de agente perdedora com uma tag Git, como hub/archive/{session-id}/{agent-id}, e depois exclui a referência da branch. Isso mantém os commits alcançáveis enquanto reduz a poluição na lista de branches. Equipes com políticas de retenção devem confirmar o padrão de nomenclatura das tags de arquivamento antes de adotar a skill.

Quando não devo usar esta skill?

Não use o merge se os nomes das branches não seguem a convenção do AgentHub, se a branch base estiver incerta, se o vencedor ainda não foi revisado ou se seu repositório proíbe exclusão automatizada de branches. Ele também é uma escolha ruim para workflows exclusivamente com squash, a menos que você adapte o comando de merge, porque o padrão da skill usa git merge --no-ff.

Como melhorar o merge skill

Melhore os resultados do merge com contexto mais claro

O merge skill funciona melhor quando sua solicitação inclui o ID da sessão, o vencedor, a branch base e quaisquer restrições de política. Por exemplo: “Merge session 20260317-143022, winner agent-2, into develop; keep losing branches archived with tags, do not delete remote branches, and stop if tests fail.” Isso é melhor do que “merge the winner” porque separa seleção, destino, limpeza e regras de segurança.

Modos de falha comuns para observar

Os principais riscos são sessões mais recentes ambíguas, resultados de avaliação ausentes, working trees sujas, referências de branch que não seguem o padrão esperado e comandos de limpeza que dependem de arquivos fora do diretório desta skill. Outro risco importante é fazer merge de um vencedor que passa tecnicamente, mas está errado do ponto de vista de produto. Trate /hub:eval como entrada para seleção, não como substituto da revisão final.

Adapte o merge à política do seu repositório

Se sua equipe exige squash merges, commits assinados, branches protegidas, pull requests, gates de CI ou retenção de branches remotas, edite o workflow antes de usá-lo em produção. Os pontos de customização mais prováveis são a estratégia de merge, o formato da tag de arquivamento, se a exclusão de branches será apenas local e quais campos são obrigatórios em merge-summary.md.

Itere depois da primeira execução

Depois da primeira saída, peça ao agente para verificar em vez de continuar às cegas: “Show the merge commit, list archive tags for this session, confirm no AgentHub worktrees remain, and summarize any conflicts or skipped cleanup.” Isso transforma o guia de merge em um Git Workflow auditável e ajuda a detectar limpezas parciais antes que a sessão seja esquecida.