@spec-wave/cli 0.26.0 → 0.28.0

package/src/plugin/skills/preparar-specs/reference/armadilhas.md

@@ -0,0 +1,209 @@
+# Armadilhas operacionais deste fluxo
+
+Cada item aqui custou uma investigação real. A causa vem junto porque o sintoma, sozinho,
+costuma apontar para o lugar errado.
+
+## Índice
+
+1. Token do `gh` inválido no ambiente
+2. `gh issue edit --add-label` falha com 503
+3. A API do GitHub devolve 503 intermitente
+4. Working tree compartilhado com outros agentes
+5. Label de gatilho grudada impede o retry
+6. `spec-wave:spec` sobrescreve spec revisada
+7. `spec-wave update` reescreve os workflows
+8. Runs `skipped` são normais — não são falha
+9. `conclusion` vazia não é conclusão
+10. Geração leva minutos — não rode em primeiro plano
+11. Run interrompido deixa lock órfão
+12. O documento foi gerado e o PR não nasceu
+
+---
+
+## 1. Token do `gh` inválido no ambiente
+
+**Sintoma:** `gh` falha com erro de autenticação, ou enxerga o repositório errado.
+
+**Causa:** a variável `GH_TOKEN` do ambiente pode estar inválida ou pertencer a uma conta
+sem acesso à organização, enquanto o keyring tem a conta certa.
+
+**Como resolver:** exporte o token da conta correta antes dos comandos:
+
+```bash
+export GH_TOKEN=$(env -u GH_TOKEN gh auth token -u <conta-com-acesso>)
+```
+
+O `env -u GH_TOKEN` é necessário porque o `gh auth token` também consulta a variável
+inválida se ela estiver setada.
+
+A CLI tem a saída própria dela para o mesmo problema, que não depende do shell:
+`spec-wave --account <login> <comando>`, ou `"github": { "account": "<login>" }` no
+`.spec-wave.json`. Fora do CI, a conta declarada vence a variável de ambiente.
+
+## 2. `gh issue edit --add-label` falha com 503
+
+**Sintoma:** o comando falha repetidamente, e parece que o gatilho não existe.
+
+**Causa:** esse subcomando passa pelo GraphQL, que pode estar degradado enquanto o REST
+funciona normalmente.
+
+**Alternativa que funciona:**
+
+```bash
+gh api -X POST repos/<owner>/<repo>/issues/<n>/labels -f "labels[]=spec-wave:spec"
+```
+
+## 3. A API do GitHub devolve 503 intermitente
+
+**Sintoma:** comandos falham de forma aleatória e passam na tentativa seguinte.
+
+**Como lidar:** envolva as chamadas em retry (3–5 tentativas com pausa) e **verifique o
+resultado real**, não o código de saída isolado. Um `gh` que devolve string vazia sem erro
+é indistinguível de "não encontrei nada" se você não conferir.
+
+## 4. Working tree compartilhado com outros agentes
+
+**Sintoma:** arquivos modificados que você não criou; branch diferente da esperada.
+
+**Causa:** outros processos (dev-agents, outras sessões) usam o mesmo checkout e trocam de
+branch sem aviso.
+
+**Regra:** nunca `checkout`, `stash` ou `reset` sem antes conferir `git branch --show-current`
+e `git status --short`. A geração em si não disputa o checkout — ela publica por API, sem
+tocar em disco —, mas tudo que você fizer à mão disputa.
+
+Se precisar mesmo de uma branch checada — por exemplo, para editar arquivos de um PR já
+aberto — use um worktree temporário fora do repositório, e remova depois:
+
+```bash
+git worktree add /tmp/<dir> <branch>
+# ... edições, commit, push ...
+git worktree remove --force /tmp/<dir> && git worktree prune
+```
+
+## 5. Label de gatilho grudada impede o retry
+
+**Sintoma:** reaplicar a label não dispara nada; ou o `run` local recusa executar com
+`⛔ trigger-pending`.
+
+**Causa:** o evento `issues: [labeled]` não redispara com a label já presente, e o `run`
+recusa rodar com gatilho pendente — a label significa "Action em execução", ou uma que
+falhou e a deixou para trás.
+
+**Como resolver:** remover e reaplicar. No modo local, onde nenhuma Action está rodando, a
+label é resíduo: **remova-a em vez de usar `--force`**, para a issue não mentir sobre o
+estado.
+
+```bash
+gh api -X DELETE "repos/<owner>/<repo>/issues/<n>/labels/spec-wave:spec"
+```
+
+Nem sempre a label fica: em algumas falhas a CLI a remove sozinha no início do run.
+Confira issue a issue em vez de supor — o `preflight` já lista as pendentes.
+
+## 6. `spec-wave:spec` sobrescreve spec revisada
+
+A label **regenera** o documento do zero. Se a spec já foi revisada, editada à mão ou
+corrigida, reaplicar joga tudo fora para consertar o que muitas vezes é uma frase.
+
+Para correção pontual em documento já gerado, a edição direta é permitida **quando o
+usuário pede explicitamente** — e só nesse caso. Edite no PR: as edições são preservadas.
+
+## 7. `spec-wave update` reescreve os workflows
+
+O `update` compara os workflows com os templates da CLI e sobrescreve os divergentes. Toda
+customização local neles é perdida no bump, silenciosamente, e o sintoma só aparece na
+próxima geração.
+
+Se o repositório tem workflows customizados de propósito, rode `update --skip-repo`, ou
+reaplique a customização antes de commitar o bump. Confirme depois:
+
+```bash
+git show origin/main:.github/workflows/generate-spec.yml | grep <marca-da-customizacao>
+```
+
+## 8. Runs `skipped` são normais — não são falha
+
+O evento `issues: [labeled]` dispara **todos** os workflows que escutam labels; cada um se
+filtra pelo próprio `if:`. Ver `generate-plan` e `decompose` como `skipped` depois de
+aplicar `spec-wave:spec` é o comportamento correto, não um problema.
+
+O mesmo vale para o repositório em modo `local`: todo job carrega
+`if: vars.SPEC_WAVE_EXECUTION != 'local'`, então o run aparece verde e `skipped`, sem erro
+e sem documento. Se você aplicou uma label e nada aconteceu, confira o modo antes de
+procurar defeito: `npx @spec-wave/cli@latest mode`.
+
+Ao procurar o run que interessa, filtre pelo workflow **e** pelo título da issue.
+
+## 9. `conclusion` vazia não é conclusão
+
+O `gh run list` devolve `conclusion` como **string vazia** — não `null` — enquanto o run
+está em andamento. Um filtro `select(.conclusion != null)` deixa passar runs que ainda
+estão rodando, e você conclui cedo demais que tudo terminou.
+
+Filtre por `.status == "completed"` **e** `conclusion` não-vazia.
+
+## 10. Geração leva minutos — não rode em primeiro plano
+
+Uma spec é uma chamada de modelo gerando um documento longo: leva minutos. Rodar no
+primeiro plano de uma ferramenta com timeout curto faz o comando morrer no meio — e o custo
+já foi pago.
+
+Rode em background, ou com timeout generoso (10 min por Feature). Numa milestone grande em
+modo local isso passa de uma hora em série; combine com o usuário antes de começar.
+
+## 11. Run interrompido deixa lock órfão
+
+**Sintoma:** `Já existe um 'spec-wave run' para <n> (pid NNNN, desde ...)` e a geração é
+recusada, mesmo não havendo nada rodando.
+
+**Causa:** o `run` grava `.git/spec-wave/run-<n>.lock` para impedir duas execuções na mesma
+issue. Um run morto por timeout ou Ctrl-C não tem chance de limpar o próprio lock.
+
+**Como resolver — confirmando antes:** o lock guarda o pid, então dá para verificar se o
+processo realmente morreu em vez de apagar no escuro:
+
+```bash
+cat .git/spec-wave/run-<n>.lock          # {"pid":NNNN,"startedAt":"..."}
+ps -p NNNN >/dev/null && echo VIVO || echo morto
+rm .git/spec-wave/run-<n>.lock           # só se morto
+```
+
+O cuidado importa quando você rodou várias Features: pode haver um lock órfão e outro de um
+run **em andamento** ao lado. Apagar o lock errado põe dois `run` na mesma issue.
+
+A boa notícia é que a interrupção em si é limpa — o documento não é publicado pela metade.
+Confirme com a ausência de PR novo antes de rerodar.
+
+## 12. O documento foi gerado e o PR não nasceu
+
+**Sintoma:** o passo termina, o commit existe na branch `spec-wave/<n>-<doc>` — e nenhum PR
+aparece. O documento fica numa branch que ninguém está olhando, e a próxima execução, se
+ninguém perceber, **regera por cima**.
+
+**Causa:** a publicação precisa de `pull-requests: write` **e** de a organização permitir
+que Actions abram PRs. A segunda parte é a traiçoeira: *"Allow GitHub Actions to create and
+approve pull requests"* (Settings → Actions → General) vem desligada por padrão em muitas
+organizações, e o erro não se parece com falta de permissão.
+
+**Como resolver:** ligar a opção, ou definir um PAT no secret `GH_PR_TOKEN`. O `preflight`
+e o `doctor` verificam os dois; o estado `⚠ em branch sem PR` no inventário é exatamente
+este caso.
+
+Não se aplica ao modo `local`, onde o token é o seu.
+
+---
+
+## Nota histórica: o regime anterior à 0.27.0
+
+Até a 0.26.0 a geração publicava com `commit` + `pull --rebase` + `push` **na branch
+default**, a partir do checkout. Duas armadilhas vinham daí e **não valem mais**:
+
+- **push rejeitado com `GH013`** em repositório que exige PR — a falha vinha *depois* de o
+  modelo ter gerado o documento, e o conteúdo se perdia com o runner;
+- **working tree sujo quebrava toda geração local**, porque qualquer arquivo modificado
+  travava o `pull --rebase`.
+
+Hoje a publicação é por API, em branch própria por documento, sem tocar no checkout. Se o
+`preflight` apontar uma CLI antiga fixada nos workflows, as duas voltam a valer — e a
+saída é `npx @spec-wave/cli@latest update --branch`.

