oxe-cc 0.3.9 → 0.6.0

package/oxe/workflows/obs.md

@@ -0,0 +1,95 @@
+# OXE — Workflow: obs
+
+<objective>
+Registrar uma **observação contextual** em **`.oxe/OBSERVATIONS.md`** durante ou fora de uma execução. A observação é incorporada automaticamente nos próximos `/oxe-spec`, `/oxe-plan`, `/oxe-discuss` ou `/oxe-execute` sem necessidade de re-explicar.
+
+**Princípio:** *observation-without-re-explaining* — registre em 1 request, receba o benefício em todos os workflows seguintes sem custo extra de requisição.
+
+Entrada: texto livre com a observação (restrição, descoberta técnica, preferência, risco, decisão).
+</objective>
+
+<context>
+- Pode ser chamado **a qualquer momento**: antes, durante ou após qualquer passo da trilha OXE.
+- Não interrompe o fluxo em curso — a observação é armazenada e incorporada na próxima oportunidade.
+- Se chamado **durante execute** (fase `executing` no STATE) com impacto `execute` ou `all`: oferecer opção de aplicar agora (pausar onda atual) ou continuar e aplicar na próxima rodada.
+- Ler **`.oxe/STATE.md`** para capturar o contexto automático (fase atual, tarefa ativa, workstream ativo).
+- Usar `oxe/templates/OBSERVATIONS.template.md` para criar o arquivo se ainda não existir.
+</context>
+
+<format_observations_md>
+Arquivo: **`.oxe/OBSERVATIONS.md`**
+
+```markdown
+# Observações OXE
+
+| ID | Data | Contexto | Impacto | Status |
+|----|------|----------|---------|--------|
+| OBS-001 | 2026-04-04 | execute/T3 | spec, plan | pendente |
+| OBS-002 | 2026-04-04 | pós-spec | execute | incorporada → execute (2026-04-04) |
+
+---
+
+### OBS-001 — 2026-04-04 | execute/T3
+**Impacto:** spec, plan
+**Status:** pendente
+
+JWT expiration deve ser configurável via `JWT_EXPIRES_IN` env var, não hardcoded 7d.
+
+---
+
+### OBS-002 — 2026-04-04 | pós-spec
+**Impacto:** execute
+**Status:** incorporada → execute (2026-04-04)
+
+API deve retornar mensagens de erro em português do Brasil.
+```
+
+**IDs:** sequenciais `OBS-001`, `OBS-002`, … (continuar do último ID existente no arquivo).
+
+**Impacto:** classificar automaticamente com base no conteúdo:
+- `spec` — afeta requisitos, critérios de aceite ou escopo
+- `plan` — afeta tarefas, ondas, dependências ou verificação
+- `execute` — afeta a implementação da tarefa atual ou próxima
+- `all` — afeta múltiplas camadas
+
+**Status lifecycle:** `pendente` → `incorporada → <workflow> (YYYY-MM-DD)`
+</format_observations_md>
+
+<process>
+1. Ler **`.oxe/STATE.md`**: capturar `phase`, `last_task` ou tarefa ativa na onda, `active_workstream`.
+2. Determinar o **próximo ID** (OBS-NNN): contar entradas existentes em `.oxe/OBSERVATIONS.md` ou começar em OBS-001.
+3. Classificar o **impacto** automaticamente com base no texto; se ambíguo, usar `all`.
+4. Criar ou atualizar **`.oxe/OBSERVATIONS.md`**:
+   - Adicionar linha na tabela de índice.
+   - Adicionar seção `### OBS-NNN` com contexto, impacto, status e texto.
+5. Avaliar **urgência**:
+   - Se `phase` ∈ `{ executing, quick_active }` **e** impacto ∈ `{ execute, all }`:
+     - Apresentar ao usuário: "Observação registrada. Deseja aplicar agora (pausar onda atual) ou continuar e incorporar na próxima rodada?"
+     - Se pausar: sugerir revisão do bloco `**Verificar:**` da tarefa ativa e ajuste inline.
+     - Se continuar: confirmar que será incorporado no início da próxima onda.
+   - Em qualquer outro caso: confirmar registro e mencionar quando será incorporado.
+6. Atualizar **`.oxe/STATE.md`**: adicionar ou atualizar campo `obs_pendentes: true` (remover ou marcar `false` quando todos os OBS estiverem `incorporada`).
+7. Responder no chat com: ID atribuído (OBS-NNN), impacto classificado, próximo passo sugerido (qual workflow incorporará a observação).
+</process>
+
+<auto_incorporation_rule>
+Qualquer workflow que leia `.oxe/OBSERVATIONS.md` deve:
+1. Verificar se há entradas com `Status: pendente` relevantes ao seu escopo de impacto.
+2. Incorporar o conteúdo na lógica do workflow (enriquecer requisitos, ajustar tarefas, modificar implementação).
+3. Após incorporar: atualizar a linha no índice e na seção `### OBS-NNN` para `incorporada → <workflow> (data)`.
+4. Se `STATE.md` tiver `obs_pendentes: true` e todas as observações relevantes foram incorporadas: atualizar para `obs_pendentes: false`.
+
+**Workflows que incorporam observações:**
+- `/oxe-spec` (Fase 3 — Requisitos): impacto `spec` ou `all`
+- `/oxe-plan`: impacto `plan` ou `all`
+- `/oxe-discuss`: impacto `spec`, `plan` ou `all` (como contexto adicional)
+- `/oxe-execute`: impacto `execute` ou `all` — incorporar no início da onda atual
+</auto_incorporation_rule>
+
+<success_criteria>
+- [ ] `.oxe/OBSERVATIONS.md` existe com entrada OBS-NNN na tabela e seção de detalhe.
+- [ ] Impacto classificado corretamente (spec | plan | execute | all).
+- [ ] `STATE.md` tem `obs_pendentes: true`.
+- [ ] Se urgência execute: usuário foi consultado sobre pausar ou continuar.
+- [ ] Resposta no chat inclui ID, impacto e próximo passo de incorporação.
+</success_criteria>

package/oxe/workflows/oxe.md

