oxe-cc 1.4.0 → 1.5.0

package/commands/oxe/workstream.md

@@ -44,6 +44,10 @@ oxe_semantics_hash: 380bd0a3f3620845
 
 <!-- oxe-reasoning-contract:end -->
 
-**Workflow canónico:** `oxe/workflows/workstream.md`
+<!-- oxe-workflow-resolution:start -->
 
-Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa o texto em `$ARGUMENTS` como subcomando e contexto.
+**Resolução do workflow canónico:** a partir do CWD atual, subir diretórios até encontrar .oxe/workflows/workstream.md ou oxe/workflows/workstream.md. Ler e aplicar integralmente o primeiro ficheiro encontrado. Não assumir que o CWD já é a raiz do repositório. Se nenhum existir, reportar os paths tentados e parar.
+
+<!-- oxe-workflow-resolution:end -->
+
+Usa o texto em `$ARGUMENTS` como subcomando e contexto.

package/docs/INCIDENT-PLAYBOOK.md

@@ -0,0 +1,181 @@
+# OXE — Incident Playbook
+
+> Para operadores de gate e tech leads. Este guia cobre os cenários de bloqueio mais comuns e como resolvê-los.
+
+---
+
+## Gate stale (>24h sem resolução)
+
+**Sintoma:** `oxe-cc runtime gates list` mostra `⚠ stale` para um ou mais gates.
+
+**Quando agir:** gate stale bloqueia a promoção da run. Se o ciclo precisa avançar, o operador deve tomar uma decisão explícita.
+
+**Sequência de diagnóstico:**
+
+```bash
+# 1. Ver detalhes do gate
+npx oxe-cc runtime gates show --dir . --gate <gate-id>
+
+# Output mostra:
+#   tipo, critério bloqueado, tempo em aberto, run afetada
+
+# 2. Avaliar o risco
+cat .oxe/runs/<run-id>/residual-risks.json
+```
+
+**Decisões possíveis:**
+
+| Decisão | Quando usar | Comando |
+|---------|-------------|---------|
+| `approve` | Evidências suficientes, risco aceitável | `--decision approve` |
+| `reject` | Implementação não atende o critério | `--decision reject` |
+| `waive` | Gate válido, mas contexto mudou (urgência, POC) | `--decision waive` |
+
+```bash
+npx oxe-cc runtime gates resolve \
+  --dir . \
+  --gate <gate-id> \
+  --decision waive \
+  --actor "nome-do-operador" \
+  --reason "Hotfix urgente — evidência formal na próxima sprint"
+```
+
+**Output esperado:**
+```
+⚠ Gate <gate-id> dispensado (waive).
+Motivo registrado. Run pode avançar.
+Gates restantes: 0
+```
+
+**Importante:** `waive` não remove o gate do histórico — ele fica registrado com o motivo para auditoria posterior.
+
+---
+
+## Run bloqueada (não avança mesmo sem gates pendentes)
+
+**Sintoma:** `runtime promote` falha ou `status` mostra run como `blocked`.
+
+**Sequência de diagnóstico:**
+
+```bash
+# 1. Ver estado completo
+npx oxe-cc status --full
+
+# 2. Tentar replay (re-executa último evento da run)
+npx oxe-cc runtime replay --dir . --run-id <run-id>
+```
+
+**Se replay não desbloquear:**
+
+```bash
+# 3. Diagnóstico detalhado
+npx oxe-cc runtime recover --dir . --run-id <run-id>
+```
+
+**Output de `runtime recover`:**
+```
+RECOVERY SUMMARY — run-id: <run-id>
+─────────────────────────────────────
+Work items órfãos: 2
+  - task-T3: última atualização há 47min, sem commit associado
+  - task-T4: dependência de T3 não satisfeita
+
+Policy drift: sim
+  - SPEC.md modificado após geração do PLAN.md (hash divergente)
+
+Evidence gaps: 1
+  - Critério A2 sem evidência registrada no VERIFY.md
+
+Ação recomendada: re-run /oxe-verify para fechar evidence gap
+```
+
+**Ações corretivas:**
+
+| Problema | Ação |
+|----------|------|
+| Work items órfãos | Marcar tarefas como concluídas ou rodar `/oxe-execute --task <id>` |
+| Policy drift (SPEC alterado) | Rodar `/oxe-verify` novamente — vai reprocessar com SPEC atual |
+| Evidence gaps | Rodar `/oxe-verify` — vai preencher lacunas de evidência |
+| State corrompido | `runtime recover --force` reinicia a run preservando artefatos |
+
+---
+
+## Como interpretar o RECOVERY-SUMMARY
+
+### Work items órfãos
+
+Tarefas que foram planejadas mas não têm evidência de conclusão. Causas comuns:
+- Executor saiu no meio da onda sem marcar a tarefa como concluída
+- Sessão fechada antes de completar a execução
+
+**O que fazer:** verificar o código gerado para a tarefa e marcar como concluída se a implementação existir, ou re-executar com `/oxe-execute --task <id>`.
+
+### Policy drift
+
+O hash do SPEC.md divergiu do hash registrado na run. Isso acontece quando o SPEC é editado manualmente após o início da execução.
+
+**O que fazer:** se as mudanças no SPEC são intencionais, rodar `/oxe-verify` para reconciliar. Se foram acidentais, restaurar o SPEC original com `git checkout -- .oxe/SPEC.md`.
+
+### Evidence gaps
+
+Critérios A* do SPEC sem evidência correspondente no VERIFY.md. Causas comuns:
+- `/oxe-verify` rodou antes da implementação estar completa
+- Critério adicionado ao SPEC após a verificação
+
+**O que fazer:** rodar `/oxe-verify` novamente — vai re-escanear implementação e preencher lacunas.
+
+---
+
+## Dashboard como painel operacional
+
+```bash
+npx oxe-cc runtime dashboard --dir .
+```
+
+O dashboard mostra o estado de todas as runs ativas em uma view consolidada.
+
+**O que observar por estado:**
+
+| Estado no dashboard | Significado | Ação |
+|--------------------|-------------|------|
+| `execute_complete` | Onda executada, aguardando verify | Rodar `/oxe-verify` |
+| `verify_complete` | Pronto para promoção | `runtime promote --target pr_draft` |
+| `blocked` | Bloqueada por gate ou error | Ver seção "Run bloqueada" acima |
+| `stale` | Run sem atividade por >24h | Investigar ou fechar sessão |
+| `pr_draft` | PR draft criado | Aguardar review do time |
+
+**Indicadores de saúde no dashboard:**
+
+- **Gates pendentes:** número de gates aguardando decisão — deve ser 0 para promoção
+- **Runs ativas:** runs com sessão aberta — fechar as que não estão em uso
+- **Evidence coverage:** percentual de critérios A* com evidência — deve ser 100% antes de promote
+
+---
+
+## Referência rápida de comandos
+
+```bash
+# Ver todos os gates com estado visual
+npx oxe-cc runtime gates list --dir .
+
+# Ver detalhes de um gate específico
+npx oxe-cc runtime gates show --dir . --gate <id>
+
+# Resolver gate
+npx oxe-cc runtime gates resolve --dir . --gate <id> --decision <approve|reject|waive> --actor <nome>
+
+# Promover run
+npx oxe-cc runtime promote --dir . --target <pr_draft|staging|production>
+
+# Re-executar último evento da run
+npx oxe-cc runtime replay --dir . --run-id <id>
+
+# Diagnóstico e recovery
+npx oxe-cc runtime recover --dir . --run-id <id>
+
+# Estado operacional completo
+npx oxe-cc status --full
+
+# Dashboard consolidado
+npx oxe-cc runtime dashboard --dir .
+```