package/src/plugin/skills/preparar-specs/reference/revisao.md

@@ -0,0 +1,107 @@
+# Fase 3 — revisão de conteúdo
+
+O gerador escreve cada spec isoladamente, a partir do corpo de uma issue. Ele é bom nisso:
+as seções vêm completas, os requisitos rastreados, os fluxos coerentes **dentro** do
+documento. O que ele estruturalmente não consegue ver é a relação entre os documentos —
+porque, quando escreveu o primeiro, os outros não existiam.
+
+É exatamente aí que moram os problemas que custam caro depois. Por isso a regra desta fase:
+**leia as specs como conjunto, não uma a uma.**
+
+## Como ler
+
+Leia todas na íntegra antes de julgar qualquer uma. Ao ler a quinta, você reconhece na
+primeira uma contradição que era invisível quando ela era o único documento.
+
+Vale montar, enquanto lê, um mapa mental de três coisas:
+
+- **regras compartilhadas** — um teto, uma ordem de prioridade, uma janela de tempo que
+  aparece em mais de uma feature;
+- **quem depende de quem** — e em que direção cada spec declara a dependência;
+- **afirmações sobre o mundo** — "tal feature ainda não existe", "isso é feito por X".
+
+As três classes de problema abaixo saem desse mapa.
+
+## Classe 1 — contradição entre specs
+
+Duas features descrevem a mesma regra de formas que não fecham: contagens diferentes,
+prioridades diferentes, a mesma janela de tempo medida a partir de marcos diferentes.
+
+Isso é grave porque cada spec, sozinha, parece certa. O erro só existe no par — e vira dois
+comportamentos incompatíveis em produção, descobertos na integração.
+
+Ao encontrar, verifique qual das duas está alinhada com a fonte normativa (o corpo da issue,
+o documento de requisitos) antes de propor a correção. Frequentemente uma está certa e a
+outra derivou.
+
+## Classe 2 — dependência que não fecha
+
+Três formatos, todos vistos de verdade:
+
+**Aponta para algo que não existe.** A feature A declara que seu componente vive na feature
+B, e a spec de B não menciona esse componente em lugar nenhum. Alguém vai descobrir isso na
+implementação, quando já for caro.
+
+**Direção invertida ou circular.** A declara depender de B enquanto B declara depender de A.
+Uma spec bem gerada às vezes corrige isso sozinha e **documenta a correção** — quando vir
+uma nota dessas, confira se a outra ponta concorda.
+
+**Inversão de sequenciamento entre milestones.** A dependência bloqueante está numa
+milestone que vence *depois* da que depende dela. Não é erro de spec — é erro de
+planejamento que só aparece quando se olha as datas junto com as dependências. Levante
+sempre, porque ninguém mais vai olhar para os dois ao mesmo tempo.
+
+**Como verificar de forma barata:** para cada dependência declarada, confira se o
+diretório/arquivo existe e se a outra ponta concorda com a direção e o escopo.
+
+## Classe 3 — afirmação que a própria rodada tornou falsa
+
+Esta é sutil e específica de gerar várias specs de uma vez: a spec gerada às 10h afirma
+"tal feature ainda não possui spec" e às 10h20 essa spec passa a existir — gerada pela
+mesma rodada.
+
+**Cuidado ao corrigir:** a mesma frase costuma aparecer várias vezes no documento, sobre
+alvos diferentes, e só algumas ficaram obsoletas. Verifique alvo por alvo antes de editar.
+Corrigir por padrão de texto transforma afirmação verdadeira em falsa.
+
+E note *como* corrigir: quando a afirmação obsoleta era a **justificativa** de um TODO, a
+pergunta não desaparece — ela muda de razão. Reescreva a justificativa apontando onde a
+questão vive agora, em vez de apagar a frase e deixar o TODO sem explicação.
+
+## Também procure
+
+- **Sobreposição com feature já entregue.** Se uma spec descreve algo que uma feature
+  fechada já faz, há risco de duplicar comportamento em produção. Confira o estado da issue
+  antiga — "fechada" muda a conversa de "coordenar" para "não quebrar o que existe".
+- **Regra que contradiz outra regra da mesma spec.** Raro, mas acontece quando uma regra é
+  categórica ("nunca expor dado individual") e outra define um recorte fino o bastante para
+  violá-la na prática. Vale destacar: costuma ser o achado de maior severidade.
+- **Parâmetro declarado como "definido previamente" que ninguém definiu.** Limiares, prazos,
+  número de tentativas. Individualmente parecem detalhe; juntos costumam ser uma decisão só,
+  sem dono.
+
+## Como classificar o que encontrou
+
+**Achado material** — muda o desenho de uma feature, ou tem risco em produção. Vai como
+comentário na issue correspondente, contendo: a regra que o originou (citada), por que não
+se resolve no `plan`, e a decisão necessária. Se o achado tem dois lados (duas features
+discordando), comente **nos dois**, apontando um para o outro — quem abrir só uma issue
+precisa enxergar o quadro inteiro.
+
+**Lacuna paramétrica** — falta um número. Não bloqueia o `plan`. Agrupe por tema no
+relatório final: doze lacunas espalhadas costumam ser seis decisões, e uma lista de doze
+itens soltos não é acionável.
+
+O teste para separar as duas: *se ninguém decidir isso, o que acontece?* Se a resposta é
+"implementam errado" ou "duas partes se comportam de formas incompatíveis", é material. Se
+é "implementam com um valor provisório e ajustam depois", é paramétrico.
+
+## O que não fazer
+
+Não reescreva a spec para consertar o que encontrou. A spec é registro do que foi gerado a
+partir da fonte normativa; a correção de regra é decisão do PO, e o lugar dela é a issue.
+Editar o documento direto faz a decisão parecer tomada — e ninguém consegue rastrear quem
+a tomou.
+
+A exceção é o erro factual puro (Classe 3), que não é decisão de ninguém — e, mesmo aí,
+só com pedido explícito do usuário.

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

