oxe-cc 0.3.0

package/commands/oxe/discuss.md

@@ -0,0 +1,16 @@
+---
+name: oxe:discuss
+description: Perguntas objetivas antes do plano — .oxe/DISCUSS.md
+argument-hint: "[contexto ou respostas]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/discuss.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa `$ARGUMENTS` como contexto ou respostas.

package/commands/oxe/execute.md

@@ -0,0 +1,16 @@
+---
+name: oxe:execute
+description: Executar onda do PLAN.md ou passos do QUICK.md
+argument-hint: "[opcional: onda ou Tn]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/execute.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa `$ARGUMENTS` como foco (onda, tarefa, confirmação).

package/commands/oxe/help.md

@@ -0,0 +1,11 @@
+---
+name: oxe:help
+description: Lista comandos OXE e o fluxo recomendado
+argument-hint: ""
+allowed-tools:
+  - Read
+---
+
+**Workflow canónico:** `oxe/workflows/help.md`
+
+Execute integralmente esse ficheiro (inclui Cursor vs Copilot).

package/commands/oxe/next.md

@@ -0,0 +1,12 @@
+---
+name: oxe:next
+description: Lê STATE.md e indica o próximo comando OXE lógico
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Glob
+---
+
+**Workflow canónico:** `oxe/workflows/next.md`
+
+Execute integralmente esse ficheiro.

package/commands/oxe/plan.md

@@ -0,0 +1,15 @@
+---
+name: oxe:plan
+description: Gera PLAN.md a partir da SPEC com tarefas atômicas e verificação por item
+argument-hint: "[--replan se já existe PLAN.md]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+---
+
+**Workflow canónico:** `oxe/workflows/plan.md`
+
+Execute integralmente esse ficheiro. Se `$ARGUMENTS` contiver `--replan`, seguir a variante de replanejamento descrita no workflow.

package/commands/oxe/quick.md

@@ -0,0 +1,16 @@
+---
+name: oxe:quick
+description: Modo rápido — .oxe/QUICK.md + STATE (sem SPEC/PLAN longos)
+argument-hint: "[objetivo]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/quick.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa o texto em `$ARGUMENTS` como objetivo e contexto.

package/commands/oxe/scan.md

@@ -0,0 +1,16 @@
+---
+name: oxe:scan
+description: Escaneia o repositório e gera mapa em .oxe/codebase/ + STATE.md
+argument-hint: "[área opcional, ex. auth, api]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/scan.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Se o utilizador passar texto em `$ARGUMENTS`, usa-o como **foco opcional** de área (pastas/módulos) no mapeamento.

package/commands/oxe/spec.md

@@ -0,0 +1,14 @@
+---
+name: oxe:spec
+description: Transforma o pedido do usuário em SPEC.md (escopo, aceite, não-objetivos)
+argument-hint: "[texto do pedido ou @arquivo.md]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+---
+
+**Workflow canónico:** `oxe/workflows/spec.md`
+
+Execute integralmente esse ficheiro. Usa `$ARGUMENTS` e o contexto da conversa como entrada do utilizador (texto ou `@ficheiro`).

package/commands/oxe/verify.md

@@ -0,0 +1,15 @@
+---
+name: oxe:verify
+description: Valida implementação contra SPEC e PLAN; produz checklist e gaps
+argument-hint: "[Tn opcional — focar uma tarefa]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+**Workflow canónico:** `oxe/workflows/verify.md`
+
+Execute integralmente esse ficheiro. Se `$ARGUMENTS` indicar um id de tarefa (ex. `T2`), restringir a verificação a essa tarefa.

package/oxe/templates/CONFIG.md

