@spec-wave/cli 0.14.0 → 0.16.0

package/src/plugin/skills/fix-pr/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: spec-wave-fix-pr
+description: "Use para auditar um Pull Request e corrigir os problemas encontrados — segurança, arquitetura, infraestrutura e qualidade — gerando um commit separado por fix, respondendo cada review comment com o hash do commit e postando um sumário no PR. Gatilhos: 'auditar o PR 42', 'corrigir os comentários de review', 'fix-pr 42', 'resolver os apontamentos do PR'."
+allowed-tools:
+  - Bash(gh pr *)
+  - Bash(gh api *)
+  - Bash(git add *)
+  - Bash(git commit *)
+  - Bash(git push *)
+  - Bash(git checkout *)
+  - Read
+  - Edit
+  - Glob
+  - Grep
+  - Agent
+---
+
+# spec-wave fix-pr — auditoria e correção de PR
+
+Cada fix vira um **commit separado** no branch do PR. Cada review comment recebe uma **resposta com o hash do commit**.
+
+**Pré-requisitos:** `.spec-wave.json` deve existir (para resolver `owner/repo`). Token com permissão de push no branch do PR.
+
+## Passos
+
+### 1. Resolver contexto
+
+Leia `.spec-wave.json` para obter `owner` e `repo`. Confirme o número do PR com o usuário se não vier como argumento.
+
+### 2. Coletar dados do PR
+
+```bash
+gh pr view <número> --json number,title,headRefName,body,changedFiles
+gh pr diff <número>
+gh api repos/<owner>/<repo>/pulls/<número>/comments
+gh api repos/<owner>/<repo>/pulls/<número>/reviews
+```
+
+Liste todos os arquivos alterados e colete os review comments (inline) e reviews gerais.
+
+### 3. Checkout do branch
+
+```bash
+gh pr checkout <número>
+```
+
+### 4. Varredura de problemas
+
+Para cada categoria, leia os arquivos alterados e identifique issues:
+
+| Categoria | O que procurar |
+|-----------|----------------|
+| **Segurança** | Credenciais hardcoded, secrets/API keys expostas, configs inseguras, injeção SQL/XSS |
+| **Arquitetura** | Dependências circulares, exports faltando, wiring incompleto, violações de camada |
+| **Infraestrutura** | OIDC mal configurado, IAM permissivo demais, Dockerfile sem usuário não-root, state remoto ausente |
+| **Qualidade** | sync-over-async, validação ausente, operações não idempotentes, error handling ausente |
+
+Se não houver review comments manuais, use um agente de review para detecção automatizada sobre o diff + arquivos alterados.
+
+### 5. Corrigir, um commit por problema
+
+Para cada problema: leia o arquivo (Read), aplique o fix (Edit), e commite isoladamente:
+
+```bash
+git add <arquivo>
+git commit -m "fix: <problema> (issue #<N>)
+
+<causa raiz>
+
+Solution: <descrição do fix>"
+git push
+```
+
+### 6. Responder aos review comments
+
+Para cada comment inline:
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<número>/comments/<comment-id>/replies \
+  -f body="✅ **FIXED** — commit **<HASH>**
+
+\`\`\`<linguagem>
+<trecho corrigido>
+\`\`\`
+
+<explicação do fix>"
+```
+
+### 7. Sumário no PR
+
+```bash
+gh pr comment <número> --body "<sumário>"
+```
+
+Formato:
+
+```markdown
+## 🔍 PR Audit — Spec Wave
+
+### Problemas encontrados e corrigidos
+
+| # | Severidade | Categoria | Problema | Commit |
+|---|-----------|-----------|---------|--------|
+| 1 | 🔴 Critical | Segurança | Credencial hardcoded em config.js | abc1234 |
+| 2 | 🟡 Medium | Qualidade | Operação não idempotente em createOrder | def5678 |
+
+### Commits criados
+- `abc1234` fix: credencial hardcoded removida (issue #1)
+- `def5678` fix: idempotency key adicionada em createOrder (issue #2)
+
+**Total:** <N> problema(s) encontrado(s) e corrigido(s).
+```
+
+## Severidade
+
+| Nível | Critério |
+|-------|----------|
+| 🔴 Critical | Segurança, dados expostos, falha em produção |
+| 🟠 High | Bug que afeta usuários, arquitetura quebrada |
+| 🟡 Medium | Qualidade, manutenibilidade, performance |
+| 🔵 Low | Estilo, naming, comentários |
+
+## Output esperado
+
+- Lista de issues (severidade + impacto)
+- Lista de commits criados (hash + mensagem)
+- Confirmação das replies postadas nos review comments
+- Estado final do PR
+
+> Reporte fielmente: se um problema foi encontrado mas **não** corrigido (fora de escopo, exige decisão do usuário), diga isso explicitamente no sumário em vez de omitir.

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

