@spec-wave/cli 0.13.0 → 0.15.0

package/src/templates/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-wave
 description: "Use when the user wants to set up a spec-driven GitHub workflow, create a Feature issue, generate spec.md or plan.md, decompose a Feature into Stories/Tasks, write RFC documentation, or audit and fix a Pull Request. Implements the RFC-001 workflow with GitHub Projects v2, labels, and AI-powered GitHub Actions."
-argument-hint: "[info|setup|update|doctor|issue|feature|spec|plan|ready|decompose|order|implement|task|story|uninstall|rfc|fix-pr] [target]"
+argument-hint: "[info|setup|update|doctor|issue|feature|spec|plan|ready|decompose|order|implement|task|story|move|uninstall|rfc|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
@@ -87,24 +87,30 @@ Essa é a sequência completa, mas **cada tipo de artefato percorre só um trech
 |----------|----------|----------|-------------|
 | **Initiative / Epic** | 📥 Backlog | — | Agrupadores. Não têm fluxo próprio; acompanham os filhos. |
 | **Feature** | 📥 Backlog | 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done | Fica parada em **✅ Ready** esperando um dev assumir — é ali que ela aparece na fila do TL. Só avança para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. |
-| **Story** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
-| **Task** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 🎉 Done | **Não** passa por Code Review, QA nem Homologação — só `task start` e `task done`. |
+| **Story** | **✅ Ready** (criada pelo `decompose-apply`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
+| **Task** | **✅ Ready** (criada pelo `decompose-apply`) | 🚧 Desenvolvimento → 🎉 Done | **Não** passa por Code Review, QA nem Homologação — só `task start` e `task done`. |
 | **RFC** | 📥 Backlog | decompõe direto em **Tasks** (que nascem em ✅ Ready) | Não usa spec/plan. |
 | **Bug** | 📥 Backlog | 🚧 Desenvolvimento → 🎉 Done | Ao aprovar, vai direto para Done (não passa por Homologação). |
 | **Spike** | 📥 Backlog | **movido só à mão pelo usuário** | Nunca avance a Etapa de um Spike por conta própria. |
 
-**Regra da Etapa:** 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 sempre os comandos da CLI (`task start|done`, `story review`) a mutações manuais no board — eles embutem essas regras.
+**Regra da Etapa:** 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 sempre os comandos da CLI (`move`, `task start|done`, `story review`) a mutações manuais no board — eles embutem essas regras.
 
 Labels de gatilho:
 - `spec-wave:spec` → dispara `generate-spec.yml` → gera `spec.md` (especificação funcional, primeiro)
 - `spec-wave:plan` → dispara `generate-plan.yml` → gera `plan.md` (plano técnico, a partir da spec)
 - `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
-- `spec-wave:decompose` → dispara `decompose.yml` → gera Stories e Tasks
+- `spec-wave:decompose` → dispara `decompose.yml` → gera (ou **re-critica**) o **rascunho** em `decomposition.md`. **Não cria issue nenhuma.**
+- `spec-wave:decompose-apply` → dispara o mesmo workflow em modo aplicação → cria as Stories e Tasks **a partir do rascunho revisado**
 
 Labels de **estado** (gravadas pelas automações — **não** são gatilhos, não as adicione por conta própria):
-- `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves** nos documentos; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
+- `spec-wave:decompose-ready` → o rascunho da decomposição passou pela crítica e espera **revisão humana**; aplique `spec-wave:decompose-apply` para criar as issues
+- `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves**; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
+- `spec-wave:needs-human` → a crítica reprovou N vezes seguidas (default 3); **para o fluxo** até uma pessoa revisar e remover a label
 - `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
 
+Label **modificadora** (esta você pode aplicar):
+- `spec-wave:model:<apelido>` → força um modelo específico **naquela execução**, resolvido por `ai.modelAliases` no `.spec-wave.json`. Serve para reprocessar um caso difícil num modelo mais forte sem editar a configuração do repositório inteiro. Duas dessas labels na mesma issue = ambíguo, nenhuma vale.
+
 A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli@latest implement <número>` (não é uma label/Action): lê uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma Story ou uma Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
 ---
@@ -174,15 +180,24 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 |------|------|-----------|
 | `--global` | flag | Verifica a skill no escopo do usuário (padrão: projeto). |
 | `--skip-skill` / `--skip-config` / `--skip-repo` | flag | Pula a categoria correspondente. |
+| `--branch [nome]` | flag/string | Envia os arquivos do repo como **Pull Request** numa branch, em **um único commit**, em vez de commitar direto na branch default. Sem valor, usa `spec-wave/update-v<versão>`. |
+| `--config-in-pr` / `--no-config-in-pr` | flag | Força incluir/excluir o `.spec-wave.json` do PR (o default decide sozinho — veja abaixo). |
 | `--dry-run` | flag | Mostra o que seria atualizado sem alterar nada. |
 | `--yes` | flag | Aplica sem pedir confirmação. |
 
 > Detecta e atualiza **somente o que divergiu** da versão atual da CLI: a **skill** instalada (por agente), o **`.spec-wave.json`** local (se versão/formato divergir) e os **workflows/labels** do repo (compara com os templates empacotados). Interativo por padrão (mostra o plano e confirma). É o atalho recomendado após atualizar a CLI.
 
+> **`--branch` (modo Pull Request).** Sem a flag, os arquivos do repo vão em **commits diretos na branch default** — o que falha no meio da execução em repositório com proteção de branch, deixando parte aplicada, e contorna a revisão. Com a flag, todos os arquivos vão em **um commit atômico** numa branch nova e um PR é aberto: se algo falhar antes da criação da branch, **nada** é alterado no repositório. É **idempotente** — rodar duas vezes não gera um segundo commit nem um segundo PR.
+>
+> Duas coisas **não** entram no PR, porque não são versionáveis: as **labels** (metadado do repositório — já valem na base, com ou sem merge) e a **skill** (arquivo em máquina local). O corpo do PR diz isso explicitamente a quem revisa.
+>
+> ⚠️ O modo PR exige **`pull_requests: write`** além de `contents: write` (ou o escopo `repo` num PAT classic). Sem essa permissão, a branch é criada e o PR falha — a mensagem oferece a URL de `compare` para abrir à mão.
+
 ### `@spec-wave/cli generate-plan` · `generate-spec` · `validate` · `decompose`
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
+| `--apply` | flag (só `decompose`) | Cria as issues a partir do `decomposition.md` revisado. **Sem** a flag, o `decompose` apenas gera/critica o rascunho e não cria nada. |
 
 > ⚠️ Esses quatro comandos são executados pelos **GitHub Actions** (disparados por labels), **não** pela skill diretamente. Veja a *Regra fundamental*: para gerar plan/spec/decompor, adicione a **label** correspondente — não rode o comando à mão (a não ser para debug local).
 >
@@ -195,12 +210,12 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 |----------|------|-----------|
 | `<issue>` | string (obrigatório) | Número da issue (Feature, Story ou Task), ex.: `12` ou `#12`. Argumento posicional. |
 | `--feature-dir <path>` | string | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` como contexto (sobrescreve a resolução automática). |
-| `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar**. |
+| `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar** e **sem escrever nada no GitHub** (não move cards, não adiciona itens ao Project). |
 
 > Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Feature** → lista as Stories (sub-issues), **ordena topologicamente pelas dependências** (`Depende de:` + *blocked by*), **pula** as já em 👀 Code Review+ (listadas no contexto como "não tocar") e monta **um único** contexto com todas as pendentes (cada uma com suas Tasks), acionando o spec-kit **uma vez** com `{issue}/{type}/{title}` da Feature — **ciclo de dependências entre Stories pendentes aborta o comando (exit 1)**; **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
 
 ### `@spec-wave/cli doctor` — preflight de auth e configuração (comando LOCAL)
-Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models`/teto de saída + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
+Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models`/escalada da crítica/apelidos de modelo/teto de saída + secrets do Actions), **higiene do board e das labels** (colunas fora do fluxo canônico, labels `spec-wave:*` descontinuadas ou ausentes), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e os workflows (presença + **versão da CLI fixada**, não `@latest`).
 
 > Saída: `✓` ok, `✗` problema confirmado, `!` não verificável (best-effort — falha de rede nunca derruba o doctor). **Exit 1** se houver algum `✗`. **Quando rodar:** no início de uma sessão de trabalho, ou sempre que aparecer um erro estranho (ex.: **404 ao criar issues** — causa típica: token sem acesso ao repo/org, que o doctor aponta). É o primeiro passo de troubleshooting — prefira-o a depurar `gh api` na mão.
 
@@ -227,23 +242,88 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 
 > Avança a Story para a Etapa **👀 Code Review** com Status **Todo** (o Status reinicia ao trocar de etapa). Mesma regra do `task`: a **Etapa nunca retrocede** — se a Story já estiver em Code Review ou adiante, o comando apenas informa a Etapa atual. Use no fim do `implement` de uma Story, em vez de mutações GraphQL manuais.
 
+### `@spec-wave/cli move <n> <etapa>` — move QUALQUER item do board (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<n>` | string (obrigatório) | Número da issue, ex.: `8` ou `#8`. |
+| `<etapa>` | string (obrigatório) | Etapa de destino, com ou sem emoji, sem acento e em qualquer caixa: `"code review"`, `"Homologação"`, `"🎉 Done"`. |
+| `--status <valor>` | string | Valor do campo Status no destino: `Todo`, `In Progress` ou `Done` (default: `Todo`). |
+
+> Serve para **Feature, Story, Task, Bug e RFC** — é o comando a usar quando `story review` e `task start|done` não cobrem o movimento desejado (ex.: mover uma **Feature** para Homologação). Embute as mesmas guardas: a **Etapa nunca retrocede** (se o item já estiver adiante, o comando informa a Etapa atual e não faz nada) e **Spike** é recusado (sua Etapa é movida à mão). Um nome de etapa ambíguo (`"p"` casa com Priorizado e Plan) é recusado listando as candidatas.
+>
+> **Prefira `move` a `gh api graphql` manual.** Não existe escape hatch para retroceder — isso é a regra do fluxo, não uma limitação.
+
 ---
 
-## Crítica adversarial, idempotência e dependências (v0.7)
+## Crítica adversarial, decomposição em duas etapas e dependências
 
 ### Crítica adversarial (comentário 🔎)
 
-Após o `generate-plan` e **antes** da criação de issues no `decompose`, um segundo agente de IA critica os documentos procurando contradições, lacunas e riscos. O resultado vira um comentário **🔎 Crítica adversarial (spec-wave)** na issue.
+Depois do `generate-plan` e **antes** de qualquer issue ser criada no `decompose`, um segundo agente de IA audita o artefato procurando contradições com a spec, o plan e o `tech_context`. O resultado vira um comentário **🔎 Crítica adversarial (spec-wave)** na issue, com cabeçalho informando a **tentativa** e o **modelo** usados.
+
+A saída da crítica é **estruturada e validada por schema**: `severity` só aceita `grave` ou `menor`, e um payload fora do contrato **falha alto** em vez de virar um finding menor com JSON cru dentro. Se a crítica não conclui, ela **não** é registrada como aprovada.
+
+**A remediação depende de ONDE a crítica 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 `spec-wave:critique-failed` → reaplique `spec-wave:ready` |
+| `decompose` (rascunho) | **`decomposition.md`** — os achados citam **`Story N`** e **`Task N.M`**, que são os títulos desse arquivo | edite o arquivo e commite → remova `spec-wave:critique-failed` → reaplique `spec-wave:decompose` (ele **critica o arquivo como está**, sem regerar) |
+
+> ⚠️ No contexto do `decompose`, os achados são sobre as **Stories propostas**, não sobre o `plan.md`. Corrigir o plan não influencia o rascunho já gravado — edite o `decomposition.md` diretamente. Foi exatamente essa confusão que fazia o ciclo não convergir.
+
+- Findings **graves** no `decompose` → **nenhuma Story/Task é criada** e o Action **falha (exit 1)**, com a label `spec-wave:critique-failed`. Um pipeline bloqueado nunca fica verde.
+- Findings **menores** não bloqueiam — trate-os como revisão de qualidade.
+- **Escalada:** na tentativa 2 a crítica roda em `ai.escalationModel` (se configurado). Ao atingir `ai.maxCritiqueAttempts` (default 3), o fluxo aplica **`spec-wave:needs-human`**, comenta e **para** — sem chamar a IA de novo. Para retomar: corrija os documentos e remova **as duas** labels (`spec-wave:needs-human` e `spec-wave:critique-failed`).
+- Uma crítica **limpa** remove a `spec-wave:critique-failed` automaticamente e zera o contador de tentativas.
+
+### Decomposição em duas etapas (`decomposition.md`)
+
+O `decompose` **não cria issues direto**. São dois passos, com um artefato revisável no meio:
+
+```
+spec-wave:decompose
+  ├─ decomposition.md ausente  → gera via IA → commita → critica
+  └─ decomposition.md presente → critica o arquivo COMO ESTÁ (preserva suas edições)
+       ├─ grave  → +critique-failed, comentário citando Story N / Task N.M, exit 1
+       └─ limpo  → +decompose-ready, comentário "revise e aplique"
+
+spec-wave:decompose-apply
+  └─ lê decomposition.md → cria Stories/Tasks → board → +decomposed
+     (sem nova crítica: aplicar a label É a aprovação humana)
+```
+
+O arquivo fica em **`docs/features/<slug>/decomposition.md`** (Feature) ou **`docs/rfcs/<slug>/decomposition.md`** (RFC). Formato:
 
-- Findings **graves** → o Action aplica a label **`spec-wave:critique-failed`**, que **bloqueia o `spec-wave:ready`** (o `validate` falha enquanto ela existir).
-- **Fluxo de resolução:** (1) leia o comentário 🔎 na issue; (2) corrija `spec.md`/`plan.md` (regenere com as labels ou edite e commite); (3) remova a label: `gh issue edit <n> --remove-label "spec-wave:critique-failed"`; (4) re-aplique `spec-wave:ready` para validar de novo.
-- Findings leves não bloqueiam — trate-os como revisão de qualidade.
+```markdown
+# Decomposição — [FEATURE] Cadastro de Pedidos
+<!-- spec-wave:decomposition v1 issue=360 kind=stories -->
+
+## Story 1 — visualizar meus pedidos
+
+**User story:** Como cliente, quero visualizar meus pedidos, para acompanhar entregas
+**Depende de:** —
+
+Descrição complementar (contexto, critérios de aceite).
+
+### Task 1.1 — criar endpoint GET /pedidos
+
+Corpo técnico.
+```
+
+**Ao editar à mão:**
+- a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona;
+- `**Depende de:**` usa referências **1-based** (`Story 1, Story 3`) ou `—`; apontar para si mesma ou para frente é **erro**, não filtro silencioso;
+- o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura;
+- **para gerar outro rascunho do zero:** apague o arquivo e reaplique `spec-wave:decompose`.
 
 ### Guard de idempotência do decompose (`spec-wave:decomposed`)
 
-O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar Stories/Tasks, o `decompose` **pula** quando a issue já tem a label **`spec-wave:decomposed`** ou já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). Ao concluir com sucesso, o Action grava a label. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
+O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar Stories/Tasks, o `decompose` **pula** quando a issue já tem a label **`spec-wave:decomposed`** ou já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). O Action grava a label ao **aplicar** a decomposição. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
+
+A `spec-wave:decompose-ready` **não** entra nesse guard: é estado de rascunho pendente, não de decomposição feita.
 