package/docs/RELEASE-READINESS.md

@@ -0,0 +1,46 @@
+# Release Readiness — OXE
+
+Este é o contrato mínimo para publicar uma versão estável do OXE sem drift entre pacote, runtime, wrappers e operação enterprise.
+
+## Gate local
+
+```bash
+npm test
+npm run scan:assets
+npm run build:vscode-ext
+npx oxe-cc doctor --release --write-manifest
+```
+
+O `doctor --release` deve bloquear a publicação quando encontrar:
+
+- drift de versão entre `package.json`, `packages/runtime/package.json`, `vscode-extension/package.json`, `README.md`, `CHANGELOG.md` e banner
+- topo do `CHANGELOG` ausente, sem data ou sem highlights
+- runtime não compilado em `lib/runtime/index.js`
+- wrappers dirty após `sync-runtime-metadata` e `sync:cursor`
+- ausência ou falha dos relatórios obrigatórios da release
+
+## Relatórios obrigatórios
+
+Todos os artefatos abaixo devem existir em `.oxe/release/`:
+
+- `release-manifest.json`
+- `runtime-smoke-report.json`
+- `recovery-fixture-report.json`
+- `multi-agent-soak-report.json`
+
+## Defaults estáveis desta publicação
+
+- `execute` e `verify`: `runtime-first`
+- `promotion`: somente `pr_draft`
+- `multi-agent`: GA apenas com `git_worktree`
+- `branch_push`: capability avançada, fora da superfície estável
+
+## CI
+
+O pipeline de CI e o pipeline de release devem rodar o mesmo gate:
+
+1. `npm test`
+2. `npm run scan:assets`
+3. `npm run release:doctor`
+
+Se qualquer etapa falhar, a release não está pronta.

