@spec-wave/cli 0.14.0 → 0.16.0

package/src/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "spec-wave",
+  "displayName": "Spec Wave",
+  "version": "0.16.0",
+  "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
+  "author": {
+    "name": "Astratech",
+    "url": "https://github.com/astratech-net-br"
+  },
+  "homepage": "https://github.com/astratech-net-br/spec-wave-cli",
+  "repository": "https://github.com/astratech-net-br/spec-wave-cli",
+  "keywords": [
+    "spec-driven",
+    "github-projects",
+    "kanban",
+    "rfc",
+    "spec-kit",
+    "workflow"
+  ]
+}

package/src/plugin/README.md

@@ -0,0 +1,73 @@
+# Plugin spec-wave
+
+Uma skill por comando do fluxo spec-driven (RFC-001). Em vez de um `SKILL.md`
+monolítico que entra inteiro no contexto para qualquer pergunta, cada comando
+carrega só a sua instrução.
+
+## Skills
+
+| Skill | Para quê |
+|-------|----------|
+| `workflow` | Mapa do processo: Kanban, labels, crítica adversarial, roteamento |
+| `setup` | Configura o repositório (`init`) |
+| `info` | Status de configuração |
+| `doctor` | Preflight de auth, escopos, IA, board e workflows |
+| `update` | Atualiza skill, `.spec-wave.json` e workflows/labels |
+| `issue` | Cria Initiative/Epic/Feature/Bug/Spike/RFC no board |
+| `spec` | Gera `spec.md` (1º documento) |
+| `plan` | Gera `plan.md` (2º documento) + `tech_context.yml` |
+| `ready` | Valida spec + plan |
+| `decompose` | Rascunho revisável → Stories/Tasks |
+| `order` | Ordem topológica das Stories |
+| `implement` | Etapa 🚧 Desenvolvimento |
+| `task` | `start` / `done` de uma Task |
+| `story` | `review` de uma Story |
+| `move` | Move qualquer item do board |
+| `rfc` | Escreve um RFC e registra no board |
+| `fix-pr` | Audita e corrige um Pull Request |
+| `uninstall` | Remove a configuração do repositório |
+
+## Instalação
+
+### Claude Code
+
+```
+/plugin marketplace add astratech-net-br/spec-wave-cli
+/plugin install spec-wave@spec-wave
+```
+
+As skills ficam namespaced: `/spec-wave:spec`, `/spec-wave:decompose`, etc.
+
+### Codex
+
+Codex não tem plugins — ele varre diretórios de skills. A CLI copia o mesmo
+conteúdo para lá:
+
+```bash
+npx @spec-wave/cli@latest install-skill --agent codex          # .agents/skills (projeto)
+npx @spec-wave/cli@latest install-skill --agent codex --global # ~/.agents/skills (usuário)
+```
+
+Como não há namespace nesse destino, o `name:` do frontmatter é
+`spec-wave-<comando>` — invocação: `$spec-wave-spec`.
+
+## Estrutura de uma skill
+
+```
+skills/plan/
+  SKILL.md                   ← o agente LÊ (dirige a CLI)
+  model-prompt.md            ← a CLI ENVIA a um modelo  (id: `plan`)
+  model-prompt.critique.md   ← idem                     (id: `plan/critique`)
+  reference/tech-context.md  ← apoio, lido sob demanda
+```
+
+Os `model-prompt*.md` **não** são instalados em agente nenhum: dizem o oposto do
+`SKILL.md` ao lado. Arquivo de apoio também não entra sozinho no contexto, então
+a cópia do marketplace fica inerte.
+
+## Manutenção
+
+- Edite os `SKILL.md` aqui; é a fonte única para os dois destinos.
+- `.claude-plugin/plugin.json` deve acompanhar a versão do `package.json` —
+  há um teste que falha se divergirem.
+- Valide com `claude plugin validate ./packages/spec-wave/src/plugin`.

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