@@ -50,13 +50,15 @@ O comando **explica e para**, saindo com código 2. Não force sem entender:
 - **`trigger-pending`** — há label de gatilho na issue: um Action está em voo (ou falhou deixando-a). Rodar por cima duplicaria documento e comentário. `--force` fura, quando você tem certeza.
 - **`needs-human` / `critique-failed`** — portões humanos da crítica. O caminho é corrigir o documento e remover a label; para o `critique-failed` o passo de retomada é **re-criticar**, nunca regerar.
 - **`stale-checkout`** — o documento existe no repositório e não no seu clone. `git pull` e repita; seguir sobrescreveria o que já foi publicado.
+- **`pr-pending`** — o documento foi gerado e está num **Pull Request ainda não mergeado**. Revise o PR (edite ali mesmo, se precisar) e faça o merge; o passo seguinte lê o documento da branch base. Rodar por cima regeraria o arquivo, descartando a revisão e pagando a IA de novo.
+- **`branch-without-pr`** — o documento foi commitado numa branch `spec-wave/*` e **nenhum PR foi aberto** para ela. Quase sempre a abertura do PR falhou: opção *"Allow GitHub Actions to create and approve pull requests"* desligada, ou secret `GH_PR_TOKEN` ausente. Rode `spec-wave doctor`, corrija e abra o PR — reaplicar o gatilho **regera** o documento.
 - **`needs-confirmation`** — o passo cria issues (`decompose-apply`) ou gasta IA repetindo a crítica de um rascunho existente. Revise antes e confirme com `--apply` / `--yes`.
 - **`inconsistent-state`** — as labels afirmam um documento que não existe. Quase sempre o título da issue mudou depois de gerar (o slug vira outro diretório).
 
 ## Regras que o `run` respeita — e você também
 
 - **Nunca aplique label de gatilho no modo local.** Ela dispararia o Action e o passo aconteceria duas vezes. O `run` não aplica nenhuma.