package/docs/ROLES.md

@@ -0,0 +1,129 @@
+# OXE — Guia por Papel
+
+Cada papel interage com o OXE de uma forma diferente. Este guia resume o que cada pessoa precisa ler, decidir e — importante — o que pode ignorar.
+
+---
+
+## Executor
+
+**Quem é:** Developer implementando a feature ou fix do ciclo atual.
+
+**O que lê:**
+- `.oxe/PLAN.md` — ondas, tarefas, hipóteses críticas, arquivos-alvo
+- `.oxe/SPEC.md` — critérios de aceite (o que constitui "pronto")
+- `.oxe/STATE.md` — fase atual e próximo passo recomendado
+
+**O que decide:**
+- Quando uma tarefa está concluída (marcar `[x]` ou deixar o executor marcar via `/oxe-execute`)
+- Se uma hipótese crítica não pode ser verificada → escalar via `/oxe-debug`
+- Se o plano precisa ser refeito → comunicar e rodar `/oxe-plan` novamente
+
+**O que não precisa conhecer:**
+- Detalhes do VERIFY.md (responsabilidade do reviewer)
+- Configuração de gates e promoção (responsabilidade do operador)
+- Funcionamento interno do runtime TypeScript
+
+**Comandos principais:**
+```
+/oxe-execute   → executa a onda atual
+/oxe-execute --task T3  → executa tarefa específica
+/oxe-debug     → diagnóstico quando travado
+/oxe-quick     → ciclo completo para tarefas S/M
+```
+
+---
+
+## Reviewer
+
+**Quem é:** Developer ou tech lead validando o que foi implementado.
+
+**O que lê:**
+- `.oxe/SPEC.md` — critérios de aceite para comparar com a implementação
+- `.oxe/VERIFY.md` — resultado da verificação gerada pelo `/oxe-verify`
+- Código e testes produzidos no ciclo
+
+**O que decide:**
+- Se os critérios A* foram atendidos
+- Se há riscos residuais que bloqueiam a promoção
+- Se é necessário um novo ciclo (respec, replan, re-execute)
+
+**O que não precisa conhecer:**
+- Detalhes de implementação de cada tarefa do PLAN.md
+- Configuração de runtime, gates ou sessions
+
+**Comandos principais:**
+```
+/oxe-verify         → valida critérios do SPEC contra evidências
+/oxe-verify --audit → auditoria adversarial (sem acesso ao PLAN)
+/oxe-review-pr      → revisão de PR/branch externo
+```
+
+---
+
+## Operador de Gate / Incidente
+
+**Quem é:** Tech lead ou SRE responsável por aprovar promoções e resolver bloqueios operacionais.
+
+**O que lê:**
+- `npx oxe-cc runtime gates list --dir .` — fila de gates pendentes
+- `.oxe/runs/<run_id>/residual-risks.json` — riscos residuais da run
+- `npx oxe-cc status --full` — estado operacional completo
+- [`docs/INCIDENT-PLAYBOOK.md`](INCIDENT-PLAYBOOK.md) — guia de resolução
+
+**O que decide:**
+- Aprovar, rejeitar ou dispensar (`waive`) cada gate
+- Quando disparar `runtime recover` vs. `runtime replay`
+- Quando promover para `pr_draft` ou bloquear a promoção
+
+**O que não precisa conhecer:**
+- Detalhes do PLAN.md ou quais tarefas foram implementadas
+- Semântica de raciocínio dos workflows
+
+**Comandos principais:**
+```bash
+npx oxe-cc runtime gates list --dir .
+npx oxe-cc runtime gates resolve --dir . --gate <id> --decision approve --actor <nome>
+npx oxe-cc runtime promote --dir . --target pr_draft
+npx oxe-cc runtime recover --dir . --run-id <id>
+npx oxe-cc status --full
+```
+
+---
+
+## Mantenedor do Pacote
+
+**Quem é:** Responsável por publicar novas versões do `oxe-cc` no npm.
+
+**O que lê:**
+- `CHANGELOG.md` — deve ter entrada para a nova versão antes de publicar
+- `README.md` — badge de versão deve estar atualizado
+- `package.json` — `version` alinhado com tag git e CHANGELOG
+- `.github/workflows/release.yml` — pipeline de publicação automatizada
+
+**O que decide:**
+- Qual semver bump aplicar (major/minor/patch)
+- Quando acionar a release (tag `v*.*.*` no git)
+- Se uma release candidate é necessária antes da publicação
+
+**O que não precisa conhecer:**
+- Detalhes de implementação dos workflows individuais
+- Estado operacional de projetos que usam OXE
+
+**Checklist de release:**
+```bash
+# 1. Bump de versão
+#    Atualizar: package.json, README.md, CHANGELOG.md
+
+# 2. Validar
+npm test
+npm run scan:assets
+node bin/oxe-cc.js doctor
+node bin/oxe-cc.js --version
+
+# 3. Dry-run
+npm publish --dry-run
+
+# 4. Tag e push (dispara release.yml automaticamente)
+git tag v1.x.0
+git push origin v1.x.0
+```

