@spec-wave/cli 0.15.0 → 0.16.1

package/src/plugin/skills/setup/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: spec-wave-setup
+description: "Use quando o usuário quiser configurar o spec-wave num repositório GitHub pela primeira vez — criar o GitHub Project (Projects v2), as labels de gatilho, os workflows de Action, os issue templates e o .spec-wave.json. Gatilhos: 'configurar spec-wave', 'inicializar spec-wave', 'rodar o init', 'setup do board'. Não use para atualizar uma instalação existente (skill update) nem para diagnosticar (skill doctor)."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh repo view *)
+  - Bash(gh auth status)
+  - Read
+  - Write
+---
+
+# spec-wave setup — configura o repositório
+
+Você dirige o `init` **com flags**. Nunca rode `npx @spec-wave/cli@latest init` sem `--repo`: sem ele a CLI abre um wizard interativo (`@clack/prompts`) que você **não consegue dirigir**.
+
+## Flags do `init`
+
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--repo <owner/repo>` | string | Repositório alvo. **Passe SEMPRE.** |
+| `--project-title <title>` | string | Nome do Project. Default: `<repo> — Spec Wave`. |
+| `--provider <provider>` | string | `anthropic` ou `openrouter`. |
+| `--model <model>` | string | Modelo dos workflows (ex.: `anthropic/claude-3.7-sonnet`). |
+| `--skip-project` | flag | Pula a criação do Project (re-rodar quando já existe). |
+| `--skip-labels` | flag | Pula as labels. |
+| `--skip-files` | flag | Pula workflows + issue templates. |
+| `--dry-run` | flag | Simula sem alterar nada. |
+
+## Passos
+
+1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
+
+2. **Descubra o repositório alvo:**
+   ```bash
+   gh repo view --json nameWithOwner -q .nameWithOwner
+   ```
+   Confirme com o usuário. Sem remote, pergunte o `owner/repo`.
+
+3. **Título do Project:** ofereça o default `<repo> — Spec Wave` e aceite-o se não houver preferência.
+
+4. **Cheque o auth:** `gh auth status`. Faltando os escopos `project,repo,workflow`, oriente o usuário a rodar **ele mesmo** (comando interativo — sugira o prefixo `!`):
+   ```
+   !gh auth refresh --scopes project,repo,workflow
+   ```
+
+5. **(Opcional) Pré-visualize:**
+   ```bash
+   npx @spec-wave/cli@latest init --repo <owner/repo> --dry-run
+   ```
+
+6. **Execute:**
+   ```bash
+   npx @spec-wave/cli@latest init --repo <owner/repo> --project-title "<título>"
+   ```
+   Use `--skip-project` / `--skip-labels` / `--skip-files` **apenas** para re-rodar uma fase que falhou antes.
+
+7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava o `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
+
+8. **Adapte o `tech_context.yml`** — o scaffold vem com dados de exemplo e a qualidade do `plan.md` depende dele. Ofereça ajustá-lo agora; o passo a passo está na skill **plan** (`reference/tech-context.md`).
+
+9. **Secret de IA:** instrua a adicionar em Settings → Secrets → Actions a chave do provider escolhido: `ANTHROPIC_API_KEY` (Anthropic) ou `OPENROUTER_API_KEY` (OpenRouter).
+
+10. **Próximo passo:** criar a primeira Feature — skill **issue**.
+
+## Depois
+
+Rode a skill **doctor** para confirmar auth, escopos, config de IA e workflows antes de começar a trabalhar.

