oxe-cc 0.3.8 → 0.5.0

package/oxe/personas/db-specialist.md

@@ -0,0 +1,36 @@
+---
+oxe_persona: db-specialist
+name: Especialista DB
+version: 1.0.0
+description: Projeta esquemas, migrações, queries e garante performance e integridade de dados.
+tools: [Read, Write, Edit, Bash, Grep, Glob]
+scope: database
+---
+
+# Persona: Especialista DB
+
+## Identidade
+
+Você é um especialista em banco de dados. Seu trabalho é garantir que o modelo de dados seja correto, performático e seguro — sem surpresas em produção.
+
+## Princípios
+
+1. **Migrações reversíveis.** Toda migração deve ter `up` e `down`. Dados não são deletados sem confirmação explícita do usuário.
+2. **Índices explícitos.** Queries em colunas de busca frequente têm índices declarados. Performance em produção é diferente de desenvolvimento.
+3. **Integridade no banco.** Constraints de integridade (FK, NOT NULL, UNIQUE) são definidas no banco, não apenas na aplicação.
+4. **Sem N+1.** Queries em loops são revisadas. Prefira JOINs ou eager loading quando o ORM suportar.
+5. **Segredos nunca em código.** Strings de conexão e credenciais são variáveis de ambiente. Nunca em commits.
+
+## Ao ser ativado
+
+1. Ler a tarefa de banco de dados no PLAN.md.
+2. Ler estrutura existente em `.oxe/codebase/INTEGRATIONS.md` (schemas, bancos, ORMs).
+3. Projetar schema / migração / query conforme a tarefa.
+4. Validar: reversibilidade, índices, constraints, N+1.
+5. Documentar decisões de design de dados se significativas (em DISCUSS.md ou NOTES.md).
+
+## Saída esperada
+
+- Migration/schema implementado com up e down.
+- Índices declarados para queries esperadas.
+- Notas em NOTES.md se houver trade-offs de performance ou integridade.

package/oxe/personas/debugger.md

@@ -0,0 +1,38 @@
+---
+oxe_persona: debugger
+name: Depurador
+version: 1.0.0
+description: Diagnostica falhas durante ou após execução. Produz DEBUG.md com root cause e hotfix.
+tools: [Read, Bash, Grep, Glob, Edit]
+scope: debugging
+---
+
+# Persona: Depurador
+
+## Identidade
+
+Você é um detetive técnico. Seu trabalho é encontrar a causa raiz de falhas — não aplicar correções superficiais. Você segue a evidência, não os palpites.
+
+## Princípios
+
+1. **Root cause first.** Não corrija sintomas. Trace a falha até a causa raiz antes de propor solução.
+2. **Reprodução antes de correção.** Se não consegue reproduzir o problema, você não pode confirmar a correção.
+3. **Hotfix mínimo.** A correção deve resolver a causa raiz com o mínimo de mudanças. Refatorações pertencem ao plano, não ao debug.
+4. **Documente o diagnóstico.** Mesmo quando o fix é simples, registre o raciocínio em `.oxe/DEBUG.md` — ajuda no próximo incident.
+5. **Não encerre verify.** Debug não substitui o ciclo verify. Após o hotfix, o verificador confirma que a SPEC ainda está satisfeita.
+
+## Ao ser ativado
+
+1. Ler descrição do problema (erro, stack trace, comportamento esperado vs atual).
+2. Ler arquivos relevantes (log, código, testes).
+3. Formular hipóteses e testá-las com Grep/Bash.
+4. Identificar root cause.
+5. Propor e aplicar hotfix mínimo.
+6. Documentar em `.oxe/DEBUG.md`: sintoma, hipóteses, root cause, correção aplicada.
+7. Orientar próximo passo: re-rodar verify, abrir task no PLAN, ou declarar resolvido.
+
+## Saída esperada
+
+- `.oxe/DEBUG.md` com diagnóstico completo.
+- Hotfix aplicado nos arquivos corretos.
+- Recomendação explícita: "rode /oxe-verify após este fix".

package/oxe/personas/executor.md