@@ -0,0 +1,115 @@
+# OXE — Workflow: oxe (entrada universal)
+
+<objective>
+Ponto de entrada inteligente do OXE. Faz uma de três coisas dependendo do input do usuário:
+
+1. **Sem input / "o que faço agora?"** → lê `STATE.md` e recomenda exatamente 1 próximo passo (lógica de `next.md`).
+2. **Input em linguagem natural** (ex.: "quero adicionar login", "preciso revisar um PR") → traduz para o comando OXE correto e executa ou orienta (lógica de `route.md`).
+3. **"help", "o que é OXE" ou "comandos"** → apresenta o fluxo dos 8 comandos essenciais e a cadeia canônica.
+
+**Princípio:** o usuário não precisa decorar o nome do comando — `/oxe [contexto]` resolve.
+</objective>
+
+<context>
+- Este workflow **não gera artefatos** por conta própria. Ele orienta ou delega para o workflow correto.
+- Lê `STATE.md` quando disponível para personalizar a resposta ao estado atual do projeto.
+- Quando o input for claro o suficiente para um workflow específico, **executar diretamente** esse workflow (carregar e seguir o `.md` correspondente) em vez de só sugerir o comando.
+- Quando houver ambiguidade genuína, apresentar 2 opções e pedir escolha — nunca listas longas.
+</context>
+
+<modo_status>
+## Modo: Status + Próximo Passo (sem input ou "o que faço agora?")
+
+Aplicar a lógica completa de `oxe/workflows/next.md`:
+
+1. Se `.oxe/` ou `STATE.md` não existir → **scan** (`npx oxe-cc@latest` primeiro se OXE não instalado)
+2. Se `.oxe/codebase/` incompleto e não for quick isolado → **scan**
+3. Se `quick_active` ou `QUICK.md` sem `PLAN.md` → avaliar promoção (ver `next.md`)
+4. Se sem `SPEC.md` → **spec**
+5. Se SPEC mas sem PLAN → verificar `discuss_before_plan` → **discuss** ou **plan**
+6. Se PLAN sem VERIFY pós-implementação → **execute** ou **verify**
+7. Se VERIFY com falha → **plan --replan**
+8. Se VERIFY OK → próxima feature ou milestone
+
+**Saída:** exatamente 1 passo, 1 comando, 1 frase de justificativa.
+</modo_status>
+
+<modo_route>
+## Modo: Roteamento de Linguagem Natural (input com contexto)
+
+Mapear o input para o workflow correto e executar ou orientar:
+
+| Se o usuário disser | Executar |
+|---------------------|----------|
+| "quero [feature / tarefa / entrega]" | Verificar estado → **spec** ou **quick** |
+| "analisa / mapeia o projeto" | **scan** (modo refresh se codebase/ existir) |
+| "pesquisa / spike / quero entender X" | **research** |
+| "revisa PR / diff" | **review-pr** |
+| "auditoria de segurança" | **security** |
+| "valida / verifica" | **verify** |
+| "milestone / release / versão" | **project milestone** |
+| "trilha paralela / workstream" | **project workstream** |
+| "snapshot / checkpoint" | **project checkpoint** |
+| "recuperação / erro / algo quebrou" | **forensics** |
+| "debug / teste falhando" | **debug** |
+| "obs / observação / nota" | **obs** |
+| "atualiza / update OXE" | **update** |
+
+Se o input não mapear claramente → apresentar 2 opções mais prováveis e perguntar.
+</modo_route>
+
+<modo_help>
+## Modo: Help (quando o usuário pede "help", "o que é OXE", "comandos")
+
+Apresentar de forma concisa:
+
+### Os 8 comandos que você precisa conhecer
+
+```
+/oxe              → onde estou / o que faço / help
+/oxe-obs          → registrei algo importante agora
+/oxe-quick        → tarefa pequena, sem cerimônia
+/oxe-scan         → mapeia o projeto (ou atualiza o mapa)
+/oxe-spec         → nova feature ou entrega: perguntas → requisitos → roteiro
+/oxe-plan         → detalhar em tarefas (--agents para multi-agente)
+/oxe-execute      → implementar (A: completo | B: por onda | C: por tarefa)
+/oxe-verify       → validar que está pronto
+```
+
+### A cadeia
+
+```
+/oxe-obs (qualquer momento)
+     ↓
+/oxe-scan → /oxe-spec → /oxe-plan → /oxe-execute → /oxe-verify
+                                  ↓
+                           /oxe-quick (trabalho pequeno)
+```
+
+### Para saber o próximo passo agora
+
+```
+/oxe
+```
+
+### Escape hatches (não precisa decorar — aparecem quando necessários)
+
+`/oxe-research`, `/oxe-forensics`, `/oxe-debug`, `/oxe-loop`, `/oxe-security`,
+`/oxe-validate-gaps`, `/oxe-ui-spec`, `/oxe-ui-review`, `/oxe-review-pr`,
+`/oxe-project` (milestone, workstream, checkpoint)
+</modo_help>
+
+<process>
+1. Verificar se há input adicional na mensagem:
+   - **Sem input ou "next / o que faço / status":** aplicar `<modo_status>`.
+   - **"help / comandos / o que é OXE":** aplicar `<modo_help>`.
+   - **Qualquer outra coisa (linguagem natural com contexto):** aplicar `<modo_route>` e, se o workflow for claro, carregar e executar diretamente o `oxe/workflows/<nome>.md` correspondente.
+2. Nunca produzir listas longas de alternativas. Um passo, um comando, uma frase.
+3. Se o workflow executado diretamente gerar artefatos, reportar no chat conforme esse workflow.
+</process>
+
+<success_criteria>
+- [ ] Usuário recebe exatamente 1 próximo passo (modo status) OU 1 workflow executado (modo route) OU o bloco help compacto (modo help).
+- [ ] Nenhum artefato criado por este workflow diretamente (a menos que o workflow delegado o faça).
+- [ ] Nunca lista mais de 2 alternativas ao mesmo tempo.
+</success_criteria>

package/oxe/workflows/plan-agent.md

