documentação — protocolo de handover

Como qualquer agente retoma de onde outro parou

Não existe sandbox — todo agente já lê a máquina inteira. O que faltava era um lugar combinado e uma convenção. É isso que esses arquivos resolvem.

É praticado hoje, ou é aspiracional?

As duas coisas. É a convenção real desde julho/2026, presente em ~11 dos ~14 repos ativos do portfólio. Mas não é 100% consistente ainda — achados reais ao auditar em 2026-08-08:

mktscout2 (onde um trabalho real de produto aconteceu) nunca teve o protocolo — foi arquivado.
G_BMAD1 (Salesforce) está fora até hoje.
Um agente da fleet, testado ao vivo, reportou sucesso sem ter seguido o protocolo de verdade (nunca leu os arquivos de referência, inventou conteúdo).

Por isso, desde 2026-08-08, dois repos (market-scout-claude, meu-brasil) têm um gate técnico, não só convenção: um hook pre-push que bloqueia o push se HANDOFF.md/context.json não foram atualizados nos commits enviados. Rollout pros demais repos ainda em andamento.

Os arquivos, um por um

.agent-context/HANDOFF.md

dentro de cada repo

O primeiro arquivo que qualquer agente lê antes de fazer qualquer coisa. Estado atual, próximo passo, quem mexeu por último, perguntas em aberto. Formato humano, não estruturado.

.agent-context/context.json

dentro de cada repo

A versão estruturada do mesmo estado — {project, title, stage, status, active_agent, updated, next_step, links}. É o que alimenta os dashboards (o interno da fleet e, agora, este portfólio público).

.agent-context/DECISIONS.md

dentro de cada repo

Decisões duráveis e o porquê — memória de longo prazo que sobrevive a qualquer sessão específica.

AGENTS.md

raiz de cada repo

O ponteiro de entrada: "leia .agent-context/HANDOFF.md primeiro" e "atualize os dois ao terminar." Toda ferramenta que suporta o padrão AGENTS.md (Claude Code, Antigravity, Cursor, Windsurf) encontra isso sozinha.

INFRA.md

repo vps-infra, não por projeto

Mapa de TODOS os domínios/portas/donos ativos na VPS — não é por projeto porque a informação que protege é justamente cruzar produtos ("esse nome já existe?"). Existe pra nunca mais repetir o incidente de 2026-07-20, quando um site novo derrubou 3 outros por descuido. Até 2026-08-08 só existia em disco na própria VPS — agora versionado.

.dag/

dentro de cada repo, só quem participa do loop

Não é handover — é um sistema separado (ver dag1). Guarda o estado do loop de direção de produto (oportunidades, decisões de go/no-go), não o "onde parei" de uma sessão qualquer. Os dois convivem no mesmo repo com propósitos diferentes.

O fluxo completo

Agente novo abre o repo → lê AGENTS.md → lê .agent-context/HANDOFF.md.
Se for mexer em infra da VPS, lê INFRA.md primeiro, sempre.
Trabalha.
Antes de terminar: atualiza HANDOFF.md + context.json.
git push — em repos com o gate instalado, o push é bloqueado se esse passo foi pulado.
Próximo agente (Claude Code, OpenClaw, você mesmo semanas depois) repete o passo 1.