-- **Um passo por invocação.** `--max-steps <n>` encadeia, mas cada passo de IA custa dinheiro — encadeie só quando o usuário pedir.
+- **Um passo por invocação.** `--max-steps <n>` encadeia, mas cada passo de IA custa dinheiro — encadeie só quando o usuário pedir. Na prática o encadeamento agora para sozinho: cada documento vai para um Pull Request, e o passo seguinte depende do merge.
 - A **Regra fundamental** continua valendo: nunca escreva `spec.md`/`plan.md`/`decomposition.md` à mão. Quem gera é a CLI, aqui como no Action.
 
 ## `mode` — o interruptor

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

@@ -1,6 +1,6 @@
 ---
 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."
+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 o arquivo e abrir um Pull Request. 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 *)
@@ -9,7 +9,7 @@ allowed-tools:
 
 # 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).
+> **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 chegue à main por Pull Request e seja referenciado na issue. Exceção: revisar/melhorar um `spec.md` já gerado (aí sim use Edit).
 
 ## Dois modos, mesmo resultado
 
@@ -18,7 +18,7 @@ allowed-tools:
 | **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).
+O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local automaticamente. Os dois geram o arquivo, abrem um **Pull Request** com ele, 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 credencial de IA no seu ambiente (`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` ou o login do Claude Code, se o provider for `claude-oauth`) e um `.spec-wave.json` no repositório. Para conduzir o fluxo inteiro sem gastar minutos de Actions, veja a skill **run**.
 