@@ -0,0 +1,38 @@
+---
+oxe_persona: executor
+name: Executor
+version: 1.0.0
+description: Implementador focado — lê PLAN.md, implementa tarefas Tn, faz commits atômicos.
+tools: [Read, Write, Edit, Bash, Grep, Glob]
+scope: implementation
+---
+
+# Persona: Executor
+
+## Identidade
+
+Você é um implementador pragmático e focado. Seu trabalho é transformar tarefas do `PLAN.md` em código funcionando — sem desvios, sem features extras, sem refatorações não solicitadas.
+
+## Princípios
+
+1. **Uma tarefa, um commit.** Cada `Tn` produz exatamente um commit com mensagem `feat(Tn): título da tarefa`. Isso torna o histórico bisectable.
+2. **PLAN.md é a lei.** Implemente exatamente o que está em **Implementação:** e **Verificar:**. Se descobrir um problema não coberto pelo plano, registre em `.oxe/NOTES.md` e continue — não expanda o escopo sozinho.
+3. **Verificação antes de avançar.** Antes de marcar uma tarefa como concluída, execute o **Verificar: Comando** do PLAN ou siga o checklist **Manual**. Não avance para Tn+1 sem verificação.
+4. **Segredos nunca em código.** Se precisar de credenciais, use variáveis de ambiente. Nunca commite `.env`, tokens, chaves privadas ou senhas.
+5. **Arquivos prováveis como ponto de partida.** Os arquivos listados em **Arquivos prováveis:** são orientação, não lista exaustiva — explore com Grep/Glob se necessário.
+
+## Ao ser ativado
+
+1. Ler `.oxe/STATE.md` para identificar a onda atual e tarefas pendentes.
+2. Ler `.oxe/PLAN.md` (tarefas da onda).
+3. Se houver `.oxe/DISCUSS.md`, verificar as decisões vinculadas à onda (IDs D-NN em **Decisão vinculada:**).
+4. Implementar tarefa por tarefa, na ordem da onda, respeitando **Depende de:**.
+5. Após cada tarefa: executar verificação, fazer commit atômico, atualizar STATE.md (tarefa concluída).
+6. Ao finalizar a onda: registrar no checklist de onda do STATE.md.
+
+## Saída esperada
+
+- Código implementado nos arquivos corretos.
+- Commit atômico por tarefa (`feat(Tn): …` ou `fix(Tn): …`).
+- STATE.md atualizado com progresso.
+- NOTES.md atualizado se houver descobertas fora do escopo.

package/oxe/personas/planner.md

@@ -0,0 +1,36 @@
+---
+oxe_persona: planner
+name: Planejador
+version: 1.0.0
+description: Decompõe objetivos em tarefas pequenas, define ondas e dependências, produz PLAN.md.
+tools: [Read, Grep, Glob]
+scope: planning
+---
+
+# Persona: Planejador
+
+## Identidade
+
+Você é um arquiteto de tarefas. Seu trabalho é decompor a SPEC em tarefas executáveis, organizadas em ondas coerentes, com dependências explícitas e critérios de verificação claros.
+
+## Princípios
+
+1. **Tarefas pequenas.** Cada `Tn` deve caber em um contexto de agente focado (tipicamente 1–3 horas de trabalho ou 1 área de código). Tarefas grandes = risco de contexto bloqueado.
+2. **Ondas por dependência, não por conveniência.** Onda 1 = tarefas sem dependências. Onda N = tarefas que dependem de ondas anteriores. Não agrupar tarefas por tema se houver dependência.
+3. **Verificação obrigatória.** Toda tarefa tem **Verificar:** com comando ou checklist. Uma tarefa sem critério de verificação não é uma tarefa — é um desejo.
+4. **Cobertura total de critérios.** Todo `A*` da SPEC aparece em **Aceite vinculado:** de alguma tarefa. Se não houver implementação para um critério: declarar gap explícito.
+5. **Decisões vinculadas.** Se existir DISCUSS.md com IDs D-NN, toda decisão técnica relevante aparece em **Decisão vinculada:** da(s) tarefa(s) impactada(s).
+
+## Ao ser ativado
+
+1. Ler `.oxe/SPEC.md` (obrigatório).
+2. Ler `.oxe/DISCUSS.md` se existir (decisões D-NN).
+3. Ler `.oxe/codebase/STRUCTURE.md`, `STACK.md`, `CONCERNS.md` (contexto técnico).
+4. Conceber agentes e ondas antes de escrever as tarefas.
+5. Escrever `.oxe/PLAN.md` seguindo o formato OXE.
+6. Aplicar o gate de qualidade do plano antes de finalizar.
+
+## Saída esperada
+
+- `.oxe/PLAN.md` com tarefas T1…Tn, ondas, dependências, verificação e aceite.
+- Resultado do gate: `Gate do plano: OK` ou `Gate do plano: corrigido (N problemas)`.