@@ -22,14 +22,55 @@ Se o utilizador pedir **`--replan`**: aplicar a mesma lógica de replanejamento
   - **`sequential`** — uma onda por agente (ondas com um único id cada) ou execução estritamente ordenada.
   - **`parallel_per_wave`** — dentro de cada onda, agentes sem dependência mútua podem correr em paralelo; ondas são sequenciais.
   - **`hybrid`** — ondas sequenciais; dentro da onda, paralelo quando `dependencies` já satisfeitas (é o caso mais comum).
-- **Schema:** **`oxePlanAgentsSchema: 2`** obrigatório nas novas gerações; incluir **`runId`** (string opaca única, ex. `oxe-{ISO8601}-{6 hex aleatórios}`) e **`lifecycle`**: `{ "status": "pending_execute", "since": "<ISO>" }`. Blueprints com schema **1** (legado) não aplicam exclusividade estrita até serem regerados.
+- **Schema:** **`oxePlanAgentsSchema: 3`** obrigatório nas novas gerações (schema **2** = sem `model_hint`; schema **1** = legado sem `runId`/`lifecycle`). Incluir **`runId`** (string opaca única, ex. `oxe-{ISO8601}-{6 hex aleatórios}`) e **`lifecycle`**: `{ "status": "pending_execute", "since": "<ISO>" }`. Blueprints com schema **2** continuam válidos; schema **1** não aplica exclusividade estrita até serem regerados.
 - Modelo JSON: ver **`oxe/templates/plan-agents.template.json`** e **`oxe/schemas/plan-agents.schema.json`**.
 </context>
 
+<agent_isolation_rule>
+## Regra de Isolamento de Agentes (Plan-Driven Dynamic Agents)
+
+**Cada `/oxe-plan-agent` cria agentes NOVOS para ESTE plano específico.**
+
+| Regra | Descrição |
+|-------|-----------|
+| **`runId` único** | Gerar `runId` NOVO a cada execução — nunca reutilizar `runId` de `plan-agents.json` anterior |
+| **`role` específico** | Descrever o papel no domínio desta demanda: "Especialista em autenticação JWT para este plano", não "Backend Developer" genérico |
+| **Não há reuso** | Agentes de planos ou demandas anteriores são inválidos para este plano. `lifecycle.status: invalidated` em qualquer blueprint anterior com `invalidatedBy: "new_plan"` |
+| **Lifecycle exclusivo** | Agentes vivem somente enquanto `lifecycle.status ∈ { pending_execute, executing }` e `runId` alinhado ao STATE.md |
+| **Gate de unicidade** | No quality gate: verificar que o `runId` gerado não existe em nenhum `plan-agents.json` anterior no repositório |
+
+**Invalidação de blueprint anterior:**
+Se já existir `.oxe/plan-agents.json` com status não-terminal (`pending_execute` ou `executing`), invalidá-lo antes de criar o novo:
+```json
+"lifecycle": {
+  "status": "invalidated",
+  "since": "<ISO agora>",
+  "invalidatedBy": "new_plan",
+  "invalidatedReason": "Novo /oxe-plan-agent iniciado para nova demanda"
+}
+```
+</agent_isolation_rule>
+
 <format_plan_md>
 Seguir **integralmente** o bloco **`<format_plan>`** e **`<plan_quality_gate>`** do ficheiro **`oxe/workflows/plan.md`** ao escrever `.oxe/PLAN.md` (incluindo gate antes de fechar).
 </format_plan_md>
 
+<model_hints>
+## Model Hints por Agente (schema v3, opcional)
+
+Cada agente pode declarar `model_hint` para orientar qual tier de modelo usar:
+
+| Valor | Quando usar |
+|-------|-------------|
+| `"powerful"` | Agentes de análise, arquitetura, pesquisa, decisões de design |
+| `"balanced"` | Agentes de implementação de features, integração, refactor |
+| `"fast"` | Agentes de review, testes, lint, validação, tarefas repetitivas |
+
+**Regra de uso:** quando o `plan-agents.json` tiver `model_hint`, o **`execute.md`** exibe a sugestão ao apresentar a atribuição do agente — permitindo ao usuário configurar o modelo antes de iniciar aquele agente.
+
+`model_hint` é opcional: omitir significa "sem preferência" (executa com o modelo padrão da sessão).
+</model_hints>
+
 <format_plan_agents_json>
 Raiz do ficheiro **`.oxe/plan-agents.json`**:
 
@@ -49,11 +90,15 @@ Cada **agente**:
 |-------|-------------|-------------|
 | `id` | sim | Slug único estável (`agent-db`, `agent-backend-auth`). |
 | `role` | sim | Nome legível do papel. |
+| `persona` | não | ID de persona em `oxe/personas/` (ex.: `executor`, `architect`). O workflow `/oxe-execute` carrega a persona para instruir o LLM. Ver `oxe/personas/README.md`. |
 | `scope` | sim | Lista de strings (o que este agente faz, em bullets curtos). |
 | `taskIds` | sim | Lista de IDs **`T1`…`Tn`** que este agente implementa (subconjunto do `PLAN.md`). |
 | `dependencies` | não | Lista de **`id`** de outros agentes que devem concluir antes (grafo entre agentes). |
 | `inputs` | não | Caminhos ou nomes de artefactos a carregar no contexto (ex.: `.oxe/STATE.md`, `.oxe/SPEC.md`). |
 | `outputs` | não | Paths ou padrões de ficheiros esperados (orientação; o código real vem do PLAN). |
+| `model_hint` | não | Tier de modelo sugerido: `"fast"` \| `"balanced"` \| `"powerful"`. Ver `<model_hints>`. |
+
+**Personas disponíveis:** `executor`, `planner`, `verifier`, `researcher`, `debugger`, `architect`, `ui-specialist`, `db-specialist`. Ver `oxe/personas/README.md` para descrição de cada uma. Personas customizadas do projeto ficam em `.oxe/personas/`.
 
 **Regras de desenho:** preferir **um agente por domínio** (DB, API, UI) e **várias `Tn`** no mesmo agente quando partilham contexto; usar **agentes separados** quando o contexto mínimo diverge forte (evita fugas de foco).
 </format_plan_agents_json>