@@ -0,0 +1,102 @@
+---
+name: spec-wave-implement
+description: "Use para implementar trabalho do spec-wave na etapa 🚧 Desenvolvimento — uma Feature inteira (todas as Stories pendentes, em ordem de dependência), uma Story (todas as suas Tasks) ou uma Task isolada. Monta o contexto e aciona o spec-kit; se não houver spec-kit configurado, você mesmo implementa seguindo o contexto. Gatilhos: 'implementar a feature 12', 'começar a story 34', 'fazer a task 56', 'rodar o implement'. Comando LOCAL — não usa label nem Action."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Bash(gh pr *)
+  - Bash(git add *)
+  - Bash(git commit *)
+  - Bash(git push *)
+  - Bash(git checkout *)
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+---
+
+# spec-wave implement — etapa 🚧 Desenvolvimento
+
+Comando **local** (lê o `.spec-wave.json`, como o `issue`), **não** disparado por label/Action.
+
+| Flag/Arg | Descrição |
+|----------|-----------|
+| `<issue>` | **Obrigatório**, posicional. Número da Feature, Story ou Task (`12` ou `#12`). |
+| `--feature-dir <path>` | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` (sobrescreve a resolução automática). |
+| `--dry-run` | Monta o contexto e imprime o comando **sem executar** e **sem escrever nada no GitHub**. |
+
+**Pré-requisitos:** `.spec-wave.json` presente (senão → skill **setup**) e a issue ser Feature, Story ou Task. Para executar de fato, o spec-kit precisa estar configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`.
+
+## Como o comando se comporta por tipo
+
+| Tipo | Comportamento |
+|------|---------------|
+| **Feature** | Lista as Stories (sub-issues), **ordena topologicamente** pelas dependências, **pula as já em 👀 Code Review ou além** (listadas no contexto como "não tocar") e monta **um único** contexto com todas as pendentes, cada uma com suas Tasks. Aciona o spec-kit **uma vez**. |
+| **Story** | Coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez. |
+| **Task** | Só aquela task. |
+
+**Abortos no modo Feature:** ciclo de dependências entre Stories pendentes → **exit 1** (corrija as linhas `Depende de:`; veja a skill **order**). Story pendente **sem Tasks** → aborta pedindo decomposição. Todas implementadas → encerra sem acionar o spec-kit.
+
+**Bug** → modo próprio (RFC-004): sem tasks e sem spec/plan, o contexto impõe quatro fases — reproduzir → causa raiz → fix mínimo → teste de regressão. O `bug.md`, quando existe, entra como **hipótese a confirmar** (foi escrito por IA sem executar código), não como fato. O Bug vai sozinho para 👀 Code Review ao abrir o PR: não arrasta a Feature-pai.
+
+Outros tipos (Spike, Epic) → o comando **recusa**.
+
+## Passos
+
+1. Confirme que há `.spec-wave.json` no repo.
+
+2. **Sempre comece com `--dry-run`:**
+   ```bash
+   npx @spec-wave/cli@latest implement <número> --dry-run
+   ```
+   Inspecione: detecção do tipo, Tasks coletadas (Story) ou ordem/puladas/ciclos (Feature), e o comando do spec-kit que seria executado.
+
+3. Mostre ao usuário o contexto montado em `.spec-wave/implement-<número>.md`. Ele inclui os comentários da issue, um **digest do código recente**, um **aviso de dependências pendentes** quando aplicável, e as instruções de execução sequencial.
+
+4. **Se o spec-kit estiver configurado** e o usuário aprovar, rode sem `--dry-run`:
+   ```bash
+   npx @spec-wave/cli@latest implement <número>
+   ```
+   Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`.
+
+   Use `--feature-dir docs/features/<slug>` se a resolução automática falhar e você quiser anexar `spec.md`/`plan.md`.
+
+5. **Se você (agente) for implementar diretamente**, siga o protocolo abaixo.
+
+6. Ao final, confirme o resultado com o usuário e oriente a revisão dos PRs.
+
+## Protocolo de execução (obrigatório)
+
+**Uma Task por vez.** Nunca deixe duas Tasks com Status "In Progress" ao mesmo tempo.
+
+Para cada Task, **prefira os comandos da CLI a mutações GraphQL/`gh` manuais** — eles embutem as regras do board (Etapa nunca retrocede; uma Task In Progress por vez):
+
+```bash
+npx @spec-wave/cli@latest task start <n>   # Etapa 🚧 Desenvolvimento + Status In Progress
+# ... implementa ...
+npx @spec-wave/cli@latest task done <n>    # Etapa 🎉 Done + Status Done
+```
+
+**Ao concluir toda a Story:** faça o commit, abra o PR e mova a Story:
+
+```bash
+npx @spec-wave/cli@latest story review <n>  # Etapa 👀 Code Review, Status Todo
+```
+
+**A Feature só avança** para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. No modo Feature isso acontece dentro da mesma execução.
+
+**No modo Feature**, siga o contexto Story a Story, **na ordem listada**: implemente as Tasks, depois commit + PR + `story review`; só então passe à próxima Story.
+
+> **Aviso de dependência pendente** no contexto (a issue depende de outra não concluída, via `Depende de: #N` ou *blocked by*) → **confirme com o usuário** antes de seguir fora de ordem.
+
+Lembre: a **Etapa só avança**, nunca volta; o **Status** mede o progresso dentro da etapa.
+
+## Quando não dá para implementar
+
+| Situação | Saída |
+|----------|-------|
+| Feature **sem Stories** | Rode a skill **decompose** primeiro |
+| **Ciclo de dependências** | Corrija as linhas `Depende de:` — veja a skill **order** |
+| Issue é Spike/Epic | O comando recusa; use a skill **move** para mexer no board |
+| Bug sem `bug.md` | Segue assim mesmo, com aviso — a investigação inteira fica com o executor. Para gerar o documento antes, use a skill **bug**. |

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

