prometeu-runtime/AGENTS.md

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.