netheremp/baton-pass-netheremp

Baton Pass

Propósito: preservar a continuidade entre múltiplos agentes com a menor quantidade de texto necessária.

Esta é uma utilidade de workflow de baixo consumo de tokens, não uma cerimônia de documentação.

Configuração Rápida

Instalar em cada agente (uma vez por máquina)

npx github:netheremp/baton-pass-netheremp install

Instala esta habilidade em ~/.claude e em todo diretório ~/.codex*. Então:

• Claude Code (CLI + IDE) — a habilidade carrega automaticamente; /new-game /save-state /baton-pass /foresight /dragon-dance /party-check /hindsight
• Codex CLI — a habilidade carrega automaticamente; execute explicitamente com $baton-pass
• Codex desktop — a habilidade carrega automaticamente; /prompts:baton-pass no compositor

Alternativas: /plugin marketplace add netheremp/baton-pass-netheremp (Claude Code) ou /plugins → instalar (Codex).

Inicializar um repositório para trabalho multi-agente

npx github:netheremp/baton-pass-netheremp init

Adicione --track-state para enviar o estado da transferência ao git (equipes que precisam de histórico compartilhado). O padrão é apenas local (ignorado pelo git).

Isso cria:

• baton-pass.config.json — onde o workflow encontra seus arquivos de memória
• baton-pass.state.json — estado leve e compartilhado de posse
• docs/agent-handoff.md — regras específicas do repositório para todos os agentes
• docs/current-state.md — o que está acontecendo agora
• docs/next-task.md — quem é o dono do trabalho e o que vem a seguir
• docs/progress.md — registro de sessão contínuo (apenas adição)

init também coloca os comandos /move nos comandos do .claude/commands/ do repositório.

O Conjunto de Movimentos

• new-game = inicializar o workflow em um repositório novo
• save-state = pausar com segurança sem transferir
• baton-pass = transferir trabalho quando os tokens estão baixos ou a posse muda
• foresight = receber ou retomar trabalho, verificar alinhamento e continuar
• dragon-dance = melhorar o workflow apenas quando uma lição real foi aprendida
• party-check = inspecionar quem agiu por último, quem deve agir a seguir e o estado atual do repositório
• hindsight = auditar toda a cadeia de transferência — marcos reivindicados, verificações feitas, riscos carregados, itens nunca resolvidos

Regra Central

Prefira delta, não resumo.

Não reescreva o histórico estável do projeto, a menos que o receptor não possa continuar com segurança sem ele.

Quando Usar Cada Movimento

new-game

Use uma vez no início do repositório, ou ao introduzir este workflow em um repositório que ainda não possui arquivos de memória compartilhada.

save-state

Use quando:

• você precisa parar abruptamente
• você está pausando o trabalho para depois
• a posse ainda não está mudando

save-state é um ponto de verificação local, não uma transferência.

baton-pass

Use quando:

• os tokens estão baixos
• outro agente está assumindo
• você precisa de um pacote de continuidade transferível

baton-pass é um ponto de verificação de transferência.

foresight

Use quando:

• estiver recebendo um bastão
• retornando após um save-state
• houver qualquer dúvida de que o estado escrito ainda corresponde ao repositório

dragon-dance

Use apenas quando:

• o workflow em si aprendeu algo
• o receptor encontrou desvio
• o bastão omitiu algo importante
• uma nova regra evitaria claramente desperdício repetido

Não acione dragon-dance por reflexo. Não o inclua em toda sessão ou baton-pass por padrão.

party-check

Use quando:

• você esqueceu de quem é a vez
• múltiplos agentes compartilham o repositório
• você deseja o status atual sem pagar por um foresight completo

party-check é o movimento dentro da sessão. De um terminal simples (sem agente, sem tokens) execute baton-pass status — ele imprime a mesma informação de posse mais a cadeia recente de transferências, e baton-pass status --json fornece saída legível por máquina para scripts e hooks.

hindsight

Use quando:

• um marco ou funcionalidade importante está concluído e você deseja um registro limpo
• algo parece errado e você precisa rastrear o que foi realmente reivindicado versus feito
• um novo agente está entrando e precisa de uma visão completa do histórico, não apenas do último bastão
• um foresight encontrou desvio severo e você precisa entender até onde ele começou
• o projeto está sendo revisado, entregue a um humano ou arquivado

Não execute hindsight após cada transferência. É uma auditoria, não um ponto de verificação de rotina.

O Que Cada Movimento Deve Escrever

save-state

Saída mínima:

• tarefa atual
• parou em
• arquivos tocados
• próxima ação imediata
• bloqueador ou risco

baton-pass

Saída mínima:

• objetivo
• feito
• tarefas (se usando um plano de tarefas — liste cada tarefa com status: concluída / em andamento / pendente)
• arquivos
• árvore de trabalho (nome do branch e caminho da árvore de trabalho, se usando git worktrees)
• verificado
• desvios (decisões tomadas durante a sessão que diferem do plano original)
• ambiente (pré-requisitos que o próximo agente deve confirmar: serviços em execução, variáveis .env definidas, bancos de dados de teste, etc.)
• próximo
• riscos
• próximo agente

Disciplina de commit:

• Faça commit antes de transferir, ou documente por que não.
• Nunca transfira uma árvore de trabalho suja sem nomear explicitamente o estado não comitado.
• Se a verificação não foi executada, diga isso — não insinue que foi aprovada.

Por que tarefas, árvore de trabalho, desvios e ambiente são importantes: A memória da sessão é perdida na transferência. Se você está no meio de um plano de 20 tarefas, o próximo agente não consegue reconstruir quais tarefas estão concluídas apenas a partir do log do git — escreva o status explicitamente. Se você está trabalhando dentro de uma árvore de trabalho, o próximo agente precisa do caminho exato. Se você corrigiu algo de forma diferente do que o plano dizia, anote — o próximo agente relerá o plano e refará do jeito errado. Se o ambiente precisa estar em um estado específico (banco de dados rodando, .env preenchido), nomeie — um agente novo encontrará o mesmo bloqueador sem isso.