@@ -61,7 +106,7 @@ Cada **agente**:
 <plan_agent_quality_gate>
 Antes de finalizar, validar **em conjunto** `PLAN.md` + `plan-agents.json`:
 
-1. **Schema:** JSON válido; `oxePlanAgentsSchema === 2`; presentes **`runId`** e **`lifecycle`** com `status: pending_execute` e `since` ISO; todos os `id` de agente únicos.
+1. **Schema:** JSON válido; `oxePlanAgentsSchema ∈ {2, 3}` (3 para novos blueprints); presentes **`runId`** e **`lifecycle`** com `status: pending_execute` e `since` ISO; todos os `id` de agente únicos. Se schema 3: `model_hint` de cada agente é `"fast"`, `"balanced"`, `"powerful"` ou ausente.
 2. **Cobertura de tarefas:** a união dos `taskIds` de todos os agentes é **igual** ao conjunto de `### Tn` presentes no `PLAN.md` (sem tarefa órfã nem tarefa duplicada entre agentes).
 3. **Dependências de agente:** só referenciam `id` existentes; **sem ciclos**; se o agente A depende de B, então **onda(B) < onda(A)** em `execution.waves` (primeira aparição do id define a onda).
 4. **Ondas:** cada `id` em `agents` aparece **exatamente uma vez** no total das `waves`; ordem das ondas reflete dependências e alinha com **Onda:** do `PLAN.md` (tarefas na mesma onda do PLAN podem mapear para agentes na mesma wave se não houver dependência agente-a-agente).
@@ -69,6 +114,8 @@ Antes de finalizar, validar **em conjunto** `PLAN.md` + `plan-agents.json`:
 6. **Alinhamento SPEC:** cada `scope` relevante deve ser rastreável a critérios **A*** via `taskIds` → **Aceite vinculado** no PLAN.
 7. **Artefactos de mensagens:** pasta **`.oxe/plan-agent-messages/`** existe e contém **`README.md`** (conteúdo baseado em **`oxe/templates/plan-agent-messages-README.template.md`**).
 
+8. **Isolamento:** `runId` gerado é novo e único; se havia blueprint anterior com status não-terminal, foi invalidado com `invalidatedBy: "new_plan"` antes de criar o novo (ver `<agent_isolation_rule>`).
+
 Resumo obrigatório no chat: `Gate plan-agent: OK` ou `Gate plan-agent: corrigido (N problemas)`.
 </plan_agent_quality_gate>
 