@@ -0,0 +1,40 @@
+---
+name: spec-wave-info
+description: "Use quando o usuário perguntar se o repositório atual já está configurado com spec-wave, qual GitHub Project está vinculado, qual versão da CLI foi usada no init, ou se a skill instalada está atualizada. Gatilhos: 'o spec-wave está configurado aqui?', 'qual o board deste repo?', 'status do spec-wave'. Para um diagnóstico completo de auth e workflows use a skill doctor."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave info — status de configuração
+
+Mostra se o repositório atual foi configurado e valida a skill instalada.
+
+| Flag | Descrição |
+|------|-----------|
+| `--json` | Saída JSON (`{"initialized":bool, ..., "skill":{...}}`) para parsing programático. |
+
+## Passos
+
+1. Execute:
+   ```bash
+   npx @spec-wave/cli@latest info
+   ```
+
+2. **Se inicializado**, apresente ao usuário os dados do `.spec-wave.json`: `owner/repo`, `project.title` + `project.url`, `version` da CLI e `initializedAt`.
+
+3. **Se NÃO inicializado**, pergunte: "Este repositório ainda não foi configurado com o spec-wave. Quer rodar o `init` agora?"
+   - Sim → use a skill **setup**.
+   - Não → encerre sem alterar nada.
+
+4. **Se a saída indicar skill pendente** (aviso "Skill pendente de instalação/atualização" ou, no `--json`, `skill.installNeeded: true`), ofereça resolver:
+   - skill `ausente` → `npx @spec-wave/cli@latest install-skill`
+   - skill `desatualizada` → `npx @spec-wave/cli@latest update` (skill **update**)
+
+   Lembre de recarregar o agente depois.
+
+5. Se a `version` do arquivo divergir de `npx @spec-wave/cli@latest --version`, sugira `npx @spec-wave/cli@latest refresh --config` (reescreve o `.spec-wave.json` com os dados atuais do Project) ou a skill **update**.
+
+## O que o comando valida além do arquivo
+
+Para cada agente de código detectado no diretório, compara a cópia instalada da skill com a versão empacotada na CLI — uma cópia **global** atualizada também conta. No `--json`, o campo `skill` traz `{agentsDetected, installNeeded, pending:[{agent, reason, path}]}`.

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