-**Para forçar um re-decompose:** remova a label (`gh issue edit <n> --remove-label "spec-wave:decomposed"`), **apague/feche as sub-issues antigas** (senão a detecção por sub-issues pula de novo) e re-adicione `spec-wave:decompose`.
+**Para forçar um re-decompose:** remova a label (`gh issue edit <n> --remove-label "spec-wave:decomposed"`), **apague/feche as sub-issues antigas** (senão a detecção por sub-issues pula de novo), apague o `decomposition.md` se quiser um rascunho novo, e re-adicione `spec-wave:decompose`.
 
 ### Dependências entre Stories (`Depende de: #N`)
 
@@ -266,12 +346,37 @@ Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo
     "models": {
       "plan": "claude-opus-4-1",
       "critique": "claude-opus-4-1"
+    },
+    "escalationModel": "claude-opus-5",
+    "maxCritiqueAttempts": 3,
+    "modelAliases": {
+      "opus": "claude-opus-5",
+      "haiku": "claude-haiku-4-5"
     }
   }
 }
 ```
 
-Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo e os overrides de `ai.models` resolvidos.
+- `escalationModel` → modelo usado a partir da **segunda** tentativa da crítica.
+- `maxCritiqueAttempts` → quantas reprovas seguidas antes de exigir revisão humana (`spec-wave:needs-human`).
+- `modelAliases` → apelidos para a label **`spec-wave:model:<apelido>`**.
+
+**Precedência do modelo:** `SPEC_WAVE_MODEL` (env) → label `spec-wave:model:<apelido>` → escalada automática da crítica → `ai.models[ação]` → `ai.model` → default do provider.
+
+Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo, os apelidos, a escalada e os overrides resolvidos.
+
+### Override de modelo numa execução (`spec-wave:model:<apelido>`)
+
+Para reprocessar **uma issue difícil** num modelo mais forte sem editar a configuração do repositório inteiro:
+
+```bash
+# 1. Garanta o apelido em ai.modelAliases (uma vez, commitado)
+# 2. Aplique a label na issue e redispare o gatilho
+gh issue edit 360 --add-label "spec-wave:model:opus"
+gh issue edit 360 --add-label "spec-wave:decompose"
+```
+
+A label vale só para as execuções daquela issue e **vence a escalada automática** (é decisão humana explícita). Apelido desconhecido é ignorado com aviso; duas labels dessas na mesma issue = ambíguo, nenhuma vale.
 
 ### Teto de saída (`ai.maxTokens`) e truncamento
 
@@ -320,12 +425,16 @@ Traz tudo para a versão atual da CLI, atualizando **só o que mudou**: a skill
    npx @spec-wave/cli@latest update --dry-run
    ```
 2. Mostre ao usuário o resumo (skill / config / arquivos do repo / labels que divergiram). Se **nada** estiver desatualizado, informe que já está tudo na versão atual e encerre.
