Há uma coisa que vem me incomodando em boa parte do trabalho com code agents: cada ferramenta inventa seu próprio jeito de entender um projeto. Uma lê um arquivo de instruções na raiz, outra espera convenções implícitas, outra simplesmente carrega tudo para o contexto e torce. Individualmente parece um detalhe. Quando o projeto cresce — mais módulos, decisões antigas, direções que mudaram — esse detalhe começa a definir a qualidade de tudo que o agente produz.

Foi daí que nasceu o Prumo. Não como “mais uma CLI”, mas como uma pergunta: e se o repositório fosse a fonte durável de verdade, legível tanto por humanos quanto por agentes, sem depender da ferramenta da vez?

O que eu estava tentando resolver

Quero que qualquer agente consiga entrar em um projeto e responder rápido: qual é o objetivo atual, quais decisões não podem ser quebradas, o que já foi validado e por quais evidências. Hoje esse contexto vive espalhado — um pouco na cabeça das pessoas, um pouco em docs soltos, um pouco em histórico de chat que ninguém mais encontra.

Onde a solução óbvia começa a falhar

O caminho mais óbvio seria escrever um AGENTS.md cada vez maior. Funciona até certo ponto, mas tem um teto baixo: quanto mais coisa entra no arquivo, menos o agente sabe o que importa para aquela tarefa específica. Podemos ter pastas inteiras de ADRs, specs e roadmaps e continuar com o mesmo problema, porque falta dizer qual documento tem autoridade sobre qual parte.

A ideia, então, não é ter mais documentação. É ter documentação com estrutura: metas, decisões, contratos, tarefas e evidências relacionados entre si, versionados em Git, validados por schema.

O que o Prumo propõe

Em termos simples: estado canônico do projeto em Markdown, JSON e JSON Schema dentro do próprio repo — e todo o resto (caches, índices, adapters por ferramenta) como derivado. Metas têm ciclo de vida com integridade verificável, planos são validados como DAG, e adapters traduzem esse estado para cada harness: Claude Code, Codex, OpenCode, Gemini e por aí vai.

O que me leva a preferir esse desenho é a reversibilidade. Se amanhã surgir um agente novo, ninguém reescreve o projeto: escreve-se um adapter. O conteúdo continua pertencendo aos lugares certos; o protocolo só mantém as relações.

O que ainda me preocupa

Duas lacunas honestas. Primeiro, protocolo sem adoção é só especificação bonita — o Prumo precisa provar valor no uso diário, não no diagrama. Segundo, existe o risco de o sistema virar uma plataforma que tenta controlar detalhe demais. Eu não quero isso: a função dele é manter relações, autoridade e proveniência, não ditar como cada ferramenta trabalha.

Estado atual

Hoje o Prumo é um binário único em Go, sem dependência externa de runtime, com testes de conformidade comparando comportamento com baselines. Eu colocaria essa parte em 7/10: a base está boa, mas ainda faltam validação em projetos grandes reais e mais adapters no dia a dia.

O próximo passo que pode confirmar ou derrubar essas escolhas é usar o protocolo em projetos de verdade por algumas semanas e medir: menos retrabalho dos agentes? Menos decisão quebrada? Se sim, temos infraestrutura. Se não, temos lição. Ambos valem. Código e docs no repositório.