@@ -0,0 +1,12 @@
+# `.oxe/config.json` — referência
+
+Copia `oxe/templates/config.template.json` para **`.oxe/config.json`** no teu projeto (ou deixa o `oxe-cc` criar na primeira instalação).
+
+| Chave | Tipo | Significado |
+|-------|------|-------------|
+| `discuss_before_plan` | boolean | Se `true`, o fluxo recomendado pede **`oxe:discuss`** entre spec e plan (perguntas objetivas antes de partir tarefas). |
+| `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 alinhada aos critérios de aceite. |
+| `default_verify_command` | string | Comando guarda-chuva opcional (ex. `npm test`) sugerido em **plan**/**verify** quando o projeto não define outro. |
+
+Valores em falta tratam-se como omissões seguras (equivalente ao template).

package/oxe/templates/PLAN.template.md

@@ -0,0 +1,38 @@
+# OXE — Plano
+
+> Gerado a partir de `.oxe/SPEC.md`. Cada tarefa deve ter bloco **Verificar**.
+
+## Resumo
+
+- **Spec vinculada:** (data ou versão informal)
+- **Ondas:** (número)
+- **Tarefas:** (número)
+
+## Dependências globais
+
+- (ex.: branch base, feature flags, migrations)
+
+## Replanejamento
+
+> Preencher apenas em **--replan** ou após verify falhado. Manter histórico legível.
+
+- **Data / motivo:** …
+- **Lições de VERIFY / SUMMARY:** …
+- **Alterações ao plano anterior:** (tarefas removidas, novas, renumeradas) …
+
+## Tarefas
+
+### T1 — (título)
+
+- **Arquivos prováveis:** `…`
+- **Depende de:** —
+- **Onda:** 1
+- **Implementação:** …
+- **Verificar:**
+  - Comando: `…`
+  - Manual: (opcional) …
+- **Aceite vinculado:** 1, 2
+
+---
+
+_(Adicione T2, T3, … conforme o comando oxe:plan.)_

package/oxe/templates/SPEC.template.md

@@ -0,0 +1,39 @@
+# OXE — Especificação
+
+> Substitua os placeholders. Remova seções vazias se não se aplicarem.
+
+## Objetivo
+
+(Uma frase: o que entregar.)
+
+## Contexto
+
+- Repo / produto: …
+- Links úteis: …
+
+## Escopo
+
+### Dentro do escopo
+
+- …
+
+### Fora do escopo (não-objetivos)
+
+- …
+
+## Critérios de aceite
+
+1. …
+2. …
+
+## Suposições
+
+- …
+
+## Riscos
+
+- …
+
+## Referências no código
+
+- Paths / módulos: …

package/oxe/templates/STATE.md

@@ -0,0 +1,30 @@
+# OXE — Estado
+
+## Fase atual
+
+`initial` — defina após primeiro scan: `scan_complete` | `spec_ready` | `discuss_complete` | `plan_ready` | `quick_active` | `executing` | `verify_complete` | `verify_failed`
+
+## Último scan
+
+- **Data:** (ISO ou legível)
+- **Notas:** (opcional)
+
+## Contexto do plano / quick (opcional)
+
+- **Spec / plano:** (revisão informal ou data de `.oxe/SPEC.md` / `.oxe/PLAN.md`)
+- **Última onda executada:** (número ou —)
+- **Tarefas concluídas:** (ex.: T1, T2 ou passos 1–3 do QUICK.md)
+
+## Decisões persistentes
+
+- (bullet: decisão → data)
+
+## Próximo passo sugerido
+
+- Comando: `oxe:scan` | `oxe:spec` | `oxe:discuss` | `oxe:plan` | `oxe:quick` | `oxe:execute` | `oxe:verify`  
+  *(no **Cursor**: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, …; Copilot prompts: `oxe-scan`, …)*
+- Motivo: (uma linha)
+
+## Bloqueios
+
+- (nenhum ou lista)

package/oxe/templates/SUMMARY.template.md

@@ -0,0 +1,20 @@
+# OXE — Resumo de sessão
+
+> Usado por **verify** (append) e por **plan --replan** para contexto incremental. Podes criar manualmente a partir deste template.
+
+## Sessão
+
+- **Data:** (ISO ou legível)
+- **Spec / plano:** (referência breve a `.oxe/SPEC.md` / `.oxe/PLAN.md`)
+
+## Feito nesta sessão
+
+- …
+
+## Decisões / notas
+
+- …
+
+## Pendente ou follow-up
+
+- …

package/oxe/templates/config.template.json

@@ -0,0 +1,6 @@
+{
+  "discuss_before_plan": false,
+  "after_verify_suggest_pr": true,
+  "after_verify_draft_commit": true,
+  "default_verify_command": ""
+}

package/oxe/workflows/discuss.md

@@ -0,0 +1,31 @@
+# OXE — Workflow: discuss
+
+<objective>
+Esclarecer requisitos **antes** do plano: registar perguntas, respostas e decisões em **`.oxe/DISCUSS.md`**, e atualizar **`.oxe/STATE.md`**. Inspirado na fase “discuss” de fluxos tipo GSD, mantido enxuto (máx. **7** perguntas).
+
+Usar quando: SPEC existe mas há ambiguidade, risco técnico, ou `discuss_before_plan: true` em `.oxe/config.json`.
+</objective>
+
+<context>
+- Ler `.oxe/SPEC.md`, `.oxe/STATE.md` e trechos relevantes de `.oxe/codebase/OVERVIEW.md` / `STACK.md`.
+- Se `.oxe/config.json` existir e `discuss_before_plan` for `true`, tratar este passo como **recomendado** antes de `oxe:plan`.
+</context>
+
+<process>
+1. Se não existir `.oxe/SPEC.md`, pedir **spec** primeiro (ou **quick** se for trabalho trivial).
+2. Identificar **lacunas** (escopo, dados, UX, edge cases, compatibilidade) — no máximo **7** perguntas objetivas.
+3. Criar ou atualizar **`.oxe/DISCUSS.md`** com estrutura fixa:
+   - **Contexto** — 2–4 bullets do que já se sabe da SPEC.
+   - **Perguntas** — numeradas; para cada uma: resposta (se o utilizador já respondeu na mensagem) ou `_(pendente)_`.
+   - **Decisões** — bullets com decisão + data (só as já fechadas).
+   - **Implicações para o plano** — bullets (ex.: “migrations necessárias”, “feature flag”).
+4. Se ainda houver perguntas **pendentes** críticas, listá-las no chat (máx. 7) e parar até resposta; depois atualizar DISCUSS.md.
+5. Atualizar **`.oxe/STATE.md`**: fase `discuss_complete` (ou `spec_ready` se preferires manter spec como fase principal e discutir como subpasso), próximo passo `oxe:plan`.
+6. Resumo no chat em ≤8 linhas.
+</process>
+
+<success_criteria>
+- [ ] `.oxe/DISCUSS.md` existe com perguntas e decisões alinhadas à SPEC.
+- [ ] Nenhuma ambiguidade crítica ficou sem registo (como pendente ou suposição explícita na SPEC).
+- [ ] `STATE.md` indica próximo passo **plan**.
+</success_criteria>

package/oxe/workflows/execute.md

@@ -0,0 +1,28 @@
+# OXE — Workflow: execute
+
+<objective>
+Guiar a **implementação por ondas** com base em **`.oxe/PLAN.md`**, atualizando **`.oxe/STATE.md`** com progresso (tarefas Tn). Não substitui o editor: estrutura o trabalho e confirma pré-requisitos antes de cada onda.
+
+Se existir apenas **`.oxe/QUICK.md`** (fluxo quick), tratar os **Passos** numerados como lista única “onda 1” em vez de tarefas T1…Tn.
+</objective>
+
+<context>
+- Se **PLAN.md** não existir mas **QUICK.md** existir, seguir **QUICK.md** neste workflow (passos = trabalho da sessão).
+- Se nem PLAN nem QUICK existir, recomendar `oxe:plan` ou `oxe:quick` primeiro.
+</context>
+
+<process>
+1. Ler `.oxe/STATE.md`, `PLAN.md` (se existir) e `QUICK.md` (se PLAN não existir).
+2. Identificar **onda atual** (ou próxima): no PLAN, todas as tarefas da mesma **Onda** sem dependências pendentes; no QUICK, os passos ainda não marcados como feitos (se STATE não indicar, assumir desde o início).
+3. Listar no chat: tarefas/passos desta onda, ficheiros prováveis, comando **Verificar** associado (do PLAN ou do QUICK).
+4. Após o utilizador confirmar que a onda foi implementada (ou após aplicares as mudanças tu mesmo), atualizar **`.oxe/STATE.md`**:
+   - Secção ou bullets: **Última onda executada**, **Tarefas concluídas** (Tn ou números dos passos).
+   - Próximo passo: continuar próxima onda, `oxe:verify`, ou `oxe:plan` se o plano ficou obsoleto.
+5. Se o PLAN tiver várias ondas, repetir execute por onda sob pedido; não apagar tarefas do PLAN.
+</process>
+
+<success_criteria>
+- [ ] Onda ou bloco de passos está explícito antes de “implementar”.
+- [ ] `STATE.md` regista progresso (Tn ou passos) e próximo passo.
+- [ ] Verificação alinhada ao bloco **Verificar** do PLAN ou QUICK.
+</success_criteria>

package/oxe/workflows/help.md

@@ -0,0 +1,50 @@
+# OXE — Workflow: help
+
+<objective>
+Apresentar o fluxo OXE (scan → spec → plan → execução → verify), o modo **quick**, o passo **execute**, e como invocar no **Cursor** e no **GitHub Copilot**. Mencionar CLI `oxe-cc` (instalar, `doctor`, `init-oxe`).
+</objective>
+
+<context>
+OXE é um fluxo **spec-driven** com artefatos em `.oxe/` no repositório alvo. Menos comandos que GSD; mesmo espírito de context engineering (ficheiros pequenos por etapa).
+</context>
+
+<output>
+## Cursor
+
+Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-verify`, `/oxe-next`, `/oxe-quick`, `/oxe-execute`, `/oxe-help` (definidos em `.cursor/commands/`).
+
+## GitHub Copilot (VS Code / IDE)
+
+1. **Instruções do repositório:** `.github/copilot-instructions.md` (ativas no chat quando o repositório está em contexto).
+2. **Prompt files:** no chat, escrever `/` e escolher **`oxe-scan`**, **`oxe-spec`**, **`oxe-discuss`**, **`oxe-plan`**, **`oxe-verify`**, **`oxe-next`**, **`oxe-quick`**, **`oxe-execute`**, **`oxe-help`**. Requer `chat.promptFiles`: true.
+
+## Fluxo completo
+
+1. **scan** — após clonar ou quando o repo mudar muito.
+2. **spec** — descrever o que se quer.
+3. **discuss** (opcional) — perguntas objetivas antes do plano; recomendado se `discuss_before_plan` em `.oxe/config.json`.
+4. **plan** — plano executável + verificação por tarefa.
+5. **execute** (opcional) — onda a onda com base no PLAN (ou passos do QUICK).
+6. Implementar mudanças no agente/editor.
+7. **verify** — validar antes de merge/PR (inclui rascunho de commit / checklist PR se configurado).
+8. **next** — retomar trabalho.
+
+## Modo rápido (quick)
+
+- **`/oxe-quick`**: cria `.oxe/QUICK.md` (passos curtos + verificar) sem SPEC/PLAN longos. Promover a spec/plan se o trabalho crescer (muitos ficheiros, API pública, segurança).
+
+## CLI (terminal)
+
+- **`npx oxe-cc`** — instala `oxe/`, Cursor, Copilot, etc.; por omissão cria **`.oxe/`** mínimo (`STATE.md` a partir do template) se ainda não existir.
+- **`oxe-cc doctor`** — verifica Node, workflows, JSON válido em `.oxe/config.json`, mapa codebase após scan (lista o que falta).
+- **`oxe-cc init-oxe`** — só inicializa `.oxe/` (STATE + `config.json` + pasta `codebase/`), sem reinstalar o resto.
+- **`oxe-cc --no-init-oxe`** — instala workflows sem criar `.oxe/`.
+
+## Artefatos
+
+- `.oxe/STATE.md`, `.oxe/config.json` (opcional), `.oxe/codebase/*`, `.oxe/SPEC.md`, `.oxe/DISCUSS.md` (opcional), `.oxe/PLAN.md`, `.oxe/VERIFY.md`, `.oxe/QUICK.md`, `.oxe/SUMMARY.md`
+
+## Gatilhos naturais (Copilot / chat)
+
+Quando o utilizador disser “oxe scan”, “oxe quick”, “executar onda OXE”, etc., seguir o workflow correspondente em `oxe/workflows/*.md`.
+</output>