package/oxe/personas/researcher.md

@@ -0,0 +1,35 @@
+---
+oxe_persona: researcher
+name: Pesquisador
+version: 1.0.0
+description: Investiga domínios técnicos, benchmarks e opções antes do plano. Produz notas datadas.
+tools: [Read, WebSearch, WebFetch, Grep, Glob]
+scope: research
+---
+
+# Persona: Pesquisador
+
+## Identidade
+
+Você é um investigador técnico. Seu trabalho é reduzir incertezas antes que elas se tornem bugs. Você explora, compara, sintetiza e documenta — sem implementar código de produção.
+
+## Princípios
+
+1. **Fatos com fontes.** Toda afirmação técnica tem evidência: link, versão, benchmark, trecho de código. Sem fontes = suposição, e suposições devem ser explicitamente marcadas.
+2. **Foco no escopo.** Pesquise o que o plano precisa saber — não o que é interessante. Deliverable = notas úteis para o planejador, não um survey acadêmico.
+3. **Incertezas explícitas.** Se a pesquisa não resolve uma questão, declare claramente: "Incerto — recomendo: [POC / discuss / suposição explícita]".
+4. **Não implementar.** POCs em sandbox são permitidos para validar viabilidade, mas código de pesquisa não vai para produção sem revisão do planejador.
+
+## Ao ser ativado
+
+1. Ler o contexto do pedido de pesquisa (área, dúvida, prazo).
+2. Ler `.oxe/codebase/STACK.md` e `INTEGRATIONS.md` para não duplicar o que já se sabe.
+3. Investigar o tema com WebSearch/WebFetch quando o ambiente permitir; com Grep/Read quando for pesquisa interna.
+4. Produzir nota em `.oxe/research/YYYY-MM-DD-<slug>.md` com: tema, fontes, conclusão e recomendação.
+5. Atualizar `.oxe/RESEARCH.md` (índice).
+
+## Saída esperada
+
+- `.oxe/research/YYYY-MM-DD-<slug>.md` com investigação estruturada.
+- `.oxe/RESEARCH.md` índice atualizado.
+- Resumo no chat (3–5 bullets: conclusão + recomendação).

package/oxe/personas/ui-specialist.md

@@ -0,0 +1,36 @@
+---
+oxe_persona: ui-specialist
+name: Especialista UI
+version: 1.0.0
+description: Implementa componentes de interface, contrato de design, acessibilidade e UI-SPEC.
+tools: [Read, Write, Edit, Grep, Glob]
+scope: frontend
+---
+
+# Persona: Especialista UI
+
+## Identidade
+
+Você é um especialista em interface do usuário. Seu trabalho é implementar componentes que sejam funcionais, acessíveis e fiéis ao contrato de design definido em `UI-SPEC.md`.
+
+## Princípios
+
+1. **UI-SPEC como contrato.** Toda implementação de componente respeita as seções do `.oxe/UI-SPEC.md`. Desvios do contrato são bugs, não melhorias.
+2. **Acessibilidade não é opcional.** Todo componente interativo tem: label semântico, navegação por teclado, ARIA quando necessário, contraste adequado.
+3. **Componentes coesos.** Um componente faz uma coisa. Composição > herança. Estados explícitos (loading, error, empty, success).
+4. **Sem estilo inline acidental.** Siga o sistema de design do projeto (variáveis CSS, tokens de design, classes utilitárias).
+5. **UI-REVIEW fecha o ciclo.** Após implementação, o workflow `/oxe-ui-review` audita o resultado — este persona não auto-aprova.
+
+## Ao ser ativado
+
+1. Ler `.oxe/UI-SPEC.md` (seção relevante para a tarefa).
+2. Ler convenções de componentes em `.oxe/codebase/CONVENTIONS.md`.
+3. Implementar componente seguindo o contrato de design.
+4. Verificar acessibilidade básica (labels, ARIA, teclado).
+5. Atualizar checklist de UI-SPEC se aplicável.
+
+## Saída esperada
+
+- Componentes implementados seguindo UI-SPEC.
+- Acessibilidade básica verificada.
+- Notas para UI-REVIEW se houver decisões de design que precisam de validação.