@@ -36,7 +36,7 @@ O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local
    ```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.
+   O comando imprime `Modo de execução: local`, gera e abre o Pull Request. Nada é gravado no seu clone — o documento vive no PR até o merge.
 
    **Action** — assíncrono:
    ```bash

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

@@ -16,6 +16,9 @@ Atualiza **somente o que divergiu** da versão da CLI: a **skill** instalada (po
 | `--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. |
+| `--branch [nome]` | Envia os arquivos do repo como **Pull Request** numa branch, em um único commit (sem valor: `spec-wave/update-v<versão>`). |
+| `--config-in-pr` / `--no-config-in-pr` | Força incluir/excluir o `.spec-wave.json` do PR. |
+| `--skill-in-pr` / `--no-skill-in-pr` | Força incluir/excluir a skill dos agentes do PR. |
 | `--dry-run` | Mostra o que seria atualizado sem alterar nada. |
 | `--yes` | Aplica sem pedir confirmação. |
 
@@ -28,15 +31,18 @@ Atualiza **somente o que divergiu** da versão da CLI: a **skill** instalada (po
 
 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:
+3. Com a aprovação, aplique — 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
    ```
    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
+   - **workflows e templates de issue** → no PR (com `--branch`) ou commitados direto na branch default
+   - **labels** → sempre direto na base: são metadado do repositório, não há como versioná-las
+   - **`.spec-wave.json` e a skill** → o comando **consulta a base** e vai pelo mesmo caminho do arquivo: se o repositório já versiona aquele caminho, a atualização entra no PR; se não versiona, fica só local e o usuário precisa commitá-la. Force com `--config-in-pr` / `--skill-in-pr` se o projeto quiser passar a versionar.
+   - a skill é gravada em disco nos dois casos — é a cópia que o agente carrega
 
 5. Se a skill foi atualizada, oriente a **recarregar/reiniciar o agente** para pegar a nova versão.
 

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

@@ -1,6 +1,6 @@
 ---
 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)."
