tjrtm/the-team-loop

The Team Loop

Use esta skill quando duas equipes ou agentes cooperativos trabalharem em um mesmo repositório. Substitua Equipe A e Equipe B pelos nomes configurados. O Proprietário é um humano e é a autoridade para decisões de prioridade, merge, deploy, congelamento e políticas.

Onboarding: configuração de cinco minutos

1. Copie esta skill para o repositório de destino e instale o adaptador para a ferramenta de agente ativa.
2. Copie templates/team-loop.yml para .team-loop.yml; defina os nomes das equipes e gate_command.
3. Execute scripts/setup-labels.sh --repo OWNER/REPO.
4. Solicite que o Proprietário crie uma issue de coordenação fixada e uma issue rotulada como ready.
5. Cada equipe lê este arquivo, reivindica no máximo um item e usa o cabeçalho de status configurado.

Funções

• Proprietário: cria ou promove trabalho pronto; publica decisões diretas Owner: em suas próprias palavras; autoriza merges e deploys, exceto dentro de um mandato escrito com escopo e horário UTC de término.
• Equipe A / Equipe B: constroem, testam, revisam, reivindicam, transferem e reportam. Usem identidades GitHub separadas quando disponível.
• Revisor (opcional): realiza uma revisão com contexto fresco. Exija-o para caminhos ou categorias de risco configurados.

Estados do ciclo

backlog -> ready -> in-progress -> blocked ou needs-owner -> PR de implementação -> ready-for-owner -> merged -> deployed.

• backlog não é reivindicável. Agrupe trabalho de backlog de baixa severidade semanalmente para promoção pelo proprietário.
• ready autoriza implementação, testes e abertura de um PR. Nunca autoriza merge ou deploy.
• Ao fechar uma issue, remova rótulos de estado obsoletos como in-progress, ready, blocked e needs-owner.

Protocolo de reivindicação

1. Releia os rótulos imediatamente antes de agir. Não reivindique trabalho in-progress, blocked ou não ready.
2. Execute scripts/claim.sh --repo OWNER/REPO --issue N --team "Equipe A" --plan "plano curto".
3. O script adiciona in-progress e um rótulo de equipe, publica a reivindicação e então rechecka o estado. Se perder uma corrida, ele recua.
4. Mantenha o trabalho em progresso igual ou abaixo de wip_limit por equipe. Finalize, transfira ou bloqueie explicitamente um item antes de reivindicar outro.
5. Para team:any, o comentário de reivindicação válido mais antigo vence; a outra equipe recua. Não resolva um empate com implementação duplicada.

Comentários e comunicação

Todo comentário de equipe começa em sua primeira linha com:

Status: <estado> | Equipe: <equipe configurada> | <contexto curto>

Publique apenas uma reivindicação com plano, veredito de revisão, resultado do gate, transferência, pergunta, escalonamento para o proprietário, concordância ou relatório de release. Não publique comentários de iniciado, na fila, ainda aguardando, rearmado ou outros comentários cerimoniais. Mantenha comentários comuns em cinco linhas curtas; coloque evidências na descrição do PR ou em detalhes recolhidos.

Apenas o Proprietário escreve decisões Owner:. As equipes devem linkar ou pedir um comentário direto do proprietário, nunca repassar um como autoridade.

Rótulos e roteamento

Use os rótulos em reference/labels.md. Uma issue pronta não atribuída por padrão vai para a Equipe A, a menos que a configuração diga o contrário. team:any permite que qualquer equipe reivindique. Enquanto ocioso, ajude a outra equipe nesta ordem: revisões solicitadas, preparação ou rebase de trem, depois lotes semanais de backlog. Não realize uma varredura de bugs sem limite sem uma solicitação do Proprietário.

Revisão, trem, gate, certificado

1. Cada PR executa verificações leves e focadas e recebe o nível de revisão exigido por seu risco.

2. Um revisor rotula PRs completos como ready-for-owner.

3. O executor do trem reúne os PRs revisados disponíveis naquele momento. Ele executa:

   scripts/train.sh --repo OWNER/REPO --name train-YYYYMMDD-N PR_NUMBER...
   

4. train.sh adiciona train-running a cada PR incluído, registra a base e as heads, realiza uma triagem de conflitos, constrói um resultado de merge temporário e invoca gate.sh uma vez.

5. gate.sh chaveia o certificado para git rev-parse HEAD^{tree}. Um certificado existente correspondente é evidência de sucesso, a menos que --force seja usado.

6. Se a base ou uma head do PR mudar, ou se a triagem/gate falhar, o trem é inválido. Remova ou divida os PRs problemáticos e reconstrua o trem. Não mescle trabalho não relacionado enquanto train-running segura o trem.

7. Após aprovação direta do proprietário ou um mandato ativo, execute train.sh novamente com --merge --owner-authorization "Owner: ..." para mesclar as heads dos PRs registrados em ordem. Ele recusa se a base ou uma head mudou e verifica a árvore da branch protegida após cada merge.

Deploy, congelamento, retenção e pausa

• Faça deploy apenas da branch protegida configurada e apenas com um certificado de árvore correspondente, a menos que o Proprietário forneça uma exceção registrada.
• Produza um relatório de deploy para o release. Rotule PRs e issues enviados como deployed; vincule-os ao relatório único em vez de duplicá-lo.
• freeze interrompe novos merges e deploys. Trate leituras de rótulo com falha como congeladas para ações irreversíveis.
• Uma retenção de trem bloqueia merges fora desse trem até que o trem saia.
• Em pausa, pare reivindicações, trens, merges e deploys. O Proprietário publica uma lista de reinício que nomeia os itens permitidos para retomar. Reconfira rótulos, heads de PR, base e certificados antes de reiniciar.

Escalonamento e mandatos

Use needs-owner quando uma decisão de produto, segurança, jurídico, release ou propriedade ambígua bloquear o trabalho. Declare o comportamento observado, opções, recomendação e prazo, se houver. Continue trabalho independente.

Um mandato deve declarar seu escopo exato e expiração UTC, por exemplo:

Owner: A Equipe A pode mesclar e implantar os PRs de documentação revisados 41 e 42 até 2026-05-01T18:00:00Z.

Qualquer coisa fora desse escopo ou após o vencimento requer uma decisão direta nova.

Retrospectiva

Pelo menos semanalmente, execute scripts/scorecard.sh e discuta as definições em reference/metrics.md. Melhore um gargalo mensurável de cada vez. Revise execuções de gate por PR mesclado, latência de reivindicação, tempo de ciclo, variação líquida da fila, tamanho médio de lote, parcela certificada e taxa de falha de mudança.

Leia reference/rules.md para as regras normativas numeradas e reference/comment-templates.md antes de postar status.