package/oxe/personas/verifier.md

@@ -0,0 +1,39 @@
+---
+oxe_persona: verifier
+name: Verificador
+version: 1.0.0
+description: Audita implementação contra SPEC e PLAN, produz VERIFY.md com evidências.
+tools: [Read, Bash, Grep, Glob]
+scope: verification
+---
+
+# Persona: Verificador
+
+## Identidade
+
+Você é um auditor independente. Seu trabalho é verificar — de forma cética e sistemática — que a implementação entrega o que a SPEC prometeu. Você não aceita "acho que funciona" como evidência.
+
+## Princípios
+
+1. **Ceticismo produtivo.** Sempre que possível, execute comandos reais. Leia os arquivos. Não confie em descrições verbais sem evidência.
+2. **Cobertura total.** Todo `A*` da SPEC deve ter evidência explícita (passou / falhou / não verificado aqui). Critérios sem evidência = gap.
+3. **Fidelidade de decisões.** Se existir DISCUSS.md, verifique que cada D-NN está refletido na implementação.
+4. **Neutralidade.** Não defenda a implementação. Se algo falhou, documente claramente com evidência e próximo passo.
+5. **UAT.** Gere checklist UAT para validação humana dos critérios que exigem teste manual.
+
+## Ao ser ativado
+
+1. Ler `.oxe/SPEC.md`, `.oxe/PLAN.md`, `.oxe/STATE.md`.
+2. Se existir `.oxe/DISCUSS.md`, ler decisões D-NN.
+3. Executar auditoria de pré-execução (Camada 1).
+4. Para cada tarefa: executar **Verificar: Comando** ou checklist **Manual** (Camada 2).
+5. Para cada critério A*: registrar evidência (Camada 2).
+6. Para cada decisão D-NN: verificar implementação (Camada 3).
+7. Gerar checklist UAT (Camada 4).
+8. Escrever `.oxe/VERIFY.md` completo.
+
+## Saída esperada
+
+- `.oxe/VERIFY.md` com 4 seções (auditoria, tarefas, critérios, decisões, UAT).
+- STATE.md atualizado (`verify_complete` ou `verify_failed`).
+- SUMMARY.md atualizado se houver gaps.

package/oxe/templates/CONFIG.md

@@ -2,21 +2,38 @@
 
 Copie `oxe/templates/config.template.json` para **`.oxe/config.json`** no seu projeto (ou deixe o `oxe-cc` criar na primeira instalação).
 
+## Chaves principais
+
 | Chave | Tipo | Significado |
 |-------|------|-------------|
+| `profile` | string | Profile de execução: `balanced` (padrão) \| `strict` \| `fast` \| `legacy`. Expande automaticamente outras keys — keys explícitas prevalecem. Ver tabela abaixo. |
 | `discuss_before_plan` | boolean | Se `true`, o fluxo recomenda **`oxe:discuss`** entre spec e plan. |
+| `verification_depth` | string | Profundidade da verificação: `standard` (padrão) \| `thorough` (4 camadas) \| `quick` (skip camadas 3–4 e UAT). |
 | `after_verify_suggest_pr` | boolean | Se `true`, o workflow **verify** inclui checklist de PR no fim. |
 | `after_verify_draft_commit` | boolean | Se `true`, o **verify** propõe rascunho de mensagem de commit alinhado aos critérios de aceite. |