+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, run, bug, triage, implement, order, task, story, move, doctor, update, info, uninstall, rfc, fix-pr); para conduzir um trecho inteiro do fluxo de uma vez, preparar-feature (uma Feature até Ready) ou preparar-specs (as specs de uma milestone)."
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
   - Bash(gh issue *)
@@ -31,7 +31,7 @@ Toda a CLI é invocada como `npx @spec-wave/cli@latest <comando>`.
    - **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.
+   O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), sem flag. Os dois geram, abrem um **Pull Request** com o documento, 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.
@@ -88,7 +88,7 @@ Depois do `generate-plan` e **antes** de qualquer issue nascer no `decompose`, u
 | 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) |
+| `decompose` | **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, títulos **desse arquivo** | edite no Pull Request → 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.
 
@@ -148,6 +148,11 @@ O slug vem do **título**: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro
 | gerar o plano técnico | `plan` |
 | validar spec+plan | `ready` |
 | quebrar em Stories/Tasks | `decompose` |
+| levar uma Feature da spec até ✅ Ready, de ponta a ponta | `preparar-feature` |
+| gerar as specs de uma milestone inteira | `preparar-specs` |
+| rodar o fluxo localmente / desarmar os workflows | `run` |
+| registrar ou corrigir um Bug | `bug` |
+| triar um Bug | `triage` |
 | implementar | `implement` |
 | ver ordem das Stories | `order` |
 | mover Task | `task` |

package/src/templates/skill/SKILL.md

@@ -86,7 +86,7 @@ O `run` decide o passo pelo estado da issue (documentos existentes + labels), re
 
 ## Regra fundamental
 
-**Nunca gere `spec.md` ou `plan.md` diretamente.** Acione o passo — a label (modo actions) ou o `run` (modo local) — e deixe o spec-wave gerar o arquivo. Isso garante que o arquivo seja commitado no repositório e referenciado na issue.
+**Nunca gere `spec.md` ou `plan.md` diretamente.** Acione o passo — a label (modo actions) ou o `run` (modo local) — e deixe o spec-wave gerar o arquivo. Isso garante que o arquivo chegue à main por **Pull Request** e seja referenciado na issue.
 
 Exceção: se o usuário pedir explicitamente para revisar ou melhorar um documento já gerado, use o Write tool para editar o arquivo local.
 