package/oxe/workflows/next.md

@@ -0,0 +1,22 @@
+# OXE — Workflow: next
+
+<objective>
+Inspecionar `.oxe/STATE.md` e a existência de `SPEC.md`, `PLAN.md`, `QUICK.md`, `VERIFY.md` e `.oxe/codebase/` para recomendar **um** próximo passo OXE e uma frase de justificativa.
+</objective>
+
+<process>
+1. Se `.oxe/` ou `STATE.md` não existir → recomendar **scan** ou `oxe-cc init-oxe` / primeiro **scan** e oferecer criar `.oxe` a partir de `oxe/templates/STATE.md`.
+2. Se não houver `.oxe/codebase/*.md` (e o trabalho não for só um quick isolado) → **scan**.
+3. Se `STATE.md` indicar fase `quick_active` ou existir `QUICK.md` sem PLAN → recomendar **execute** (se ainda há passos) ou **verify** depois de implementar; se o trabalho cresceu → **spec**.
+4. Se não houver `SPEC.md` e não estiveres em modo quick intencional → **spec** (ou **quick** se o utilizador quiser só um fix pequeno).
+5. Se houver SPEC mas não PLAN → se `.oxe/config.json` tiver `discuss_before_plan: true` e faltar **`.oxe/DISCUSS.md`** (ou estiver incompleto) → **discuss**; senão → **plan**.
+6. Se PLAN (ou QUICK) existe, há implementação pendente e ainda não verificaste → **execute** opcionalmente, depois **verify**.
+7. Se VERIFY ausente ou desatualizado após mudanças → **verify**.
+8. Se VERIFY passou → sugerir PR/commit ou novo **spec** / **quick** para próxima tarefa.
+
+Responder em formato fixo:
+
+- **Próximo passo:** `scan` | `spec` | `discuss` | `plan` | `quick` | `execute` | `verify` (Cursor: `/oxe-discuss`, …; `oxe:discuss`, …)
+- **Por quê:** …
+- **Artefatos em jogo:** (lista curta)
+</process>

