# AGENTS

## Missao

Este repositorio deve operar com um pipeline rigido de conhecimento e execucao:

`agenda -> decision -> PR/plan -> spec ou codigo -> learn`

Regra central:

- nao pular etapas;
- nao resolver ambiguidade estrutural no meio da implementacao;
- nao transformar `learn` em deposito cru de historico;
- nao escrever spec ou codigo sem base em `decision` e `PR/plan` quando houver impacto arquitetural.

## Mapa Canonico

- `docs/runtime/agendas/`: discussao, enquadramento do problema, pontos mais importantes, sugestoes e recomendacao.
- `docs/runtime/decisions/`: registro normativo do que foi decidido. Deve estar pronto para propagar em spec ou implementacao.
- `docs/runtime/pull-requests/`: plano executavel de entrega para spec e/ou codigo.
- `docs/runtime/specs/`: contrato tecnico normativo consolidado.
- `docs/runtime/learn/`: consolidacao didatica do que ja foi fechado e executado.
- `crates/`: implementacao em codigo.

## Fluxo Obrigatorio

### 1. Agenda

Use `agenda` quando ainda existe ambiguidade, disputa de abordagem, risco arquitetural, escopo mal fechado ou falta de recomendacao.

Toda agenda deve:

- apresentar o problema real;
- listar os pontos mais importantes da discussao;
- separar fato, risco, tradeoff e hipotese;
- trazer sugestoes objetivas, nao so perguntas soltas;
- terminar com uma recomendacao clara, mesmo que condicional;
- explicitar o que ainda impede a decisao.

Template minimo:

- `Contexto`
- `Problema`
- `Pontos Criticos`
- `Opcoes`
- `Sugestao / Recomendacao`
- `Perguntas em Aberto`
- `Criterio para Encerrar`

Regra de saida:

- agenda concluida deve virar `decision`;
- agenda que ainda nao fecha contrato nao pode virar PR de implementacao.

### 2. Decision

Toda agenda concluida deve se tornar uma `decision`.

Uma `decision` deve conter tudo que a equipe precisa para propagar a decisao em spec ou implementacao, inclusive referencias para specs ja consolidadas quando existirem.

Toda decision deve:

- declarar a decisao tomada sem ambiguidade;
- registrar contexto e drivers;
- listar alternativas descartadas e por que foram descartadas;
- definir invariantes e contrato operacional;
- delimitar impacto em specs, runtime, host, firmware e tooling quando aplicavel;
- apontar referencias normativas existentes;
- deixar claro o que ainda precisa ser implementado ou publicado.

Template minimo:

- `Status`
- `Contexto`
- `Decisao`
- `Rationale`
- `Invariantes / Contrato`
- `Impactos`
- `Referencias`
- `Propagacao Necessaria`

Regra de saida:

- decision fechada deve evoluir para `PR/plan`;
- se a decision nao estiver pronta para orientar execucao, ela ainda nao esta fechada.

### 3. PR / Plan

`PR` e o artefato de planejamento de execucao. Ele nasce de uma ou mais `decisions`.

Toda PR deve:

- citar explicitamente as decisions de origem;
- separar implementacao de spec e implementacao de codigo quando o escopo pedir;
- definir alvo, fora de escopo, riscos e ordem de execucao;
- trazer criterios de aceite verificaveis;
- definir estrategia de testes e evidencias esperadas;
- bloquear reabertura de debate arquitetural dentro da fase de execucao.

Template minimo:

- `Briefing`
- `Decisions de Origem`
- `Alvo`
- `Escopo`
- `Fora de Escopo`
- `Plano de Execucao`
- `Criterios de Aceite`
- `Tests / Validacao`
- `Riscos`

Regra de saida:

- PR de spec alimenta `docs/runtime/specs/`;
- PR de codigo alimenta `crates/`;
- PR concluida deve deixar rastro para consolidacao em `learn`.

### 4. Learn

`learn` recebe conhecimento consolidado de decisions que ja viraram PR e tiveram resultado publicado em spec, codigo ou ambos.

`learn` nao e fonte normativa. `learn` explica, organiza, ensina e melhora a transmissao do modelo mental.