package/src/plugin/skills/spec/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: spec-wave-spec
+description: "Use para iniciar a geração da especificação funcional (spec.md) de uma Feature do spec-wave — o PRIMEIRO documento do ciclo, antes do plano técnico. Aplica a label spec-wave:spec e deixa o GitHub Action gerar e commitar o arquivo. Gatilhos: 'gerar a spec da feature 12', 'criar especificação funcional', 'rodar o spec-wave:spec'. Só vale para Features — Spike, RFC e Bug não usam spec."
+allowed-tools:
+  - Bash(gh issue *)
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave spec — especificação funcional (1º documento)
+
+> **Regra fundamental: nunca escreva o `spec.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. É isso que garante que o arquivo seja commitado e referenciado na issue. Exceção: revisar/melhorar um `spec.md` já gerado (aí sim use Edit).
+
+## Dois modos, mesmo resultado
+
+| Modo | Como acionar | Quando |
+|------|--------------|--------|
+| **Action** | aplicar a label `spec-wave:spec` | fluxo assíncrono; roda no CI, você acompanha pela issue |
+| **Local** | `npx @spec-wave/cli@latest generate-spec --issue-number <n>` | você quer o documento **agora**, nesta sessão, e iterar em cima dele |
+
+O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local automaticamente. Os dois geram o arquivo, commitam, dão push, comentam na issue e removem a label de gatilho. **Pergunte ao usuário qual ele quer** se não estiver claro; na dúvida numa sessão interativa, prefira o local (o resultado aparece em segundos, em vez de exigir acompanhar o Action).
+
+> Local exige a chave de IA no seu ambiente (`OPENROUTER_API_KEY` ou `ANTHROPIC_API_KEY`) e um `.spec-wave.json` no repositório. O provider `anthropic` **só** funciona local — no Action ele precisaria do Claude Code como subprocesso, que o runner não tem.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## Passos
+
+1. **Confirme que a issue é uma Feature.**
+
+   > **Apenas Features.** Para **Spike, RFC e Bug** o Action **pula** a geração, remove a label e comenta. Não use esta skill nesses tipos.
+
+2. **Escolha o modo** (veja a tabela acima) e acione:
+
+   **Local** — resultado nesta sessão:
+   ```bash
+   npx @spec-wave/cli@latest generate-spec --issue-number <número>
+   ```
+   O comando imprime `Modo de execução: local`, gera, commita e faz push.
+
+   **Action** — assíncrono:
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:spec"
+   ```
+   Informe: "Label `spec-wave:spec` adicionada. O Action `generate-spec.yml` vai gerar o `spec.md`. Acompanhe em Actions → Generate Spec."
+
+4. Quando concluir, ofereça revisar o arquivo em `docs/features/<slug>/spec.md`. O slug vem do título: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`.
+
+5. **Próximo passo:** o plano técnico — mova para **📋 Plan** e use a skill **plan**.
+
+## Se falhar
+
+- **Comentário 🔎 de crítica com `spec-wave:critique-failed`** → corrija o `spec.md` (ou o corpo da issue que o embasa), commite, remova a label e reaplique o gatilho.
+- **Erro de teto de tokens** → a geração **falha e nada é gravado** (um documento cortado no meio valeria menos que documento nenhum). Aumente `ai.maxTokens` no `.spec-wave.json` ou reduza o corpo da issue; depois re-aplique a label.
+- Para reprocessar num modelo mais forte só nesta issue, aplique também `spec-wave:model:<apelido>` (o apelido precisa existir em `ai.modelAliases`).

package/src/plugin/skills/spec/model-prompt.md

@@ -0,0 +1,61 @@
+---
+name: spec
+action: spec
+description: Gera a especificação funcional (spec.md) de uma Feature a partir da issue do GitHub.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+---
+
+# Geração de spec.md
+
+Você é um Product Manager experiente. Gere uma especificação funcional (spec.md) completa para a Feature descrita pelo usuário.
+
+## Entrada
+
+Você recebe um payload JSON com:
+
+- `metadata.feature_title` — título da issue
+- `metadata.feature_description` — corpo da issue
+- `metadata.labels` — labels aplicadas
+- `business_input.raw` — a entrada de negócio bruta
+
+<!-- requires-tools -->
+## Exploração antes de escrever
+
+Você tem `Read`, `Glob` e `Grep` no repositório de destino. Antes de escrever qualquer seção, procure o que já existe: specs de features vizinhas em `docs/features/`, modelos de domínio, endpoints e telas relacionados. Uma spec ancorada no que o sistema já faz vale mais que uma escrita no vácuo.
+
+Isso **não** autoriza inventar regras a partir do código: o código mostra o que existe, não o que o negócio quer. Continue marcando lacunas de negócio com `[TODO: requer esclarecimento do PO]`.
+<!-- /requires-tools -->
+
+## Estrutura obrigatória
+
+O spec deve conter EXATAMENTE estas seções em português, nesta ordem:
+
+```
+# Visão Geral
+  - Objetivo, Personas e Critérios de Sucesso como bullets.
+# Regras de Negócio
+# Fluxos
+  - Subseções: ## Fluxo Principal (Happy Path), ## Fluxos Alternativos, ## Cenários de Erro.
+  - O Fluxo Principal DEVE conter, além da descrição passo a passo, um diagrama de
+    sequência Mermaid (bloco ```mermaid iniciado com sequenceDiagram) mostrando a
+    interação entre as personas (actor) e o sistema (participant). Rotule mensagens
+    e notas em português.
+  - Cubra os Fluxos Alternativos e Cenários de Erro relevantes no mesmo diagrama
+    usando blocos alt/opt/break — ou, se ficarem complexos, em um segundo diagrama
+    na subseção correspondente.
+# Critérios de Aceite
+  - OBRIGATORIAMENTE no formato Gherkin, dentro de um bloco ```gherkin com
+    Given/When/Then. Um cenário por critério.
+# Dependências
+  - Subdivida em Internas e Externas.
+# Requisitos Não-Funcionais
+  - Performance, Segurança e Usabilidade.
+```
+
+## Regras
+
+- NÃO invente regras de negócio. Se faltar informação, marque explicitamente com `[TODO: requer esclarecimento do PO]`.
+- Seja específico e detalhado em cada seção.
+- Escreva em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
+- O arquivo deve conter APENAS o conteúdo do spec.md — nada de preâmbulo, comentário sobre o processo ou resumo do que você fez.

package/src/plugin/skills/story/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: spec-wave-story
+description: "Use para mandar uma Story do spec-wave para 👀 Code Review depois de implementar todas as suas Tasks e abrir o PR. Gatilhos: 'terminei a story 34', 'mandar a story para review', 'story pronta para code review'. Prefira este comando a mutações GraphQL manuais no board."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh pr *)
+  - Read
+---
+
+# spec-wave story — move a Story para Code Review
+
+Comando **local**:
+
+```bash
+npx @spec-wave/cli@latest story review <n>
+```
+
+| Arg | Descrição |
+|-----|-----------|
+| `<action>` | `review` — única ação hoje. |
+| `<n>` | Número da issue da **Story**, ex.: `12` ou `#12`. |
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## O que ele faz
+
+Avança a Story para a Etapa **👀 Code Review** com Status **Todo** — o Status reinicia ao trocar de etapa.
+
+Mesma guarda do `task`: a **Etapa nunca retrocede**. Se a Story já estiver em Code Review ou adiante, o comando apenas informa a Etapa atual.
+
+## Quando usar
+
+No fim da implementação de uma Story, **depois** de:
+
+1. Todas as Tasks da Story em 🎉 Done (skill **task**)
+2. Commit feito
+3. PR aberto
+
+Só então:
+
+```bash
+npx @spec-wave/cli@latest story review <n>
+```
+
+## Depois
+
+A **Feature** só avança para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento — não a mova antes.
+
+Para mover a Feature (ou qualquer item) quando chegar a hora, use a skill **move**.

package/src/plugin/skills/task/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: spec-wave-task
+description: "Use para iniciar ou concluir uma Task do spec-wave no board: task start move para 🚧 Desenvolvimento com Status In Progress, task done move para 🎉 Done. Gatilhos: 'comecei a task 56', 'terminei a task 56', 'marcar task como feita'. Prefira sempre este comando a mexer no board via GraphQL ou gh — ele embute a regra de uma única Task In Progress por Story."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave task — transições de Task no board
+
+Comando **local**:
+
+```bash
+npx @spec-wave/cli@latest task start <n>
+npx @spec-wave/cli@latest task done <n>
+```
+
+| Arg | Descrição |
+|-----|-----------|
+| `<action>` | `start` → Etapa 🚧 Desenvolvimento + Status **In Progress**. `done` → Etapa 🎉 Done + Status **Done**. |
+| `<n>` | Número da issue da **Task**, ex.: `12` ou `#12`. |
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## Por que usar este comando
+
+Ele embute as regras do fluxo que uma mutação manual não tem:
+
+- **A Etapa nunca retrocede** — se a Task já estiver adiante, só o Status é ajustado.
+- **Uma única Task "In Progress" por vez** dentro da mesma Story — `start` **recusa** e aponta a Task em andamento se houver outra irmã em In Progress.
+
+> Task **não** passa por Code Review, QA nem Homologação. O ciclo dela é só `start` → `done`.
+
+## Passos
+
+1. Identifique o número da Task e a ação pretendida.
+2. Rode o comando.
+3. Se `start` recusar por já haver uma Task irmã em In Progress, mostre ao usuário qual é e conclua-a antes (`task done <outra>`) — não contorne a regra manualmente.
+4. Quando **todas** as Tasks da Story estiverem em 🎉 Done, faça commit + PR e mova a Story com a skill **story**.
+
+Para mover um item que **não** é Task, ou para uma etapa que estes dois verbos não cobrem, use a skill **move**.

package/src/plugin/skills/triage/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: spec-wave-triage
+description: "Use para dar o desfecho da triagem de um Bug do spec-wave: aceitar para a fila técnica, rejeitar, ou marcar como duplicata. Gatilhos: 'aceitar o bug 42', 'rejeitar esse bug', 'marcar como duplicata da 17', 'triar os bugs'. Só vale para issues do tipo Bug."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Read
+---
+
+# spec-wave triage — o desfecho da triagem
+
+A triagem decide **uma** coisa: isto vira trabalho, e com que urgência? Daí as três saídas — e nenhuma delas ser "editar". Corrigir o relato é conversa na issue.
+
+```bash
+npx @spec-wave/cli@latest triage accept 42
+npx @spec-wave/cli@latest triage accept 42 --severity P1
+npx @spec-wave/cli@latest triage reject 42 --reason "comportamento esperado, documentado em X"
+npx @spec-wave/cli@latest triage duplicate 42 --of 17
+```
+
+| Ação | Efeito |
+|---|---|
+| `accept` | → **✅ Ready** (fila técnica), label `spec-wave:triaged`. `--severity` reclassifica **trocando** a label, nunca acumulando. |
+| `reject` | Fecha a issue com `spec-wave:wont-fix`. **`--reason` é obrigatório.** |
+| `duplicate` | Fecha com `spec-wave:duplicate` e comenta **nas duas** issues. **`--of` é obrigatório.** |
+
+> `reject` e `duplicate` **não mexem na Etapa**. Ela nunca retrocede, e um bug rejeitado não avançou para lugar nenhum — quem o tira das filas é o estado `closed` da issue.
+
+## O portão de aceite
+
+| Severidade | Exige `bug.md` validado? |
+|---|---|
+| **P0 / P1** | Não — esperar o documento custa mais que investigar durante a correção. |
+| **P2 / P3** | **Sim** (`spec-wave:bug-approved`). Um bug sem causa raiz investigada empurra a investigação para o dev, e é aí que "corrigir o sintoma" acontece. |
+
+`spec-wave:critique-failed` e `spec-wave:needs-human` bloqueiam **qualquer** severidade, P0 inclusive: aceitar um bug cujo documento foi reprovado é exatamente o que o portão existe para evitar.
+
+## Se o aceite for recusado
+
+O comando diz qual portão barrou. Os caminhos:
+
+- **Falta o `bug.md`** → skill **bug** (aplica `spec-wave:bug`), depois `spec-wave:ready` para validar. Ou `--severity P1`, se for de fato urgente — mas isso é reclassificar o defeito, não contornar o portão.
+- **`spec-wave:critique-failed`** → corrija o `bug.md`, commite, remova a label.
+- **`spec-wave:needs-human`** → uma pessoa precisa revisar antes de remover.
+
+## Criar um Bug
+
+```bash
+npx @spec-wave/cli@latest bug --title "Duplicidade de pedidos no PIX" --parent 17 --priority P2
+```
+
+Nasce em **🐞 Triagem** — ou direto em **✅ Ready** se for **P0**.

package/src/plugin/skills/uninstall/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: spec-wave-uninstall
+description: "Use quando o usuário quiser remover a configuração do spec-wave de um repositório: labels, arquivos .github (workflows e issue templates) e o .spec-wave.json. Gatilhos: 'remover o spec-wave', 'desinstalar spec-wave deste repo', 'limpar as labels do spec-wave'. O GitHub Project NUNCA é apagado — o usuário decide isso à mão."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave uninstall — remove a configuração
+
+Remove labels + arquivos `.github` + `.spec-wave.json`. **NUNCA apaga o GitHub Project** — isso preserva o histórico do board de propósito.
+
+| Flag | Descrição |
+|------|-----------|
+| `--repo <owner/repo>` | Repositório. Default: lê do `.spec-wave.json`. |
+| `--skip-labels` | Não remove as labels. |
+| `--skip-files` | Não remove os arquivos `.github`. |
+| `--keep-config` | Mantém o `.spec-wave.json` local. |
+| `--dry-run` | Mostra o que seria removido sem alterar nada. |
+| `--yes` | Não pede confirmação. |
+
+## Passos
+
+1. **Confirme com o usuário.** A ação remove labels e faz **commits removendo os workflows** do repositório remoto. Deixe claro que issues e o Project permanecem.
+
+2. **Mostre antes o que será removido:**
+   ```bash
+   npx @spec-wave/cli@latest uninstall --dry-run
+   ```
+
+3. Execute:
+   ```bash
+   npx @spec-wave/cli@latest uninstall
+   ```
+   A CLI pede confirmação própria. Use `--yes` **apenas** se o usuário já confirmou explicitamente.
+
+4. **Lembre o usuário** de excluir o **GitHub Project** manualmente, se desejar — a CLI não o apaga.
+
+## Observações
+
+- Remover as labels não desfaz o histórico das issues; elas continuam no board com suas Etapas.
+- Os documentos gerados em `docs/features/` e `docs/rfcs/` **não** são removidos.
+- Para apenas atualizar uma instalação existente (em vez de removê-la), use a skill **update**.

package/src/plugin/skills/update/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: spec-wave-update
+description: "Use depois de atualizar a CLI @spec-wave/cli, ou quando a skill instalada, o .spec-wave.json e os workflows/labels do repositório ficaram para trás da versão atual. Detecta e atualiza SÓ o que divergiu. Gatilhos: 'atualizar spec-wave', 'a skill está desatualizada', 'os workflows estão velhos', 'update do spec-wave'. Para configurar do zero use a skill setup; para remover, uninstall."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave update — traz tudo para a versão atual
+
+Atualiza **somente o que divergiu** da versão da CLI: a **skill** instalada (por agente), o **`.spec-wave.json`** local e os **workflows/labels** do repositório.
+
+| Flag | Descrição |
+|------|-----------|
+| `--global` | Verifica a skill no escopo do usuário (padrão: projeto). |
+| `--skip-skill` | Não verifica/atualiza a skill instalada. |
+| `--skip-config` | Não verifica/atualiza o `.spec-wave.json`. |
+| `--skip-repo` | Não verifica/atualiza workflows e labels do repo. |
+| `--dry-run` | Mostra o que seria atualizado sem alterar nada. |
+| `--yes` | Aplica sem pedir confirmação. |
+
+## Passos
+
+1. **Sempre comece com `--dry-run`:**
+   ```bash
+   npx @spec-wave/cli@latest update --dry-run
+   ```
+
+2. Mostre ao usuário o resumo por categoria (skill / config / arquivos do repo / labels). Se **nada** divergiu, informe que já está tudo na versão atual e encerre.
+
+3. Com a aprovação, aplique:
+   ```bash
+   npx @spec-wave/cli@latest update --yes
+   ```
+   Limite o escopo com `--skip-skill`, `--skip-config` ou `--skip-repo` se o usuário só quiser parte.
+
+4. **Onde cada coisa aterrissa:**
+   - **arquivos do repo** (workflows, labels) → commitados no remoto pelo comando
+   - **`.spec-wave.json`** → arquivo **local**; lembre o usuário de commitá-lo
+
+5. Se a skill foi atualizada, oriente a **recarregar/reiniciar o agente** para pegar a nova versão.
+
+## Por que isso é necessário
+
+A skill instalada é uma **cópia estática** — ela não acompanha o `npx @spec-wave/cli@latest` sozinha. Se o banner de versão no topo do arquivo instalado for menor que `npx @spec-wave/cli@latest --version` (ou estiver ausente), está desatualizada.
+
+Para atualizar **só a skill**, sem tocar em config e repo:
+
+```bash
+npx @spec-wave/cli@latest install-skill --force
+```

package/src/plugin/skills/workflow/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: spec-wave-workflow
+description: "Use quando a pergunta for sobre o fluxo spec-wave como um todo — qual é a próxima etapa de uma issue, o que cada coluna do Kanban significa, quais labels disparam quais Actions, como funciona a crítica adversarial, ou quando o usuário pedir spec-wave sem dizer qual comando. É o mapa do processo RFC-001; para executar uma ação específica, use a skill do comando correspondente (setup, issue, spec, plan, ready, decompose, implement, order, task, story, move, doctor, update, info, uninstall, rfc, fix-pr)."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Bash(gh api *)
+  - Read
+  - Glob
+  - Grep
+---
+
+# spec-wave — mapa do fluxo
+
+Referência do processo RFC-001. Use para orientar; para **agir**, chame a skill do comando.
+
+> Se existir `rfc/rfc-integrate-spec-kit-into-kanban.md` no repositório, leia-o: é o processo real da equipe e vence esta referência.
+
+## Contexto obrigatório
+
+Leia `.spec-wave.json` na raiz do repositório (Read) antes de qualquer coisa.
+
+- **Existe** → o repo já está configurado. Use `owner`/`repo` nos comandos `gh` e `project.url` nas referências ao board. Não repita perguntas já respondidas por esse arquivo.
+- **Não existe** → o repo não foi configurado. Direcione para a skill **setup** e pare.
+
+Toda a CLI é invocada como `npx @spec-wave/cli@latest <comando>`.
+
+## Regras fundamentais
+
+1. **Nunca escreva `spec.md` ou `plan.md` à mão.** Quem gera é o spec-wave — e ele roda de **dois modos**, com o mesmo resultado:
+   - **Action:** aplique a label de gatilho (`spec-wave:spec`, `spec-wave:plan`, `spec-wave:decompose`);
+   - **Local:** `npx @spec-wave/cli@latest generate-spec|generate-plan|decompose --issue-number <n>` na sua sessão.
+
+   O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), sem flag. Os dois geram, commitam, fazem push, comentam na issue e sincronizam o board — o board é a fonte de verdade independentemente de onde rodou. Local exige a chave de IA no seu ambiente e um `.spec-wave.json`. Exceção à regra: revisar/melhorar um documento já gerado.
+2. **Nunca crie Story ou Task avulsa.** Elas nascem do `decompose`, já em **✅ Ready** e vinculadas ao pai. Criadas à mão caem em 📥 Backlog e **não aparecem em tela nenhuma** da UI (o inbox do PM lista Features, a tela do Dev lê 🚧 Desenvolvimento, a fila do TL lê ✅ Ready).
+3. **Nunca use `gh issue create`** para work items — não adiciona ao Project, a issue fica sem Etapa e some das telas. Use `npx @spec-wave/cli@latest issue`.
+4. **A Etapa só avança, nunca retrocede.** O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira `move`, `task start|done` e `story review` a mutações GraphQL manuais — os comandos embutem essas regras.
+
+## Fluxo Kanban
+
+```
+📥 Backlog → 🐞 Triagem → 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready
+→ 🚧 Desenvolvimento → 👀 Code Review
+→ 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done
+```
+
+Cada artefato percorre só um trecho — e **nasce numa Etapa diferente**:
+
+| Artefato | Nasce em | Percorre | Observações |
+|----------|----------|----------|-------------|
+| **Initiative / Epic** | 📥 Backlog | — | Agrupadores; acompanham os filhos. |
+| **Feature** | 📥 Backlog | 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done | Fica parada em ✅ Ready esperando um dev. Só avança para Code Review quando **TODAS** as Stories já estiverem lá. |
+| **Story** | **✅ Ready** (via `decompose-apply`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | Nunca nasce em Backlog. |
+| **Task** | **✅ Ready** (via `decompose-apply`) | 🚧 Desenvolvimento → 🎉 Done | Não passa por Code Review, QA nem Homologação. |
+| **RFC** | 📥 Backlog | decompõe direto em **Tasks** | Não usa spec/plan. |
+| **Bug** | **🐞 Triagem** (reportado) ou **✅ Ready** (achado em QA/UAT/review) | ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 🚀 Deploy → 🎉 Done | Não passa por Priorizado, Spec, Plan nem Homologação. Bug P0 nasce direto em ✅ Ready. |
+| **Spike** | 📥 Backlog | **movido só à mão pelo usuário** | Nunca avance a Etapa de um Spike por conta própria. |
+
+## Labels
+
+**Gatilho** (você pode aplicar):
+
+| Label | Dispara | Resultado |
+|-------|---------|-----------|
+| `spec-wave:spec` | `generate-spec.yml` | `spec.md` — especificação funcional (1º) |
+| `spec-wave:plan` | `generate-plan.yml` | `plan.md` — plano técnico (2º, usa a spec) |
+| `spec-wave:ready` | `validate.yml` | valida os dois documentos |
+| `spec-wave:decompose` | `decompose.yml` | gera ou **re-critica** o rascunho `decomposition.md`. **Não cria issue nenhuma.** |
+| `spec-wave:decompose-apply` | `decompose.yml` (modo aplicação) | cria as Stories/Tasks a partir do rascunho revisado |
+
+**Estado** (gravadas pelas automações — **não** as adicione):
+
+- `spec-wave:decompose-ready` → rascunho passou pela crítica, espera revisão humana
+- `spec-wave:critique-failed` → contradições **graves**; **bloqueia** o `ready` até ser removida
+- `spec-wave:needs-human` → a crítica reprovou N vezes (default 3); **para o fluxo**
+- `spec-wave:decomposed` → guard de idempotência; o `decompose` pula enquanto existir
+
+**Modificadora** (você pode aplicar):
+
+- `spec-wave:model:<apelido>` → força um modelo **naquela execução**, resolvido por `ai.modelAliases` no `.spec-wave.json`. Duas dessas na mesma issue = ambíguo, nenhuma vale.
+
+## Crítica adversarial (comentário 🔎)
+
+Depois do `generate-plan` e **antes** de qualquer issue nascer no `decompose`, um segundo agente audita o artefato procurando contradições com a spec, o plan e o `tech_context`. A saída é validada por schema (`severity` só aceita `grave` ou `menor`); payload fora do contrato **falha alto**.
+
+**A remediação depende de ONDE reprovou — são superfícies diferentes:**
+
+| Reprovou depois de | O que corrigir | Como retomar |
+|--------------------|----------------|--------------|
+| `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija/regere → remova `critique-failed` → reaplique `spec-wave:ready` |
+| `decompose` | **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, títulos **desse arquivo** | edite e commite → remova `critique-failed` → reaplique `spec-wave:decompose` (critica o arquivo como está, sem regerar) |
+
+> ⚠️ No `decompose` os achados são sobre as **Stories propostas**, não sobre o `plan.md`. Corrigir o plan não muda o rascunho já gravado.
+
+- Grave no `decompose` → **nada é criado** e o Action **falha (exit 1)**.
+- Menor → não bloqueia; trate como revisão de qualidade.
+- **Escalada:** tentativa 2 usa `ai.escalationModel`. Ao atingir `ai.maxCritiqueAttempts` (default 3), aplica `needs-human` e **para**. Para retomar, remova **as duas** labels.
+- Crítica limpa remove `critique-failed` e zera o contador.
+
+## Modelo de IA (`ai` no `.spec-wave.json`)
+
+```json
+{
+  "ai": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "models": { "plan": "claude-opus-4-1", "critique": "claude-opus-4-1" },
+    "escalationModel": "claude-opus-5",
+    "maxCritiqueAttempts": 3,
+    "modelAliases": { "opus": "claude-opus-5" },
+    "maxTokens": 32768,
+    "maxTokensByAction": { "spec": 49152 }
+  }
+}
+```
+
+**Precedência:** `SPEC_WAVE_MODEL` (env) → label `spec-wave:model:<apelido>` → escalada da crítica → `ai.models[ação]` → `ai.model` → default do provider.
+
+**Teto de saída:** quando a saída não cabe, a geração **FALHA e nada é gravado** (um documento cortado passaria na validação de seções e valeria menos que documento nenhum). Saídas: aumentar `ai.maxTokens` ou reduzir o corpo da issue. Modelos com raciocínio gastam parte do teto pensando.
+
+## Arquivos gerados
+
+```
+docs/
+  features/<slug>/
+    spec.md            ← spec-wave:spec (1º)
+    plan.md            ← spec-wave:plan (2º)
+    decomposition.md   ← spec-wave:decompose (3º) — rascunho REVISÁVEL;
+                          as issues só nascem com spec-wave:decompose-apply
+  rfcs/<slug>/
+    decomposition.md   ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
+```
+
+O slug vem do **título**: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`.
+
+> ⚠️ Renomear a Feature entre o rascunho e o apply muda o diretório e órfã o `decomposition.md` — o apply reclama que não achou o rascunho.
+
+## Roteamento
+
+| O usuário quer | Skill |
+|----------------|-------|
+| configurar o repo | `setup` |
+| ver se está configurado | `info` |
+| diagnosticar erro / 404 ao criar issue | `doctor` |
+| atualizar skill/config/workflows | `update` |
+| criar Initiative/Epic/Feature/Bug/Spike/RFC | `issue` |
+| gerar a especificação funcional | `spec` |
+| gerar o plano técnico | `plan` |
+| validar spec+plan | `ready` |
+| quebrar em Stories/Tasks | `decompose` |
+| implementar | `implement` |
+| ver ordem das Stories | `order` |
+| mover Task | `task` |
+| mandar Story para review | `story` |
+| mover qualquer item | `move` |
+| escrever um RFC | `rfc` |
+| auditar e corrigir um PR | `fix-pr` |
+| remover a configuração | `uninstall` |