Tarefa ou ADR

Duas peças, duas perguntas. A ADR responde “o que se decidiu e o que se fez no código, e por quê” — é o contexto do repositório e a execução viva, escrita para o agente ver o projeto. A tarefa do Gestor responde “o que eu tenho para fazer, e para quando” — é o controle do dono, e também do agente.

“As tarefas são o controle do que (de forma mais simplória) fazer; as ADRs são a execução viva. Tudo que mexe no código precisa de ADR. Tudo que é útil no contexto do repositório é ADR; tudo que é útil para me organizar e não me perder fica no Gestor.” — Joseph Trupel, 2026-10-08

A regra

• Mexe no código do repositório → ADR. Código, testes, configuração, migration, contrato (API, MCP, formato de arquivo), dependência, infraestrutura descrita no repositório, runbook em .specs/stack/, o próprio Manifesto. Do módulo inteiro ao bugfix de uma linha.
• Não mexe no código → não é ADR. Um deploy, um roadmap, a organização das próximas semanas, uma pergunta, um backup, o acompanhamento de um cliente. Isso é uma tarefa no Gestor — se valer registrar.
• Estudo: vira ADR só quando é complexo e vai ser reaproveitado no contexto do repositório (como um estudo que decide o desenho de várias ADRs seguintes). O estudo rápido fica na conversa ou numa tarefa.
• A tarefa é opcional. Nem toda sessão nasce de uma tarefa: o trabalho simples segue sem ela, e ela pode ser criada depois, ou nunca. O Gestor é para gerir, não para documentar.

Os casos comuns

Trabalho	É…	Observação
Funcionalidade nova, mudança de tela, regra de negócio	ADR	Com tarefa vinculada quando a pessoa a acompanha no Gestor
Bugfix, ajuste, “mudar a cor do botão”	ADR	Mexe no código. A tarefa pode ser só uma linha no Gestor; a ADR tem a análise
Um lote de correções	ADR (uma)	Os passos do 004 são as correções; cada uma pode citar a sua tarefa
Fazer um deploy	Tarefa	Mudar como se faz o deploy (o runbook, o script) é ADR
Roadmap, backlog, “fase 2”	Tarefa	Tarefa-mãe com subitens, ou um ciclo; cada item que mexer no código vira a sua ADR na hora
Auditoria do código	Tarefa com o relatório anexo	O que a auditoria mandar mudar no código é ADR; ela própria é ADR só quando vale como estudo reaproveitável
Estudo complexo que outras ADRs vão seguir	ADR	O 003 vira o estudo; as ADRs de execução o citam
Pergunta do cliente, conversa, organização	Tarefa (ou nada)	Responde-se no Gestor

A orquestração autônoma

A pessoa não precisa dizer “abre a tarefa tal” ou “abre a ADR tal”. A IA conhece a regra e orquestra sozinha — quando a pessoa não quer orquestrar, ela não orquestra. O bloco abaixo é a regra que a IA segue, numa fonte só: o Gestor o lê deste arquivo e o leva às instruções do MCP, à resposta de “começar um trabalho” e ao texto do Executar, e um teste confere que os três dizem o mesmo.

• Você orquestra sozinho. Não espere a pessoa dizer “abre a tarefa X” ou “abre a ADR Y”: decida pela regra, siga e diga no fim o que decidiu.
• ADR ou só tarefa? Mexe no código do repositório (código, testes, configuração, migration, contrato, dependência, runbook, o Manifesto) → ADR, do módulo ao bugfix de uma linha. Não mexe no código (deploy, roadmap, organização, pergunta) → não é ADR: no máximo uma tarefa no Gestor. Estudo vira ADR só quando é complexo e vai ser reaproveitado no repositório.
• Ache antes de criar. Se há uma tarefa, leia as ADRs vinculadas a ela: a que ela implementa e ainda não está Concluída é a deste trabalho. Sem isso, procure no índice (.specs/readme.md) uma ADR aberta do mesmo assunto. Só então crie uma nova: o número reservado pelo Gestor (sem o Gestor, o maior número + 1), os seis arquivos do esqueleto do Manifesto, e confira o formato antes do commit.
• Vincule. Com uma tarefa, vincule a ADR a ela: “implementa” quando a tarefa executa a ADR, “contexto” quando só a lê. Viu uma ADR citada na tarefa? Vincule também. Tarefa é opcional: não crie tarefa só para documentar.
• Ande a tarefa. Ao começar, mova a tarefa para Em andamento. Ao fechar a ADR (005, 006 e o 001 Concluído), mova para Revisão com um comentário interno: a ADR, os commits e o que ficou de fora. Concluído é do dono: mova só quando ele pedir.
• Mantenha o 004 vivo. Cada passo com a situação (todo, doing, done, blocked) enquanto trabalha; o passo que também é uma tarefa leva o identificador ao lado (KBP-12). Decisões e desvios do plano vão para o 004.
• Commits citam. No rodapé da mensagem, uma linha por referência: Tarefa: KBP-12 e ADR: 143.
• Sem o Gestor, nada para. A ADR segue no repositório, o número é o maior + 1 e as tarefas ficam para quando ele voltar.

O formato do bloco

O bloco é um contrato com o Gestor. Ele vale entre as marcas <!-- manifesto:regra:inicio --> e <!-- manifesto:regra:fim -->, cada uma numa linha sozinha, que existem uma vez só em todo o Manifesto, e só neste arquivo (a citação delas dentro de um trecho de código, como aqui, não conta). Dentro delas: Markdown simples (itens de lista e parágrafos), sem títulos nem links (o texto é colado em outros lugares, onde um link relativo não leva a nada) e com até 3.000 caracteres. O pnpm manifesto:check confere tudo isso. Mudar o bloco é mudar o Manifesto: uma ADR, uma versão.

O bloco fala de ações (“reserve o número”, “vincule”, “mova para Revisão”), não de nomes de ferramentas: o Gestor diz, nas instruções do MCP, qual ferramenta faz cada ação (ver Gestor). Assim o método sobrevive a uma ferramenta trocada.