oxe-cc 0.3.1 → 0.3.2

package/.github/copilot-instructions.md

@@ -18,6 +18,7 @@ Se o utilizador mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear
 | Execute | `oxe/workflows/execute.md` | “oxe execute”, “executar onda”, “onda 2 OXE” |
 | Verify | `oxe/workflows/verify.md` | “oxe verify”, “validar plano OXE”, “VERIFY.md” |
 | Next | `oxe/workflows/next.md` | “oxe next”, “próximo passo OXE” |
+| Review PR | `oxe/workflows/review-pr.md` | “revisar PR”, link `…/pull/10`, “diff entre branches”, “code review OXE” *(prompt: `/oxe-review-pr`)* |
 | Help | `oxe/workflows/help.md` | “oxe help”, “como usar OXE” |
 
 **Regra:** lê o Markdown indicado e executa **todos** os passos e critérios de sucesso descritos nesse ficheiro. Não atalhes: cria ou atualiza os ficheiros em `.oxe/` conforme o workflow.
@@ -30,7 +31,7 @@ Se o utilizador mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear
 ## Cursor vs Copilot
 
 - **Cursor:** slash commands em `.cursor/commands/oxe-*.md` apontam para os mesmos workflows.
-- **Copilot:** prompt files em `.github/prompts/oxe-*.prompt.md`; cada um indica o workflow em `oxe/workflows/<passo>.md` na raiz do repo.
+- **Copilot:** prompt files em `.github/prompts/oxe-*.prompt.md`; cada um indica o workflow em `oxe/workflows/<passo>.md` na raiz do repo. **`oxe-review-pr`** existe só como prompt Copilot (não há slash command Cursor correspondente).
 
 ## Manutenção deste pacote (oxe-build)
 

package/.github/prompts/oxe-review-pr.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-review-pr
+agent: agent
+description: OXE — Revisão de PR (link GitHub, branches ou SHAs)
+argument-hint: "URL ou refs: https://github.com/org/repo/pull/10 | main feature/foo"
+---
+
+Executa o workflow **OXE review-pr**. Lê e aplica **integralmente**:
+
+`oxe/workflows/review-pr.md` (na raiz do repositório em contexto)
+
+**Exemplos de entrada:** cola o URL da PR (`https://github.com/org/repo/pull/10`, com ou sem `/files`); ou `org/repo#10`; ou **base** e **head** (branches/tags/SHAs). Sem refs, o agente infere (ex.: `main` vs branch atual).

package/AGENTS.md

@@ -6,6 +6,6 @@ Este repositório empacota o fluxo **OXE** (spec-driven, artefatos em `.oxe/`).
 - **Instruções do repositório:** [.github/copilot-instructions.md](.github/copilot-instructions.md) — aplicadas automaticamente no Copilot Chat quando o repo está em contexto.
 - **Workflows canónicos:** [oxe/workflows/](oxe/workflows/) — editar aqui primeiro; Cursor e Copilot apontam para estes ficheiros (inclui `quick.md`, `execute.md`).
 - **CLI:** `oxe-cc` instala assets e bootstrap (`.oxe/STATE.md`, `config.json`, `codebase/`); `oxe-cc doctor` valida workflows, JSON de config e mapa scan; `oxe-cc init-oxe` só inicializa `.oxe/`.
-- **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`) após `chat.promptFiles` estar ativo.
+- **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`, `/oxe-review-pr` para diff tipo PR) após `chat.promptFiles` estar ativo.
 
 Quando o utilizador pedir uma etapa OXE por linguagem natural, segue o ficheiro `oxe/workflows/<passo>.md` correspondente sem atalhar passos.

package/README.md

@@ -1,226 +1,236 @@
-# oxe-build
+<div align="center">
 