Toda consolidacao em `learn` deve:

- partir de decisions ja fechadas;
- refletir o estado publicado em specs e/ou codigo;
- explicar o "como pensar" e nao so o "o que aconteceu";
- linkar para specs e decisions correspondentes;
- remover redundancia historica quando houver material sobreposto.

Regra de manutencao:

- de tempos em tempos, refatorar `learn` por tema, modelo mental e progressao didatica;
- preferir guias tematicos a acumulo cronologico de decisions aposentadas;
- preservar backlinks para decisions/specs originais.

## Workers Obrigatorios

### Agenda Worker

Use para abrir ou conduzir discussoes.

Responsabilidades:

- sintetizar pontos mais importantes;
- propor sugestoes concretas;
- separar sinal de ruido;
- empurrar para uma recomendacao.

Nao faz:

- fechar contrato normativo cedo demais;
- planejar implementacao detalhada.

### Decision Worker

Use para transformar agenda concluida em decisao clara.

Responsabilidades:

- cristalizar a decisao;
- registrar invariantes;
- preparar a propagacao para spec e implementacao;
- referenciar material normativo ja existente.

Nao faz:

- escrever plano de execucao detalhado;
- deixar ambiguidades estruturais escondidas.

### PR Worker

Use para transformar decisions em execucao.

Responsabilidades:

- decompor o trabalho;
- separar fases editorial e de codigo;
- definir aceite, testes, riscos e sequenciamento.

Nao faz:

- rediscutir arquitetura base;
- improvisar contrato no meio do plano.

### Learn Worker

Use para consolidar conhecimento e refatorar `docs/runtime/learn/`.

Perfil esperado:

- didatico;
- editorial;
- orientado a modelo mental, exemplos e progressao pedagogica.

Responsabilidades:

- consolidar varias decisions em artefatos mais ensinaveis;
- reorganizar material por tema;
- reduzir repeticao e melhorar navegacao.

Nao faz:

- redefinir contrato tecnico;
- competir com specs.

### Spec Worker

Use para implementar specs a partir de decisions e PRs.

Perfil esperado:

- editorial;
- normativo;
- preciso em contrato, escopo e linguagem.

Responsabilidades:

- atualizar ou criar specs coerentes com a decision;
- manter contrato tecnico consistente;
- citar referencias normativas corretas.

Nao faz:

- inventar decisao nova durante edicao;
- introduzir framing pedagogico de `learn` dentro do texto normativo.

### Code Worker

Use para implementar codigo a partir de decisions, specs e PRs.

Perfil esperado:

- executor;
- rigoroso;
- focado em comportamento, testes e aderencia ao contrato.

Responsabilidades:

- implementar o que a spec/decision manda;
- validar impacto e cobertura;
- apontar qualquer conflito entre codigo e contrato.

Nao faz:

- compensar ambiguidade arquitetural com heuristica local;
- esconder mudanca de contrato dentro de refactor.

## Regras de Transicao

- nunca criar PR de implementacao se o assunto ainda e uma agenda em aberto;
- toda agenda encerrada deve resultar em `decision` ou ser explicitamente descartada;
- toda decision relevante deve gerar `PR/plan` antes de alterar spec ou codigo;
- toda decision executada deve deixar consolidacao em `learn`, direta ou agrupada;
- quando `learn` acumular historico demais, ativar o `Learn Worker` para refatoracao didatica.

## Regra Editorial

- `agenda` discute;
- `decision` decide;
- `PR` planeja;
- `spec` normatiza;
- `codigo` implementa;
- `learn` ensina.

Se um artefato comecar a fazer o trabalho do outro, ele esta errado.

## Regra de Idioma

- todo conteudo publicado em `docs/runtime/specs/` deve ser escrito em ingles;
- todo conteudo publicado em `docs/runtime/learn/` deve ser escrito em ingles;
- essa regra vale mesmo quando a discussao, agenda, decision, PR ou conversa com o usuario acontecer em portugues;
- ao editar artefatos existentes em `specs` ou `learn`, corrigir para ingles qualquer trecho residual em outro idioma.