@@ -0,0 +1,63 @@
+---
+name: spec-wave-issue
+description: "Use para criar um work item tipado no spec-wave — Initiative, Epic, Feature, Bug, Spike ou RFC — já adicionado ao GitHub Project com Etapa, Work Item Type e Area. Gatilhos: 'criar uma feature', 'nova initiative', 'abrir um epic', 'registrar um bug no board', 'criar issue do spec-wave'. NÃO use para Story ou Task (nascem do decompose — skill decompose) e nunca use gh issue create."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Read
+---
+
+# spec-wave issue — cria um work item no board
+
+Faz tudo de uma vez: cria a issue com a label de tipo, vincula ao parent como **sub-issue** nativa do GitHub, adiciona ao Project e define os campos **Etapa**, **Work Item Type**, **Area** e — só se informada — **Priority**. Grava `Parent: #N` no corpo.
+
+> **Nunca use `gh issue create`.** Ele não adiciona ao board nem vincula o parent: a issue fica sem Etapa e some de todas as telas da UI.
+
+**Contexto:** leia `.spec-wave.json` (Read) para confirmar que o repo está configurado. Ausente → skill **setup**.
+
+## Flags
+
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--title <title>` | **obrigatório** | Título **sem** o prefixo de tipo — a CLI adiciona (`[FEATURE]`, `[STORY]`…). |
+| `--type <type>` | string | `initiative`, `epic`, `feature`, `story`, `task`, `bug`, `spike`, `rfc`. Default: `feature`. |
+| `--parent <n>` | string | Número da issue pai — cria como sub-issue dela. |
+| `--body <text>` | string | Descrição. |
+| `--priority <p>` | string | **Opcional.** `P0`–`P3`. **Omita** se o usuário não pediu. |
+| `--area <area>` | string | `Frontend`, `Backend`, `Mobile`, `Infra`, `DevOps`, `Data`. |
+
+Atalhos: `initiative` (raiz, sem `--parent`) e `feature` — mesmas flags, `--type` fixo.
+
+## Hierarquia
+
+`Initiative → Epic → Feature → Story → Task`. Use `--parent <n>` para pendurar no nível acima.
+
+## Passos
+
+1. **Colete com o usuário:** tipo, título (sem prefixo), descrição e o número da issue **pai**, se houver.
+
+   > **Prioridade e área são opcionais.** Só inclua se o usuário pedir explicitamente. **Nunca atribua uma prioridade por conta própria** — omitindo `--priority`, a prioridade fica `null` (sem prioridade) no board.
+
+2. **Execute** com **apenas** as flags que o usuário forneceu:
+   ```bash
+   npx @spec-wave/cli@latest issue \
+     --type "<tipo>" \
+     --title "<título>" \
+     --body "<descrição>" \
+     --area "<área>" \            # opcional
+     --priority "<prioridade>" \  # opcional — se o usuário não pediu, OMITA
+     --parent "<número-do-pai>"   # opcional
+   ```
+   Para Features, o atalho `npx @spec-wave/cli@latest feature --title ...` equivale a `--type feature`.
+
+3. Informe o número criado e o vínculo com o pai.
+
+4. Para Features, aponte o próximo passo: mover para **📋 Spec** e usar a skill **spec** para gerar a especificação funcional (o plano técnico vem depois).
+
+## Cuidados por tipo
+
+⚠️ **A Etapa inicial é sempre 📥 Backlog, para qualquer `--type`.** Correto para Initiative, Epic, Feature, RFC, Bug e Spike.
+
+**Story e Task:** está errado para elas — pertencem a ✅ Ready. O caminho normal é a skill **decompose**. Se o usuário insistir numa Story/Task avulsa: crie **com `--parent <n>`** e, logo em seguida, avance para ✅ Ready (skill **move**), explicando por que o passo extra é necessário — senão o item fica invisível na UI.
+
+**Spike:** entra em 📥 Backlog e o **usuário** o move à mão pelas etapas. Nunca avance a Etapa de um Spike por conta própria.

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

@@ -0,0 +1,52 @@
+---
+name: spec-wave-move
+description: "Use para mover qualquer item do board spec-wave — Feature, Story, Task, Bug ou RFC — para uma Etapa, quando task start|done e story review não cobrem o movimento (ex.: mover uma Feature para Homologação ou Deploy). Gatilhos: 'mover a feature 12 para homologação', 'passar para deploy', 'avançar o card'. Prefira este comando a gh api graphql manual: a Etapa nunca retrocede, e isso é regra do fluxo, não limitação."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave move — move qualquer item do board
+
+Comando **local**:
+
+```bash
+npx @spec-wave/cli@latest move <n> <etapa> [--status <valor>]
+```
+
+| Flag/Arg | Descrição |
+|----------|-----------|
+| `<n>` | **Obrigatório.** Número da issue, ex.: `8` ou `#8`. |
+| `<etapa>` | **Obrigatório.** Etapa de destino — com ou sem emoji, sem acento, em qualquer caixa: `"code review"`, `"Homologação"`, `"🎉 Done"`. |
+| `--status <valor>` | Status no destino: `Todo`, `In Progress` ou `Done`. Default: `Todo`. |
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## Etapas válidas
+
+```
+📥 Backlog → 🐞 Triagem → 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready
+→ 🚧 Desenvolvimento → 👀 Code Review
+→ 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done
+```
+
+## Guardas embutidas
+
+- **A Etapa nunca retrocede.** Se o item já estiver adiante, o comando informa a Etapa atual e **não faz nada**. **Não existe escape hatch** para retroceder — é a regra do fluxo.
+- **Spike é recusado** — a Etapa de um Spike é movida à mão pelo usuário. Nunca a avance por conta própria.
+- **Nome ambíguo é recusado** listando as candidatas (`"p"` casa com Priorizado e Plan). Seja específico.
+
+## Passos
+
+1. Confirme o número da issue e a Etapa de destino com o usuário.
+2. Rode o comando. Passe `--status` se o item já deve entrar na etapa em andamento ou concluído.
+3. Se o comando recusar por Etapa já adiante, apenas informe a Etapa atual — não tente contornar via `gh api graphql`.
+4. Se recusar por ambiguidade, escolha entre as candidatas listadas e rode de novo.
+
+## Quando preferir outra skill
+
+| Caso | Skill |
+|------|-------|
+| Task iniciando ou concluindo | **task** (`start` / `done`) |
+| Story indo para Code Review | **story** (`review`) |
+| Feature avançando após todas as Stories em review, ou indo para QA/Homologação/Deploy | **move** (esta) |

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

