oxe-cc 0.5.0 → 0.6.0

package/commands/oxe/loop.md

@@ -0,0 +1,17 @@
+---
+name: oxe:loop
+description: OXE — Execução iterativa de onda com retries automáticos e diagnóstico inline
+argument-hint: "onda <N> [max:<tentativas>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Task
+---
+
+**Workflow canônico:** `oxe/workflows/loop.md`
+
+Execute integralmente esse ficheiro na raiz do repositório. `$ARGUMENTS` = onda alvo e máximo de tentativas. Pré-requisito: `.oxe/PLAN.md`.

package/commands/oxe/oxe.md

@@ -0,0 +1,16 @@
+---
+name: oxe
+description: OXE — Entrada universal: próximo passo, roteamento de linguagem natural ou help dos 8 comandos essenciais
+argument-hint: "[contexto | 'help' | vazio]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canônico:** `oxe/workflows/oxe.md`
+
+Execute integralmente esse ficheiro. `$ARGUMENTS`: vazio → próximo passo; texto → roteamento inteligente; "help" → 8 comandos essenciais.

package/commands/oxe/project.md

@@ -0,0 +1,16 @@
+---
+name: oxe:project
+description: OXE — Gestão de projeto: milestone (M-NN), workstream (trilhas paralelas), checkpoint (snapshot)
+argument-hint: "milestone new|complete|status|audit | workstream new|switch|list|close <nome> | checkpoint [slug]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canônico:** `oxe/workflows/project.md`
+
+Execute integralmente esse ficheiro. `$ARGUMENTS` = subcomando. Sem argumento: mostra status atual (milestone ativo, workstreams, último checkpoint).

package/commands/oxe/security.md

@@ -0,0 +1,16 @@
+---
+name: oxe:security
+description: OXE — Auditoria de segurança OWASP (.oxe/SECURITY.md): P0 crítico / P1 alto / P2 médio
+argument-hint: "[opcional: categoria OWASP, módulo ou arquivo]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canônico:** `oxe/workflows/security.md`
+
+Execute integralmente esse ficheiro na raiz do repositório. Lê `STACK.md` para determinar categorias OWASP pertinentes. `$ARGUMENTS` = foco opcional.

package/oxe/templates/SECURITY.template.md

@@ -0,0 +1,72 @@
+---
+oxe_doc: security
+status: draft
+updated: YYYY-MM-DD
+stack_ref: .oxe/codebase/STACK.md
+plan_ref: .oxe/PLAN.md
+---
+
+# Auditoria de Segurança OXE
+
+## Stack e escopo
+
+**Stack identificado:** [linguagem, framework, DB, auth]
+**Categorias OWASP avaliadas:** A01, A02, A03, ...
+**Categorias descartadas:** A04 (motivo), A08 (motivo), ...
+
+---
+
+## Achados
+
+### P0 — Crítico (requer ação imediata)
+
+| ID | Categoria | Arquivo:linha | Padrão encontrado | Recomendação | Tarefa |
+|----|-----------|--------------|-------------------|--------------|--------|
+| S-01 | A07 — Auth | `src/auth/login.ts:42` | Senha comparada sem hash | Usar bcrypt/argon2 | T_new |
+
+### P1 — Alto (antes do próximo deploy)
+
+| ID | Categoria | Arquivo:linha | Padrão encontrado | Recomendação | Tarefa |
+|----|-----------|--------------|-------------------|--------------|--------|
+| S-02 | A05 — Config | `.env.example:8` | JWT_SECRET sem rotação documentada | Documentar política de rotação | T3 |
+
+### P2 — Médio (ação recomendada, compensação aceitável)
+
+| ID | Categoria | Arquivo:linha | Padrão encontrado | Recomendação | Tarefa |
+|----|-----------|--------------|-------------------|--------------|--------|
+| S-03 | A09 — Logging | `src/api/handler.ts:15` | Erro logado com stack trace completo em produção | Filtrar dados sensíveis em prod | T_new |
+
+---
+
+## Resultado por categoria
+
+| Categoria OWASP | Status | Achados |
+|-----------------|--------|---------|
+| A01 — Broken Access Control | ✅ Sem achados | — |
+| A02 — Cryptographic Failures | ⚠️ P1 | S-02 |
+| A03 — Injection | ✅ Sem achados | — |
+| A05 — Security Misconfiguration | ⚠️ P1 | S-02 |
+| A07 — Authentication Failures | ❌ P0 | S-01 |
+| A09 — Logging & Monitoring | ⚠️ P2 | S-03 |
+
+---
+
+## Sugestões de tarefas novas
+
+```
+T_new-S01: Implementar hash de senha com bcrypt (custo ≥ 12)
+  Verificar: login falha com senha errada; hash visível no DB.
+  Aceite vinculado: [A* de segurança se existir na SPEC]
+
+T_new-S03: Filtrar stack traces em logs de produção
+  Verificar: log em NODE_ENV=production não expõe stacktrace.
+  Aceite vinculado: —
+```
+
+---
+
+## Próximo passo
+
+- **P0 presente:** ação obrigatória antes de qualquer deploy — criar tarefas e adicionar ao PLAN via `/oxe-plan --replan`.
+- **Apenas P1/P2:** priorizar P1 na próxima onda; P2 pode ir para backlog v2.
+- **Sem achados:** registrar como "auditoria limpa em YYYY-MM-DD" e prosseguir.