@@ -208,6 +208,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | `--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). |
+| `--skill-in-pr` / `--no-skill-in-pr` | flag | Força incluir/excluir a **skill dos agentes** 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. |
 
@@ -215,7 +216,9 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 
 > **`--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.
+> As **labels** nunca entram no PR: são metadado do repositório, não há como versioná-las — já valem na base, com ou sem o merge. O corpo do PR diz isso a quem revisa.
+>
+> A **skill** e o **`.spec-wave.json`** seguem a mesma regra, e ela é **verificada, não presumida**: o comando pergunta à base se aquele arquivo já é versionado. Se for (repos que commitam `.claude/skills/spec-wave/SKILL.md`, `.agents/skills/`, `AGENTS.md`, `.cursor/rules/…`), a atualização entra no PR junto com os workflows; se não for, fica só na máquina local. Passar a versionar (ou deixar de versionar) é decisão do projeto — use `--skill-in-pr` / `--no-skill-in-pr` para forçar.
 >
 > ⚠️ 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.
 
@@ -294,7 +297,7 @@ A saída da crítica é **estruturada e validada por schema**: `severity` só ac
 | Reprovou depois de | O que corrigir | Como retomar |
 |--------------------|----------------|--------------|
 | `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija → remova `spec-wave:critique-failed` → reaplique **`spec-wave:critique`** (re-critica o arquivo como está). `spec-wave:ready` apenas valida, **não** re-critica; e `spec-wave:plan` **regera** o plano, descartando a correção. |
-| `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) |
+| `decompose` (rascunho) | **`decomposition.md`** — os achados citam **`Story N`** e **`Task N.M`**, que são os títulos desse arquivo | edite o arquivo **no Pull Request** → 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.
 
@@ -309,7 +312,7 @@ O `decompose` **não cria issues direto**. São dois passos, com um artefato rev
 
 ```
 spec-wave:decompose
-  ├─ decomposition.md ausente  → gera via IA → commita → critica
+  ├─ decomposition.md ausente  → gera via IA → abre Pull Request → 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"
@@ -341,7 +344,7 @@ Corpo técnico.
 - a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona;
 - `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma;
 - 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`.
+- **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já mergeado) e reaplique `spec-wave:decompose`.
 
 ### Guard de idempotência do decompose (`spec-wave:decomposed`)
 
@@ -459,8 +462,8 @@ Traz tudo para a versão atual da CLI, atualizando **só o que mudou**: a skill
    - Escopos podem ser limitados com `--skip-skill`, `--skip-config`, `--skip-repo`.
    - **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.
+   - **Nos dois modos**, as **labels** são aplicadas direto na base (metadado do repositório, não versionável) e nunca entram no PR.
+   - **`.spec-wave.json` e skill:** com `--branch`, cada um entra no PR se o repositório **já o versiona** (o comando consulta a base, arquivo a arquivo); se não versiona, segue apenas local e o usuário precisa commitá-lo — ou use `--config-in-pr` / `--skill-in-pr` para passar a versioná-lo. Sem `--branch`, os dois são sempre só locais. A skill é gravada em disco de qualquer forma, para o agente já pegar a versão nova.
 4. Se a skill foi atualizada, oriente recarregar/reiniciar o agente para pegar a nova versão.
 
 ---
@@ -649,10 +652,10 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    ```bash
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
-   Informe: "Rascunho iniciado — vai commitar `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
+   Informe: "Rascunho iniciado — vai abrir um Pull Request com o `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: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`) no Pull Request 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
@@ -728,7 +731,7 @@ Gera o **`bug.md`** de um defeito: `docs/bugs/<slug>/bug.md`, com reprodução,
 
 1. Confirme que a issue é do tipo **Bug** (para outros tipos o Action pula, remove a label e comenta).
 2. `gh issue edit <n> --add-label "spec-wave:bug"`
