Instale. Leia o estado. Comece do ponto certo.

Invocar um agente diretamente

/docod:run <agent> <action>

Quando você já sabe qual responsabilidade precisa ser exercida, chame o dono dela. O primeiro argumento é o agente; o segundo é o verbo que ele sabe executar.

Um exemplo aterrado:

/docod:run prd create_prd

Aciona o agente dono do PRD para criar o documento. O nome da action pertence à referência viva do runtime e pode evoluir; a responsabilidade por trás dela, não.

Uma tarefa. Um mandato.

/docod:loop <task>

Build → Verify → QA → Fix → Re-QA → Code review

Coordena uma única tarefa através do fluxo de construção e confirmação. Pode corrigir bugs encontrados dentro daquele mandato e, por padrão, segue até o code review.

O loop devolve controle quando:

E há coisas que ele deliberadamente nunca faz:

não aprova, não faz deploy, não faz release, não executa um lote inteiro de tarefas, e não transforma insistência em evidência.

Retomar e fechar uma frente

Um projeto com várias frentes precisa de duas coisas que o estado sozinho não dá: voltar para uma delas e encerrar a que morreu.

/docod:continue <ws>

Retoma UMA frente: o estado dela e o próximo passo. Responde onde você parou e qual é o movimento seguinte.

/docod:ws list | done | abandon --reason <razão>

O ciclo de vida da frente: listar as que existem, registrar, encerrar e abandonar.

A razão é obrigatória ao abandonar, e isso não é burocracia: uma frente que some sem motivo registrado volta como pergunta seis meses depois.

Aprovação pertence a uma versão.

/docod:approve <file> --by <who>

Ao aprovar, o runtime sela aquela decisão contra o corpo do artefato: quem aprovou, quando, e o hash do conteúdo.

Edição → hash diferente → aprovação inválida.

Nenhum serviço precisa processar um evento para lembrar disso. A próxima derivação encontra a inconsistência.

Revalidando mudanças deliberadas

Quando as alterações são intencionais e vários artefatos precisam ser revalidados, o runtime tem o caminho de revalidação. Ele exige identidade, razão e escopo quando necessário, e mostra o plano antes de aplicar.

E se a origem de alguma relação for ambígua, ele para e diz que não consegue resolver. O runtime não escolhe uma interpretação apenas para conseguir continuar.

Verify

node .docod/docod.mjs verify <file>

O estado declarado por este artefato ainda é sustentado pelo que existe agora?

Ele pode falhar quando encontra, entre outras coisas:

E produz avisos para situações que merecem atenção sem necessariamente bloquear: hash em campo que não contém hash válido, hashes perdidos em prosa, âncoras frágeis, ADRs usados mas não declarados, cobertura incompleta no índice de tarefas e atribuições inconsistentes.

O objetivo não é produzir um check verde. É fazer o verde significar algo.

Status não mente.

/docod:status

Lê o estado derivado e mostra:

Ele não mantém esse estado. Ele o calcula.

Report é outra visão da mesma verdade.

/docod:report

Produz um HTML estático, self-contained e offline. Sem servidor, sem CDN, sem tracking. Ele organiza artefatos, status declarado e efetivo, aprovações inválidas, relações vencidas, tarefas em cada estado, ações possíveis e bloqueadas, workstreams e o fluxo do projeto.

O report não é outro painel que precisa ficar sincronizado. Ele é uma projeção do mesmo estado derivado dos arquivos.

Pergunte ao projeto, não à memória do chat.

/docod:lead

O tech lead é o counsel residente do runtime. Ele lê o que o projeto realmente contém: decisões, documentos, código, workstreams, estado das tarefas, resultados de QA, inputs vencidos e perguntas abertas. Então devolve alternativas, custos, evidência relevante, recomendação e impacto.

Quando o conselho muda a direção do projeto, ele deixa uma entrada append-only no registro de counsel.

Mas a decisão continua humana. O tech lead não aprova, não invoca outros agentes por conta própria e não edita artefatos que pertencem a outro dono.

Você pode diagnosticar antes de adotar.

/docod:diagnose

Um sistema legado não precisa ser convertido inteiro antes que o runtime consiga ajudar. O modo diagnóstico faz um pre-read sem compromisso de adoção: observa o repositório e reconstrói apenas os artefatos aplicáveis.

Cada afirmação recebe proveniência:

evidence

observado diretamente, com referência à fonte

inferred

deduzido a partir do que foi encontrado

user-supplied

informação fornecida por alguém de fora do código

O diagnóstico também registra divergências entre uma afirmação e a realidade observada, riscos relevantes que a documentação não menciona, e questões que o repositório não consegue responder e precisam de um dono externo.

E nada disso vira aprovação: não cria pins, não cria gates, não congela baseline e não exige adoção.

Pre-read, not pre-approved.