package/docs/RUNTIME-SMOKE-MATRIX.md

@@ -0,0 +1,128 @@
+# OXE — Runtime Smoke Matrix
+
+> Estado de suporte por runtime de IA. Atualizado em v1.5.0.
+>
+> `✓` = suportado e testado | `~` = suportado parcialmente | `✗` = não suportado | `?` = não testado
+
+Este documento descreve a matrix estável da release. O artefato operacional consumido por `doctor --release` é `.oxe/release/runtime-smoke-report.json`.
+
+---
+
+## Matriz de operações × runtimes
+
+| Runtime       | install | `/oxe` | plan | execute | verify | runtime-first |
+|---------------|:-------:|:------:|:----:|:-------:|:------:|:-------------:|
+| Cursor        | ✓       | ✓      | ✓    | ✓       | ✓      | ✓             |
+| Copilot VS Code | ✓     | ✓      | ✓    | ✓       | ✓      | ~             |
+| Claude Code   | ✓       | ✓      | ✓    | ✓       | ✓      | ✓             |
+| Codex CLI     | ✓       | ✓      | ✓    | ✓       | ~      | ✗             |
+| Gemini CLI    | ✓       | ✓      | ~    | ~       | ~      | ✗             |
+| OpenCode      | ✓       | ✓      | ✓    | ✓       | ✓      | ~             |
+| Windsurf      | ✓       | ✓      | ✓    | ✓       | ✓      | ~             |
+| Antigravity   | ~       | ~      | ~    | ?       | ?      | ✗             |
+
+---
+
+## Definição de operações
+
+| Operação | O que significa |
+|----------|----------------|
+| `install` | `npx oxe-cc@latest` completa sem erro; `doctor` retorna ✓ |
+| `/oxe` | Router lê STATE.md e retorna próximo passo correto |
+| `plan` | `/oxe-plan` gera PLAN.md com ondas e tarefas válidas |
+| `execute` | `/oxe-execute` implementa tarefas e as marca como concluídas |
+| `verify` | `/oxe-verify` produz VERIFY.md com evidências para critérios A* |
+| `runtime-first` | `npx oxe-cc runtime gates/promote/recover` funcionam sem fallback |
+
+---
+
+## Pressupostos por runtime
+
+### Cursor
+
+- Lê `.cursor/commands/oxe-*.md` via slash commands
+- Suporte completo a runtime-first via terminal integrado
+- Contexto de arquivo `.oxe/STATE.md` disponível automaticamente
+- **Limitação:** multi-agent requer Cursor Agent mode (não Background Agents)
+
+### Copilot VS Code
+
+- Lê `.github/prompts/oxe-*.prompt.md` via `#` references
+- `runtime-first` é parcial: `runtime verify` e `runtime gates list` funcionam; `runtime promote` requer terminal externo
+- **Limitação:** prompts longos podem ser truncados na janela de contexto do Copilot Chat
+
+### Claude Code
+
+- Lê `commands/oxe/*.md` (Claude Code slash commands)
+- Suporte completo a runtime-first via CLI integrado
+- Raciocínio em cadeia (CoT) é nativo — contratos de raciocínio funcionam sem adaptação
+- **Pressuposto:** `~/.claude/commands/` ou `commands/` no projeto configurado
+
+### Codex CLI
+
+- Lê `.github/prompts/` via `--instructions` flag
+- `verify` parcial: gera VERIFY.md mas evidências são menos detalhadas (sem análise de AST)
+- `runtime-first` não suportado: Codex CLI não tem acesso a subprocessos Node
+- **Limitação:** não suporta contexto multi-arquivo simultâneo em tasks longas
+
+### Gemini CLI
+
+- `plan` e `execute` parciais: segue o fluxo mas pode divergir dos critérios A* do SPEC
+- `verify` parcial: produz VERIFY.md mas com menor cobertura de evidências
+- `runtime-first` não suportado: sem integração com `oxe-cc` CLI
+- **Limitação:** não lê `.oxe/STATE.md` nativamente — requer instrução explícita no prompt
+
+### OpenCode
+
+- Suporte completo ao ciclo spec→plan→execute→verify
+- `runtime-first` parcial: `runtime gates list` e `runtime recover` funcionam; `runtime promote` requer verificação manual de output
+- **Pressuposto:** modo de agente ativo (não completions puras)
+
+### Windsurf
+
+- Suporte completo ao ciclo principal
+- `runtime-first` parcial: comandos `npx oxe-cc runtime *` funcionam via terminal integrado mas sem UX nativa
+- **Pressuposto:** Cascade mode ativo para execução de tarefas multi-step
+
+### Antigravity
+
+- `install` parcial: `npx oxe-cc@latest` funciona; `doctor` pode reportar warnings em alguns ambientes
+- `/oxe` parcial: router funciona mas leitura de STATE.md depende de configuração manual
+- `plan`, `execute` parciais: testados apenas em POC inicial
+- `runtime-first` não suportado: sem testes realizados neste runtime
+- **Status:** em avaliação — abrir issue no repositório com resultados de testes
+
+---
+
+## Comportamentos suportados vs. não suportados (por todos os runtimes)
+
+### Suportados em todos os runtimes com `✓`
+
+- Geração de SPEC.md, PLAN.md, VERIFY.md
+- Marcação de tarefas concluídas (`[x]`)
+- Leitura de STATE.md para roteamento
+- `oxe-cc doctor` e `oxe-cc status` via terminal
+
+### Não suportados em nenhum runtime
+
+- Execução automática de `npm test` sem aprovação explícita do usuário
+- Push para branch remota sem confirmação
+- Modificação de `.oxe/config.json` em runtime (requer restart do agente)
+
+### Comportamentos específicos por runtime
+
+| Comportamento | Runtimes afetados |
+|---------------|-------------------|
+| Truncamento de prompts longos | Copilot, Codex |
+| CoT nativo sem instrução explícita | Claude Code |
+| Requer modo agente explícito | OpenCode, Windsurf |
+| Leitura de STATE.md automática | Cursor, Claude Code |
+
+---
+
+## Como reportar um problema de compatibilidade
+
+1. Identificar qual operação falhou e em qual runtime
+2. Coletar: output do comando, versão do runtime, `oxe-cc --version`
+3. Abrir issue no repositório com label `runtime-compat`
+4. Incluir o output de `npx oxe-cc doctor` e `npx oxe-cc status --full`