@@ -0,0 +1,60 @@
+---
+name: spec-wave-bug
+description: "Use para gerar o bug.md de um defeito do spec-wave — reprodução, causa raiz, escopo do fix e teste de regressão. Aplica a label spec-wave:bug e deixa o GitHub Action gerar e commitar o arquivo em docs/bugs/<slug>/. Gatilhos: 'gerar o bug.md da issue 42', 'documentar a causa raiz do bug', 'rodar o spec-wave:bug'. Só vale para issues do tipo Bug — Feature usa spec/plan."
+allowed-tools:
+  - Bash(gh issue *)
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave bug — o documento do defeito
+
+> **Regra fundamental: nunca escreva o `bug.md` você mesmo.** Aplique a label e deixe o Action gerar — é isso que garante que o arquivo seja commitado e referenciado na issue. Exceção: revisar/melhorar um `bug.md` já gerado (aí sim use Edit no arquivo local).
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## Por que existe
+
+Um Bug **não** gera `spec.md` + `plan.md`. Esses documentos pedem visão geral funcional, critérios de aceite, requisitos não-funcionais e plano de rollback — peso desproporcional para um defeito.
+
+O `bug.md` tem seis seções e uma finalidade: permitir que outra pessoa (ou o dev-agent) **reproduza, entenda e corrija** o defeito, com prova de que corrigiu.
+
+## Passos
+
+1. **Confirme que a issue é do tipo Bug.**
+
+   > **Apenas Bug.** Para qualquer outro tipo o Action **pula** a geração, remove a label e comenta.
+
+2. Adicione a label de gatilho:
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:bug"
+   ```
+
+3. Informe ao usuário: "Label `spec-wave:bug` adicionada. O Action `generate-bug.yml` vai gerar o `bug.md` automaticamente. Acompanhe em Actions → Generate Bug."
+
+4. Quando concluir, ofereça revisar `docs/bugs/<slug>/bug.md`. O slug vem do título: `[BUG] Duplicidade de pedidos no PIX` → `duplicidade-de-pedidos-no-pix`.
+
+   Concentre a revisão em **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 — o resto do documento é contexto.
+
+5. **Validar:** aplique `spec-wave:ready`. O Action confere as seis seções obrigatórias e aplica `spec-wave:bug-approved`.
+
+## Quando é obrigatório
+
+| Severidade | `bug.md` |
+|---|---|
+| **P0** | Opcional — o fix não espera documento. Documente depois, se valer. |
+| **P1** | Recomendado. |
+| **P2 / P3** | **Obrigatório** antes de o bug entrar na fila técnica (✅ Ready). |
+
+## As seis seções
+
+`Reprodução` · `Esperado e Obtido` · `Impacto e Severidade` · `Causa Raiz` · `Escopo do Fix` · `Teste de Regressão`
+
+O validador procura estes títulos byte a byte — se alguém renomear uma seção ao editar o arquivo, o `spec-wave:ready` reprova.
+
+## Se falhar
+
+- **Comentário 🔎 de crítica com `spec-wave:critique-failed`** → a crítica adversarial achou problema grave. Os três alvos mais comuns: a causa raiz não explica todos os sintomas relatados; o escopo do fix é maior que a causa (refatoração pegando carona); o teste de regressão passaria mesmo sem o fix. Corrija o `bug.md`, commite, remova a label e reaplique `spec-wave:bug`.
+- **`spec-wave:needs-human`** → a crítica reprovou N vezes seguidas e o fluxo está **parado**. Uma pessoa precisa revisar e remover a label.
+- **Relato insuficiente** → o `bug.md` sai com "Causa raiz não determinada" e uma lista de hipóteses. Isso é comportamento correto, não falha: leve as perguntas a quem reportou, acrescente as respostas como comentário na issue e reaplique `spec-wave:bug` — os comentários entram no próximo payload.
+- 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/bug/model-prompt.critique.md

@@ -0,0 +1,48 @@
+---
+name: critique-bug
+action: critique
+description: Critério da crítica adversarial do bug.md contra o relato original — causa raiz, escopo do fix e teste de regressão.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+verifiers: 3
+lenses:
+  - "explicação — a causa raiz proposta explica TODOS os sintomas relatados, ou só o mais visível?"
+  - "escopo — o fix cobre a causa raiz e apenas ela, sem refatoração oportunista nem correção de sintoma?"
+  - "prova — o teste de regressão descrito falharia mesmo sem o fix, ou passaria de qualquer jeito?"
+---
+
+# Crítica adversarial do bug.md
+
+Você é um engenheiro cético revisando a investigação de um defeito **antes** de alguém gastar tempo corrigindo. Sua função não é melhorar o texto: é encontrar onde ele levaria à correção errada.
+
+Você recebe o **relato original** (issue e comentários) e o **bug.md** proposto. O relato é a verdade sobre o comportamento observado; o bug.md é a hipótese.
+
+## O que auditar
+
+**1. A causa raiz explica os sintomas?**
+Compare cada sintoma do relato com a causa proposta. Um sintoma relatado que a causa não explica significa uma de duas coisas: a causa está errada, ou há um segundo defeito. As duas são **graves**.
+
+**2. É causa ou sintoma?**
+"O campo chega nulo" descreve o sintoma. Por que chega nulo é a causa. Uma correção que trata o sintoma reaparece na próxima entrada — **grave**.
+
+**3. O escopo bate com a causa?**
+- Escopo **menor** que a causa: o fix não resolve. Grave.
+- Escopo **maior** que a causa: há refatoração pegando carona. Grave — aumenta o risco de uma correção que deveria ser cirúrgica.
+- Escopo que não diz o que **não** muda: menor.
+
+**4. O teste de regressão prova alguma coisa?**
+A pergunta é única: **esse teste falharia sem o fix?** Um teste que passa nos dois cenários não é regressão, é decoração — **grave**. Um teste descrito vagamente demais para responder a essa pergunta é **menor**.
+
+**5. A reprodução é executável?**
+Passos que dependem de estado não descrito ("com o usuário na situação X") não reproduzem. Menor — a menos que tornem impossível verificar o fix, aí grave.
+
+**6. Severidade coerente com o impacto?**
+Um P3 cujo impacto descrito é "nenhum usuário consegue finalizar a compra" está classificado errado. Menor.
+
+## O que NÃO é achado
+
+- Preferência de redação, formatação ou ordem das seções.
+- Ausência de código — o `bug.md` **não deve** propor implementação.
+- "Causa raiz não determinada" **acompanhada de hipóteses testáveis**: isso é honestidade, e é o comportamento correto quando a investigação não conclui. Já uma causa afirmada sem evidência é grave.
+
+Prefira o silêncio ao achado inventado: um comentário cheio de observações menores treina o time a ignorar o portão.

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

@@ -0,0 +1,74 @@
+---
+name: bug
+action: bug
+description: Gera o bug.md — reprodução, causa raiz, escopo do fix e teste de regressão — a partir do relato na issue.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+---
+
+# Geração de bug.md
+
+Você é um engenheiro sênior investigando um defeito relatado. Produza o `bug.md`: o documento que outra pessoa (ou um agente) vai usar para **reproduzir, entender e corrigir** o defeito.
+
+Este documento é **leve por decisão**. Um defeito não gera especificação funcional nem plano técnico — gera o mínimo que torna a correção possível e verificável.
+
+## Entrada
+
+Você recebe um payload JSON com:
+
+- `metadata.bug_title` — título da issue
+- `metadata.labels` — labels aplicadas (a prioridade `P0`–`P3` é a **severidade**)
+- `metadata.required_sections` — os títulos exatos que o documento precisa ter
+- `report.raw` — o relato: corpo da issue **e** os comentários humanos, em ordem
+
+Trate o relato como a única fonte sobre o comportamento observado. Ele costuma ser incompleto — dizer o que falta é parte do trabalho, inventar não é.
+
+<!-- requires-tools -->
+## Investigação antes de escrever
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para transformar sintoma em causa:
+
+1. Localize o código do caminho descrito no relato (comece pela mensagem de erro, nome de tela, endpoint ou função citada).
+2. Leia o trecho e os arredores — a causa quase nunca está na linha que estourou.
+3. Procure o teste que deveria ter pego isto. A ausência dele é um achado, e vira a seção **Teste de Regressão**.
+
+Cite arquivo e função nas seções **Causa Raiz** e **Escopo do Fix**. Um `bug.md` sem referência a código é um relato reescrito, não uma investigação.
+<!-- /requires-tools -->
+
+## Estrutura obrigatória
+
+Use **exatamente** estes títulos, nesta ordem, como headings de nível 2:
+
+```markdown
+# Bug: <título sem o prefixo [BUG]>
+
+## Reprodução
+## Esperado e Obtido
+## Impacto e Severidade
+## Causa Raiz
+## Escopo do Fix
+## Teste de Regressão
+```
+
+O validador procura estes títulos byte a byte. Não os traduza, abrevie nem reordene.
+
+## O que cada seção precisa conter
+
+**Reprodução** — passos numerados e determinísticos. Ambiente, dados de entrada e pré-condições. Se o relato não permite reproduzir, escreva os passos até onde dá e liste explicitamente, em "Informação faltante", o que precisa ser perguntado a quem reportou.
+
+**Esperado e Obtido** — duas afirmações curtas e contrastantes. O que o sistema deveria fazer × o que ele faz. Sem narrativa.
+
+**Impacto e Severidade** — quem é afetado, com que frequência, e o que fica impossível de fazer. Justifique a severidade (`P0`–`P3`) com base nisso; se discordar da que veio nas labels, diga e explique.
+
+**Causa Raiz** — a origem, não o sintoma. Cite arquivo e função. Se a investigação não permitir concluir, escreva **"Causa raiz não determinada"** e liste as hipóteses em ordem de probabilidade, cada uma com o que a confirmaria ou descartaria. Uma causa inventada é pior que uma ausente: ela produz correção errada com aparência de fundamentada.
+
+**Escopo do Fix** — o que muda, e — igualmente importante — **o que deliberadamente não muda**. Um bug é o convite mais comum para refatoração oportunista; delimitar aqui é o que impede isso.
+
+**Teste de Regressão** — o teste que **falha sem o fix e passa com ele**. Nomeie o arquivo, descreva o caso e os dados. Se não houver como testar automaticamente, diga por quê e descreva a verificação manual.
+
+## Regras
+
+- Escreva em **português (pt-BR)**.
+- Seja específico: "a validação de CPF aceita string vazia em `validators.ts:checkCpf`" vale mais que "há um problema na validação".
+- **Não proponha código.** O documento descreve o defeito e delimita a correção; implementar é outra etapa.
+- Distinga o que você **observou** do que você **supõe**. Marque suposição como suposição.

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

@@ -0,0 +1,111 @@
+---
+name: spec-wave-decompose
+description: "Use para quebrar uma Feature em Stories+Tasks, ou um RFC em Tasks, no spec-wave. São DUAS etapas com um rascunho revisável no meio: spec-wave:decompose gera/critica o decomposition.md sem criar nada, e spec-wave:decompose-apply cria as issues a partir do rascunho aprovado. Gatilhos: 'decompor a feature 12', 'gerar as stories', 'quebrar em tasks', 'aplicar a decomposição', 'o decompose falhou na crítica'. Também cobre re-decompose e o guard de idempotência."
+allowed-tools:
+  - Bash(gh issue *)
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+  - Edit
+  - Write
+---
+
+# spec-wave decompose — 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
+
+Para qualquer outro tipo (Spike, Bug, Story, Task…) o Action **recusa** e comenta.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## O modelo mental
+
+```
+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)
+```
+
+## Passos
+
+1. **Pré-requisito.** Feature: confirme que está em **✅ Ready** (spec e plan validados — skill **ready**). RFC: basta a descrição estar completa.
+
+2. **Etapa 1 — gerar o rascunho:**
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:decompose"
+   ```
+   Informe: "Rascunho iniciado — vai commitar o `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
+
+3. **Leia o resultado** quando o Action terminar:
+
+   | Label resultante | O que fazer |
+   |------------------|-------------|
+   | `spec-wave:decompose-ready` | Passou na crítica. **Leia o `decomposition.md`** e mostre ao usuário o que será criado (Stories, Tasks, dependências). Ofereça editar antes de aplicar. |
+   | `spec-wave:critique-failed` | O Action **falhou (exit 1)** e nada foi criado. Os achados citam `Story N` / `Task N.M`. **Corrija o `decomposition.md`** — 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. Pai e filhas entram no board em **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem `Depende de: #N` — use a skill **order** para ver a ordem de execução.
+
+6. A issue recebe `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues.
+
+> **Nunca pule a etapa 1** aplicando `spec-wave:decompose-apply` direto — sem `decomposition.md` o Action falha pedindo o rascunho.
+
+## O arquivo `decomposition.md`
+
+Fica em `docs/features/<slug>/decomposition.md` (Feature) ou `docs/rfcs/<slug>/decomposition.md` (RFC):
+
+```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`
+
+> ⚠️ O slug vem do **título**. 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.
+
+## Guard de idempotência (`spec-wave:decomposed`)
+
+O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar issues, o `decompose` **pula** quando a issue já tem `spec-wave:decomposed` **ou** já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). A label é gravada ao **aplicar**. Os workflows ainda usam `concurrency` por issue.
+
+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:**
+
+```bash
+gh issue edit <n> --remove-label "spec-wave:decomposed"
+```
+Depois **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
+
+O `decompose` grava `Depende de: #N, #M` no corpo das Stories e cria a relação nativa *blocked by*. Isso alimenta as skills **order** e **implement**. **Não apague essa linha** ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).