-3. Se o usuário aprovar, aplique:
+3. **Pergunte como os arquivos do repo devem sair** — e prefira o Pull Request:
    ```bash
-   npx @spec-wave/cli@latest update --yes
+   npx @spec-wave/cli@latest update --yes --branch     # 1 commit atômico + PR (recomendado)
+   npx @spec-wave/cli@latest update --yes              # commits diretos na branch default
    ```
    - Escopos podem ser limitados com `--skip-skill`, `--skip-config`, `--skip-repo`.
-   - Atualizações de **arquivos do repo** são commitadas no remoto; o **`.spec-wave.json`** é local (lembre o usuário de commitá-lo).
+   - **Com `--branch`:** os arquivos do repo vão em **um único commit** numa branch nova e um PR é aberto — nada é escrito na branch default. Passe o link do PR ao usuário e lembre que o merge é dele. Exige `pull_requests: write` no token.
+   - **Sem `--branch`:** cada arquivo é um commit direto na branch default. Em repositório com **proteção de branch** isso falha no meio e deixa parte aplicada — nesses casos use `--branch`.
+   - **Nos dois modos**, as **labels** são aplicadas direto na base (metadado do repositório, não versionável) e a **skill** é gravada em máquina local. Nenhuma das duas entra no PR.
+   - **`.spec-wave.json`:** com `--branch`, ele entra no PR se o repositório **já o versiona**; se não versiona, segue apenas local e o usuário precisa commitá-lo (ou use `--config-in-pr` para passar a versioná-lo). Sem `--branch`, é sempre só local.
 4. Se a skill foi atualizada, oriente recarregar/reiniciar o agente para pegar a nova versão.
 
 ---