@@ -0,0 +1,36 @@
+---
+name: spec-wave-order
+description: "Use para descobrir em que ordem as Stories de uma Feature do spec-wave devem ser implementadas, segundo as dependências declaradas (Depende de: #N e a relação nativa blocked by). Também detecta ciclos de dependência e Stories fora de ordem. Gatilhos: 'qual story implementar primeiro', 'ordem das stories da feature 12', 'tem ciclo de dependência?'. Use antes da skill implement."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+---
+
+# spec-wave order — ordem topológica das Stories
+
+Comando **local**:
+
+```bash
+npx @spec-wave/cli@latest order <feature>
+```
+
+| Arg | Descrição |
+|-----|-----------|
+| `<feature>` | Número da issue da **Feature**, ex.: `12` ou `#12`. Posicional, obrigatório. |
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## O que a saída traz
+
+- As Stories da Feature em **ordem topológica** pelas dependências — a linha `Depende de: #N` no corpo **mesclada** com a relação nativa *blocked by* do GitHub
+- A **Etapa atual** de cada Story no board
+- Avisos de **ciclo de dependência** — essas Stories ficam **fora da ordem**; corrija as linhas `Depende de:`
+- Avisos de **dependência fora de ordem** — Story já em 🚧 Desenvolvimento ou além dependendo de outra que não está em 🎉 Done
+
+## Passos
+
+1. Rode o comando para a Feature.
+2. Apresente a ordem ao usuário, marcando o que já está concluído e o que está pendente.
+3. **Se houver ciclo**, isso é bloqueante para a skill **implement** no modo Feature (o comando aborta com exit 1). Ajude a quebrar o ciclo editando as linhas `Depende de:` nos corpos das Stories.
+4. **Se houver dependência fora de ordem**, aponte o risco ao usuário antes de seguir.
+5. Com a ordem clara, siga para a skill **implement**.

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