package/src/plugin/skills/decompose/model-prompt.critique.md

@@ -0,0 +1,46 @@
+---
+name: critique-stories
+action: critique
+description: Critério da crítica adversarial das Stories propostas contra o spec.md e o plan.md, antes de virarem issues.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+verifiers: 3
+lenses:
+  - "contradição — alguma story contradiz, inverte ou ignora um requisito da spec ou uma decisão do plan?"
+  - "critérios de aceite — os critérios embutidos nas stories são compatíveis com as regras de negócio da spec?"
+  - "cobertura e ordem — as stories cobrem a Feature inteira, e a ordem/dependências declaradas são executáveis?"
+---
+
+# Crítica adversarial das Stories
+
+Você audita as Stories propostas (JSON) contra o `spec.md` e o `plan.md` fornecidos. Seu papel é encontrar problemas, não elogiar.
+
+Procure stories que contradizem, invertem ou ignoram requisitos da spec ou decisões do plan, e critérios de aceite incompatíveis com as regras de negócio.
+
+Esta auditoria roda **antes de qualquer issue ser criada**. É a última chance de impedir que trabalho errado vire backlog.
+
+## O que caracteriza um achado
+
+- **Contradições diretas** entre as stories e a spec/plan.
+- **Inversões de requisito** — ex.: a spec exige consentimento ANTES de persistir e a story persiste antes de pedir consentimento.
+- **Violações de restrição explícita** — minimização de dados (LGPD), limites de retenção, campos proibidos.
+- **Critérios de aceite incompatíveis** com as regras de negócio da spec.
+- **Lacuna de cobertura** — um Critério de Aceite da spec que nenhuma story endereça.
+- **Dependência impossível** — `dependsOn` que aponta para uma story que entrega depois, ou ordem que exige o que ainda não existe.
+
+<!-- requires-tools -->
+## Como verificar
+
+Você tem `Read`, `Glob` e `Grep`. Confira as stories contra os arquivos reais, não contra o que elas afirmam sobre eles.
+<!-- /requires-tools -->
+## Barra de rigor
+
+NÃO invente problemas. Se as stories estiverem consistentes com spec e plan, diga isso — uma decomposição limpa é um resultado legítimo e frequente.
+
+O inverso também vale: "não consegui confirmar" é uma refutação, não uma aprovação.
+
+## Consequência
+
+Um achado marcado como **grave** **aborta** a decomposição: nenhuma story ou task é criada, a label `spec-wave:critique-failed` é aplicada e o trigger `spec-wave:decompose` é removido. Um achado **menor** é comentado na issue, e a decomposição segue.
+
+Ou seja: um achado grave seu cancela a criação de dezenas de issues. Reserve-o para contradição real, não para preferência de estilo.