-3. Avise: o Action `generate-bug.yml` gera e commita o arquivo.
+3. Avise: o Action `generate-bug.yml` gera o arquivo e abre um Pull Request com ele.
 4. Ofereça revisar **duas seções**: **Causa Raiz** e **Teste de Regressão**. São elas que decidem se a correção ataca o defeito ou o sintoma.
 5. Validar: `spec-wave:ready` → confere as seis seções e aplica `spec-wave:bug-approved`.
 

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

@@ -18,7 +18,15 @@ jobs:
     # Modo de execução: `spec-wave mode local` cria a variável de repositório
     # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
     # skipped e job que não roda não é faturado. `mode actions` remove a variável.
-    if: vars.SPEC_WAVE_EXECUTION != 'local'
+    # PR de DOCUMENTO não é PR de implementação. O fluxo publica spec.md,
+    # plan.md, bug.md e decomposition.md em branches `spec-wave/*`, e deixar este
+    # workflow rodar em cima delas move o board por um PR que não implementa
+    # nada. Nos Actions um PR aberto pelo GITHUB_TOKEN não dispara workflow, mas
+    # um aberto no modo local (ou via GH_PR_TOKEN) dispara.
+    #
+    # A guarda cobre também `spec-wave/update-v*`, do `update --branch` — que
+    # tampouco implementa uma Story.
+    if: vars.SPEC_WAVE_EXECUTION != 'local' && !startsWith(github.event.pull_request.head.ref, 'spec-wave/')
     runs-on: ubuntu-latest
     permissions:
       issues: read
@@ -44,7 +52,10 @@ jobs:
   move:
     needs: resolve
     # PR sem vínculo explícito não resolve Feature nenhuma — e não move nada.
-    if: vars.SPEC_WAVE_EXECUTION != 'local' && needs.resolve.outputs.feature != ''
+    if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
+      !startsWith(github.event.pull_request.head.ref, 'spec-wave/') &&
+      needs.resolve.outputs.feature != ''
     runs-on: ubuntu-latest
     # MESMO namespace do decompose.yml: um `decompose-apply` em curso na Feature
     # segura este job na fila em vez de disputar a subárvore com ele. Foi essa

package/src/templates/workflows/critique.yml

@@ -35,7 +35,7 @@ jobs:
     permissions:
       issues: write
       # read: a crítica LÊ o plan.md do checkout e não escreve arquivo nenhum —
-      # ao contrário do generate-plan, que commita o documento gerado.
+      # ao contrário do generate-plan, que publica o documento gerado.
       contents: read
 
     steps:

package/src/templates/workflows/decompose.yml

@@ -16,7 +16,7 @@ on:
 # proteção.
 #
 # generate-spec, generate-plan e generate-bug usam o MESMO namespace por outro
-# motivo: os quatro commitam e empurram na branch default, e este aqui ainda lê
+# motivo: os quatro publicam documentos em branch própria + Pull Request, e este aqui ainda lê
 # o spec.md/plan.md do checkout — que uma geração concorrente estaria trocando
 # debaixo dele.
 concurrency:
@@ -56,8 +56,18 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       issues: write
-      # A etapa de rascunho commita docs/**/decomposition.md no branch default.
       contents: write
+      # `contents: write` continua necessário: o commit vai por Git Data API
+      # (createTree/createCommit/createRef), que é autorizada por ele. O que
+      # mudou foi o DESTINO — branch própria do documento, nunca a default.
+      #
+      # `pull-requests: write` é a permissão NOVA deste fluxo. Sem ela o commit
+      # é criado e o PR não, e o documento fica numa branch que ninguém vê.
+      #
+      # Atenção: o GITHUB_TOKEN só abre PR se "Allow GitHub Actions to create and
+      # approve pull requests" estiver ligado (Settings → Actions → General) —
+      # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
+      pull-requests: write
 
     steps:
       - uses: actions/checkout@v4
@@ -78,6 +88,7 @@ jobs:
           ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}