foresight

Saída mínima:

• alinhado ou não
• se não alinhado, o que estava desatualizado ou faltando
• próximo passo corrigido apenas se necessário

Se o desvio for severo (o bastão reivindica trabalho feito, mas o repositório mostra o contrário), escreva um relatório de desvio estruturado antes de continuar:

• o que foi reivindicado
• o que o repositório realmente mostra
• o que deve ser refeito
• se este desvio justifica um dragon-dance

dragon-dance

Saída mínima:

• problema
• impacto
• melhoria
• nova convenção

party-check

Saída mínima:

• estado
• último movimento
• último agente
• próximo agente
• atualizado em
• resumo curto

hindsight

Saída mínima:

• escopo da auditoria (cadeia completa ou intervalo limitado)
• tabela da cadeia de transferência (de → para, data, resumo do objetivo)
• marcos reivindicados por agente com status de verificação
• lacunas de verificação (reivindicações feitas sem evidência)
• riscos transportados através de transferências
• desvios encontrados através de transferências
• itens abertos nunca resolvidos
• veredito da auditoria: limpo, lacunas encontradas, riscos não resolvidos ou ação necessária

Fontes a verificar:

• docs/progress.md — registro completo da sessão
• docs/next-task.md — histórico do estado da vez
• baton-pass.state.json — estado programático
• git log — mensagens e datas de commit
• quaisquer arquivos salvos de bastão ou save-state referenciados no progresso

Procedimento de Recebimento Para foresight

Verifique apenas o mínimo necessário para evitar erros:

• objetivo atual do usuário
• estado da árvore de trabalho
• último(s) commit(s)
• current-state
• next-task
• entrada mais recente do progress
• arquivos nomeados no estado salvo ou no bastão
• status da lista de tarefas se um plano estava em andamento

Então decida:

• se alinhado, continue
• se desalinhado, corrija o bastão e continue
• se o desalinhamento revela uma lição reutilizável, execute dragon-dance

Descoberta de Habilidades Entre Agentes

Quando habilidades são instaladas localmente no projeto (em .claude/commands/ ou via instalação de plugin no repositório), o Codex e outros agentes que pegarem o repositório encontrarão as mesmas definições de habilidades. Os arquivos de habilidade viajam com o repositório.

O que NÃO atravessa um limite de sessão:

• Estado de tarefas de gerenciadores de tarefas em memória (listas TaskCreate são perdidas quando a sessão termina)
• Estado de execução de subagentes (quais loops de revisão foram concluídos, quais agentes executaram)
• Estado do ambiente (quais serviços estão rodando, quais variáveis .env estão definidas)

O bastão deve escrever tudo isso explicitamente. As habilidades dizem aos agentes como trabalhar; o bastão diz a eles onde as coisas estão.

Modelo de Estado

Use o arquivo de estado compartilhado para rastrear:

• estado atual
• último movimento
• último agente
• próximo agente
• hora da atualização
• resumo

Estados recomendados:

• active (ativo)
• paused (pausado)
• handed-off (transferido)
• claimed (reivindicado)
• blocked (bloqueado)

Vocabulário de Verificação

Use uma linguagem consistente para que os receptores saibam exatamente o que foi verificado.

• passed (aprovado) — executado localmente, saída confirmada limpa
• passed outside sandbox (aprovado fora do sandbox) — executado localmente, mas não no ambiente CI/build
• not run — [reason] (não executado — [motivo]) — pulado, declare o motivo
• expected to pass, unverified (esperado passar, não verificado) — não executado, mas acredita-se correto

Nunca escreva passed quando você quer dizer expected to pass, unverified. Essa única ambiguidade causa a maior parte do retrabalho de transferência.

Estado da Vez

O bloco Turn State em next-task é o principal sinal de posse legível por humanos. baton-pass.state.json o espelha para uso programático.

Ao atualizar um, atualize ambos. Se eles discordarem, next-task vence.

Valores de state recomendados em ambos:

• active (ativo) — alguém está trabalhando agora
• paused (pausado) — parou com segurança, o mesmo agente retomará
• handed-off (transferido) — transferido, aguardando o receptor reivindicar
• claimed (reivindicado) — o receptor executou foresight e está continuando
• blocked (bloqueado) — não pode prosseguir, o motivo deve estar em next-task

Antipadrões

Evite:

• usar baton-pass para cada pequeno ponto de verificação
• usar dragon-dance quando nada foi aprendido
• reescrever todos os arquivos de memória para trabalho trivial
• transformar foresight em uma auditoria completa do repositório toda vez
• executar hindsight após cada transferência — é uma auditoria, não uma etapa de rotina
• reescrever todo o projeto em vez do delta
• escrever passed quando você quer dizer expected to pass, unverified
• transferir com uma árvore de trabalho suja sem nomear o estado não comitado
• omitir o status da tarefa quando no meio de um plano numerado
• omitir o caminho da árvore de trabalho quando o trabalho está dentro de um git worktree
• omitir pré-requisitos de ambiente que um agente novo não saberia

Fluxo Prático Ideal

Pausar:

• save-state
• depois foresight

Transferir:

• baton-pass
• o receptor executa foresight

Melhorar:

• dragon-dance apenas se foresight expôs um problema significativo no workflow

Verificar posse da vez:

• party-check

Auditar a cadeia completa:

• hindsight
• se lacunas ou riscos não resolvidos forem encontrados, execute dragon-dance