package/oxe/templates/plan-agents.template.json

@@ -1,5 +1,5 @@
 {
-  "oxePlanAgentsSchema": 2,
+  "oxePlanAgentsSchema": 3,
   "runId": "oxe-YYYY-MM-DD-substituir-por-id-opaco",
   "lifecycle": {
     "status": "pending_execute",
@@ -18,7 +18,8 @@
       "taskIds": ["T1"],
       "dependencies": [],
       "inputs": [".oxe/STATE.md", ".oxe/SPEC.md"],
-      "outputs": ["src/example.ts"]
+      "outputs": ["src/example.ts"],
+      "model_hint": "balanced"
     }
   ],
   "execution": {

package/oxe/workflows/execute.md

@@ -72,11 +72,33 @@ Este plano tem [N] tarefas em [X] ondas. Como quer executar?
 **Persistir escolha:** registrar em STATE.md: `execute_mode: completo | por_onda | por_tarefa`. Se STATE já tiver o campo, não perguntar novamente — usar o modo armazenado.
 </execution_mode_selection>
 
+<failure_mode>
+## Modo de falha inline (Verificar falha durante execute)
+
+Quando o comando `**Verificar:**` de uma tarefa `Tn` falha, **não parar silenciosamente**. Executar este ciclo inline sem exigir que o usuário chame `/oxe-debug` separadamente:
+
+1. **Diagnóstico rápido:** listar 2-3 hipóteses de causa baseadas no output de erro.
+2. **Fix mais provável:** aplicar o fix para a hipótese #1.
+3. **Re-verificar:** rodar o `Verificar` novamente.
+4. Se passou: continuar onda normalmente; registrar na onda que houve 1 iteração de fix.
+5. Se falhou novamente (2ª tentativa): aplicar hipótese #2 e tentar 1 vez mais.
+6. Se falhou após 2 tentativas: **pausar** — exibir as hipóteses testadas, evidências coletadas, e sugerir `/oxe-forensics` com contexto completo. Registrar em STATE.md: `execute_blocked: Tn | motivo`.
+
+**Auto-loop no Modo B:** se `execute_mode: por_onda` e `loop_max` > 1 em STATE.md, o ciclo de retry roda automaticamente até `loop_max` tentativas antes de escalar para forensics.
+</failure_mode>
+
 <context>
 **Observações pendentes:** verificar `.oxe/OBSERVATIONS.md` no início de cada onda. Se houver entradas `pendente` com impacto `execute` ou `all`, incorporar no trabalho da onda atual e marcá-las `incorporada → execute (data)`.
 
 **Quick-agents (lean PDDA):** se existir **`.oxe/quick-agents.json`** com `status: active` e a execução for baseada em **`QUICK.md`** (não há PLAN.md), adotar o `role` e `persona` de cada agente para os `steps[]` atribuídos. Ao concluir todos os steps, marcar `quick-agents.json` → `status: done` e sugerir `/oxe-verify`.
 
+**Model hints (blueprint com agentes):** ao apresentar a atribuição de cada agente no início da onda, exibir `model_hint` se presente:
+```
+Agente: agent-auth — "Especialista em JWT"  [modelo: powerful]
+Tarefas: T1, T2
+```
+Se `model_hint` estiver ausente, não exibir a linha. O usuário pode configurar o modelo no IDE antes de iniciar aquele agente.
+
 **Blueprint plan-agent (Modo com Agentes):** adotar `role`/`scope` de **`.oxe/plan-agents.json`** SOMENTE quando:
 1. `lifecycle.status` ∈ `{ pending_execute, executing }` (não usar se `closed` ou `invalidated`).
 2. **`runId`** no JSON coincide com **`run_id`** no STATE.md (secção Blueprint de agentes).

package/oxe/workflows/help.md

@@ -11,11 +11,30 @@ No **projeto**, os passos canónicos estão em **`.oxe/workflows/*.md`** (layout
 </context>
 
 <output>
+## Os 8 comandos essenciais
+
+```
+/oxe              → onde estou / o que faço / help (entrada universal)
+/oxe-obs          → registrei algo importante — incorporado automaticamente nos próximos passos
+/oxe-quick        → tarefa pequena, sem cerimônia (com agentes lean quando necessário)
+/oxe-scan         → mapeia o projeto (ou atualiza o mapa se já existir)
+/oxe-spec         → nova feature: perguntas → pesquisa → requisitos → roteiro → aprovação
+/oxe-plan         → tarefas por onda (--agents para blueprint multi-agente)
+/oxe-execute      → implementar (A: 1 sessão | B: por onda | C: por tarefa)
+/oxe-verify       → validar (camadas 5+6 opcionais via config: gaps + segurança)
+```
+
+Tudo o mais é ativado automaticamente por contexto, por config, ou existe como escape hatch.
+
+---
+
 ## Integrações principais (referência)
 
 ### Cursor
 
-Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-plan-agent`, `/oxe-verify`, `/oxe-next`, `/oxe-quick`, `/oxe-execute`, `/oxe-obs`, `/oxe-update`, `/oxe-help`, `/oxe-forensics`, `/oxe-debug`, `/oxe-route`, `/oxe-research`, `/oxe-validate-gaps`, `/oxe-compact`, `/oxe-checkpoint`, `/oxe-ui-spec`, `/oxe-ui-review`, `/oxe-milestone`, `/oxe-workstream` (instalados em `~/.cursor/commands/` pelo `oxe-cc` após `npm run sync:cursor` no pacote ou cópia equivalente). **Review de PR:** no Cursor não há slash dedicado — peça em linguagem natural seguindo `oxe/workflows/review-pr.md` (ou `.oxe/workflows/review-pr.md`) em contexto.
+Slash commands essenciais: `/oxe`, `/oxe-obs`, `/oxe-quick`, `/oxe-scan`, `/oxe-spec`, `/oxe-plan`, `/oxe-execute`, `/oxe-verify`
+
+Slash commands completos: `/oxe-discuss`, `/oxe-plan-agent`, `/oxe-project`, `/oxe-loop`, `/oxe-security`, `/oxe-update`, `/oxe-forensics`, `/oxe-debug`, `/oxe-route`, `/oxe-research`, `/oxe-validate-gaps`, `/oxe-compact`, `/oxe-checkpoint`, `/oxe-ui-spec`, `/oxe-ui-review`, `/oxe-milestone`, `/oxe-workstream`, `/oxe-next`, `/oxe-help` (instalados em `~/.cursor/commands/` pelo `oxe-cc`). **Review de PR:** no Cursor não há slash dedicado — peça em linguagem natural seguindo `oxe/workflows/review-pr.md` em contexto.
 
 ### GitHub Copilot (VS Code)
 
@@ -49,29 +68,26 @@ Com **`compact_max_age_days`** em `.oxe/config.json` (ver `oxe/templates/CONFIG.
 
 ## Fluxo completo
 
-0. **obs** *(qualquer momento)* — `/oxe-obs` registra uma observação contextual em `.oxe/OBSERVATIONS.md`; incorporada automaticamente no próximo spec/plan/execute sem re-explicar (ver seção **Observações** abaixo).
-1. **scan** — após clonar ou quando o repositório mudar muito. Repositórios **legado** (COBOL, JCL, copybooks, VB6, SQL procedures): o passo **scan** aplica `oxe/workflows/references/legacy-brownfield.md` quando esses sinais existirem — preencha `TESTING.md` com honestidade (sem `npm test` fictício) e use `scan_focus_globs` em `.oxe/config.json` (ver `oxe/templates/CONFIG.md`).
-2. **spec** — fluxo em **5 fases**: perguntas (máx 3 rodadas) → pesquisa (opcional) → requisitos R-ID (v1/v2/fora) → roteiro (`.oxe/ROADMAP.md`) → aprovação → instrui plan ou plan-agent.
-2b. **research** (opcional, pode ser proposto pela Fase 2 do spec) — notas datadas em `.oxe/research/` + índice `.oxe/RESEARCH.md`; spikes, mapa de sistema, engenharia reversa, modernização.
-3. **discuss** (opcional) — decisões com IDs D-NN antes do plano; recomendado se `discuss_before_plan` em `.oxe/config.json`. Incorpora OBS pendentes de impacto spec/plan.
-4. **plan** — plano executável + **Verificar** por tarefa, ligado aos critérios A* da SPEC. Incorpora OBS pendentes de impacto plan.
-4b. **plan-agent** (opcional) — igual ao **plan** + **`.oxe/plan-agents.json`** (schema **2**: `runId` **novo** por demanda, `lifecycle`). Agentes criados especificamente para ESTE plano — sem reuso entre demandas. `/oxe-quick` invalida o blueprint.
-5. **execute** — seleção de modo ao iniciar: **A) Completo** (1 sessão/requisição), **B) Por onda** (N sessões), **C) Por tarefa** (controle máximo). Incorpora OBS pendentes de impacto execute.
-6. Implementar mudanças no agente/editor.
-7. **verify** — 4 camadas: auditoria pré-exec, tarefas + critérios A*, fidelidade D-NN, UAT checklist.
-7b. **validate-gaps** (opcional) — após verify, auditoria de cobertura em `.oxe/VALIDATION-GAPS.md`.
-8. **next** — retomar trabalho; no terminal: **`npx oxe-cc status`** sugere um único próximo passo.
-
-**Recuperação e meta (mesma trilha, outra camada):**
-
-- **`/oxe-forensics`** — após `verify` falhar, `doctor` em falta ou estado incoerente; escreve `.oxe/FORENSICS.md` e recomenda **um** reingresso: `scan`, `plan` ou `execute` (ver `forensics.md`).
-- **`/oxe-debug`** — durante **`execute`**, para sintomas técnicos (teste vermelho, stack); escreve `.oxe/DEBUG.md`; **não** substitui `verify` após corrigir (ver `debug.md`).
-- **`/oxe-route`** — desambigua pedido em linguagem natural → **um** workflow/comando; não gera SPEC/PLAN (ver `route.md` e tabela **Router** abaixo).
-
-**Contexto em disco (opcional):**
-
-- **`/oxe-compact`** — **refresh do projeto**: compara **`.oxe/codebase/*.md`** ao repositório atual, **atualiza** os sete mapas (incremental ou bootstrap como `scan.md` se faltar base), escreve **`.oxe/CODEBASE-DELTA.md`** (o que mudou na documentação) e **`.oxe/RESUME.md`** (trilha OXE + ponte para o delta). Rotina de desenvolvimento; **não** está ligado a limites de chat ou a ferramentas específicas (ver `compact.md`). *Exemplo:* scan mapeou **Angular 17**; após migração implementada para **21**, o compact **corrige** `STACK.md`/testes/convenções face ao repo — intenção: **documentação OXE = código atual**, não refazer scan completo só por bump de major.
-- **`/oxe-checkpoint`** — **snapshot de sessão**: **`.oxe/checkpoints/…md`** + **`.oxe/CHECKPOINTS.md`**; marco nomeado sem apagar SPEC/PLAN (ver `checkpoint.md`).
+0. **obs** *(qualquer momento)* — `/oxe-obs` registra uma observação contextual; incorporada automaticamente no próximo spec/plan/execute sem re-explicar.
+1. **scan** — após clonar ou quando o codebase mudar. **Inteligente:** se `.oxe/codebase/` já existir, opera em modo refresh (incremental) automaticamente — sem precisar chamar `/oxe-compact` separadamente. Use `--full` para forçar scan completo. Repositórios **legado** (COBOL, JCL, VB6): aplica `legacy-brownfield.md` automaticamente.
+2. **spec** — fluxo em **5 fases**: perguntas (máx 3 rodadas) → pesquisa (proposta inline na Fase 2, sem sair do spec) → requisitos R-ID (v1/v2/fora) → roteiro (`.oxe/ROADMAP.md`) → aprovação. Se `discuss_before_plan: true` na config, o próximo passo após aprovação é `oxe:discuss` antes de plan.
+3. **plan** — plano executável + **Verificar** por tarefa. Se 3+ domínios distintos, **sugere automaticamente** blueprint de agentes (`/oxe-plan --agents`). Sem `--agents`: solo. Com `--agents`: gera também `plan-agents.json` (schema 3 com `model_hint`).
+4. **execute** — modo selecionado 1 vez: **A) Completo** (1 sessão), **B) Por onda**, **C) Por tarefa**. Se Verificar falhar inline: diagnóstico automático (2-3 hipóteses + fix), sem precisar chamar `/oxe-debug` separadamente. Escalação para `/oxe-forensics` só se esgotar tentativas.
+5. **verify** — até **6 camadas** por config: auditoria pré-exec, tarefas + critérios A*, fidelidade D-NN, UAT, **gaps de cobertura** (camada 5 — `verification_depth: "thorough"`), **segurança OWASP** (camada 6 — `security_in_verify: true`). Sem comandos extras.
+6. **→ próximo passo** — `/oxe` sugere automaticamente o que fazer agora (nova feature, milestone, ou revisar gaps).
+
+**Escape hatches (não precisam ser decorados — aparecem quando necessários):**
+
+- **`/oxe-forensics`** — sugerido automaticamente pelo execute/verify quando falha persiste. Diagnóstico pós-falha + 1 caminho de reentrada.
+- **`/oxe-debug`** — diagnóstico técnico inline durante execute (já integrado ao execute; disponível standalone para controle explícito).
+- **`/oxe-loop`** — iteração até verify passar (disponível standalone; integrado ao Modo B do execute via `loop_max`).
+- **`/oxe-research`** — notas datadas em `.oxe/research/` para spikes, mapas de sistema, engenharia reversa.
+- **`/oxe-route`** — traduz linguagem natural → comando. Equivalente a `/oxe [texto]`.
+- **`/oxe-compact`** — refresh explícito do codebase. Equivalente a `/oxe-scan` sem `--full`.
+
+**Gestão de projeto (`/oxe-project`):**
+
+Um único comando para: `milestone new|complete|status|audit`, `workstream new|switch|list|close <nome>`, `checkpoint [slug]`. Sem argumento: mostra status atual.
 
 **Vertical UI (opcional, mesma trilha):**
 