package/docs/TEAM-ADOPTION.md

@@ -0,0 +1,153 @@
+# OXE — Adoção em Times
+
+> Para times de 2–20 devs usando OXE em projetos compartilhados.
+
+---
+
+## Fluxo branch/PR recomendado
+
+Cada feature ou fix percorre este caminho:
+
+```
+git checkout -b feature/minha-feature
+/oxe-spec   → define critérios de aceite em .oxe/SPEC.md
+/oxe-plan   → gera .oxe/PLAN.md com ondas e tarefas
+/oxe-execute → implementa onda a onda
+/oxe-verify  → valida critérios do SPEC com evidências
+npx oxe-cc runtime promote --dir . --target pr_draft  → abre PR draft
+```
+
+O PR draft já vem com `.oxe/VERIFY.md` como evidência de qualidade. O reviewer usa `/oxe-verify --audit` para validação adversarial antes de aprovar.
+
+**Regra de ouro:** nunca mergear sem `VERIFY.md` existente e fase `verify_complete` no STATE.md.
+
+---
+
+## Ship local vs. promote remoto
+
+| Situação | Comando | Quando usar |
+|----------|---------|-------------|
+| Tarefa solo, ciclo completo local | `/oxe-quick` | Tasks S/M sem necessidade de review formal |
+| Feature com review de time | `/oxe-verify` + `runtime promote --target pr_draft` | Qualquer feature que vai para revisão |
+| Hotfix urgente | `/oxe-execute --task T1` + `/oxe-verify` + `runtime promote --target pr_draft` | Correções urgentes com rastreabilidade |
+| Experimento / POC | `/oxe-spec` + `/oxe-plan` + `/oxe-execute` sem promote | Validações rápidas, sem PR |
+
+`/oxe-ship` (comando legado) equivale a `/oxe-verify` + `git add/commit/push` sem passar pelo gate de promoção formal. Prefira `runtime promote` quando rastreabilidade importa.
+
+---
+
+## Sessões e workstreams sem poluir `.oxe/`
+
+### Sessões
+
+Cada sessão de trabalho tem um ID único. Para manter o diretório `.oxe/` limpo:
+
+```bash
+# Nomear sessão explicitamente
+npx oxe-cc runtime session start --name "feat-auth-2fa"
+
+# Ver sessão ativa
+npx oxe-cc runtime session status
+
+# Fechar sessão ao final do dia / feature
+npx oxe-cc runtime session close
+```
+
+**Não deixar sessões abertas.** Sessões esquecidas acumulam gates `stale` e bloqueiam relatórios de status do time.
+
+### Workstreams paralelos
+
+Para times trabalhando em features paralelas no mesmo repo:
+
+```bash
+# Workstream A (feature de autenticação)
+npx oxe-cc runtime workstream create --name auth --branch feature/auth-2fa
+
+# Workstream B (feature de dashboard)
+npx oxe-cc runtime workstream create --name dashboard --branch feature/dashboard-v2
+```
+
+Cada workstream mantém STATE.md e gates separados. Use `npx oxe-cc status --workstream auth` para ver o estado de um workstream específico sem poluir a view padrão.
+
+**Regra:** um workstream por feature branch. Nunca compartilhar um workstream entre duas features não relacionadas.
+
+---
+
+## Governança mínima
+
+### Quando exigir `discuss_before_plan`
+
+Ative quando a feature afeta:
+- Contratos de API públicos ou schemas compartilhados
+- Decisões de arquitetura que impactam outros times
+- Mudanças em infraestrutura ou pipelines de CI/CD
+
+```json
+// .oxe/config.json
+{
+  "governance": {
+    "discuss_before_plan": ["contracts/**", "infra/**", "*.schema.json"]
+  }
+}
+```
+
+Sem esse gate, o planner vai direto para PLAN.md sem esperar alinhamento.
+
+### Quando ativar `strict`
+
+Modo `strict` exige evidências formais para cada critério A* do SPEC antes de autorizar promoção. Use em:
+- Releases com SLA de qualidade (produção, clientes enterprise)
+- Features de segurança ou compliance
+- Qualquer ciclo onde um reviewer externo vai auditar
+
+```json
+{
+  "verification": {
+    "strict": true
+  }
+}
+```
+
+Em modo `strict`, `runtime promote` falha se qualquer critério A* não tiver evidência verificada.
+
+### Quando usar multi-agent
+
+Use orquestração multi-agent (`/oxe-plan --multi-agent`) quando:
+- A feature tem ondas independentes que podem ser paralelizadas
+- Time tem múltiplos devs disponíveis para executar simultaneamente
+- Tarefa de refactor em múltiplos módulos sem dependência entre eles
+
+Não use multi-agent para:
+- Features com dependências sequenciais fortes entre tarefas
+- Mudanças em arquivos compartilhados (conflitos de merge)
+- Ciclos onde um único dev vai executar tudo
+
+### Quando não usar OXE
+
+- Scripts one-off que não vão para produção
+- Experimentos de < 30 minutos sem necessidade de rastreabilidade
+- Mudanças em documentação pura (typos, formatação)
+
+Para esses casos, trabalhe direto sem o ciclo spec→plan→execute→verify.
+
+---
+
+## Checklist de integração para times novos
+
+```
+[ ] oxe-cc doctor retorna ✓ para todos os checks
+[ ] .oxe/config.json criado com profile do time
+[ ] Todos os devs têm o wrapper da IDE configurado (/oxe no Cursor, etc.)
+[ ] Branch protection rule exige VERIFY.md antes de merge
+[ ] Primeiro ciclo completo feito em pair programming
+[ ] Operador de gate designado (quem aprova runtime gates)
+```
+
+---
+
+## Referências
+
+- **Primeiros 15 minutos** → [`QUICKSTART.md`](../QUICKSTART.md)
+- **Por papel** → [`docs/ROLES.md`](ROLES.md)
+- **Exemplo completo** → [`docs/WALKTHROUGH.md`](WALKTHROUGH.md)
+- **Incidentes e gates** → [`docs/INCIDENT-PLAYBOOK.md`](INCIDENT-PLAYBOOK.md)