@@ -0,0 +1,53 @@
+---
+name: spec-wave-plan
+description: "Use para iniciar a geração do plano técnico (plan.md) de uma Feature do spec-wave — o SEGUNDO documento, derivado da spec.md. Aplica a label spec-wave:plan e deixa o GitHub Action gerar. Também cobre a criação e manutenção do .github/config/tech_context.yml, de que a qualidade do plano depende. Gatilhos: 'gerar o plano técnico', 'criar o plan.md da feature 12', 'configurar o tech_context'. Só vale para Features."
+allowed-tools:
+  - Bash(gh issue *)
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+  - Write
+  - Glob
+  - Grep
+---
+
+# spec-wave plan — plano técnico (2º documento)
+
+> **Regra fundamental: nunca gere o `plan.md` você mesmo.** Aplique a label e deixe o Action gerar e commitar. Exceção: revisar/melhorar um plano já gerado.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+O plano segue o schema do **RFC-002 §3.2**: **Estratégia Técnica** (com Matriz de Rastreabilidade), **Detalhamento da Implementação**, **Segurança e Conformidade**, **Estratégia de Testes** e **Rollback e Monitoramento**. O agente usa o `tech_context` do repositório (`.github/config/tech_context.yml` + versões de pacote e migrations recentes) para embasar o plano e usar **APENAS** as tecnologias declaradas.
+
+## Passos
+
+1. **A spec existe?** Verifique `docs/features/<slug>/spec.md` — o plano usa a especificação funcional como contexto. Se não existir, gere a spec primeiro (skill **spec**).
+
+2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read). **Se não existir, ajude a criar AGORA** — o passo a passo está em `reference/tech-context.md`, ao lado deste arquivo. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
+
+3. Adicione a label de gatilho:
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:plan"
+   ```
+
+4. Informe: "Label `spec-wave:plan` adicionada. O Action `generate-plan.yml` vai gerar o `plan.md`. Acompanhe em Actions → Generate Plan."
+
+5. Quando concluir, ofereça revisar `docs/features/<slug>/plan.md`.
+
+6. **Próximo passo:** validar a Feature — mova para **✅ Ready** e use a skill **ready**.
+
+## Desvios pontuais (`## Tech Override`)
+
+Para uma Feature específica usar algo fora do padrão, oriente a adicionar no **corpo da issue** uma seção com um bloco YAML que será mesclado (deep-merge) sobre o `tech_context.yml`:
+
+````markdown
+## Tech Override
+```yaml
+system_info:
+  stack:
+    database: "DynamoDB"
+```
+````
+
+## Se falhar
+
+Depois do `generate-plan` roda a **crítica adversarial**, que vira um comentário 🔎 na issue. Se ela apontar findings **graves**, a issue recebe `spec-wave:critique-failed` — corrija o **`plan.md`** (ou a `spec.md` que o embasa), commite, remova a label e reaplique `spec-wave:ready`. Detalhes na skill **workflow**.

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