package/src/plugin/skills/decompose/model-prompt.feature.md

@@ -0,0 +1,69 @@
+---
+name: decompose-feature
+action: decompose
+description: Decompõe uma Feature em Stories ordenadas, cada uma com suas Tasks técnicas.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+json:
+  shape: '{"stories": [{"title": "...", "userStory": "...", "body": "...", "dependsOn": [0], "tasks": [{"title": "...", "body": "..."}]}]}'
+  retries: 1
+---
+
+# Decomposição de Feature em Stories
+
+Você é um Tech Lead experiente em decomposição de trabalho ágil. A partir da Feature fornecida (com spec.md e plan.md), gere uma lista de Stories e Tasks.
+
+## Entrada
+
+- Título e número da issue da Feature
+- O conteúdo de `spec.md` — critérios de aceite em Gherkin, fluxos, regras de negócio
+- O conteúdo de `plan.md` — estratégia técnica, matriz de rastreabilidade, detalhamento por camada
+
+Quando um dos dois documentos não existir, a entrada diz isso explicitamente. Decomponha com o que houver, mas não invente o que faltou.
+
+<!-- requires-tools -->
+## Exploração antes de decompor
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para dimensionar as tasks contra o código que existe de verdade: uma task "criar endpoint X" é diferente conforme o controller já exista ou não. Ancore os títulos técnicos nos caminhos e nomes reais que encontrar.
+<!-- /requires-tools -->
+
+## Contrato de saída
+
+Responda APENAS com JSON válido neste formato:
+
+```json
+{
+  "stories": [
+    {
+      "title": "Título curto da story (apenas a parte 'quero', sem prefixo)",
+      "userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
+      "body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
+      "dependsOn": [0],
+      "tasks": [
+        {
+          "title": "Título técnico curto da task (sem prefixo)",
+          "body": "Descrição técnica detalhada"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Regras
+
+- `title` deve ser CURTO (máx. ~60 caracteres): apenas a parte "quero" da user story, sem o "Como" nem o "para", e sem prefixo. Ex.: "visualizar meus repositórios em layout responsivo"
+- `userStory` deve trazer a user story completa no formato "Como <perfil>, quero <objetivo>, para <benefício>"
+- `body` é texto complementar (contexto, critérios de aceite); não repita o título
+- Cada Story deve ter 2–5 Tasks associadas
+- Tasks devem ser atividades técnicas concretas, com `title` curto e `body` detalhado
+- Gere entre 3 e 7 Stories por Feature
+- Ordene as stories na sequência de implementação — a ORDEM da lista importa
+- `dependsOn` (opcional): índices 0-based das stories ANTERIORES na lista das quais esta story depende. Referencie apenas índices menores que o da própria story. Use `[]` quando a story puder ser feita em paralelo (sem dependências); se omitido, assume-se dependência da story anterior (sequencial)
+- Escreva títulos e corpos em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
+
+## O que acontece com a sua saída
+
+Cada story vira uma issue `[STORY]` e cada task uma issue `[TASK]` vinculada como sub-issue, posicionadas na etapa **✅ Ready** do board. As dependências viram a relação nativa `blocked_by` do GitHub e uma linha "Depende de: #N" no corpo. Ou seja: a ordem e o `dependsOn` que você devolver determinam a ordem real de execução do time.
+
+Antes disso, uma crítica adversarial audita as stories contra a spec e o plan (ver a skill `critique-stories`). Achados graves cancelam a criação — nenhuma issue é aberta.

package/src/plugin/skills/decompose/model-prompt.rfc.md

@@ -0,0 +1,52 @@
+---
+name: decompose-rfc
+action: decompose
+description: Decompõe um RFC diretamente em Tasks técnicas, sem camada de Stories.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+json:
+  shape: '{"tasks": [{"title": "...", "body": "..."}]}'
+  retries: 1
+---
+
+# Decomposição de RFC em Tasks
+
+Você é um Tech Lead experiente. A partir do RFC fornecido (proposta técnica/de processo), gere a lista de Tasks técnicas concretas necessárias para implementá-lo.
+
+Um RFC não passa por spec/plan — ele é a proposta em si. Por isso não há camada de Stories aqui: as tasks penduram direto no RFC.
+
+## Entrada
+
+- Título e número da issue do RFC
+- O corpo da issue, que é o texto da proposta
+
+<!-- requires-tools -->
+## Exploração antes de decompor
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Um RFC quase sempre descreve mudança em algo que já existe — localize esse algo antes de listar tasks, e nomeie na `body` os arquivos e áreas que cada task vai tocar.
+<!-- /requires-tools -->
+## Contrato de saída
+
+Responda APENAS com JSON válido neste formato:
+
+```json
+{
+  "tasks": [
+    {
+      "title": "Título técnico curto da task (sem prefixo)",
+      "body": "Descrição técnica detalhada (o que fazer, áreas/arquivos afetados, critério de pronto)"
+    }
+  ]
+}
+```
+
+## Regras
+
+- `title` CURTO (máx. ~60 caracteres), sem prefixo.
+- `body` detalhado e acionável.
+- Gere entre 3 e 10 Tasks concretas que, juntas, cubram o RFC.
+- Escreva títulos e corpos em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
+
+## O que acontece com a sua saída
+
+Cada task vira uma issue `[TASK]` vinculada como sub-issue do RFC e posicionada na etapa **✅ Ready** do board.

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

@@ -0,0 +1,51 @@
+---
+name: spec-wave-doctor
+description: "Use como PRIMEIRO passo de troubleshooting do spec-wave: erro 404 ao criar issues, comando falhando sem motivo claro, board com colunas estranhas, Action que não roda, dúvida sobre token/escopos ou sobre qual modelo de IA está configurado. Também no início de uma sessão de trabalho. Gatilhos: 'spec-wave está com erro', 'não consigo criar issue', 'diagnosticar spec-wave', 'rodar o doctor'. Prefira esta skill a depurar gh api na mão."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh auth status)
+  - Read
+---
+
+# spec-wave doctor — preflight de auth e configuração
+
+Comando **local**, sem flags:
+
+```bash
+npx @spec-wave/cli@latest doctor
+```
+
+## O que ele checa
+
+- **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. o owner do repositório
+- **`.spec-wave.json`**: campos presentes 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 e os 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, sugere exemplos por agente (Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code)
+- **Workflows**: presença + **versão da CLI fixada** (não `@latest`)
+
+## Como ler a saída
+
+| Símbolo | Significado |
+|---------|-------------|
+| `✓` | ok |
+| `✗` | problema confirmado |
+| `!` | não verificável (best-effort — falha de rede nunca derruba o doctor) |
+
+**Exit 1** se houver algum `✗`.
+
+## Passos
+
+1. Rode o comando.
+2. Para cada `✗`, explique a causa ao usuário e proponha a correção concreta:
+   - escopo faltando → o usuário roda `!gh auth refresh --scopes project,repo,workflow` (interativo, ele executa)
+   - `.spec-wave.json` dessincronizado → `npx @spec-wave/cli@latest refresh --config`
+   - workflows/labels divergentes → skill **update**
+   - secret de IA ausente → Settings → Secrets → Actions (`ANTHROPIC_API_KEY` ou `OPENROUTER_API_KEY`)
+   - `specKit.command` ausente → configure antes de usar a skill **implement**
+3. Trate `!` como "não deu para verificar", não como falha.
+4. Se tudo passar e o problema original persistir, aí sim investigue a superfície específica (Action, issue, board).
+
+> **404 ao criar issues** é o caso clássico: quase sempre token sem acesso ao repo/org — e o doctor aponta exatamente isso.