package/oxe/workflows/plan.md

@@ -0,0 +1,52 @@
+# OXE — Workflow: plan
+
+<objective>
+Produzir **`.oxe/PLAN.md`**: tarefas **pequenas**, **ondas** (paralelizáveis vs sequenciais), e **cada tarefa com bloco de verificação** (comando de teste e/ou checklist manual).
+
+Base: `.oxe/SPEC.md` + `.oxe/codebase/*` + código quando necessário (Grep/Read pontual).
+
+Se o utilizador pedir **--replan** (ou replanejamento implícito após `verify_failed`):
+- Ler **`.oxe/VERIFY.md`** (gaps e falhas), **`.oxe/SUMMARY.md`** se existir, e o **PLAN.md** atual.
+- Preservar tarefas já concluídas ou renumerar com nota no **Replanejamento**; não apagar histórico útil do ficheiro — deslocar para a secção **Replanejamento** e reescrever a secção **Tarefas** conforme necessário.
+- Se **SUMMARY.md** não existir, criar a partir de `oxe/templates/SUMMARY.template.md` só para registar o contexto do replan (ou append se já existir).
+</objective>
+
+<context>
+- Não inventar APIs inexistentes: cruzar com **STRUCTURE.md**, **INTEGRATIONS.md** e ficheiros reais; respeitar **CONCERNS.md** (evitar agravar dívida conhecida sem tarefa explícita).
+- Se existir **`.oxe/DISCUSS.md`**, alinhar tarefas às decisões registadas.
+- Se existir **`.oxe/config.json`** com `default_verify_command` não vazio, usar como fallback quando a SPEC não indicar comando.
+- Tamanho alvo: cada tarefa cabe em **um** contexto de agente focado.
+- Id das tarefas: `T1`, `T2`, … estáveis para referência em verify.
+</context>
+
+<format_plan>
+Cada tarefa em PLAN.md deve seguir:
+
+```markdown
+### Tn — título curto
+- **Arquivos prováveis:** `...`
+- **Depende de:** Tk ou —
+- **Onda:** 1 | 2 | …
+- **Implementação:** 1–3 frases do que fazer.
+- **Verificar:**
+  - Comando: `...` (ex.: npm test, pytest, mvn test)
+  - Manual: (opcional) passos breves
+- **Aceite vinculado:** (números dos critérios na SPEC)
+```
+</format_plan>
+
+<process>
+1. Ler `.oxe/SPEC.md` (obrigatório). Se faltar, pedir **spec** primeiro.
+2. Se `.oxe/config.json` tiver `discuss_before_plan: true` e **não** existir `.oxe/DISCUSS.md` com decisões fechadas, pedir **discuss** antes de planear.
+3. Ler `.oxe/codebase/*.md` (incl. CONVENTIONS / CONCERNS) e inspecionar pontos de entrada se a spec exigir.
+4. Escrever ou atualizar `.oxe/PLAN.md` usando `oxe/templates/PLAN.template.md` como cabeçalho; em **--replan**, preencher a secção **Replanejamento** (data, motivo, lições de VERIFY/SUMMARY, tarefas removidas/alteradas).
+5. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes.
+6. Atualizar `.oxe/STATE.md`: fase `plan_ready`, próximo passo executar PLAN depois **verify** (ou **execute**).
+7. Listar no chat: ondas, contagem de tarefas, comando de teste guarda-chuva se houver.
+</process>
+
+<success_criteria>
+- [ ] Cada tarefa tem seção **Verificar** com comando ou checklist explícito.
+- [ ] Dependências entre tarefas estão explícitas.
+- [ ] Critérios da SPEC mapeados para tarefas ou marcados como gap.
+</success_criteria>