package/oxe/workflows/loop.md

@@ -0,0 +1,57 @@
+# OXE — Workflow: loop (execução iterativa até verificação passar)
+
+<objective>
+Executar uma **onda do PLAN.md** em ciclo iterativo até que a verificação inline passe ou o limite de tentativas seja atingido. Complementa o **Modo B** (por onda) do **`execute.md`** com retries automáticos e diagnóstico inline de falhas.
+
+Quando verify falha, não interrompe — diagnostica (2-3 hipóteses), corrige, tenta de novo. Escala para **`/oxe-forensics`** apenas quando esgota as tentativas.
+</objective>
+
+<context>
+- **Pré-requisito:** `.oxe/PLAN.md` existente com pelo menos 1 onda; `STATE.md` com fase ≥ `plan_ready`.
+- **Máximo de iterações:** padrão = 3; configurável via argumento `max:<N>` (ex.: `/oxe-loop onda 2 max:5`). Nunca exceder 10.
+- **Artefato:** não cria novos arquivos — atualiza `STATE.md` com campos `loop_*` e registra cada iteração como bloco inline no chat.
+- **Escalação:** se esgotou tentativas e ainda falhou → registrar estado em STATE.md + sugerir `/oxe-forensics` com contexto das hipóteses já tentadas.
+- **Não substitui** `/oxe-verify` global (4 camadas): o loop faz verificação **inline por onda** (comando `**Verificar:**` de cada Tn); o verify completo deve ser chamado ao final de todas as ondas.
+</context>
+
+<loop_state>
+## Campos em STATE.md durante o loop
+
+```yaml
+loop_onda: 2              # número da onda sendo executada
+loop_iteracao: 2/3        # tentativa atual / máximo
+loop_status: retrying     # retrying | passed | escalated
+loop_hipoteses: ["H1: ...", "H2: ..."]  # hipóteses da última falha
+```
+
+Limpar campos `loop_*` ao concluir com `passed` (ou manter `escalated` se escalou para forensics).
+</loop_state>
+
+<process>
+1. Ler `.oxe/STATE.md` e `.oxe/PLAN.md`. Identificar a onda alvo (argumento do usuário ou próxima onda pendente em STATE).
+2. Registrar em STATE.md: `loop_onda: N`, `loop_iteracao: 1/<max>`, `loop_status: retrying`.
+3. **Iteração:**
+   a. Listar tarefas da onda N com seus comandos `**Verificar:**`.
+   b. Implementar todas as tarefas da onda (seguindo `execute.md` `<modo_solo>`).
+   c. Executar os comandos `Verificar` de cada `Tn`.
+   d. **Se todos passaram:** registrar `loop_status: passed`; limpar campos `loop_*`; atualizar STATE.md com onda concluída; informar usuário e sugerir próxima onda ou `/oxe-verify`.
+   e. **Se algum falhou:**
+      - Listar 2-3 hipóteses de causa (baseado no erro/output da verificação).
+      - Registrar `loop_hipoteses` em STATE.md.
+      - Incrementar iteração: `loop_iteracao: K+1/<max>`.
+      - Se `K+1 > max`: ir para passo 4 (escalação).
+      - Senão: aplicar fix para a hipótese mais provável → voltar a `c`.
+4. **Escalação (tentativas esgotadas):**
+   - Registrar `loop_status: escalated` em STATE.md.
+   - Exibir no chat: tentativas realizadas, hipóteses testadas, evidência de cada falha.
+   - Sugerir `/oxe-forensics` com contexto: "onda N falhou após <max> tentativas — hipóteses testadas: H1, H2, H3".
+</process>
+
+<success_criteria>
+- [ ] STATE.md tem campos `loop_*` atualizados a cada iteração.
+- [ ] Cada falha gera 2-3 hipóteses registradas antes de tentar fix.
+- [ ] Ao passar: campos `loop_*` limpos; onda marcada como concluída em STATE.md.
+- [ ] Ao esgotar: `loop_status: escalated` + sugestão de `/oxe-forensics` com contexto completo.
+- [ ] Nunca excede `max` iterações configurado.
+- [ ] Não altera `.oxe/PLAN.md` (só implementa o que já está planejado).
+</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,7 +22,7 @@ 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>
 