@@ -0,0 +1,44 @@
+---
+name: critique-plan
+action: critique
+description: Critério da crítica adversarial do plan.md contra o spec.md, as regras de negócio e o tech_context.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+verifiers: 3
+lenses:
+  - "contradição — o plano decide algo que a spec proíbe, inverte ou já decidiu de outro jeito?"
+  - "fronteira técnica — o plano usa alguma tecnologia, serviço ou API fora do tech_context declarado?"
+  - "rastreabilidade — existe mudança de banco, endpoint ou componente de UI que não referencia nenhum Critério de Aceite?"
+---
+
+# Crítica adversarial do plan.md
+
+Você audita o `plan.md` contra o `spec.md`, as regras de negócio e o `tech_context` fornecidos. Seu papel é encontrar problemas, não elogiar.
+
+Procure decisões técnicas que contradizem ou ignoram requisitos da spec, e tecnologias/serviços fora do tech_context.
+
+## O que caracteriza um achado
+
+- **Contradições diretas** entre os documentos.
+- **Inversões de requisito** — ex.: a spec exige consentimento ANTES de persistir e o plano persiste antes de pedir consentimento.
+- **Violações de restrição explícita** — minimização de dados (LGPD), limites de retenção, campos proibidos.
+- **Itens que contradizem ou ignoram a spec**.
+- **Rastreabilidade quebrada** — mudança de banco, endpoint de API ou componente de UI que não referencia nenhum Critério de Aceite.
+- **Tecnologia fora da fronteira** — qualquer serviço, biblioteca ou API que não esteja no tech_context nem seja definido no próprio plano.
+
+<!-- requires-tools -->
+## Como verificar
+
+Você tem `Read`, `Glob` e `Grep`. Não confie na descrição que o plano faz do repositório — abra os arquivos que ele cita. Um plano que afirma estender `PedidoService` quando esse arquivo não existe tem um achado, e só a leitura revela isso.
+<!-- /requires-tools -->
+## Barra de rigor
+
+NÃO invente problemas. Se os documentos estiverem consistentes, diga isso — uma auditoria limpa é um resultado legítimo e frequente.
+
+O inverso também vale: "não consegui confirmar" é uma refutação, não uma aprovação. Se você não conseguiu verificar uma afirmação que importa, trate-a como refutada e diga o que faltou.
+
+## Consequência
+
+Um achado marcado como **grave** aplica a label `spec-wave:critique-failed`, que bloqueia o `spec-wave:ready` até correção. Um achado **menor** é reportado na issue sem bloquear.
+
+Calibre com isso em mente: um achado grave custa o tempo de um humano. Reserve-o para contradição real com a spec, o tech_context ou uma regra explícita — não para preferência de estilo.

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