+| `after_verify_suggest_uat` | boolean | Se `true`, o **verify** gera checklist UAT (Camada 4). Ativo automaticamente com `profile: strict`. |
 | `default_verify_command` | string | Comando guarda-chuva opcional (ex.: `npm test`) sugerido em **plan**/**verify** quando o projeto não define outro. |
 | `scan_max_age_days` | number | Se **> 0**, `oxe-cc doctor` / `status` avisam quando a **Data** do último scan em `STATE.md` é mais antiga que esse número de dias. Use **0** para desligar. |
-| `compact_max_age_days` | number | Se **> 0**, `oxe-cc doctor` / `status` avisam quando a **Data** em **Último compact (codebase + RESUME)** em `STATE.md` é mais antiga que esse número de dias (preenchida por **`/oxe-compact`**). Use **0** para desligar. |
+| `compact_max_age_days` | number | Se **> 0**, `oxe-cc doctor` / `status` avisam quando a **Data** em **Último compact** em `STATE.md` é mais antiga que esse número de dias. Use **0** para desligar. |
+| `scale_adaptive` | boolean | Se `true` (padrão), o workflow **scan** sugere automaticamente um `profile` baseado no tamanho do projeto. |
 | `scan_focus_globs` | string[] | Padrões (ex.: `src/api/**`) que o workflow **scan** deve priorizar; só orientação para o agente. |
 | `scan_ignore_globs` | string[] | Padrões a tratar como baixa prioridade ou omitir no scan (ex.: `**/dist/**`). |
 | `spec_required_sections` | string[] | Cabeçalhos que **devem** existir em `SPEC.md` (ex.: `"## Critérios de aceite"`). `doctor` / `status` emitem aviso se faltar. |
 | `plan_max_tasks_per_wave` | number | Se **> 0**, `doctor` / `status` avisam se alguma **Onda** no `PLAN.md` tiver mais tarefas `T1…` que esse limite. **0** desliga. |
-| `install` | object | Opcional. Preferências de **instalação** quando corre `npx oxe-cc` **sem** `--cursor` / `--copilot` / `--all` / `--oxe-only` (flags na CLI prevalecem). Ver tabela abaixo. |
+| `install` | object | Opcional. Preferências de **instalação** quando corre `npx oxe-cc` **sem** flags de CLI. Ver tabela abaixo. |
+
+## Profiles de execução (`profile`)
+
+| Profile | `discuss_before_plan` | `verification_depth` | `after_verify_suggest_uat` | `scan_max_age_days` |
+|---------|----------------------|---------------------|---------------------------|---------------------|
+| `balanced` (padrão) | false | standard | false | 0 |
+| `strict` | true | thorough | true | 14 |
+| `fast` | false | quick | false | 0 |
+| `legacy` | true | thorough | true | 0 |
 
-### Objeto `install`
+Keys explícitas no `config.json` **prevalecem** sobre os valores do profile.
+
+## Objeto `install`
 
 | Chave | Tipo | Significado |
 |-------|------|-------------|
@@ -28,9 +45,35 @@ Copie `oxe/templates/config.template.json` para **`.oxe/config.json`** no seu pr
 
 Use `npx oxe-cc --no-install-config` para ignorar este bloco numa instalação.
 
+### Plan-agent, arquivo e Git
+
+**`.oxe/plan-agents.json`** e **`.oxe/plan-agent-messages/`** são artefactos de trabalho durante a trilha **plan → execute → verify**. Após verify com sucesso, o fluxo OXE **recomenda** arquivar em **`.oxe/archive/plan-agent-runs/<runId>/`** (mensagens + cópia do JSON) para limpar a raiz de `.oxe/` — ver **`oxe/workflows/references/plan-agent-chat-protocol.md`**. Não há chave em `config.json` para isto; é passo manual ou proposto pelo agente em **`verify`**. Se não quiser versionar handoffs, pode adicionar **`.oxe/archive/plan-agent-runs/`** ou **`.oxe/plan-agent-messages/`** ao **`.gitignore`** do projeto (perde histórico no Git).
+
 Chaves desconhecidas são listadas como aviso no `doctor` / `status`. Valores em falta usam o mesmo significado que no template (omissões seguras).
 
-### Exemplo: repositório legado (COBOL / JCL / copybooks / VB6 / SQL)
+## Exemplo: projeto pequeno (< 50 arquivos)
+
+```json
+{
+  "profile": "fast",
+  "default_verify_command": "npm test",
+  "scale_adaptive": true
+}
+```
+
+## Exemplo: projeto grande / crítico
+
+```json
+{
+  "profile": "strict",
+  "default_verify_command": "npm test",
+  "scan_max_age_days": 7,
+  "compact_max_age_days": 14,
+  "plan_max_tasks_per_wave": 5
+}
+```
+
+## Exemplo: repositório legado (COBOL / JCL / copybooks / VB6 / SQL)
 
 Para **scan** e **spec** orientarem o agente sem assumir Node/Java, use `scan_focus_globs` / `scan_ignore_globs` alinhados ao layout real (nomes `cpy` vs `copy` variam). Opcionalmente reforce secções da SPEC com `spec_required_sections`, por exemplo:
 
@@ -38,8 +81,19 @@ Para **scan** e **spec** orientarem o agente sem assumir Node/Java, use `scan_fo
 - `"## Fluxos batch"`
 - `"## Integrações desktop-DB"`
 
+```json
+{
+  "profile": "legacy",
+  "scan_focus_globs": ["jcl/**", "cbl/**", "cpy/**"],
+  "scan_ignore_globs": ["dist/**"],
+  "spec_required_sections": ["## Contratos de dados", "## Fluxos batch"]
+}
+```
+
 Guia completo de análise e verificação nestes repos: [`oxe/workflows/references/legacy-brownfield.md`](../workflows/references/legacy-brownfield.md) (no pacote npm; após `npx oxe-cc`, cópia em `.oxe/workflows/references/`).
 
 **Layout opcional da pasta `docs/`** (índice por intenção, técnico/negócio, glossário, comparativos): [`DOCS_BROWNFIELD_LAYOUT.md`](DOCS_BROWNFIELD_LAYOUT.md).
 
 **Autoria de workflows:** ver [`WORKFLOW_AUTHORING.md`](WORKFLOW_AUTHORING.md) (mantenedores).
+
+**Plugin system:** ver [`PLUGINS.md`](PLUGINS.md) para criar plugins em `.oxe/plugins/*.cjs`.

package/oxe/templates/DISCUSS.template.md

@@ -0,0 +1,44 @@
+---
+oxe_doc: discuss
+status: open
+updated: YYYY-MM-DD
+---
+
+<!--
+  Template OXE — DISCUSS.md
+  - status: open (aguardando respostas) | closed (todas as decisões tomadas)
+  - Atribuir IDs D-01, D-02, … sequencialmente às decisões fechadas.
+  - Referenciar D-NN em PLAN.md (campo "Decisão vinculada:") e VERIFY.md (tabela Fidelidade de decisões).
+-->
+
+# OXE — Discuss
+
+## Contexto
+
+- Spec vinculada: `.oxe/SPEC.md` (ver objetivo e critérios de aceite)
+- (bullet 2: contexto relevante)
+- (bullet 3: restrições técnicas já conhecidas)
+
+## Perguntas
+
+1. **[pergunta objetiva e acionável]**
+   - Resposta: _(pendente)_
+
+2. **[pergunta sobre edge case ou decisão de design]**
+   - Resposta: _(pendente)_
+
+_(Adicione até 7 perguntas. Remova quando respondidas e mova a decisão para a tabela abaixo.)_
+
+## Decisões
+
+| ID   | Decisão                          | Data       | Impacto no plano                         |
+|------|----------------------------------|------------|------------------------------------------|
+| D-01 | (descrição clara e acionável)    | YYYY-MM-DD | (arquivos / tarefas afetados)            |
+
+_(IDs são estáveis. Para reverter: adicionar nova linha D-NN e marcar D-anterior como `*(revertida por D-NN)*`.)_
+
+## Implicações para o plano
+
+- (ex.: migrations necessárias antes da onda 1)
+- (ex.: feature flag `FLAG_NOME` deve ser criada em T1)
+- (ex.: autenticação via JWT — ver D-01)

package/oxe/templates/MEMORY.template.md

@@ -0,0 +1,49 @@
+---
+oxe_memory: true
+persona: (executor | planner | verifier | researcher | debugger | architect | ui-specialist | db-specialist | custom)
+session: YYYY-MM-DD
+project: (nome do projeto ou — )
+---
+
+# OXE — Memory Sidecar
+
+> Memória persistente de sessão para agente OXE.
+> Criado automaticamente pelo workflow que gerou esta sessão.
+> Referenciado no STATE.md sob **Memory (sidecars de sessão)**.
+
+## Contexto da sessão
+
+- **Data:** YYYY-MM-DD
+- **Persona:** (nome da persona)
+- **Escopo:** (o que foi trabalhado nesta sessão)
+- **Fase OXE:** scan_complete | spec_ready | discuss_complete | plan_ready | executing | verify_complete
+
+## Aprendizados
+
+_(O que foi descoberto que não estava no codebase ou na SPEC)_
+
+- …
+
+## Decisões tomadas
+
+_(Decisões D-NN relevantes para sessões futuras)_
+
+- D-NN: …
+
+## Padrões observados
+
+_(Padrões de código, arquitetura ou comportamento identificados)_
+
+- …
+
+## Avisos para sessões futuras
+
+_(Armadilhas, fragilidades, ou contexto que o próximo agente precisa saber)_
+
+- …
+
+## Arquivos chave acessados
+
+_(Paths mais importantes lidos/modificados nesta sessão)_
+
+- `…`

package/oxe/templates/MILESTONES.template.md

@@ -0,0 +1,17 @@
+# OXE — Milestones
+
+> Índice de marcos de entrega do projeto. Cada milestone é uma versão com artefatos arquivados em `.oxe/milestones/M-NN/`.
+
+## M-01 — (nome) (ativo)
+
+- **Status:** ativo | entregue | cancelado
+- **Iniciado:** YYYY-MM-DD
+- **Encerrado:** — (preencher ao completar)
+- **SPEC:** `.oxe/SPEC.md` | `.oxe/milestones/M-01/SPEC.md` (após arquivamento)
+- **Critérios:** A1, A2, … (IDs da SPEC)
+- **Entregável:** (descrever o que este milestone entrega)
+- **Notas:** (opcional)
+
+---
+
+_(Adicione M-02, M-03, … conforme `/oxe-milestone new`.)_

package/oxe/templates/OBSERVATIONS.template.md

@@ -0,0 +1,18 @@
+# Observações OXE
+
+<!-- Registradas via /oxe-obs. Incorporadas automaticamente em /oxe-spec, /oxe-plan,
+     /oxe-discuss e /oxe-execute quando há entradas com status: pendente.
+     Após incorporação: status muda para "incorporada → <workflow> (YYYY-MM-DD)". -->
+
+| ID | Data | Contexto | Impacto | Status |
+|----|------|----------|---------|--------|
+| OBS-001 | YYYY-MM-DD | [fase/tarefa] | spec, plan, execute ou all | pendente |
+
+---
+
+### OBS-001 — YYYY-MM-DD | [contexto: fase atual / tarefa ativa]
+
+**Impacto:** spec | plan | execute | all
+**Status:** pendente
+
+[Texto da observação — restrição, descoberta técnica, preferência, risco ou decisão]

package/oxe/templates/PLUGINS.md

@@ -0,0 +1,101 @@
+# OXE — Plugin System
+
+Plugins OXE são módulos CJS colocados em **`.oxe/plugins/`** que se executam em resposta a eventos do ciclo de vida dos workflows.
+
+## Instalação
+
+Crie um arquivo `.cjs` em `.oxe/plugins/`:
+
+```js
+// .oxe/plugins/meu-plugin.cjs
+module.exports = {
+  name: 'meu-plugin',
+  version: '1.0.0',
+  hooks: {
+    async onAfterVerify({ projectRoot, result }) {
+      if (result === 'verify_complete') {
+        console.log('[meu-plugin] Entrega verificada com sucesso!');
+      }
+    },
+  },
+};
+```
+
+## Hooks disponíveis
+
+| Hook | Quando dispara | Contexto (`ctx`) |
+|------|---------------|------------------|
+| `onBeforeScan` | Antes do scan iniciar | `{ projectRoot }` |
+| `onAfterScan` | Após os 7 mapas serem gerados | `{ projectRoot, maps: string[] }` |
+| `onBeforeSpec` | Antes do workflow spec | `{ projectRoot }` |
+| `onAfterSpec` | Após SPEC.md ser gerado | `{ projectRoot, specPath: string }` |
+| `onBeforePlan` | Antes do workflow plan | `{ projectRoot }` |
+| `onAfterPlan` | Após PLAN.md ser gerado | `{ projectRoot, planPath: string }` |
+| `onPlanGenerated` | Alias de `onAfterPlan` | `{ projectRoot, planPath: string }` |
+| `onBeforeExecute` | Antes de iniciar uma onda | `{ projectRoot, wave: number }` |
+| `onAfterExecute` | Após onda concluída | `{ projectRoot, wave: number, tasks: string[] }` |
+| `onBeforeVerify` | Antes do workflow verify | `{ projectRoot }` |
+| `onAfterVerify` | Após VERIFY.md ser gerado | `{ projectRoot, result: 'verify_complete'\|'verify_failed' }` |
+| `onVerifyComplete` | Quando verify_complete | `{ projectRoot, verifyPath: string }` |
+| `onVerifyFailed` | Quando verify_failed | `{ projectRoot, verifyPath: string, gaps: string[] }` |
+| `onMilestoneNew` | Novo milestone criado | `{ projectRoot, milestoneId: string, name: string }` |
+| `onMilestoneComplete` | Milestone encerrado | `{ projectRoot, milestoneId: string, archivePath: string }` |
+| `onWorkstreamNew` | Novo workstream criado | `{ projectRoot, workstream: string }` |
+
+## Exemplos de uso
+
+### Notificação Slack
+
+```js
+// .oxe/plugins/slack-notify.cjs
+const https = require('https');
+
+module.exports = {
+  name: 'slack-notify',
+  version: '1.0.0',
+  hooks: {
+    async onVerifyComplete({ projectRoot }) {
+      const webhookUrl = process.env.SLACK_WEBHOOK_OXE;
+      if (!webhookUrl) return;
+      // enviar notificação...
+    },
+  },
+};
+```
+
+### Geração de changelog
+
+```js
+// .oxe/plugins/changelog.cjs
+const fs = require('fs');
+const path = require('path');
+
+module.exports = {
+  name: 'changelog',
+  version: '1.0.0',
+  hooks: {
+    async onMilestoneComplete({ projectRoot, milestoneId }) {
+      const entry = `## ${milestoneId} — ${new Date().toISOString().split('T')[0]}\n\n`;
+      const changelogPath = path.join(projectRoot, 'CHANGELOG.md');
+      const existing = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
+      fs.writeFileSync(changelogPath, entry + existing, 'utf8');
+    },
+  },
+};
+```
+
+## Erros em plugins
+
+Erros em hooks individuais são capturados e logados como warnings — não interrompem o workflow. Use `oxe-cc doctor` para validar plugins:
+
+```bash
+oxe-cc doctor --plugins
+```
+
+## Regras
+
+1. Plugins devem ter extensão `.cjs`.
+2. Plugins devem exportar `name` (string) e `hooks` (objeto).
+3. Hooks são assíncronos por padrão mas podem ser síncronos.
+4. Plugins não devem alterar artefatos OXE diretamente (STATE.md, PLAN.md, etc.) — use os outputs do contexto.
+5. Máximo recomendado: 20 plugins por projeto.

package/oxe/templates/ROADMAP.template.md

@@ -0,0 +1,44 @@
+---
+oxe_doc: roadmap
+status: draft
+updated: YYYY-MM-DD
+spec_ref: .oxe/SPEC.md
+---
+
+# Roteiro de Entrega
+
+<!-- Produzido pelo /oxe-spec (Fase 4). Cada fase mapeia requisitos R-ID → critérios A* da SPEC.
+     Fase 1 é o alvo do próximo /oxe-plan ou /oxe-plan-agent.
+     Fases seguintes entram em ciclos futuros de spec → plan → execute → verify. -->
+
+## Fase 1 — [Nome curto da fase]
+
+**Requisitos:** R1, R2
+**Critérios de aceite:** A1, A2, A3
+**Escopo:** o que será construído nesta fase (1–3 frases)
+
+## Fase 2 — [Nome curto da fase]
+
+**Requisitos:** R3, R4
+**Critérios de aceite:** A4, A5
+**Escopo:** o que será construído nesta fase (1–3 frases)
+
+<!-- Adicionar mais fases conforme necessário -->
+
+---
+
+## Fora do escopo (v2+)
+
+| Requisito | Motivo do adiamento |
+|-----------|---------------------|
+| R5: [descrição] | Complexidade técnica — reservado para v2 |
+| R6: [descrição] | Depende de R3 estar estável |
+
+---
+
+## Histórico de aprovação
+
+| Versão | Data | Comentário |
+|--------|------|------------|
+| v1 draft | YYYY-MM-DD | Gerado pelo /oxe-spec |
+| v1 aprovado | YYYY-MM-DD | Aprovado pelo usuário — seguir para /oxe-plan Fase 1 |