@@ -55,6 +55,22 @@ Se já existir `.oxe/plan-agents.json` com status não-terminal (`pending_execut
 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`**:
 
@@ -80,6 +96,7 @@ Cada **agente**:
 | `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/`.
 
@@ -89,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).
@@ -107,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

@@ -73,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/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`).

package/oxe/workflows/scan.md

@@ -18,6 +18,20 @@ Se **`.oxe/config.json`** tiver `scan_focus_globs` ou `scan_ignore_globs`, **pri
 
 </context>
 
+<mode_detection>
+## Detecção automática de modo: bootstrap vs refresh
+
+Antes de iniciar, verificar se `.oxe/codebase/` já existe com os sete mapas:
+
+- **Modo bootstrap** (padrão quando codebase/ não existe ou está incompleto): produzir os sete arquivos do zero. Comportamento descrito no `<process>` abaixo.
+- **Modo refresh** (quando codebase/ existe e tem os sete mapas): executar a lógica de `oxe/workflows/compact.md` — comparar mapas existentes ao repo atual, atualizar incrementalmente, produzir `CODEBASE-DELTA.md` e `RESUME.md`. **Não refazer do zero.**
+
+Flag `--full`: forçar modo bootstrap mesmo se codebase/ existir.
+Flag `--refresh`: forçar modo refresh.
+
+**Sem flag:** automático por contexto. Se os mapas existem e o último scan foi há menos de `scan_max_age_days` (config), sugerir refresh mas perguntar ao usuário antes de executar o scan completo.
+</mode_detection>
+
 <process>
 1. Garantir pastas `.oxe/` e `.oxe/codebase/`.
 2. Inventariar o repo (Glob/Grep): linguagens, manifests (`package.json`, `pom.xml`, `go.mod`, etc.), pastas principais — aplicando foco/ignore da config se houver.