@@ -495,28 +604,39 @@ Valida que spec.md e plan.md estão completos e a Feature pode avançar.
    ```
 2. Informe: "Validação iniciada. O workflow verificará se spec.md e plan.md contêm todas as seções obrigatórias."
 3. Se a validação falhar, o workflow comentará os problemas na issue e adicionará automaticamente `spec-wave:spec`. Informe o usuário para corrigir e tentar novamente.
-4. **Se a issue tiver a label `spec-wave:critique-failed`**, a validação falha de imediato: a crítica adversarial apontou contradições graves (comentário 🔎 na issue). Siga o fluxo de resolução da seção *Crítica adversarial*: corrigir os documentos → remover a label → re-aplicar `spec-wave:ready`.
-5. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e use `/spec-wave decompose <número>` para gerar as Stories."
+4. **Se a issue tiver `spec-wave:critique-failed` ou `spec-wave:needs-human`**, a validação falha de imediato — são portões humanos: a crítica apontou contradições graves (comentário 🔎 na issue) ou esgotou as tentativas. Nesses casos a Feature **não** é devolvida para a etapa de spec; siga o fluxo da seção *Crítica adversarial* (corrigir a superfície certa → remover a label → re-aplicar `spec-wave:ready`).
+5. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e use `/spec-wave decompose <número>` para gerar o **rascunho** das Stories (nada é criado ainda)."
 
 ---
 
 ### `/spec-wave decompose <número-da-issue>`
 
-Decompõe automaticamente. Aplica-se a **dois tipos**:
-- **Feature** → gera **Stories** (cada uma com suas **Tasks**), a partir de `spec.md` + `plan.md`.
-- **RFC** → gera **Tasks diretamente** (sem Stories), a partir da descrição do RFC.
+Decompõe em **duas etapas**, com um rascunho revisável no meio (veja *Decomposição em duas etapas*). Aplica-se a **dois tipos**:
+- **Feature** → **Stories** (cada uma com suas **Tasks**), a partir de `spec.md` + `plan.md`.
+- **RFC** → **Tasks diretamente** (sem Stories), a partir da descrição do RFC.
 
 Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e comenta.
 
 **Passos:**
 1. Para **Feature**: confirme que está em **✅ Ready** (spec.md e plan.md validados). Para **RFC**: basta a descrição estar completa (RFC não usa spec/plan).
-2. Adicione a label de decomposição:
+2. **Etapa 1 — gerar o rascunho:**
    ```bash
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
-3. Informe: "Decomposição iniciada — Feature gera Stories+Tasks; RFC gera Tasks."
-4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories geradas trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução.
-5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
+   Informe: "Rascunho iniciado — vai commitar `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
+3. Quando o Action terminar, leia o comentário na issue:
+   - **`spec-wave:decompose-ready`** → o rascunho passou pela crítica. **Leia o `decomposition.md`** e mostre ao usuário o que será criado (Stories, Tasks, dependências). Ofereça editar o arquivo antes de aplicar.
+   - **`spec-wave:critique-failed`** → o Action **falhou (exit 1)** e nada foi criado. Os achados citam `Story N` / `Task N.M` do `decomposition.md`. **Corrija esse arquivo** (não o `plan.md`), commite e reaplique `spec-wave:decompose` — o arquivo é criticado como está, sem ser regerado.
+   - **`spec-wave:needs-human`** → a crítica esgotou as tentativas. Pare e envolva o usuário: as duas labels precisam sair à mão.
+4. **Etapa 2 — aplicar o rascunho aprovado** (só depois da revisão):
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:decompose-apply"
+   ```
+   Aplicar essa label **é** a aprovação humana — não há nova crítica.
+5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução.
+6. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
+
+> **Nunca pule a etapa 1** aplicando `spec-wave:decompose-apply` direto: sem `decomposition.md` o Action falha pedindo o rascunho.
 
 ---
 
@@ -682,8 +802,16 @@ Audita um Pull Request e corrige automaticamente os problemas encontrados — se
 docs/
   features/
     <slug-da-feature>/
-      spec.md    ← gerado pelo GitHub Action quando spec-wave:spec é adicionado (1º)
-      plan.md    ← gerado pelo GitHub Action quando spec-wave:plan é adicionado (2º, usa a spec)
+      spec.md            ← gerado quando spec-wave:spec é adicionado (1º)
+      plan.md            ← gerado quando spec-wave:plan é adicionado (2º, usa a spec)
+      decomposition.md   ← rascunho gerado quando spec-wave:decompose é adicionado (3º).
+                            REVISÁVEL e EDITÁVEL à mão; as issues só nascem com
+                            spec-wave:decompose-apply
+  rfcs/
+    <slug-do-rfc>/
+      decomposition.md   ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
 ```
 
 O slug é gerado a partir do título da issue: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`
+
+> ⚠️ O slug vem do **título**. Renomear a Feature entre o rascunho e o apply muda o diretório e o `decomposition.md` antigo fica órfão — o apply reclama que não encontrou o rascunho.

package/src/templates/workflows/code-review.yml

@@ -24,7 +24,7 @@ jobs:
           node-version: '24'
 
       - name: Move Feature to Code Review
-        run: npx @spec-wave/cli@latest code-review --pr-number ${{ github.event.pull_request.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} code-review --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/decompose.yml

@@ -4,8 +4,9 @@ on:
   issues:
     types: [labeled]
 
-# O evento `labeled` pode redisparar (re-add da label, retry de runner):
-# o concurrency serializa runs da mesma issue e o guard de idempotência
+# O evento `labeled` pode redisparar (re-add da label, retry de runner). O
+# concurrency serializa runs da mesma issue — inclusive um `decompose-apply`
+# enfileirado atrás de um `decompose` — e o guard de idempotência
 # (label spec-wave:decomposed) descarta o run enfileirado.
 concurrency:
   group: spec-wave-decompose-${{ github.event.issue.number }}
@@ -13,23 +14,36 @@ concurrency:
 
 jobs:
   decompose:
+    # Duas etapas, duas labels:
+    #  • spec-wave:decompose       → grava/re-critica docs/**/decomposition.md
+    #  • spec-wave:decompose-apply → cria as Stories/Tasks a partir do rascunho
+    # O `[RFC]` no título também dispara: o caminho RFC → Tasks existe na CLI
+    # desde sempre, mas era inalcançável porque o filtro exigia `[FEATURE]`.
     if: >
-      github.event.label.name == 'spec-wave:decompose' &&
-      contains(github.event.issue.title, '[FEATURE]')
+      (github.event.label.name == 'spec-wave:decompose' ||
+       github.event.label.name == 'spec-wave:decompose-apply') &&
+      (contains(github.event.issue.title, '[FEATURE]') ||
+       contains(github.event.issue.title, '[RFC]'))
     runs-on: ubuntu-latest
     permissions:
       issues: write
-      contents: read
+      # A etapa de rascunho commita docs/**/decomposition.md no branch default.
+      contents: write
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
 
       - uses: actions/setup-node@v4
         with:
           node-version: '24'
 
       - name: Decompose into Stories and Tasks
-        run: npx @spec-wave/cli@latest decompose --issue-number ${{ github.event.issue.number }}
+        run: >
+          npx @spec-wave/cli@{{CLI_VERSION}} decompose
+          --issue-number ${{ github.event.issue.number }}
+          ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/generate-plan.yml

@@ -28,7 +28,7 @@ jobs:
           node-version: '24'
 
       - name: Generate plan.md
-        run: npx @spec-wave/cli@latest generate-plan --issue-number ${{ github.event.issue.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-plan --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/generate-spec.yml

@@ -28,7 +28,7 @@ jobs:
           node-version: '24'
 
       - name: Generate spec.md
-        run: npx @spec-wave/cli@latest generate-spec --issue-number ${{ github.event.issue.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-spec --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/qa.yml

@@ -25,7 +25,7 @@ jobs:
           node-version: '24'
 
       - name: Move Feature to QA
-        run: npx @spec-wave/cli@latest qa --pr-number ${{ github.event.pull_request.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} qa --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/validate.yml

@@ -26,7 +26,7 @@ jobs:
           node-version: '24'
 
       - name: Validate spec and plan
-        run: npx @spec-wave/cli@latest validate --issue-number ${{ github.event.issue.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} validate --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_REPOSITORY: ${{ github.repository }}