package/oxe/workflows/quick.md

@@ -0,0 +1,32 @@
+# OXE — Workflow: quick
+
+<objective>
+Registar 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.
+
+**Promover para fluxo completo** (spec → plan) se: tocar em **mais de ~8 ficheiros**, alterar **contrato público** (API, schema, eventos), ou houver **risco de segurança/dados**.
+</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.
+</context>
+
+<process>
+1. Garantir `.oxe/` (usar `oxe/templates/STATE.md` só se `STATE.md` não existir).
+2. Criar ou substituir **`.oxe/QUICK.md`** com:
+   - **Objetivo** — uma frase.
+   - **Contexto** — 2–5 bullets (ficheiros/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.
+   - **Promover para spec/plan?** — sim/não + critério (uma linha).
+3. Atualizar **`.oxe/STATE.md`**: fase `quick_active`, próximo passo `oxe:execute` ou implementação manual + `oxe:verify` (se usares plano completo depois, volta a `oxe:spec`).
+4. Responder no chat com resumo em ≤8 linhas e o comando de verificação escolhido.
+</process>
+
+<success_criteria>
+- [ ] `.oxe/QUICK.md` existe com passos e bloco **Verificar**.
+- [ ] `STATE.md` reflete fase `quick_active` e próximo passo coerente.
+- [ ] Fica explícito quando **não** usar quick (promoção a spec/plan).
+</success_criteria>

package/oxe/workflows/scan.md

@@ -0,0 +1,36 @@
+# OXE — Workflow: scan
+
+<objective>
+Analisar o codebase e produzir documentação **estruturada e enxuta** em `.oxe/codebase/`, atualizando `.oxe/STATE.md`. Cada documento deve ser navegável por humanos e por agentes sem carregar o repo inteiro no contexto.
+
+**Foco opcional:** se o utilizador indicar uma área (ex. `api`, `auth`), priorizar essa pasta ou módulo nos mapeamentos.
+</objective>
+
+<context>
+- Diretório de saída: **`.oxe/`** na raiz do projeto (não `.planning/`).
+- Se `.oxe/` não existir, criar.
+- Carregar `oxe/templates/STATE.md` como base se `STATE.md` ainda não existir; caso exista, preservar histórico útil e atualizar seção **Último scan** e **Fase**.
+- Se existir **`.oxe/config.json`**, respeitar preferências (ex. comandos por defeito documentados em `oxe/templates/CONFIG.md`); não sobrescrever o ficheiro no scan.
+- Não apagar `SPEC.md` / `PLAN.md` se já existirem — apenas atualizar codebase.
+</context>
+
+<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.
+3. Produzir **sete** arquivos em `.oxe/codebase/` (paralelize subagentes quando disponível):
+   - **OVERVIEW.md** — propósito aparente do projeto, módulos de alto nível, fluxo principal (5–15 tópicos).
+   - **STACK.md** — runtime, frameworks, build, versões relevantes, dependências críticas.
+   - **STRUCTURE.md** — árvore lógica (não listar mil arquivos): entrypoints, `src/` por domínio, onde ficam testes e configs.
+   - **TESTING.md** — como rodar testes/lint/format (comandos exatos), frameworks de teste, pastas `*test*`, CI se houver.
+   - **INTEGRATIONS.md** — APIs externas, bases de dados, auth, filas, segredos (nomes de env **sem valores**), webhooks. Se não houver integrações, escrever explicitamente *Não detetado* com uma linha de contexto.
+   - **CONVENTIONS.md** — estilo de código (naming, formatação, imports), padrões de erros/logging, organização de módulos; **prescreve** o que seguir em novas alterações (com paths em backticks).
+   - **CONCERNS.md** — dívida técnica, áreas frágeis, riscos de segurança/performance, dependências sensíveis; cada item com impacto breve e **ficheiros** referenciados.
+4. Atualizar **`.oxe/STATE.md`**: data do scan, fase sugerida `scan_complete`, próximo passo recomendado `oxe:spec` ou `oxe:plan` se já houver SPEC.
+5. Resumir em 5–10 linhas no chat: o que foi escrito e o próximo passo sugerido.
+</process>
+
+<success_criteria>
+- [ ] `.oxe/codebase/OVERVIEW.md`, `STACK.md`, `STRUCTURE.md`, `TESTING.md`, `INTEGRATIONS.md`, `CONVENTIONS.md`, `CONCERNS.md` existem e têm conteúdo útil.
+- [ ] `.oxe/STATE.md` reflete último scan e próximo passo.
+- [ ] Comandos de teste em TESTING.md foram validados ou marcados como “não verificado” se o ambiente não permitir rodar.
+</success_criteria>

package/oxe/workflows/spec.md

@@ -0,0 +1,37 @@
+# OXE — Workflow: spec
+
+<objective>
+Registrar a intenção do utilizador em **`.oxe/SPEC.md`**: escopo, critérios de aceite mensuráveis, não-objetivos e suposições. A spec deve ser o contrato antes do plano.
+
+Para trabalho **muito pequeno**, o utilizador pode preferir **`oxe:quick`** (`.oxe/QUICK.md`) em vez deste fluxo — não bloqueies: se pedirem explicitamente quick, redireciona.
+
+Se **`.oxe/config.json`** tiver `discuss_before_plan: true`, mencionar no fim da resposta que o próximo passo recomendado é **`oxe:discuss`** antes do plano.
+
+Entrada: texto livre na mensagem ou caminho `@arquivo.md` / anexo para incorporar PRD/notas.
+</objective>
+
+<context>
+**Pré-requisito:** preferencialmente **scan** já executado. Se não existir scan, mencionar na spec que o mapa está pendente.
+
+Leia `.oxe/STATE.md` e, se existirem, trechos relevantes de `.oxe/codebase/OVERVIEW.md` e `STACK.md` para não contradizer o projeto real.
+</context>
+
+<process>
+1. Resolver entrada: se começar com `@`, ler ficheiro; senão usar o texto da conversa.
+2. Criar ou atualizar **`.oxe/SPEC.md`** usando `oxe/templates/SPEC.template.md` como esqueleto (substituir placeholders).
+3. Incluir seções obrigatórias:
+   - **Objetivo** — uma frase clara.
+   - **Escopo** — bullet in / out.
+   - **Critérios de aceite** — verificáveis (Given/When/Then ou checklist numerado).
+   - **Não-objetivos** — o que não será feito.
+   - **Suposições e riscos** — dependências técnicas ou de produto.
+   - **Referências** — paths/arquivos tocados se já conhecidos.
+4. Atualizar **`.oxe/STATE.md`**: fase `spec_ready`, próximo passo `oxe:plan`.
+5. Responder com resumo da spec e no máximo 3 perguntas objetivas se algo crítico estiver ambíguo.
+</process>
+
+<success_criteria>
+- [ ] `.oxe/SPEC.md` existe e critérios de aceite são testáveis ou observáveis.
+- [ ] `STATE.md` atualizado.
+- [ ] Ambiguidades críticas foram perguntadas ou registradas como suposição explícita.
+</success_criteria>

package/oxe/workflows/verify.md

@@ -0,0 +1,34 @@
+# OXE — Workflow: verify
+
+<objective>
+Executar ou orientar verificação pós-implementação: rodar os comandos definidos no **PLAN.md**, confrontar com **SPEC.md**, registrar resultado em **`.oxe/VERIFY.md`** (e atualizar **STATE**).
+
+Se o utilizador indicar uma tarefa (ex. `T2`), focar só nela; caso contrário, percorrer todas as tarefas com blocos **Verificar**.
+</objective>
+
+<context>
+- Preferir rodar comandos reais no terminal quando o ambiente permitir; se sandbox bloquear, marcar como “não executado aqui” e deixar comando para o utilizador.
+- Não destruir `PLAN.md`; anexar achados em `VERIFY.md`.
+- Ler **`.oxe/config.json`** se existir: chaves `after_verify_draft_commit` e `after_verify_suggest_pr` controlam passos opcionais abaixo (omissão = `true` onde o template por defeito as define).
+</context>
+
+<process>
+1. Ler `.oxe/SPEC.md`, `.oxe/PLAN.md`, `.oxe/STATE.md`.
+2. Para cada tarefa relevante, executar **Verificar: Comando** do PLAN (ou subconjunto se foco Tn).
+3. Checar critérios de aceite da SPEC contra o estado do código (Read/Grep).
+4. Escrever **`.oxe/VERIFY.md`** com:
+   - Data, ambiente (OS/node versão se relevante).
+   - Tabela ou lista: Tarefa | Verificação | Passou? | Notas.
+   - **Gaps** — o que falhou e sugestão de correção (pode virar novas entradas no PLAN).
+5. Atualizar **`.oxe/STATE.md`**: `verify_complete` ou `verify_failed` + próximo passo (replan, corrigir, ou ship).
+6. Append curto em **`.oxe/SUMMARY.md`** (sessão) se existir; se não existir, criar a partir de **`oxe/templates/SUMMARY.template.md`** e acrescentar a entrada desta sessão.
+7. **Só se todas as verificações relevantes passarem:** se `after_verify_draft_commit` não for `false` em `.oxe/config.json` (se o ficheiro não existir, assumir `true` como no template): acrescentar a **VERIFY.md** secção **Rascunho de commit** — mensagem convencional (ex. `feat:` / `fix:`) + bullets alinhados aos critérios de aceite; **não** incluir segredos.
+8. **Só se passou:** se `after_verify_suggest_pr` não for `false` (ausência de config = `true`): acrescentar **Checklist PR** — branch base, título sugerido, screenshots se UI, ligações a SPEC/PLAN, testes corridos.
+</process>
+
+<success_criteria>
+- [ ] VERIFY.md reflete o que foi de fato verificado.
+- [ ] Falhas têm próximo passo claro (qual tarefa replanejar ou qual ficheiro corrigir); se falhou, próximo passo inclui **plan --replan** ou correção direta.
+- [ ] STATE.md atualizado.
+- [ ] Se passou: secções **Rascunho de commit** e **Checklist PR** presentes em VERIFY.md salvo se desativadas em config.
+</success_criteria>