-[![npm version](https://img.shields.io/npm/v/oxe-cc.svg)](https://www.npmjs.com/package/oxe-cc)
-[![license](https://img.shields.io/npm/l/oxe-cc.svg)](https://www.npmjs.com/package/oxe-cc)
+<p align="center">
+  <img src="assets/readme-banner.svg" alt="OXE" width="920" />
+</p>
 
-*(O badge de versão só reflete uma release real depois de `npm publish` concluído com sucesso.)*
+**Fluxo spec-driven e context engineering para [Cursor](https://cursor.com) e [GitHub Copilot](https://github.com/features/copilot) — inspirado na ideia do [GSD](https://github.com/gsd-build/get-shit-done), com **menos comandos** e foco em **`.oxe/`** + **`oxe/workflows/`**.**
 
-Fluxo **spec-driven** enxuto (inspirado em context engineering / GSD), com prefixo **OXE** e artefatos em **`.oxe/`**.
+[![npm](https://img.shields.io/npm/v/oxe-cc.svg?style=flat-square)](https://www.npmjs.com/package/oxe-cc)
+[![license](https://img.shields.io/npm/l/oxe-cc.svg?style=flat-square)](LICENSE)
 
-Os alvos **iniciais** são **Cursor** e **GitHub Copilot** (VS Code e IDEs compatíveis). Outros clientes podem usar os mesmos workflows em Markdown.
+```bash
+npx oxe-cc@latest
+```
 
-O nome previsto no npm é **`oxe-cc`**. Confirma se já está publicado: `npm view oxe-cc version`. Se responder **404**, o pacote **ainda não existe** no registry — usa uma das opções abaixo até publicares com sucesso.
+**Manter atualizado:** `npx oxe-cc@latest --force` (na raiz do projeto).
 
-## Instalação (escolhe uma)
+[Para quem é](#para-quem-é) · [Começar](#começar) · [Como funciona](#como-funciona) · [Modo rápido](#modo-rápido) · [Porque funciona](#porque-funciona) · [Comandos](#comandos) · [Configuração](#configuração) · [Problemas](#resolução-de-problemas)
 
-Precisas de **Node.js 18+**. O executável chama-se **`oxe-cc`**.
+</div>
 
-### A) Repositório local (sem npm registry)
+---
 
-```bash
-cd C:\caminho\para\oxe-build
-npm link
-cd C:\caminho\para\teu-projeto
-npm link oxe-cc
-oxe-cc
-```
+## Para quem é
+
+Para quem quer **descrever o que quer e ver isso construído de forma consistente** — **sem** simular uma organização enorme de processos em cima do repositório.
+
+OXE é **enxuto**: não há dezenas de slash commands nem instalador multi-runtime. Há **um CLI** que copia ficheiros para o projeto, **workflows em Markdown** que o agente segue, e **estado em disco** para a sessão principal não “inchada” com tudo o que já foi decidido.
+
+---
 
-Ou, sem `link`, apontando ao script:
+## Começar
+
+**Requisito:** [Node.js 18+](https://nodejs.org/).
+
+Na **raiz do repositório** do teu projeto:
 
 ```bash
-node C:\caminho\para\oxe-build\bin\oxe-cc.js
+npx oxe-cc@latest
 ```
 
-### B) Depois de publicado no npm
+Isto copia, entre outros: **`oxe/`** (workflows + templates), **`.cursor/`** (slash commands), **`.github/`** (instruções Copilot + prompt files), **`commands/oxe/`** (atalhos estilo `oxe:*` para outros clientes), **`AGENTS.md`**, e cria um **`.oxe/`** mínimo (`STATE.md`, `config.json` a partir de template, pasta `codebase/`) — salvo flags como `--no-init-oxe`.
+
+**Confirmar instalação no agente**
+
+| Onde | O que correr |
+|------|----------------|
+| **Cursor** | `/oxe-help` |
+| **Copilot** (VS Code) | `/oxe-help` no chat, se [prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files) estiverem ativos (`"chat.promptFiles": true` — exemplo em [`.vscode/settings.json`](.vscode/settings.json)) |
+
+> **Nota:** O Copilot usa **instruções do repositório** (`.github/copilot-instructions.md`) **e** os ficheiros em `.github/prompts/*.prompt.md`. Sem prompt files, ainda podes pedir em linguagem natural (“executa o workflow OXE scan”) com o repo em contexto.
+
+**Sem pacote no npm** (`npm view oxe-cc version` → 404): clone este repo, `npm link` na pasta **oxe-build**, `npm link oxe-cc` no teu projeto, e corre `oxe-cc`. Alternativa: `node /caminho/oxe-build/bin/oxe-cc.js`.
+
+<details>
+<summary><strong>Instalação: flags úteis (CI, ou só parte do pacote)</strong></summary>
+
+| Flag | Efeito |
+|------|--------|
+| `--force` / `-f` | Sobrescreve ficheiros já existentes (**obrigatório** para atualizar cópias antigas) |
+| `--dry-run` | Lista ações sem escrever |
+| `--cursor` / `--copilot` | Instala só uma das stacks |
+| `--oxe-only` | Só a pasta `oxe/` (workflows) |
+| `--no-init-oxe` | Não cria `.oxe/` no fim |
+| `--vscode` | Copia `.vscode/settings.json` de exemplo |
+| `--no-commands` | Omite `commands/oxe/` |
+| `--no-agents` | Omite `AGENTS.md` |
+| `--dir <pasta>` ou argumento posicional | Destino em vez do diretório atual |
+
+**Global:** `npm install -g oxe-cc`.
+
+**Subcomandos:** `oxe-cc doctor` (valida Node, workflows, `.oxe/`), `oxe-cc init-oxe` (só bootstrap `.oxe/`).
+
+</details>
+
+<details>
+<summary><strong>Desenvolvimento (clonar o oxe-build)</strong></summary>
 
 ```bash
-cd /caminho/do/teu-projeto
-npx oxe-cc@latest
+git clone https://github.com/propagno/oxe-build.git
+cd oxe-build
+npm test
+node bin/oxe-cc.js --help
 ```
 
-Já tens OXE nesse repo e saiu release nova? Vê a secção **Atualizar para a versão mais recente** mais abaixo (resumo: `npx oxe-cc@latest --force` na raiz do projeto).
+Para testar no teu app: `npm link` aqui, depois `npm link oxe-cc` no projeto alvo.
 
-Página do pacote (quando existir): [npmjs.com/package/oxe-cc](https://www.npmjs.com/package/oxe-cc). Versões: [aba Versions](https://www.npmjs.com/package/oxe-cc?activeTab=versions).
+</details>
 
-### C) Erro `npm error 404` / `'oxe-cc@latest' is not in this registry`
+---
 
-Significa que **nenhuma versão** de `oxe-cc` foi aceite no `registry.npmjs.org`. Causas frequentes:
+## Como funciona
 
-1. **`npm publish` falhou** (ex. **403** — conta com **2FA obrigatória** para publicar). Ativa 2FA em [npm → Security](https://www.npmjs.com/settings/~/security) e volta a correr `npm publish --access public` dentro da pasta do repo, já autenticado (`npm login`).
-2. **Nome diferente** — publicaste com **scope** (ex. `@propagno/oxe-cc`). Nesse caso usa `npx @propagno/oxe-cc@latest` (ajusta ao `name` real do `package.json`).
-3. **Outro registry** — confirma: `npm config get registry` → deve ser `https://registry.npmjs.org/` para o público.
+**Já tens código?** Começa por **`/oxe-scan`**. Gera mapas em **`.oxe/codebase/`** (stack, estrutura, testes, convenções, etc.). Assim o **spec** e o **plan** alinham com o repo real — à semelhança de correres *map-codebase* antes do roadmap no GSD.
 
-Até o 404 desaparecer, usa a opção **A** (`npm link` ou `node …/bin/oxe-cc.js`).
+### 1. Mapear — `/oxe-scan`
 
-Opções úteis:
+Inventaria o projeto e preenche **`.oxe/codebase/*.md`**, atualiza **`.oxe/STATE.md`**. Podes indicar foco opcional (ex. “só API”).
 
-| Opção | Efeito |
-|--------|--------|
-| *(omissão)* | **Cursor + Copilot** + `oxe/` + `commands/oxe` + `AGENTS.md` |
-| `--all`, `-a` | Garante Cursor e Copilot (mesmo efeito que omitir `--cursor` e `--copilot`) |
-| `--dir <pasta>` | Instala noutro diretório em vez do cwd |
-| `--cursor` | Só `.cursor/commands` e `.cursor/rules` |
-| `--copilot` | Só `.github/copilot-instructions.md` e `.github/prompts` |
-| `--vscode` | Copia também `.vscode/settings.json` (`chat.promptFiles`) |
-| `--no-commands` | Não copia `commands/oxe/` |
-| `--no-agents` | Não copia `AGENTS.md` |
-| `--force` / `-f` | Sobrescreve ficheiros já existentes |
-| `--dry-run` | Mostra o que faria sem escrever |
-| `--no-init-oxe` | Não cria `.oxe/` (STATE, config, codebase) após instalar |
-| `--oxe-only` | Copia só a pasta `oxe/` (sem Cursor, Copilot, `commands/oxe`, `AGENTS.md`) |
-| `-h` / `--help`, `-v` / `--version` | Ajuda e versão |
+### 2. Especificar — `/oxe-spec`
 
-**Subcomandos:**
+Produz ou atualiza **`.oxe/SPEC.md`**: objetivo, escopo, critérios de aceite, riscos. Isto é o contrato antes do plano.
 
-| Comando | Efeito |
-|---------|--------|
-| `oxe-cc doctor [dir]` | Node, workflows vs pacote, JSON válido em `.oxe/config.json`, mapa scan (7 ficheiros em `codebase/`) |
-| `oxe-cc init-oxe [dir]` | Só `.oxe/`: STATE, `config.json` (template), pasta `codebase/` |
+### 3. Discutir *(opcional)* — `/oxe-discuss`
 
-A pasta **`oxe/`** (workflows + templates) é **sempre** copiada na instalação normal. `--cursor` / `--copilot` apenas controlam se entram ficheiros em `.cursor/` e `.github/`.
+Captura decisões de implementação (UI, API, tom, edge cases) em **`.oxe/DISCUSS.md`**, para o plano não “adivinhar” o que preferes. Útil quando `discuss_before_plan` está ativo em `.oxe/config.json`. Saltar = defaults razoáveis; usar = mais próximo da tua visão.
 
-Instalação global (só depois do pacote existir no npm): `npm install -g oxe-cc`.
+### 4. Planear — `/oxe-plan`
 
-### Atualizar para a versão mais recente (depois de um novo `npm publish`)
+Gera **`.oxe/PLAN.md`**: tarefas **atómicas**, **ondas** (paralelo vs sequencial), e bloco **Verificar** (comando de teste ou checklist) **por tarefa**. Ideia: cada tarefa cabe num contexto de agente focado, com verificação explícita — mesmo espírito dos planos XML pequenos do GSD, em Markdown.
 
-O **`oxe-cc` não se auto-atualiza** nos teus projetos: copia ficheiros (`oxe/`, `.cursor/`, …) na altura em que corres o comando. Quando há uma release nova no npm:
+Ondas em resumo: tarefas **independentes** na mesma onda podem correr em paralelo; **dependentes** vão para ondas posteriores (como no diagrama de *waves* do GSD, só que com menos cerimónia).
 
-| Como usas o CLI | O que fazer |
-|-----------------|-------------|
-| **`npx oxe-cc@latest`** no projeto | Volta a correr na **raiz do repo alvo**: `npx oxe-cc@latest` (ou `npx oxe-cc@latest --force` para sobrescrever ficheiros já existentes). O `npx` resolve `@latest` no registry; se parecer “preso” a uma versão antiga, limpa a cache: `npx clear-npx-cache` (npm 7+) e tenta de novo. |
-| **`npm install -g oxe-cc`** | Atualiza o global: `npm install -g oxe-cc@latest` (ou `npm update -g oxe-cc`). Confirma com `oxe-cc --version`. |
-| **`npm link`** ao clone local | Faz `git pull` (ou equivalente) na pasta **`oxe-build`** e volta a correr `oxe-cc` — o link aponta para essa pasta, logo usas o código atual **sem** novo publish. Para alinhar com o que está no npm, publica e usa `npx`/`npm i -g` como acima. |
+### 5. Executar — implementação + `/oxe-execute` *(opcional)*
 
-Ver qual é a última versão publicada:
+Implementas no editor ou deixas o agente seguir **`/oxe-execute`** sobre o plano (ou QUICK). O OXE não impõe subagentes nem commits atómicos por tarefa como o GSD; isso fica ao teu fluxo Git.
 
-```bash
-npm view oxe-cc version
-```
+### 6. Verificar — `/oxe-verify`
 
-Comparar com a tua cópia (ficheiro `oxe/workflows/scan.md` etc.): se faltam workflows novos, corre outra vez o instalador com **`--force`** onde fizer sentido.
+Cruza **SPEC** + **PLAN** com o código; escreve **`.oxe/VERIFY.md`**. Se algo falhar, corrigis ou replanejas (`/oxe-plan` com lógica de replanejamento descrita no workflow).
 
-### Nova versão no npm (mantenedores)
+### 7. Seguir em frente — `/oxe-next` e ciclo
 
-1. Atualiza **`version`** em `package.json` (semver).  
-2. Garante **`repository`**, **`homepage`** e **`bugs`** corretos para o teu GitHub.  
-3. Conta npm com **2FA** ativa: `npm login`, depois **`npm publish --access public`**.  
-4. O script **`prepublishOnly`** corre testes + `scan:assets` + `--version` antes do upload.
+Para a **próxima** feature ou fase: de novo **spec → plan → …** ou **`/oxe-next`** para sugerir o passo lógico a partir de **STATE.md**.
 
-### Fork com outro nome no npm
+---
 
-1. Edita `package.json`: **`name`** (ex. `@tua-org/oxe-cc`) e **`repository.url`**.  
-2. `npm publish --access public` (scopes `@org/...` precisam de `--access public` na primeira publicação).
+## Modo rápido
 
-### CLI com nome personalizado
+Para trabalho **adhoc** sem roadmap completo — equivalente conceptual ao **`/gsd:quick`**:
 
-No `package.json`, o binário é o mapa **`bin`**: a chave é o comando no terminal, o valor é o script.
+**`/oxe-quick`** gera **`.oxe/QUICK.md`** com passos curtos e verificação. Depois podes usar **`/oxe-execute`** em cima disso ou implementar direto e fechar com **`/oxe-verify`**.
 
-```json
-"bin": {
-  "oxe-cc": "bin/oxe-cc.js",
-  "meu-oxe": "bin/oxe-cc.js"
-}
-```
+Se o trabalho crescer, **promove** para spec + plan completos.
 
-Depois de publicar, o comando extra fica disponível **globalmente** com `npm i -g nome-do-pacote` como `meu-oxe`. Com **npx**, o pacote continua a identificar-se pelo **`name`** em `package.json`; para correr um binário que não é o nome do pacote, usa por exemplo `npx -p oxe-cc meu-oxe` (ajusta `oxe-cc` / `meu-oxe` aos teus nomes).
+---
 
-O ficheiro do script (`bin/oxe-cc.js`) pode ser renomeado desde que atualizes o caminho no mapa `bin`.
+## Porque funciona
 
-**Desenvolvimento local sem publicar:** na pasta `oxe-build`, `npm link` e no projeto alvo `npm link oxe-cc`, depois `oxe-cc`; ou `node /caminho/para/oxe-build/bin/oxe-cc.js`. **Testes:** `npm test`. **Scan de assets (padrões tipo segredo em markdown):** `npm run scan:assets`.
+**Context engineering:** o agente não precisa de “lembrar” tudo na janela principal — o que importa está em ficheiros **pequenos e por etapa**.
 
-### Imagem / banner no início do CLI
+| Artefato | Função |
+|----------|--------|
+| `.oxe/STATE.md` | Fase, decisões, próximo passo — memória entre sessões |
+| `.oxe/codebase/*.md` | Mapa do repo após scan |
+| `.oxe/SPEC.md` | O que entregar e como saber que está certo |
+| `.oxe/DISCUSS.md` | Preferências antes do plano *(opcional)* |
+| `.oxe/PLAN.md` | Tarefas atómicas + **Verificar** por item |
+| `.oxe/QUICK.md` | Modo rápido |
+| `.oxe/VERIFY.md` | Resultado das verificações |
+| `oxe/workflows/*.md` | **Fonte única** dos passos (Cursor e Copilot só delegam aqui) |
 
-Ao correr `oxe-cc` (instalar, `doctor`, `init-oxe`, `--help`), aparece um **cabeçalho ASCII** vindo de [`bin/banner.txt`](bin/banner.txt). Podes **personalizar** editando esse ficheiro no teu fork antes de publicar no npm.
+**Formato:** planos em Markdown com secções fixas (incl. verificação), legíveis por humanos e por modelos — sem XML obrigatório, mas com a mesma ideia de *precise instructions + verify*.
 
-- Placeholder **`{version}`** — substituído pela versão do `package.json` (ex. `v0.3.0`).
-- **Cores:** em terminal TTY, o corpo usa ciano + negrito; a linha com a versão fica mais discreta. Define **`NO_COLOR`** (ou `FORCE_COLOR=0`) para saída só texto.
-- **Desligar o banner:** variável de ambiente **`OXE_NO_BANNER=1`** (útil em CI ou testes).
-- **`--version`** não mostra banner — só uma linha `oxe-cc v…` para scripts.
+---
 
-Para um “logo” mais elaborado, substitui o conteúdo de `banner.txt` pelo teu ASCII art (várias linhas, largura ~60 colunas costuma caber bem). Não é suportada imagem bitmap no terminal; para isso seria preciso outra ferramenta (ex. `terminal-image`) e dependências extra.
+## Comandos
 
-## Fonte única
+### Fluxo principal
 
-Os passos detalhados vivem em **`oxe/workflows/`** (`scan.md`, `spec.md`, `discuss.md`, `plan.md`, `quick.md`, `execute.md`, `verify.md`, `next.md`, `help.md`). Comandos Cursor, prompts Copilot e `commands/oxe/*` **delegam** para esses ficheiros.
+| Comando | O que faz |
+|---------|-----------|
+| `/oxe-scan` | Mapeia o codebase → `.oxe/codebase/` |
+| `/oxe-spec` | Escreve/atualiza `.oxe/SPEC.md` |
+| `/oxe-discuss` | Decisões antes do plano → `.oxe/DISCUSS.md` |
+| `/oxe-plan` | Pesquisa no repo + plano com ondas e Verificar |
+| `/oxe-execute` | Execução guiada do plano (ou QUICK) |
+| `/oxe-verify` | Validação; `.oxe/VERIFY.md` |
+| `/oxe-next` | Sugere o próximo passo |
+| `/oxe-help` | Ajuda e visão geral |
 
-Por omissão, após instalar, o CLI cria **`.oxe/`** mínimo: `STATE.md`, **`config.json`** (a partir de `oxe/templates/config.template.json`) e pasta **`codebase/`** — exceto com `--no-init-oxe`. Documentação das chaves: **`oxe/templates/CONFIG.md`**.
+### Modo rápido
 
-## Cursor
+| Comando | O que faz |
+|---------|-----------|
+| `/oxe-quick` | `.oxe/QUICK.md` — tarefa pontual |
 
-| Slash | Workflow |
-|-------|----------|
-| `/oxe-scan` | `oxe/workflows/scan.md` |
-| `/oxe-spec` | `oxe/workflows/spec.md` |
-| `/oxe-discuss` | `oxe/workflows/discuss.md` |
-| `/oxe-plan` | `oxe/workflows/plan.md` |
-| `/oxe-quick` | `oxe/workflows/quick.md` |
-| `/oxe-execute` | `oxe/workflows/execute.md` |
-| `/oxe-verify` | `oxe/workflows/verify.md` |
-| `/oxe-next` | `oxe/workflows/next.md` |
-| `/oxe-help` | `oxe/workflows/help.md` |
+### Revisão de PR / diff entre branches *(só Copilot)*
 
-Ficheiros: `.cursor/commands/oxe-*.md` e regra `.cursor/rules/oxe-workflow.mdc`.
+| Prompt | O que faz |
+|--------|-----------|
+| `/oxe-review-pr` | Segue `oxe/workflows/review-pr.md`: diff estilo PR (`git diff base...head`, `gh pr diff <n>`, ou fetch `pull/<n>/head`), riscos, testes e checklist. Podes colar o **link da PR** (ex. `https://github.com/org/repo/pull/10`) ou indicar `main` e `feature/x`. **Não** há slash command em `.cursor/commands/`; no Cursor podes pedir o mesmo em linguagem natural com o workflow em contexto. |
 
-## GitHub Copilot
+### Outros clientes
 
-1. **Instruções do repositório** — [`.github/copilot-instructions.md`](.github/copilot-instructions.md): ativadas automaticamente no chat quando o repositório está em contexto (ver [documentação](https://docs.github.com/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)).
-2. **Prompt files** — [`.github/prompts/*.prompt.md`](.github/prompts/): no chat, escreve `/` e escolhe por exemplo **`oxe-scan`**, **`oxe-quick`**, **`oxe-execute`**, etc. (o `name` no frontmatter define o comando). Cada prompt referencia `oxe/workflows/<passo>.md` na **raiz do repo em contexto**.
+Em **Claude Code** (ou ferramentas que leem `commands/oxe/`), os mesmos passos expõem nomes **`oxe:scan`**, **`oxe:plan`**, etc. (frontmatter `name:`).
 
-Este repo inclui [`.vscode/settings.json`](.vscode/settings.json) com `"chat.promptFiles": true` para expor a pasta `.github/prompts`. Podes copiar essa definição para o teu `settings.json` global se preferires.
+---
 
-3. **Agentes** — [`AGENTS.md`](AGENTS.md) resume o pacote para modos que leem instruções de agente no repo.
+## Configuração
 
-## Fluxo recomendado
+Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir de `oxe/templates/config.template.json`). Chaves e comportamento: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md) (ex.: `discuss_before_plan`, texto pós-verify, comando de teste por defeito).
 
-**Completo:** 1. **scan** (7 ficheiros em `codebase/`, incl. CONVENTIONS + CONCERNS) → 2. **spec** → 3. **discuss** (opcional; recomendado se `discuss_before_plan` em `.oxe/config.json`) → 4. **plan** (secção **Replanejamento** em `--replan`) → 5. **execute** (opcional) → 6. implementar → 7. **verify** (rascunho de commit + checklist PR se ativo em config) → 8. **next**.
+---
 
-**Rápido (tarefas pequenas):** **quick** gera `.oxe/QUICK.md` com passos curtos + verificação; depois **execute** (sobre o QUICK) ou implementação direta e **verify**. Promover a spec/plan se o trabalho crescer (muitos ficheiros, API pública, segurança).
+## Resolução de problemas
 
-## Artefatos (`.oxe/` no projeto alvo)
+| Situação | O que tentar |
+|----------|----------------|
+| Comandos não aparecem no Cursor | Confirma que `.cursor/commands/` existe; reinicia o Cursor |
+| Prompts `/oxe-*` não aparecem no Copilot | Ativa `"chat.promptFiles": true`; confirma `.github/prompts/*.prompt.md` |
+| **`ETARGET`** / versão não encontrada no `npx` | `npm cache clean --force`, `npx clear-npx-cache`, ou fixa versão: `npx oxe-cc@0.3.0`. Verifica `npm config get registry` |
+| **404** no `npm view oxe-cc` | Pacote com outro nome (scope) ou ainda não publicado — usa `npm link` ou `node …/bin/oxe-cc.js` |
+| Ficheiros não atualizam | Reinstala com **`--force`** |
 
-| Caminho | Conteúdo |
-|---------|----------|
-| `.oxe/STATE.md` | Fase, último scan, próximo passo |
-| `.oxe/config.json` | Opcional (criado no bootstrap): `discuss_before_plan`, texto de verify pós-sucesso, comando de teste por defeito — ver `oxe/templates/CONFIG.md` |
-| `.oxe/codebase/*.md` | Mapa: OVERVIEW, STACK, STRUCTURE, TESTING, INTEGRATIONS, **CONVENTIONS**, **CONCERNS** |
-| `.oxe/SPEC.md` | Especificação |
-| `.oxe/DISCUSS.md` | Perguntas e decisões antes do plano (opcional) |
-| `.oxe/PLAN.md` | Plano com **Verificar** por tarefa + secção **Replanejamento** |
-| `.oxe/QUICK.md` | Modo rápido: passos curtos + verificar |
-| `.oxe/VERIFY.md` | Resultado das verificações |
-| `.oxe/SUMMARY.md` | Resumo de sessão / contexto para replan (opcional) |
+**Ajuda no terminal:** `oxe-cc --help`. **Diagnóstico:** `oxe-cc doctor`.
 
-Templates: **`oxe/templates/`** (`STATE.md`, `config.template.json`, `CONFIG.md`, `SPEC.template.md`, `PLAN.template.md`, `SUMMARY.template.md`).
+**Banner no CLI:** [`bin/banner.txt`](bin/banner.txt) (`{version}`). `OXE_NO_BANNER=1` desliga; `NO_COLOR` remove cores.
 
-Neste repositório, **`.oxe/` está no `.gitignore`** para não versionar scans locais do *oxe-build*. No teu produto, remove ou ajusta essa regra se quiseres commitar `.oxe/` com a equipa.
+<details>
+<summary><strong>Publicar no npm (mantenedores)</strong></summary>
 
-## Usar noutro projeto
+Sobe `version` em `package.json`, `npm login` (2FA se exigido), `npm publish --access public`. O `prepublishOnly` corre testes e `scan:assets`.
 
-- Com pacote no npm: **`npx oxe-cc@latest`** na raiz do repo alvo, ou **`npx oxe-cc@<versão>`** (versões na [página do pacote](https://www.npmjs.com/package/oxe-cc?activeTab=versions) quando existir).
-- Sem pacote no npm: **`npm link oxe-cc`** (após `npm link` no clone do `oxe-build`) ou **`node …/oxe-build/bin/oxe-cc.js`**.
+</details>
 
-Alternativa manual: copia os mesmos caminhos que o instalador usa (`oxe/`, `.cursor/`, `.github/`, `commands/oxe`, `AGENTS.md`, opcionalmente `.vscode/settings.json` ou só `"chat.promptFiles": true` nas definições).
+<details>
+<summary><strong>Estrutura do repositório</strong></summary>
 
-`commands/oxe/*.md` mantém frontmatter estilo GSD (`name: oxe:scan`, …) para ferramentas que importam comandos nesse formato.
+| Caminho | Função |
+|---------|--------|
+| `assets/readme-banner.svg` | Banner deste README |
+| `bin/oxe-cc.js`, `bin/banner.txt` | CLI |
+| `oxe/workflows/` | Workflows canónicos |
+| `oxe/templates/` | Modelos e CONFIG |
+| `.cursor/`, `.github/` | Cursor e Copilot |
+| `commands/oxe/` | `oxe:*` para outros runtimes |
+| `tests/`, `scripts/`, `.github/workflows/` | CI e qualidade |
 
-## Estrutura deste repositório
+</details>
 
-| Pasta / ficheiro | Função |
-|------------------|--------|
-| `bin/oxe-cc.js` | CLI: instalar, `doctor`, `init-oxe` |
-| `bin/banner.txt` | Cabeçalho ASCII ao arrancar o CLI (`{version}`) |
-| `package.json` | Metadados npm (`oxe-cc`, `files`, `bin`) |
-| `oxe/workflows/` | Workflows canónicos (fonte única) |
-| `oxe/templates/` | Modelos (STATE, config, SPEC, PLAN, SUMMARY, CONFIG.md) |
-| `scripts/oxe-assets-scan.cjs` | Verificação leve de padrões sensíveis em markdown (CI / `npm run scan:assets`) |
-| `.github/workflows/ci.yml` | `npm test` + `scan:assets` |
-| `.cursor/commands/` | Slash commands Cursor |
-| `.cursor/rules/` | Regras do projeto Cursor |
-| `.github/copilot-instructions.md` | Instruções Copilot no repo |
-| `.github/prompts/` | Ficheiros `*.prompt.md` (`/oxe-scan`, …) |
-| `commands/oxe/` | Comandos com frontmatter estilo GSD |
-| `AGENTS.md` | Resumo para agentes (ex. Copilot) |
+---
 
 ## Licença
 
-[GPL-3.0](LICENSE) — ver [LICENSE](LICENSE).
+[GPL-3.0](LICENSE).

package/assets/readme-banner.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="200" viewBox="0 0 920 200" role="img" aria-label="OXE  spec-driven workflows">
+  <defs>
+    <linearGradient id="oxe-bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0d1117"/>
+      <stop offset="50%" style="stop-color:#161b22"/>
+      <stop offset="100%" style="stop-color:#21262d"/>
+    </linearGradient>
+    <linearGradient id="oxe-accent" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#58a6ff"/>
+      <stop offset="100%" style="stop-color:#79c0ff"/>
+    </linearGradient>
+  </defs>
+  <rect width="920" height="200" rx="16" fill="url(#oxe-bg)"/>
+  <rect x="2" y="2" width="916" height="196" rx="14" fill="none" stroke="url(#oxe-accent)" stroke-width="2" opacity="0.45"/>
+  <text x="460" y="100" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="72" font-weight="800" fill="url(#oxe-accent)" letter-spacing="0.12em">OXE</text>
+  <text x="460" y="138" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="17" fill="#8b949e">Fluxo spec-driven � Cursor &amp; GitHub Copilot � CLI npm</text>
+  <text x="460" y="168" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Consolas, monospace" font-size="13" fill="#6e7681">npx oxe-cc@latest</text>
+</svg>

package/oxe/workflows/help.md

@@ -16,7 +16,7 @@ Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-ver
 ## 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.
+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`**, **`oxe-review-pr`** (revisão: URL `github.com/.../pull/N`, branches ou SHAs). Requer `chat.promptFiles`: true.
 
 ## Fluxo completo
 
@@ -46,5 +46,7 @@ Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-ver
 
 ## Gatilhos naturais (Copilot / chat)
 
-Quando o utilizador disser “oxe scan”, “oxe quick”, “executar onda OXE”, etc., seguir o workflow correspondente em `oxe/workflows/*.md`.
+Quando o utilizador disser “oxe scan”, “oxe quick”, “executar onda OXE”, “revisar PR”, “diff entre branches”, etc., seguir o workflow correspondente em `oxe/workflows/*.md`.
+
+**Nota:** **`oxe-review-pr`** não tem homólogo em `.cursor/commands/`; no Cursor podes pedir em linguagem natural seguindo `oxe/workflows/review-pr.md` ou abrir o mesmo ficheiro como contexto.
 </output>

package/oxe/workflows/review-pr.md

@@ -0,0 +1,45 @@
+# OXE — Workflow: review-pr (revisão de diff / PR)
+
+<objective>
+Rever alterações como num pull request: **URL do GitHub** (`…/pull/<n>`), **branches** ou **SHAs**. Cobre diff, risco, convenções do projeto e sugestões acionáveis. **Não** substitui CI nem testes manuais; complementa-os.
+</objective>
+
+<context>
+- **Base** e **head** são nomes de branch, tags ou SHAs (ex.: `main` e `feature/foo`).
+- **URL de PR no GitHub** — O utilizador pode colar o link da PR (ex.: `https://github.com/org/repo/pull/10` ou atalho `org/repo#10`). O número da PR é o segmento depois de `/pull/`.
+- Em Git, o diff “estilo PR” (só o que a branch introduz) usa o **merge base**: `git diff base...head` (três pontos).
+- Diff literal entre pontas: `git diff base..head` (dois pontos) — útil quando o utilizador pede explicitamente.
+- Este passo é **opcional** no fluxo OXE; não atualiza `STATE.md` com fases canónicas, salvo o utilizador pedir registo do resultado em disco.
+</context>
+
+<process>
+1. **Resolver entrada**
+   - **URL ou `#` de PR** — Se a mensagem contiver um URL `github.com/.../pull/<n>` (com ou sem `https://`, com sufixo `/files` ou `/commits`) ou texto `owner/repo#n`, extrair `<n>` (e opcionalmente `owner/repo` para confirmar que o clone local é o mesmo repositório).
+   - **Refs explícitas** — Caso contrário, tratar como base/head: se faltar um dos dois, inferir base = `main` ou `master` (o que existir) e head = branch atual (`git rev-parse --abbrev-ref HEAD`), ou pedir clarificação.
+2. **Obter diff (com URL / número de PR)** — Ordem de preferência quando o cwd é o repositório certo:
+   - **GitHub CLI:** `gh pr diff <n>` (ou `gh pr diff <n> --patch`). Se `gh` não estiver disponível ou falhar auth, tentar Git puro.
+   - **Git fetch ref da PR:** `git fetch origin pull/<n>/head:oxe-pr-<n>` (ajustar `origin` se o remoto tiver outro nome). Descobrir branch base com `gh pr view <n> --json baseRefName -q .baseRefName` ou assumir `main`/`master`; depois `git diff origin/<base>...oxe-pr-<n>` ou `git diff <base>...oxe-pr-<n>` após `fetch` da base.
+   - **Sem terminal / outro repo:** Pedir ao utilizador que cole o diff da aba “Files changed” no GitHub ou o output de `gh pr diff <n>` corrido localmente no repo certo.
+3. **Obter diff (só branches / SHAs)** — Preferir terminal quando disponível:
+   - `git fetch` (se fizer sentido e o ambiente permitir rede).
+   - `git merge-base base head` (opcional, para confirmar ancestral comum).
+   - `git diff base...head` (revisão tipo PR).
+   - `git log base..head --oneline -n 30` (contexto de commits).
+   Se o sandbox bloquear Git, pedir ao utilizador que cole o output de `git diff base...head` ou use o diff da UI do GitHub/GitLab.
+   Se o diff já foi obtido no passo 2 (URL da PR), **não** repetir este passo.
+4. **Ler contexto do projeto** — Se existirem, usar trechos relevantes de `.oxe/codebase/CONVENTIONS.md`, `STACK.md`, `OVERVIEW.md` e, se aplicável, `.oxe/SPEC.md` / `.oxe/PLAN.md` para alinhar expectativas (sem assumir que o PR cobre só OXE).
+5. **Analisar** — Estruturar a resposta com:
+   - **Resumo** — O que muda em 3–6 frases.
+   - **Ficheiros / áreas** — Agrupar por domínio (API, UI, config, etc.).
+   - **Riscos** — Regressões, breaking changes, segurança (inputs, segredos, auth), performance óbvia, migrações.
+   - **Testes** — O que deveria ser coberto ou correr localmente (comandos sugeridos se conhecidos do repo).
+   - **Checklist PR** — Título sugerido, descrição curta, breaking changes, rollback.
+6. **Opcional em disco** — Se o utilizador pedir registo: criar ou atualizar **`.oxe/PR-REVIEW.md`** com data, URL ou refs (base/head), resumo, achados e próximos passos (formato Markdown legível).
+</process>
+
+<success>
+- [ ] URL da PR ou par base/head está explícito na resposta (ou foi pedida clarificação).
+- [ ] A análise baseia-se no diff (terminal ou colado), não só em suposições.
+- [ ] Há secção de riscos e de testes/verificação sugerida.
+- [ ] Nenhum segredo ou credencial é repetido na análise; redigir se aparecerem no diff.
+</success>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxe-cc",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "OXE — spec-driven workflows for Cursor and GitHub Copilot (install via npx)",
   "license": "GPL-3.0",
   "author": "",
@@ -29,6 +29,7 @@
   "files": [
     "bin",
     "oxe",
+    "assets",
     ".cursor",
     ".github",
     "commands",