@@ -0,0 +1,59 @@
+---
+name: plan
+action: plan
+description: Gera o plano técnico (plan.md) de uma Feature a partir do spec.md e do tech_context.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+---
+
+# Geração de plan.md
+
+Você é um Tech Lead experiente. Gere um plano técnico (plan.md) completo e detalhado, baseado ESTRITAMENTE no spec.md fornecido.
+
+## Entrada
+
+Você recebe um payload JSON com:
+
+- `spec_content` — o spec.md já gerado (ou um aviso de que ainda não existe)
+- `feature_title` / `feature_description` — título e corpo da issue
+- `tech_context.static` — o stack declarado em `.github/config/tech_context.yml`
+- `tech_context.dynamic` — o que foi detectado no repositório
+- `tech_context.overrides` — ajustes declarados no corpo da issue
+
+<!-- requires-tools -->
+## Exploração antes de escrever
+
+Você tem `Read`, `Glob` e `Grep` no repositório de destino. Use-os: localize os módulos, endpoints, migrations e componentes que esta Feature vai tocar, e ancore o plano nos **caminhos e nomes reais** que encontrar. Um plano que cita `src/services/pedido.ts` porque leu o arquivo vale muito mais que um que inventa `PedidoService`.
+
+O `tech_context` continua sendo a fronteira do que você pode propor — explorar o repositório serve para ser preciso dentro dela, não para ampliá-la.
+<!-- /requires-tools -->
+## Estrutura obrigatória
+
+O plano deve conter EXATAMENTE estas seções em português, nesta ordem:
+
+```
+# Estratégia Técnica
+  - Abordagem Arquitetural, Decisões-Chave e uma Matriz de Rastreabilidade (tabela)
+    ligando cada Critério de Aceite do spec a um componente técnico.
+# Detalhamento da Implementação
+  - Abra a seção com um diagrama de sequência Mermaid (bloco ```mermaid iniciado com
+    sequenceDiagram) do fluxo principal ponta a ponta, com os componentes técnicos
+    reais como participants (frontend, endpoints/controllers, services, banco de
+    dados, filas). Use APENAS componentes do tech_context ou definidos neste plano;
+    rotule as mensagens com os caminhos de endpoint e nomes de método reais, em
+    português.
+  - Subseções: ## Backend, ## Banco de Dados, ## Frontend, ## Infraestrutura.
+# Segurança e Conformidade
+# Estratégia de Testes
+  - Unitários, Integração e E2E.
+# Rollback e Monitoramento
+  - Plano de Rollback, Métricas Observadas e Alertas.
+```
+
+## Regras OBRIGATÓRIAS
+
+- TODA mudança de banco, endpoint de API ou componente de UI DEVE referenciar um Critério de Aceite específico do spec.md (rastreabilidade).
+- Use APENAS as tecnologias e serviços listados no tech_context fornecido. Não invente APIs ou serviços inexistentes.
+- Forneça detalhes acionáveis: caminhos exatos de endpoints, nomes de DTOs, constraints de banco.
+- Escreva em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
+- O arquivo deve conter APENAS o conteúdo do plan.md — nada de preâmbulo, comentário sobre o processo ou resumo do que você fez.

package/src/plugin/skills/plan/reference/tech-context.md

@@ -0,0 +1,56 @@
+# Tech Context (`.github/config/tech_context.yml`)
+
+Fonte de verdade **estática** da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias e serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes.
+
+O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
+
+## Como ajudar a criar
+
+1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, confirme com o usuário se reflete a stack atual e pule para o fim.
+
+2. **Detecte a stack lendo os arquivos do repositório** (use Read — **não invente**):
+
+   | Arquivo | O que extrair |
+   |---------|---------------|
+   | `package.json` | backend/frontend e libs (`@nestjs/core`, `next`, `react`, `@prisma/client`, `express`) |
+   | `pom.xml` / `build.gradle` | stack Java |
+   | `requirements.txt` / `pyproject.toml` | stack Python |
+   | `go.mod` | stack Go |
+   | `prisma/schema.prisma` ou `migrations/` | tabelas e colunas para `database_schemas` |
+   | `Dockerfile` / `docker-compose.yml` / charts Helm | `infra` |
+   | enums de RBAC no código | `security.rbac_roles` |
+
+3. **Rascunhe** o YAML seguindo EXATAMENTE este schema. Preencha só o que conseguir confirmar; deixe `# TODO` no que faltar:
+
+   ```yaml
+   system_info:
+     name: "<nome do sistema>"
+     stack:
+       backend: "<ex.: Node.js (NestJS v11)>"
+       frontend: "<ex.: Next.js 16 (React 19)>"
+       database: "<ex.: PostgreSQL (Prisma 5)>"
+       infra: "<ex.: Docker / Kubernetes>"
+     architecture: "<ex.: Monorepo Nx / Microservices>"
+   security:
+     auth_protocol: "<ex.: JWT>"
+     rbac_roles: ["ADMIN", "..."]
+   database_schemas:
+     - table: "<tabela>"
+       columns: "<col1, col2, ...>"
+   existing_services:
+     - name: "<serviço>"
+       endpoint: "<caminho>"
+       auth: "<ex.: JWT, mTLS>"
+   internal_libraries:
+     - "<lib interna>"
+   ```
+
+4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar — ele conhece serviços internos e roles que o código pode não revelar.
+
+5. **Grave** com Write em `.github/config/tech_context.yml`.
+
+6. **Oriente a commitar e pushar antes de seguir** — o Action lê do repositório, não do disco local. Sugira ao usuário rodar, via prefixo `!`:
+
+   ```
+   !git add .github/config/tech_context.yml && git commit -m "chore: tech_context.yml [spec-wave]" && git push
+   ```