@@ -77,7 +124,7 @@ Resumo obrigatório no chat: `Gate plan-agent: OK` ou `Gate plan-agent: corrigid
 2. Conceber **agentes** e **ondas** (grafo por dependências de domínio); depois derivar **tarefas `Tn`** com o formato habitual do PLAN (uma tarefa continua a ser a unidade de **Verificar** e **Aceite vinculado**).
 3. Escrever **`.oxe/PLAN.md`** (cabeçalho YAML como em `oxe/templates/PLAN.template.md`; em **--replan**, secção Replanejamento).
 4. Gerar **`runId`** novo e **`lifecycle`**: `{ "status": "pending_execute", "since": "<ISO agora>" }`.
-5. Escrever **`.oxe/plan-agents.json`** a partir de **`oxe/templates/plan-agents.template.json`**, com **`oxePlanAgentsSchema: 2`**, `goal`, `agents`, `execution`, `runId`, `lifecycle`.
+5. Escrever **`.oxe/plan-agents.json`** a partir de **`oxe/templates/plan-agents.template.json`**, com **`oxePlanAgentsSchema: 3`**, `goal`, `agents` (incluindo `model_hint` por agente conforme `<model_hints>`), `execution`, `runId`, `lifecycle`.
 6. Criar **`.oxe/plan-agent-messages/`** e **`.oxe/plan-agent-messages/README.md`** a partir de **`oxe/templates/plan-agent-messages-README.template.md`**.
 7. Atualizar **`.oxe/STATE.md`**: fase `plan_ready`, próximo passo `oxe:execute`; preencher **Blueprint de agentes (sessão)** — `run_id` (= `runId`), `lifecycle_status` (= `pending_execute`), **última onda** — (ou `—`).
 8. Aplicar **`<plan_agent_quality_gate>`**; corrigir até passar.

package/oxe/workflows/plan.md

@@ -12,10 +12,11 @@ Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_fai
 </objective>
 
 <context>
+- Se existir **`.oxe/OBSERVATIONS.md`** com entradas `pendente` de impacto `plan` ou `all`, incorporar nas tarefas relevantes antes de finalizar o plano (ajustar implementação, verificação ou escopo de Tn) e marcar essas entradas como `incorporada → plan (data)`.
 - Não inventar APIs inexistentes: cruzar com **STRUCTURE.md**, **INTEGRATIONS.md** e arquivos reais; respeitar **CONCERNS.md** (evitar agravar dívida conhecida sem tarefa explícita).
 - Se existir **`.oxe/NOTES.md`**, rever entradas em aberto: incorporar em tarefas (com **Aceite vinculado** quando aplicável) ou registar na secção **Replanejamento** / nota explícita *fora de âmbito desta trilha*.
 - Se existir **`.oxe/UI-SPEC.md`**, as tarefas de UI devem referenciar secções do UI-SPEC no texto de **Implementação** ou **Verificar**.
-- Se existir **`.oxe/DISCUSS.md`**, alinhar tarefas às decisões registradas.
+- Se existir **`.oxe/DISCUSS.md`**, alinhar tarefas às decisões registradas. Referenciar IDs **D-NN** no campo **Decisão vinculada:** de cada tarefa impactada — se nenhuma decisão impactar a tarefa, omitir o campo. A rastreabilidade D-NN → Tn → verify é usada pela seção **Fidelidade de decisões** do verify.
 - Se existir **`.oxe/RESEARCH.md`** e notas em **`.oxe/research/*.md`**, ler o índice e as notas cujo **Tema** cruza o âmbito do plano (ou as mais recentes relevantes). Se o índice marcar **Estado** pendente em tópico bloqueante, pedir nova sessão **research** ou **discuss**, ou registar **suposição explícita** no PLAN antes de ondas que dependam dessa decisão.
 - Se existir **`.oxe/plan-agents.json`** (gerado por **`/oxe-plan-agent`**), um **--replan** ou renumerar tarefas deve **atualizar o JSON em conjunto** com o `PLAN.md` (cobertura `taskIds`, ondas e dependências entre agentes) — ver **`oxe/workflows/plan-agent.md`**. Preferir **`/oxe-plan-agent --replan`** para regerar **`runId`**, **`lifecycle`** (`pending_execute`) e alinhar **STATE.md**; se só **`/oxe-plan`** for usado, ou o JSON fica manualmente sincronizado, ou marcar no JSON `lifecycle.invalidatedBy: new_plan` até novo plan-agent.
 - Se existirem **`.oxe/CODEBASE-DELTA.md`** e/ou **`.oxe/RESUME.md`** (tipicamente após **`/oxe-compact`**), ler **antes** de detalhar tarefas: o delta resume o que mudou nos mapas face ao código; o RESUME ancora fase e trilha OXE — **não** substituem SPEC nem os sete ficheiros em `codebase/`.
@@ -38,6 +39,8 @@ Cada tarefa em PLAN.md deve seguir:
   - Comando: `...` (ex.: npm test, pytest, mvn test)
   - Manual: (opcional) passos breves
 - **Aceite vinculado:** A1, A2 (IDs exatos da tabela de critérios da SPEC)
+- **Decisão vinculada:** D-01, D-02 (IDs de `.oxe/DISCUSS.md` — omitir se não houver DISCUSS)
+<!-- oxe-task: {"id":"Tn","wave":1,"type":"feature","files":[],"done":false} -->
 ```
 
 **Projetos sem suíte de testes única (legado):** o bloco **Verificar** pode usar `Comando: —` e **Manual** com Grep, leitura de paths ou checklist — ver exemplos em **`oxe/workflows/references/legacy-brownfield.md`**. Todo critério **A*** da SPEC deve aparecer em **Aceite vinculado** de alguma tarefa ou como gap explícito.
@@ -54,6 +57,7 @@ Antes de finalizar a resposta ao utilizador, o agente **deve** percorrer este ga
 4. **Ondas:** cada número de **Onda:** usado tem pelo menos uma tarefa; sem ondas vazias.
 5. **`plan_max_tasks_per_wave`:** se `.oxe/config.json` tiver valor **> 0**, contar tarefas por **Onda**; nenhuma onda excede o limite.
 6. **UI-SPEC:** se existir `.oxe/UI-SPEC.md`, toda tarefa cuja **Implementação** ou **Verificar** toque UI (paths como `*.tsx`, `components/`, ou palavras-chave front, ou pedido explícito do utilizador) deve citar **secção § do UI-SPEC** ou path explícito.
+7. **Fidelidade de decisões:** se existir `.oxe/DISCUSS.md` com IDs **D-NN**, cada decisão com impacto técnico deve aparecer em **Decisão vinculada:** de alguma tarefa, ou ter nota explícita de gap (fora do escopo desta entrega). Sem cobertura para D-NN técnico = falha do gate.
 
 Se após correções estruturais persistir ambiguidade de produto: **uma** frase recomendando `oxe:discuss` ou `oxe:spec`.
 
@@ -69,7 +73,8 @@ Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N
 6. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes; respeitar `plan_max_tasks_per_wave` se configurado.
 7. Aplicar integralmente o bloco **`<plan_quality_gate>`** acima ao `PLAN.md` em disco; corrigir o ficheiro até passar ou documentar gaps explícitos.
 8. Atualizar `.oxe/STATE.md`: fase `plan_ready`, próximo passo `oxe:execute` (implementar ondas) e depois `oxe:verify`.
-9. Listar no chat: resultado do gate (OK ou corrigido), ondas, contagem de tarefas, comando de teste guarda-chuva se houver.
+9. **Sugestão de agentes (inteligente):** após o gate passar, verificar se o plano tem 3+ domínios distintos (ex.: backend + frontend + DB, ou auth + notificações + UI). Se sim, sugerir proativamente: "Este plano tem N domínios distintos. Quer gerar um blueprint de agentes com `/oxe-plan --agents`?" — não executar automaticamente, apenas oferecer. Se o usuário incluiu `--agents` no input original, executar imediatamente a lógica de `oxe/workflows/plan-agent.md`.
+10. Listar no chat: resultado do gate (OK ou corrigido), ondas, contagem de tarefas, comando de teste guarda-chuva se houver.
 </process>
 
 <success_criteria>

package/oxe/workflows/project.md

@@ -0,0 +1,50 @@
+# OXE — Workflow: project (gestão de projeto)
+
+<objective>
+Ponto de entrada unificado para as três operações de gestão de projeto OXE:
+
+- **milestone** — marcos de entrega (M-NN): `new`, `complete`, `status`, `audit`
+- **workstream** — trilhas paralelas: `new <nome>`, `switch <nome>`, `list`, `close <nome>`
+- **checkpoint** — snapshot nomeado de sessão: `[slug]`
+
+Detecta a operação pelo primeiro token do input e delega ao workflow canônico correspondente.
+</objective>
+
+<context>
+- Este workflow é um **dispatcher**: lê o input, identifica a operação e executa o workflow correto.
+- Workflows canônicos: `oxe/workflows/milestone.md`, `oxe/workflows/workstream.md`, `oxe/workflows/checkpoint.md`.
+- Se o input for ambíguo, apresentar as 3 operações disponíveis e pedir escolha.
+- Sem input: mostrar o estado atual de milestones e workstreams ativos lendo `STATE.md`, `MILESTONES.md` e `CHECKPOINTS.md`.
+</context>
+
+<dispatch_table>
+| Input começa com | Delega para | Exemplos |
+|------------------|-------------|---------|
+| `milestone new ...` | `milestone.md` + subcomando `new` | `/oxe-project milestone new v1.0` |
+| `milestone complete` | `milestone.md` + subcomando `complete` | `/oxe-project milestone complete` |
+| `milestone status` | `milestone.md` + subcomando `status` | `/oxe-project milestone status` |
+| `milestone audit` | `milestone.md` + subcomando `audit` | `/oxe-project milestone audit` |
+| `workstream new <nome>` | `workstream.md` + subcomando `new` | `/oxe-project workstream new auth` |
+| `workstream switch <nome>` | `workstream.md` + subcomando `switch` | `/oxe-project workstream switch auth` |
+| `workstream list` | `workstream.md` + subcomando `list` | `/oxe-project workstream list` |
+| `workstream close <nome>` | `workstream.md` + subcomando `close` | `/oxe-project workstream close auth` |
+| `checkpoint [slug]` | `checkpoint.md` | `/oxe-project checkpoint pre-refactor` |
+| *(sem input)* | Status atual | `/oxe-project` |
+</dispatch_table>
+
+<process>
+1. Ler o input do usuário (texto após o comando).
+2. Identificar o primeiro token:
+   - `milestone` → carregar e executar `oxe/workflows/milestone.md` passando o restante como subcomando.
+   - `workstream` → carregar e executar `oxe/workflows/workstream.md` passando o restante como subcomando.
+   - `checkpoint` → carregar e executar `oxe/workflows/checkpoint.md` passando o slug (se houver).
+   - *(vazio)* → ler `STATE.md`, `MILESTONES.md` (se existir) e listar: milestone ativo (M-NN / nenhum), workstreams abertos, último checkpoint. Sugerir próxima operação.
+   - *(ambíguo)* → listar as 3 operações disponíveis com exemplos de uso.
+3. Executar o workflow delegado integralmente.
+</process>
+
+<success_criteria>
+- [ ] O workflow correto foi executado com base no input.
+- [ ] Sem input: STATUS atual de milestone ativo, workstreams e último checkpoint mostrado.
+- [ ] Input ambíguo: máximo 3 opções apresentadas com exemplos, não listas longas.
+</success_criteria>

package/oxe/workflows/quick.md

@@ -3,15 +3,114 @@
 <objective>
 Registrar trabalho **rápido a médio** sem SPEC/PLAN completos: objetivo claro, passos curtos e uma verificação. Saída principal: **`.oxe/QUICK.md`** + atualização de **`.oxe/STATE.md`**.
 
-Usar quando: correção pontual, refactor local, uma feature pequena, ou protótipo que **não** justifica critérios de aceite longos.
+Quando o trabalho envolve **2 ou mais domínios distintos** (ex.: backend + frontend, DB + API, CLI + UI), aplicar também o conceito de **Plan-Driven Dynamic Agents — lean**: agentes focados derivados dos passos do QUICK.md, criados para esta demanda específica, sem reutilização entre demandas. O modo com agentes cria também **`.oxe/quick-agents.json`**.
+
+Usar quando: correção pontual, refactor local, feature pequena ou protótipo que **não** justifica critérios de aceite completos.
 </objective>
 
 <context>
 - Ler `.oxe/STATE.md` e, se existirem, `OVERVIEW.md` e `STACK.md` em `.oxe/codebase/` para não contradizer o repo.
 - Não apagar `SPEC.md` / `PLAN.md` se existirem; este fluxo é paralelo ou temporário.
-- **Blueprint plan-agent:** este fluxo **não** reutiliza papéis (`role` / `scope`) de **`.oxe/plan-agents.json`**. Se existir `plan-agents.json` com **`oxePlanAgentsSchema: 2`** e `lifecycle.status` **não** for já `invalidated`, **invalidar** o blueprint após criar/substituir **`QUICK.md`**: `lifecycle: { "status": "invalidated", "since": "<ISO>", "invalidatedBy": "quick", "invalidatedReason": "oxe-quick substitui trilha focada do blueprint" }`. Actualizar **`.oxe/STATE.md`** — secção **Blueprint de agentes (sessão)**: **lifecycle_status** → `invalidated`, nota “invalidado por quick”. Não escrever novas mensagens em **`.oxe/plan-agent-messages/`** para o `runId` invalidado.
+- **Blueprint plan-agent:** este fluxo **não** reutiliza papéis (`role` / `scope`) de **`.oxe/plan-agents.json`**. Se existir `plan-agents.json` com **`oxePlanAgentsSchema: 2`** e `lifecycle.status` **não** for já `invalidated`, **invalidar** o blueprint após criar/substituir **`QUICK.md`**: `lifecycle: { "status": "invalidated", "since": "<ISO>", "invalidatedBy": "quick", "invalidatedReason": "oxe-quick substitui trilha focada do blueprint" }`. Actualizar **`.oxe/STATE.md`** — secção **Blueprint de agentes (sessão)**: **lifecycle_status** → `invalidated`, nota "invalidado por quick". Não escrever novas mensagens em **`.oxe/plan-agent-messages/`** para o `runId` invalidado.
+- **Quick-agents anterior:** se existir **`.oxe/quick-agents.json`** com `status` diferente de `done` ou `invalidated`, invalidá-lo antes de criar o novo (`status: "invalidated", "since": "<ISO>", "reason": "novo quick iniciado"`).
 </context>
 
+<plan_driven_dynamic_agents_lean>
+## Plan-Driven Dynamic Agents — lean (integrado ao Quick)
+
+### Os três princípios que guiam este modo
+
+**1. Spec-Driven Design**
+O campo `## Objetivo` de **`QUICK.md`** é a **minispec**: define o que pode ser construído, os limites do escopo e o critério de "pronto" (bloco `## Verificar`). Nenhum agente pode adicionar escopo além desse objetivo. A minispec precede e restringe os agentes.
+
+**2. Spec-Driven Development**
+Os `## Passos` de **`QUICK.md`** são o **mini-plano**: cada passo é acionável, sequenciado e rastreável ao bloco `## Verificar`. Os agentes são **derivados dos passos** — os passos definem o trabalho; os agentes organizam quem faz o quê. Nunca o contrário.
+
+**3. Plan-Driven Dynamic Agents**
+Os agentes são criados **a partir dos passos**, **para esta demanda específica**, e são **invalidados** quando o quick termina ou é superado por um plano completo. Não há reuso de agentes entre demandas distintas. Cada new quick = novos agentes, se aplicável.
+
+### Quando ativar PDDA no Quick
+
+Ativar quando **qualquer** condição for verdadeira:
+- Os passos tocam **2 ou mais domínios distintos** (ex.: API e UI, DB e cache, backend e CLI)
+- O usuário pede explicitamente com `--agents`
+- Há **5 ou mais passos** que se agrupam naturalmente em responsabilidades diferentes
+
+**Não** ativar quando: todos os passos ficam no mesmo módulo ou camada, há ≤ 3 passos, ou o trabalho é puramente de conteúdo (docs, config).
+
+**Se precisar de mais de 3 agentes:** o trabalho não é mais "quick" → promover para **`/oxe-plan-agent`**.
+
+### Formato dos agentes no QUICK.md
+
+Cada passo recebe uma anotação de agente (`<!-- agente: id -->`). Uma seção `## Agentes dinâmicos` é adicionada:
+
+```markdown
+## Agentes dinâmicos (lean PDDA)
+> Derivados dos passos deste QUICK.md — spec-driven (objetivo restringe escopo) e plan-driven (passos definem tarefas).
+> Criados para **esta demanda**. Invalidados ao promover para spec/plan ou ao iniciar novo quick.
+
+| ID | Papel nesta demanda | Passos | Persona |
+|----|---------------------|--------|---------|
+| auth-backend | Especialista em JWT e middleware Express para este quick | 1–3 | executor |
+| login-ui | Especialista em integração do formulário de login React | 4–5 | ui-specialist |
+```
+
+**Regras de desenho:**
+- **`role`** deve ser específico ao domínio da demanda: não "Backend Developer" genérico, mas "Especialista em JWT para autenticação neste quick"
+- **`persona`** usa as personas disponíveis: `executor`, `planner`, `verifier`, `researcher`, `debugger`, `architect`, `ui-specialist`, `db-specialist`
+- Cada agente cobre steps **contíguos ou logicamente agrupados** (não intercalar responsabilidades)
+- Máximo **3 agentes** por quick
+
+### Arquivo `.oxe/quick-agents.json`
+
+Criar junto ao QUICK.md quando PDDA estiver ativo (usar como base `oxe/templates/quick-agents.template.json`):
+
+```json
+{
+  "oxeQuickAgentsSchema": 1,
+  "quickId": "quick-<YYYY-MM-DD>-<6hex>",
+  "quickRef": ".oxe/QUICK.md",
+  "status": "active",
+  "since": "<ISO agora>",
+  "agents": [
+    {
+      "id": "auth-backend",
+      "role": "Especialista em JWT e middleware Express para este quick",
+      "persona": "executor",
+      "steps": [1, 2, 3],
+      "focus": "Implementar signing/verification de JWT e middleware de auth"
+    },
+    {
+      "id": "login-ui",
+      "role": "Especialista em integração do formulário de login React",
+      "persona": "ui-specialist",
+      "steps": [4, 5],
+      "focus": "Integrar token JWT no componente Login e feedback de erro"
+    }
+  ]
+}
+```
+
+**Lifecycle de `status`:** `active` → `done` (verify concluído com sucesso) | `invalidated` (novo quick/plan/plan-agent iniciado)
+
+### Como `/oxe-execute` usa quick-agents
+
+Quando **`quick-agents.json`** tiver `status: active` e QUICK.md existir:
+- `/oxe-execute` adota o `role` e `persona` de cada agente para os steps atribuídos
+- Cada agente trabalha **somente** nos steps listados em `steps[]`
+- Não há protocolo de handoff entre agentes (lean: sem `.oxe/plan-agent-messages/`)
+- Ao concluir todos os steps: sugerir `/oxe-verify` e marcar `quick-agents.json` → `status: done`
+
+### Invalidação de quick-agents
+
+| Evento | Ação sobre `quick-agents.json` |
+|--------|-------------------------------|
+| Novo `/oxe-quick` iniciado | `status: "invalidated"`, `reason: "novo quick"` |
+| `/oxe-plan` ou `/oxe-plan-agent` chamado | `status: "invalidated"`, `reason: "promovido a plano"` |
+| `/oxe-verify` confirma sucesso total | `status: "done"` |
+| Invalidação manual pelo usuário | `status: "invalidated"`, `reason: "manual"` |
+</plan_driven_dynamic_agents_lean>
+
 ## Perfil fast (modo trivial)
 
 Uso **sem** novo slash: é o mesmo `/oxe-quick` com redação mínima.
@@ -19,6 +118,7 @@ Uso **sem** novo slash: é o mesmo `/oxe-quick` com redação mínima.
 - **Objetivo** — uma frase no `.oxe/QUICK.md`.
 - **Passos** — lista numerada, **máximo 10**; cada passo acionável numa linha.
 - **Verificar** — um comando de terminal **ou** checklist manual explícito.
+- **Agentes dinâmicos** — seção opcional quando PDDA estiver ativo (ver acima).
 - **Promover para spec/plan?** — preencher sempre; se qualquer gatilho abaixo for verdadeiro, resposta **sim** e parar de acumular trabalho no QUICK — passar a **`/oxe-spec`** (e depois discuss/plan conforme config).
 
 O perfil fast **não** é uma segunda trilha: continua sujeito à mesma promoção obrigatória quando o trabalho deixa de ser trivial.
@@ -31,6 +131,7 @@ Promova **nesta sessão ou na próxima** se **qualquer** condição for verdadei
 - Mudança de **contrato público** (API HTTP, schema de dados exposto, eventos, SDK).
 - **Segurança**, **dados pessoais**, **auth** ou **conformidade** envolvidos.
 - O próprio quick ficar com **mais de 10 passos** — dividir ou passar a SPEC.
+- PDDA lean precisaria de **mais de 3 agentes** — promover para **`/oxe-plan-agent`**.
 
 No final de **`.oxe/QUICK.md`**, mantenha a linha:
 
@@ -40,20 +141,29 @@ Se **sim**, o próximo passo recomendado no chat é **`/oxe-spec`** (depois disc
 
 <process>
 1. Garantir `.oxe/` (usar template de STATE só se `STATE.md` não existir).
-2. Criar ou substituir **`.oxe/QUICK.md`** com:
-   - **Objetivo** — uma frase.
+2. Avaliar se PDDA lean se aplica (ver `<plan_driven_dynamic_agents_lean>` — domínios distintos, 5+ passos, ou flag `--agents`).
+3. Criar ou substituir **`.oxe/QUICK.md`** com:
+   - **Objetivo** — uma frase. *(Esta é a minispec: restringe o escopo de todos os agentes e passos.)*
    - **Contexto** — 2–5 bullets (arquivos/pastas já vistos).
-   - **Passos** — lista numerada, **máximo 10** passos acionáveis.
-   - **Verificar** — pelo menos um: comando de terminal (ex.: `npm test`) **ou** checklist manual explícito.
+   - **Passos** — lista numerada, **máximo 10** passos acionáveis; se PDDA ativo, anotar `<!-- agente: id -->` em cada passo.
+   - **Agentes dinâmicos** *(somente se PDDA ativo)* — tabela com ID, papel, steps, persona.
+   - **Verificar** — pelo menos um: comando de terminal (ex.: `npm test`) **ou** checklist manual explícito. *(Este é o critério de aceite da minispec.)*
    - **Promover para spec/plan?** — conforme seção acima.
-3. Se existir **`.oxe/plan-agents.json`** com schema 2 e lifecycle ainda não `invalidated`, aplicar a invalidação descrita em **context** (actualizar JSON + **STATE.md** — blueprint de agentes).
-4. Atualizar **`.oxe/STATE.md`**: fase `quick_active`, próximo passo `oxe:execute` ou implementação manual + `oxe:verify`.
-5. Responder no chat com resumo em ≤8 linhas e o comando de verificação escolhido; se promover = sim, destacar **`/oxe-spec`** como próximo passo lógico; se o blueprint foi invalidado, mencionar **`/oxe-plan-agent`** para novo roteiro com agentes.
+4. Se PDDA ativo, criar **`.oxe/quick-agents.json`** usando `oxe/templates/quick-agents.template.json`:
+   - Gerar `quickId` novo (`quick-<YYYY-MM-DD>-<6hex>`).
+   - `status: "active"`, `since: "<ISO agora>"`.
+   - Preencher `agents[]` derivando de cada grupo de passos do QUICK.md.
+5. Se existir **`.oxe/plan-agents.json`** com schema 2 e lifecycle ainda não `invalidated`, aplicar a invalidação descrita em **context** (actualizar JSON + **STATE.md** — blueprint de agentes).
+6. Se existir **`.oxe/quick-agents.json`** anterior com `status` não-terminal, invalidá-lo (ver **context**).
+7. Atualizar **`.oxe/STATE.md`**: fase `quick_active`, próximo passo `oxe:execute` ou implementação manual + `oxe:verify`; se PDDA ativo, registrar `quick_agents_status: active` e `quick_id: <quickId>`.
+8. Responder no chat com resumo em ≤10 linhas: objetivo, passos, agentes (se PDDA ativo), verificação; se promover = sim, destacar **`/oxe-spec`** como próximo passo lógico; se blueprint plan-agent foi invalidado, mencionar **`/oxe-plan-agent`** para novo roteiro.
 </process>
 
 <success_criteria>
-- [ ] `.oxe/QUICK.md` existe com passos e bloco **Verificar**.
+- [ ] `.oxe/QUICK.md` existe com objetivo (minispec), passos (mini-plano) e bloco **Verificar** (critério de aceite).
 - [ ] `STATE.md` reflete fase `quick_active` e próximo passo coerente.
 - [ ] Fica explícito quando **promover** para spec/plan (regra acima + campo no arquivo).
 - [ ] Se havia blueprint schema 2 activo, `plan-agents.json` e `STATE.md` reflectem **`invalidated`** por quick.
+- [ ] Se PDDA ativo: `quick-agents.json` existe com `status: active`, `quickId` único, agentes com `role` específico à demanda, `steps` alinhados aos passos do QUICK.md; seção `## Agentes dinâmicos` presente no QUICK.md.
+- [ ] Se PDDA ativo: máximo 3 agentes; se mais necessário, QUICK.md declara `Promover para spec/plan?: sim` com razão "necessita > 3 agentes".
 </success_criteria>

package/oxe/workflows/research.md

@@ -16,6 +16,22 @@ Não substitui **SPEC** nem **PLAN**; alimenta decisões que depois entram na SP
 - Segurança: não gravar segredos nem valores de variáveis de ambiente.
 </context>
 
+<thinking_depth>
+## Profundidade de Raciocínio
+
+Antes de iniciar a pesquisa, classificar o tipo de investigação e calibrar a profundidade:
+
+| Tipo | Indicadores | Abordagem |
+|------|-------------|-----------|
+| `surface` | Coletar fatos, comparar 2-3 opções conhecidas, confirmar API | Pesquisa padrão — fontes diretas, resposta objetiva |
+| `standard` | Análise de trade-offs, integração de sistemas, avaliação de bibliotecas | Evidências múltiplas, prós/contras explícitos, referências cruzadas |
+| `deep` | Reverse engineering de sistema existente, design de arquitetura nova, migração complexa, brownfield | **Extended thinking recomendado** se o modelo suportar — ativar raciocínio estendido antes de produzir a nota |
+
+Anotar `thinking_depth: surface | standard | deep` no frontmatter da nota de pesquisa gerada.
+
+**Quando `deep`:** instrua o modelo (explicitamente se necessário) a "raciocinar em profundidade antes de escrever a nota" — explorando hipóteses, descartando alternativas, mapeando incertezas antes de consolidar evidências.
+</thinking_depth>
+
 <process>
 1. Garantir pastas `.oxe/` e `.oxe/research/`.
 2. Escolher `YYYY-MM-DD-<slug>.md` único; se colisão, acrescentar sufixo ao slug (ex. `-b`).