@spec-wave/cli 0.5.7 → 0.5.8

package/README.md

@@ -0,0 +1,390 @@
+# @spec-wave/cli
+
+CLI e skill para implementar um fluxo **spec-driven** completo no GitHub — do backlog ao deploy — com GitHub Projects v2, labels de gatilho e GitHub Actions com IA.
+
+---
+
+## Conceito
+
+Spec Wave é um sistema de processo de desenvolvimento baseado em especificações. Cada Feature passa por um ciclo documentado antes de ser implementada:
+
+1. **Spec funcional** gerada por IA a partir do título e descrição da issue
+2. **Plano técnico** gerado por IA a partir da spec e do contexto tecnológico do repositório
+3. **Validação automática** das seções obrigatórias
+4. **Decomposição em Stories e Tasks** gerada por IA
+5. **Automação do board** durante o ciclo de desenvolvimento (Code Review → QA → Done)
+
+O resultado é um board Kanban no GitHub Projects v2 que avança automaticamente conforme o trabalho progride, com toda a documentação versionada no próprio repositório.
+
+---
+
+## Fluxo Kanban
+
+```
+📥 Backlog
+  → 🎯 Priorizado
+  → 📋 Spec          ← label spec-wave:spec → Action gera spec.md
+  → 📋 Plan          ← label spec-wave:plan → Action gera plan.md
+  → ✅ Ready         ← label spec-wave:ready → Action valida ambos
+  → 📋 Backlog Técnico
+  → 🚧 Desenvolvimento ← comando local: spec-wave implement <n>
+  → 👀 Code Review   ← PR aberto → Action move automaticamente
+  → 🧪 QA            ← PR aprovado → Action move automaticamente
+  → 📋 Homologação
+  → 🚀 Deploy
+  → 🎉 Done
+```
+
+---
+
+## Hierarquia de Work Items
+
+```
+Initiative
+  └── Epic
+        └── Feature
+              ├── Story
+              │     └── Task
+              └── Task
+```
+
+Cada nível é uma GitHub Issue com prefixo no título (`[FEATURE]`, `[STORY]`, etc.) e vínculo de sub-issue nativo do GitHub.
+
+---
+
+## Componentes
+
+### CLI (`@spec-wave/cli`)
+
+Ferramenta Node.js que configura e opera o fluxo via linha de comando.
+
+| Comando | O que faz |
+|---------|-----------|
+| `init` | Cria o GitHub Project, labels, workflows e `.spec-wave.json` |
+| `info` | Mostra o estado de configuração do repositório atual |
+| `refresh` | Re-sincroniza o `.spec-wave.json` com o GitHub Project |
+| `issue` | Cria qualquer work item (initiative/epic/feature/story/task/bug/spike/rfc) |
+| `initiative` | Atalho para `issue --type initiative` |
+| `feature` | Atalho para `issue --type feature` |
+| `generate-spec` | Gera `spec.md` (usado pelo GitHub Action) |
+| `generate-plan` | Gera `plan.md` (usado pelo GitHub Action) |
+| `validate` | Valida spec.md e plan.md (usado pelo GitHub Action) |
+| `decompose` | Decompõe Feature em Stories e Tasks (usado pelo GitHub Action) |
+| `code-review` | Move Feature para Code Review ao abrir PR (usado pelo GitHub Action) |
+| `qa` | Move Feature para QA ao aprovar PR (usado pelo GitHub Action) |
+| `implement` | Aciona o spec-kit localmente para implementar uma Story ou Task |
+| `uninstall` | Remove labels, workflows e `.spec-wave.json` |
+
+### GitHub Actions (instalados pelo `init`)
+
+| Workflow | Gatilho | Ação |
+|----------|---------|------|
+| `generate-spec.yml` | label `spec-wave:spec` | Gera `docs/features/<slug>/spec.md` via IA |
+| `generate-plan.yml` | label `spec-wave:plan` | Gera `docs/features/<slug>/plan.md` via IA |
+| `validate.yml` | label `spec-wave:ready` | Valida seções obrigatórias; adiciona `spec-wave:plan-approved` |
+| `decompose.yml` | label `spec-wave:decompose` | Cria Stories e Tasks como sub-issues |
+| `code-review.yml` | PR aberto/reaberto | Move Feature para `👀 Code Review` |
+| `qa.yml` | PR aprovado | Move Feature para `🧪 QA` |
+
+### Skill (`src/templates/skill/SKILL.md`)
+
+Skill que guia o usuário pelo fluxo via comandos como `/spec-wave spec 42`, `/spec-wave plan 42`, `/spec-wave decompose 42`. A skill lê o `.spec-wave.json` local, detecta o estado atual e executa os comandos corretos sem abrir wizards interativos. Instale-a no seu agente com `install-skill` (ver abaixo).
+
+### `.spec-wave.json`
+
+Arquivo de configuração gerado pelo `init` na raiz do repositório. Armazena `owner/repo`, dados do GitHub Project (ID, URL, campos) e o provider de IA configurado. Todos os comandos leem este arquivo para operar sem precisar de flags adicionais.
+
+### `tech_context.yml`
+
+Arquivo em `.github/config/tech_context.yml` que descreve a stack tecnológica do sistema (backend, frontend, banco, infra, roles RBAC, schemas, serviços). O `generate-plan` usa este arquivo para embasar o plano técnico — sem ele, o plano fica genérico.
+
+---
+
+## Pré-requisitos
+
+- Node.js >= 20
+- GitHub CLI (`gh`) autenticado com escopos `project`, `repo` e `workflow`:
+  ```bash
+  gh auth refresh --scopes project,repo,workflow
+  ```
+- Secret no repositório: `ANTHROPIC_API_KEY` ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
+- Para repositórios em organizações: criar PAT com escopo `project` e adicionar como secret `GH_PROJECT_TOKEN`
+
+---
+
+## Instalação da CLI
+
+Não é necessário instalar globalmente — use `npx`:
+
+```bash
+npx @spec-wave/cli --help
+```
+
+Para instalar globalmente:
+
+```bash
+npm install -g @spec-wave/cli
+spec-wave --help
+```
+
+---
+
+## Instalação da Skill
+
+A skill permite usar o fluxo diretamente no seu agente via `/spec-wave`.
+
+**1. Instale a skill com o comando `install-skill`:**
+
+```bash
+# Autodetecta o agente em uso e instala no local/formato correto
+npx @spec-wave/cli install-skill
+```
+
+O comando suporta Claude Code, Cursor, opencode, Cline, Kilo Code, Antigravity e o
+padrão genérico `AGENTS.md`. Por padrão instala no escopo do projeto (versionável
+com o time); use `--global` para o escopo do usuário. Escolha alvos com
+`--agent <nomes>` (ex.: `--agent claude,cursor`) ou `--all` para todos os
+detectados. Use `--dry-run` para pré-visualizar sem gravar.
+
+**2. Adicione ao `CLAUDE.md` (ou equivalente) do projeto:**
+
+```markdown
+# spec-wave skill
+Trigger `/spec-wave` to invoke the spec-wave skill.
+```
+
+**3. Use no seu agente:**
+
+```
+/spec-wave setup
+/spec-wave spec 42
+/spec-wave plan 42
+/spec-wave ready 42
+/spec-wave decompose 42
+/spec-wave implement 45
+```
+
+---
+
+## Exemplo de uso — do início ao fim
+
+### Contexto
+
+Equipe quer implementar uma feature de "Checkout com PIX" em um repositório `acme/loja`.
+
+---
+
+### 1. Configurar o repositório
+
+```bash
+# Verificar autenticação
+gh auth status
+
+# Se faltarem escopos:
+gh auth refresh --scopes project,repo,workflow
+
+# Configurar spec-wave (cria Project, labels e workflows)
+npx @spec-wave/cli init --repo acme/loja --project-title "Loja — Spec Wave"
+```
+
+O `init` cria:
+- GitHub Project v2 com 12 colunas Kanban e campos personalizados (Work Item Type, Priority, Story Points, Area)
+- 20+ labels de tipo, prioridade e gatilho
+- 6 GitHub Actions workflows em `.github/workflows/`
+- `.spec-wave.json` com os IDs do Project
+
+Adicionar o secret de IA no GitHub: **Settings → Secrets → Actions → `ANTHROPIC_API_KEY`**.
+
+---
+
+### 2. Criar a hierarquia de issues
+
+```bash
+# Criar Epic
+npx @spec-wave/cli issue \
+  --type epic \
+  --title "Checkout e Pagamentos" \
+  --priority P1 \
+  --area Backend
+# → Issue #5 criada: [EPIC] Checkout e Pagamentos
+
+# Criar Feature como sub-issue do Epic
+npx @spec-wave/cli feature \
+  --title "Checkout com PIX" \
+  --parent 5 \
+  --priority P1 \
+  --area Backend
+# → Issue #12 criada: [FEATURE] Checkout com PIX (sub-issue de #5)
+# → Adicionada ao board em 📥 Backlog
+```
+
+---
+
+### 3. Gerar a especificação funcional
+
+```bash
+gh issue edit 12 --add-label "spec-wave:spec"
+```
+
+O GitHub Action `generate-spec.yml` dispara, chama a IA e faz commit de:
+```
+docs/features/checkout-com-pix/spec.md
+```
+
+A issue #12 recebe um comentário com o link para o arquivo.
+
+---
+
+### 4. Gerar o plano técnico
+
+Antes de gerar o plano, garanta que `.github/config/tech_context.yml` existe e reflete a stack real. O `init` cria um scaffold — edite-o:
+
+```yaml
+system_info:
+  name: "Loja ACME"
+  stack:
+    backend: "Node.js (NestJS v11)"
+    frontend: "Next.js 16"
+    database: "PostgreSQL (Prisma 5)"
+    infra: "Docker / AWS ECS"
+security:
+  auth_protocol: "JWT"
+  rbac_roles: ["ADMIN", "CUSTOMER"]
+database_schemas:
+  - table: "orders"
+    columns: "id, customer_id, status, total, created_at"
+```
+
+```bash
+git add .github/config/tech_context.yml
+git commit -m "chore: tech_context.yml"
+git push
+
+# Acionar geração do plano
+gh issue edit 12 --add-label "spec-wave:plan"
+```
+
+O Action gera `docs/features/checkout-com-pix/plan.md` com:
+- Estratégia Técnica e Matriz de Rastreabilidade
+- Detalhamento da Implementação
+- Segurança e Conformidade
+- Estratégia de Testes
+- Rollback e Monitoramento
+
+---
+
+### 5. Validar spec e plan
+
+```bash
+gh issue edit 12 --add-label "spec-wave:ready"
+```
+
+O Action `validate.yml` verifica se todas as seções obrigatórias estão presentes em spec.md e plan.md. Se passar:
+- Remove a label `spec-wave:ready`
+- Adiciona a label `spec-wave:plan-approved`
+- Comenta "Validação aprovada ✅" na issue
+
+---
+
+### 6. Decompor em Stories e Tasks
+
+```bash
+gh issue edit 12 --add-label "spec-wave:decompose"
+```
+
+O Action `decompose.yml` usa IA para criar sub-issues da Feature #12:
+
+```
+#13 [STORY] Como cliente, quero selecionar PIX como forma de pagamento
+  #14 [TASK] Criar endpoint POST /orders/:id/payment/pix
+  #15 [TASK] Integrar API do banco via webhook
+  #16 [TASK] Exibir QR Code na tela de checkout
+#17 [STORY] Como cliente, quero receber confirmação do pagamento
+  #18 [TASK] Webhook de confirmação do banco
+  #19 [TASK] Notificação por e-mail ao confirmar
+```
+
+Todas as Stories e Tasks são adicionadas ao board em **📋 Backlog Técnico** com Status `Todo`.
+
+---
+
+### 7. Implementar
+
+```bash
+# Via skill no Claude Code:
+/spec-wave implement 13
+
+# Ou direto:
+npx @spec-wave/cli implement 13 --dry-run   # ver contexto antes
+npx @spec-wave/cli implement 13             # executar
+```
+
+O comando monta um arquivo de contexto com spec.md, plan.md e todas as Tasks da Story, e aciona o spec-kit configurado.
+
+---
+
+### 8. Code Review automático
+
+Ao abrir um PR que referencia `Closes #14` (ou qualquer issue da hierarquia):
+
+```markdown
+## Descrição
+Implementa endpoint PIX
+
+Closes #14
+```
+
+O Action `code-review.yml` detecta a referência, sobe a hierarquia Task → Story → Feature, e move a Feature #12 para **👀 Code Review** no board.
+
+---
+
+### 9. QA automático
+
+Quando um reviewer aprova o PR, o Action `qa.yml` move a Feature #12 para **🧪 QA**.
+
+---
+
+### 10. Estado final no board
+
+```
+Feature #12: [FEATURE] Checkout com PIX
+  Etapa: 🧪 QA
+  Status: Todo
+  Work Item Type: Feature
+  Priority: P1
+  Area: Backend
+```
+
+Após QA passar, mover manualmente para **📋 Homologação → 🚀 Deploy → 🎉 Done**.
+
+---
+
+## Atualizar repositórios existentes
+
+Quando uma nova versão da CLI for publicada, rode em cada repositório configurado:
+
+```bash
+npx @spec-wave/cli@latest init --skip-project --skip-labels
+```
+
+Isso atualiza apenas os arquivos de workflow sem recriar o Project ou as labels.
+
+---
+
+## Providers de IA
+
+| Provider | Secret | Modelo padrão |
+|----------|--------|---------------|
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
+| OpenRouter | `OPENROUTER_API_KEY` | `anthropic/claude-3.7-sonnet` |
+
+Configurar no `init`:
+```bash
+npx @spec-wave/cli init --repo owner/repo --provider openrouter --model anthropic/claude-3.7-sonnet
+```
+
+---
+
+## Licença
+
+MIT

package/bin/spec-wave.mjs

@@ -86,6 +86,20 @@ program
     await feature(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('install-skill')
+  .description('Instala a skill spec-wave no(s) agente(s) detectado(s): Claude Code, Cursor, opencode, Cline, Kilo, Antigravity, AGENTS.md')
+  .option('--agent <names>', 'Agente(s) alvo, separados por vírgula (pula a detecção)')
+  .option('--all', 'Instala em todos os agentes detectados')
+  .option('--global', 'Instala no escopo do usuário (padrão: projeto)')
+  .option('--dry-run', 'Mostra o que seria instalado sem gravar')
+  .option('--force', 'Sobrescreve arquivos existentes sem confirmar')
+  .option('--yes', 'Modo não-interativo')
+  .action(async (options) => {
+    const { installSkill } = await import('../src/commands/install-skill.mjs');
+    await installSkill(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('uninstall')
   .description('Remove labels, arquivos .github e o .spec-wave.json (mantém o GitHub Project)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -218,6 +218,6 @@ export async function init(options) {
     `  2. Configure o board view para agrupar por "Etapa"\n` +
     `  3. Crie uma Feature com o prefixo [FEATURE] no título\n` +
     `  4. Use a skill spec-wave para guiar o fluxo\n\n` +
-    `  ${chalk.dim('Para usar a skill: adicione skill/SKILL.md ao seu projeto Claude Code')}`
+    `  ${chalk.dim('Para instalar a skill no seu agente: npx @spec-wave/cli install-skill')}`
   );
 }

package/src/commands/install-skill.mjs

@@ -0,0 +1,292 @@
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import yaml from 'js-yaml';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+// Fonte única da skill, publicada via "files": ["src"] no package.json.
+const SKILL_SOURCE = path.join(__dir, '..', 'templates', 'skill', 'SKILL.md');
+
+// Marcadores usados para gravar/atualizar a skill de forma idempotente em
+// arquivos compartilhados (AGENTS.md) — permite reinstalar sem duplicar.
+const BLOCK_START = '<!-- spec-wave:start -->';
+const BLOCK_END = '<!-- spec-wave:end -->';
+
+// Registro de agentes suportados. Cada alvo descreve como detectá-lo no
+// diretório-base, onde gravar (projeto vs. global) e em que formato converter
+// o SKILL.md. Caminhos conferidos na doc oficial de cada ferramenta.
+const TARGETS = [
+  {
+    key: 'claude',
+    name: 'Claude Code',
+    format: 'skill',
+    detect: ['.claude'],
+    project: '.claude/skills/spec-wave/SKILL.md',
+    global: '.claude/skills/spec-wave/SKILL.md',
+  },
+  {
+    key: 'opencode',
+    name: 'opencode',
+    format: 'skill',
+    detect: ['.opencode'],
+    project: '.opencode/skills/spec-wave/SKILL.md',
+    global: '.config/opencode/skills/spec-wave/SKILL.md',
+  },
+  {
+    key: 'cursor',
+    name: 'Cursor',
+    format: 'mdc',
+    detect: ['.cursor'],
+    project: '.cursor/rules/spec-wave.mdc',
+    global: null, // Cursor user rules não são baseadas em arquivo.
+  },
+  {
+    key: 'cline',
+    name: 'Cline',
+    format: 'rules',
+    detect: ['.clinerules'],
+    project: '.clinerules/spec-wave.md',
+    global: null,
+  },
+  {
+    key: 'kilo',
+    name: 'Kilo Code',
+    format: 'rules',
+    detect: ['.kilocode'],
+    project: '.kilocode/rules/spec-wave.md',
+    global: '.kilocode/rules/spec-wave.md',
+  },
+  {
+    key: 'antigravity',
+    name: 'Antigravity',
+    format: 'rules',
+    detect: ['.agent', 'GEMINI.md'],
+    project: '.agent/rules/spec-wave.md',
+    global: '.gemini/AGENTS.md',
+    globalFormat: 'agents', // ~/.gemini/AGENTS.md é compartilhado → append.
+  },
+  {
+    key: 'agents',
+    name: 'AGENTS.md (genérico)',
+    format: 'agents',
+    detect: ['AGENTS.md'],
+    project: 'AGENTS.md',
+    global: '.config/opencode/AGENTS.md',
+  },
+];
+
+const TARGET_BY_KEY = new Map(TARGETS.map((t) => [t.key, t]));
+
+// Separa o frontmatter YAML do corpo do SKILL.md. Retorna { meta, body }.
+function parseSkill(raw) {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: raw.trim() };
+  let meta = {};
+  try {
+    meta = yaml.load(match[1]) || {};
+  } catch {
+    meta = {};
+  }
+  return { meta, body: match[2].trim() };
+}
+
+// Converte o SKILL.md para o formato exigido por cada agente.
+function renderContent(format, raw, parsed) {
+  const { meta, body } = parsed;
+  const description = meta.description ?? 'Skill spec-wave.';
+  switch (format) {
+    case 'skill':
+      // Claude Code / opencode consomem o SKILL.md nativo. Campos extras do
+      // frontmatter são ignorados pelo opencode — sem problema.
+      return raw.trimEnd() + '\n';
+    case 'mdc':
+      return (
+        `---\n` +
+        `description: ${JSON.stringify(description)}\n` +
+        `alwaysApply: false\n` +
+        `---\n\n` +
+        `${body}\n`
+      );
+    case 'rules':
+      return `# spec-wave\n\n${description}\n\n${body}\n`;
+    case 'agents':
+      return `${BLOCK_START}\n\n# spec-wave\n\n${description}\n\n${body}\n\n${BLOCK_END}\n`;
+    default:
+      return raw;
+  }
+}
+
+// Insere/atualiza o bloco spec-wave num arquivo compartilhado (AGENTS.md),
+// preservando o restante do conteúdo. Idempotente via marcadores.
+function mergeAgentsFile(destPath, block) {
+  const existing = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
+  const blockRe = new RegExp(
+    `${escapeRe(BLOCK_START)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`,
+  );
+  if (blockRe.test(existing)) {
+    return existing.replace(blockRe, block);
+  }
+  if (existing.trim() === '') return block;
+  return `${existing.trimEnd()}\n\n${block}`;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Resolve o alvo do agente para um destino concreto no escopo escolhido.
+// Retorna null quando o agente não suporta o escopo global.
+function resolveDest(target, baseDir, isGlobal) {
+  const rel = isGlobal ? target.global : target.project;
+  if (!rel) return null;
+  const format = isGlobal && target.globalFormat ? target.globalFormat : target.format;
+  return { path: path.join(baseDir, rel), format };
+}
+
+// Retorna true se algum dos sinais de detecção existir em baseDir.
+function isDetected(target, baseDir) {
+  return target.detect.some((sig) => existsSync(path.join(baseDir, sig)));
+}
+
+export async function installSkill(options = {}) {
+  p.intro(chalk.bold('spec-wave install-skill'));
+
+  if (!existsSync(SKILL_SOURCE)) {
+    p.log.error(`SKILL.md não encontrado no pacote (${SKILL_SOURCE}).`);
+    process.exitCode = 1;
+    return;
+  }
+  const raw = readFileSync(SKILL_SOURCE, 'utf-8');
+  const parsed = parseSkill(raw);
+
+  const isGlobal = !!options.global;
+  const baseDir = isGlobal ? homedir() : process.cwd();
+  const scopeLabel = isGlobal ? 'global (usuário)' : 'projeto (local)';
+
+  // 1) Determinar quais agentes receberão a skill.
+  let selectedKeys;
+  if (options.agent) {
+    const requested = String(options.agent)
+      .split(',')
+      .map((s) => s.trim().toLowerCase())
+      .filter(Boolean);
+    const invalid = requested.filter((k) => !TARGET_BY_KEY.has(k));
+    if (invalid.length) {
+      p.log.error(
+        `Agente(s) inválido(s): ${invalid.join(', ')}.\n` +
+          `Válidos: ${TARGETS.map((t) => t.key).join(', ')}.`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    selectedKeys = requested;
+  } else {
+    const detected = TARGETS.filter((t) => isDetected(t, baseDir)).map((t) => t.key);
+
+    if (options.all) {
+      if (!detected.length) {
+        p.log.error(
+          `Nenhum agente detectado em ${scopeLabel}. Use --agent <nome> para escolher manualmente.`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      selectedKeys = detected;
+    } else if (options.yes) {
+      if (!detected.length) {
+        p.log.error(
+          `Nenhum agente detectado em ${scopeLabel}. Use --agent <nome> em modo não-interativo.`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      selectedKeys = detected;
+    } else {
+      const answer = await p.multiselect({
+        message: `Onde instalar a skill? (escopo: ${scopeLabel})`,
+        options: TARGETS.map((t) => ({
+          value: t.key,
+          label: t.name,
+          hint: isDetected(t, baseDir) ? 'detectado' : undefined,
+        })),
+        initialValues: detected,
+        required: true,
+      });
+      if (p.isCancel(answer)) {
+        p.cancel('Instalação cancelada.');
+        return;
+      }
+      selectedKeys = answer;
+    }
+  }
+
+  // 2) Resolver destinos, avisando sobre escopos não suportados.
+  const jobs = [];
+  for (const key of selectedKeys) {
+    const target = TARGET_BY_KEY.get(key);
+    const dest = resolveDest(target, baseDir, isGlobal);
+    if (!dest) {
+      p.log.warn(`${target.name}: escopo global não suportado — pulado.`);
+      continue;
+    }
+    jobs.push({ target, dest });
+  }
+
+  if (!jobs.length) {
+    p.log.warn('Nenhum destino a instalar.');
+    p.outro('Nada foi feito.');
+    return;
+  }
+
+  // 3) Dry-run: apenas listar.
+  if (options.dryRun) {
+    p.note(
+      jobs
+        .map((j) => `${chalk.dim(j.target.name.padEnd(20))} ${j.dest.path}  ${chalk.dim(`(${j.dest.format})`)}`)
+        .join('\n'),
+      `Dry-run — nada será gravado (escopo: ${scopeLabel})`,
+    );
+    p.outro('Dry-run concluído.');
+    return;
+  }
+
+  // 4) Gravar cada destino.
+  const written = [];
+  for (const { target, dest } of jobs) {
+    const content =
+      dest.format === 'agents'
+        ? mergeAgentsFile(dest.path, renderContent('agents', raw, parsed))
+        : renderContent(dest.format, raw, parsed);
+
+    // Confirmar sobrescrita de arquivos "próprios" (skill/rules/mdc). Para
+    // 'agents' o merge por marcadores já é seguro (não apaga conteúdo alheio).
+    if (existsSync(dest.path) && dest.format !== 'agents' && !options.force && !options.yes) {
+      const ok = await p.confirm({
+        message: `${target.name}: ${dest.path} já existe. Sobrescrever?`,
+        initialValue: true,
+      });
+      if (p.isCancel(ok) || !ok) {
+        p.log.info(`${target.name}: mantido (não sobrescrito).`);
+        continue;
+      }
+    }
+
+    mkdirSync(path.dirname(dest.path), { recursive: true });
+    writeFileSync(dest.path, content, 'utf-8');
+    written.push({ target, dest });
+  }
+
+  if (!written.length) {
+    p.outro('Nada foi gravado.');
+    return;
+  }
+
+  p.note(
+    written.map((w) => `${chalk.green('✓')} ${chalk.bold(w.target.name)}\n  ${chalk.dim(w.dest.path)}`).join('\n'),
+    `Skill instalada (escopo: ${scopeLabel})`,
+  );
+  p.outro('Reinicie/recarregue o agente para que ele detecte a skill.');
+}

package/src/templates/skill/SKILL.md

@@ -0,0 +1,517 @@
+---
+name: spec-wave
+description: "Use when the user wants to set up a spec-driven GitHub workflow, create a Feature issue, generate spec.md or plan.md, decompose a Feature into Stories/Tasks, write RFC documentation, or audit and fix a Pull Request. Implements the RFC-001 workflow with GitHub Projects v2, labels, and AI-powered GitHub Actions."
+argument-hint: "[info|setup|issue|feature|spec|plan|ready|decompose|implement|uninstall|rfc|fix-pr] [target]"
+user-invocable: true
+allowed-tools:
+  - Bash(npx spec-wave *)
+  - Bash(gh issue *)
+  - Bash(gh project *)
+  - Bash(gh repo view *)
+  - Bash(gh auth status)
+  - Bash(gh pr *)
+  - Bash(gh api *)
+  - Bash(git add *)
+  - Bash(git commit *)
+  - Bash(git push *)
+  - Bash(git checkout *)
+  - Read
+  - Edit
+  - Write
+  - Agent
+---
+
+# spec-wave Skill
+
+Este skill guia o usuário pelo fluxo spec-driven definido no RFC-001.
+
+> **Antes de responder a qualquer sub-comando**, leia o arquivo `rfc/rfc-integrate-spec-kit-into-kanban.md` se ele existir no diretório atual, para embasar suas respostas no processo real da equipe.
+
+---
+
+## Detecção de configuração (faça isto primeiro, sempre)
+
+Antes de qualquer sub-comando, leia o arquivo `.spec-wave.json` na raiz do repositório atual (use o tool Read). Esse arquivo é gravado pelo `npx spec-wave init` e é a fonte de estado persistente entre sessões.
+
+- **Se existir**, o spec-wave já foi configurado. Use seus campos para contextualizar as respostas, sem perguntar de novo:
+  - `owner`/`repo` → repositório alvo dos comandos `gh`
+  - `project.url` / `project.title` → o GitHub Project a referenciar
+  - `version` → versão da CLI usada no `init` (compare com `npx spec-wave --version`; se divergir, sugira `npx spec-wave refresh --config` para atualizar o arquivo, ou re-rodar o `init` para atualizar workflows/labels)
+  - `initializedAt` → quando foi configurado
+  Não rode `/spec-wave setup` de novo a menos que o usuário peça explicitamente.
+- **Se não existir**, o repositório provavelmente ainda não foi configurado. Sugira começar por `/spec-wave setup`.
+
+Exemplo de `.spec-wave.json`:
+```json
+{
+  "version": "0.1.0",
+  "owner": "acme",
+  "repo": "loja",
+  "project": {
+    "title": "loja — Spec Wave",
+    "url": "https://github.com/users/acme/projects/5",
+    "id": "PVT_..."
+  },
+  "initializedAt": "2026-06-18T13:40:00.000Z"
+}
+```
+
+---
+
+## Regra fundamental
+
+**Nunca gere `spec.md` ou `plan.md` diretamente.** Sempre acione a label correspondente e deixe o GitHub Action gerar o arquivo. Isso garante que o arquivo seja commitado no repositório e 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.
+
+---
+
+## Fluxo Kanban
+
+```
+📥 Backlog → 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready
+→ 📋 Backlog Técnico → 🚧 Desenvolvimento → 👀 Code Review
+→ 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done
+```
+
+Labels de gatilho:
+- `spec-wave:spec` → dispara `generate-spec.yml` → gera `spec.md` (especificação funcional, primeiro)
+- `spec-wave:plan` → dispara `generate-plan.yml` → gera `plan.md` (plano técnico, a partir da spec)
+- `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
+- `spec-wave:decompose` → dispara `decompose.yml` → gera Stories e Tasks
+
+A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `spec-wave implement <número>` (não é uma label/Action): lê uma Story ou Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
+
+---
+
+## Referência da CLI (conheça os parâmetros ANTES de executar)
+
+Esta skill é um **wrapper** da CLI `spec-wave`. Regra de ouro: **nunca rode um comando sem os parâmetros que ele aceita** esperando que ele pergunte — colete os valores com o usuário e passe via flags. Em especial, **`init` sem `--repo` abre um wizard interativo (@clack/prompts) que a skill NÃO consegue dirigir** — sempre passe `--repo`.
+
+### `spec-wave init` — configura o repositório
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--repo <owner/repo>` | string | Repositório alvo. **Passe SEMPRE** para evitar o wizard interativo. |
+| `--project-title <title>` | string | Nome do GitHub Project. Padrão: `<repo> — Spec Wave`. |
+| `--skip-project` | flag | Pula a criação do Project (use ao re-rodar se já existe). |
+| `--skip-labels` | flag | Pula a criação das labels. |
+| `--skip-files` | flag | Pula a criação dos workflows + issue templates. |
+| `--dry-run` | flag | Simula a configuração sem alterar nada. |
+
+### `spec-wave issue` — cria um work item tipado, opcionalmente como sub-issue, e adiciona ao board
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--title <title>` | string (obrigatório) | Título, **sem** o prefixo de tipo (a CLI adiciona, ex.: `[STORY]`). |
+| `--type <type>` | string | `initiative`, `epic`, `feature`, `story`, `task`, `bug`, `spike` ou `rfc`. Default: `feature`. |
+| `--parent <n>` | string | Número da issue pai — cria como **sub-issue** dela (relação nativa do GitHub). |
+| `--body <text>` | string | Descrição. |
+| `--priority <p>` | string | `P0`, `P1`, `P2` ou `P3`. |
+| `--area <area>` | string | `Frontend`, `Backend`, `Mobile`, `Infra`, `DevOps` ou `Data`. |
+
+> Faz tudo: cria a issue (label de tipo + prioridade), vincula ao parent como sub-issue, adiciona ao Project e define os campos **Etapa = 📥 Backlog**, **Work Item Type**, **Priority** e **Area**. Grava `Parent: #N` no corpo. Lê o Project do `.spec-wave.json`. **Não use `gh issue create` direto** — ele não adiciona ao board nem vincula o parent.
+
+### `spec-wave initiative` — atalho de `issue --type initiative`
+Cria o nó raiz da hierarquia (agrupa Epics). Mesmas flags do `issue` exceto `--type` (fixo em `initiative`) e `--parent` (Initiative é raiz, não tem pai).
+
+### `spec-wave feature` — atalho de `issue --type feature`
+Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o fluxo do RFC-001.
+
+### `spec-wave uninstall` — remove a configuração (mantém o Project)
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--repo <owner/repo>` | string | Repositório (default: lê do `.spec-wave.json`). |
+| `--skip-labels` | flag | Não remove as labels. |
+| `--skip-files` | flag | Não remove os arquivos `.github`. |
+| `--keep-config` | flag | Mantém o `.spec-wave.json` local. |
+| `--dry-run` | flag | Mostra o que seria removido sem alterar nada. |
+| `--yes` | flag | Não pede confirmação. |
+
+> Remove labels + arquivos `.github` + `.spec-wave.json`. **NUNCA apaga o GitHub Project** (preserva o histórico do board) — o usuário deve excluí-lo manualmente se quiser.
+
+### `spec-wave info` — status de configuração do repo atual
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--json` | flag | Saída JSON (`{"initialized":bool, ...}`) para parsing programático. |
+
+### `spec-wave refresh` — atualiza o `.spec-wave.json` local
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--config` | flag | Re-consulta o GitHub Project e reescreve o `.spec-wave.json` (IDs do campo Etapa, opções, number, versão da CLI). |
+
+> Use quando o `.spec-wave.json` estiver desatualizado: repos inicializados por uma versão antiga (sem `etapaFieldId`/`stageOptions`), Project renomeado, ou versão da CLI divergente. Escreve no arquivo **local** — faça commit depois.
+
+### `spec-wave generate-plan` · `generate-spec` · `validate` · `decompose`
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
+
+> ⚠️ Esses quatro comandos são executados pelos **GitHub Actions** (disparados por labels), **não** pela skill diretamente. Veja a *Regra fundamental*: para gerar plan/spec/decompor, adicione a **label** correspondente — não rode o comando à mão (a não ser para debug local).
+
+### `spec-wave implement` — aciona o spec-kit para uma Story ou Task (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<issue>` | string (obrigatório) | Número da issue (Story ou Task), ex.: `12` ou `#12`. Argumento posicional. |
+| `--feature-dir <path>` | string | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` como contexto (sobrescreve a resolução automática). |
+| `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar**. |
+
+> Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto já inclui uma instrução para o agente mover a Story e as Tasks para **🚧 Desenvolvimento** (in progress) ao iniciar.
+
+---
+
+## Sub-comandos
+
+### `/spec-wave info`
+
+Mostra se o repositório atual já foi configurado com o spec-wave.
+
+**Passos:**
+1. Execute: `npx spec-wave info`
+2. **Se o repositório estiver inicializado**, o comando mostra os dados do `.spec-wave.json` (owner/repo, project, versão da CLI, data). Apresente essas informações ao usuário.
+3. **Se NÃO estiver inicializado**, pergunte ao usuário: "Este repositório ainda não foi configurado com o spec-wave. Quer rodar o `init` agora?"
+   - Se sim → siga o fluxo de `/spec-wave setup`.
+   - Se não → encerre sem alterar nada.
+
+---
+
+### `/spec-wave setup`
+
+Configura o spec-wave no repositório. Você dirige o `init` com flags — **nunca rode `npx spec-wave init` sem `--repo`** (abre o wizard interativo que você não controla).
+
+**Passos:**
+1. **Já configurado?** Leia `.spec-wave.json` (ou rode `npx spec-wave info`). Se existir, avise (mostre `project.url` e `version`) e confirme com o usuário antes de reconfigurar.
+2. **Descubra o repositório alvo** (parâmetro `--repo`): rode `gh repo view --json nameWithOwner -q .nameWithOwner` para obter `owner/repo` do repo atual. Confirme com o usuário; se não houver remote, pergunte o `owner/repo`.
+3. **Pergunte o título do Project** (parâmetro `--project-title`). Ofereça o default `<repo> — Spec Wave` e aceite-o se o usuário não tiver preferência.
+4. **Cheque o auth:** `gh auth status`. Se faltarem os escopos `project,repo,workflow`, oriente o usuário a rodar ele mesmo `gh auth refresh --scopes project,repo,workflow` (comando interativo — o usuário executa, não você).
+5. **(Opcional) Pré-visualize** antes de aplicar: `npx spec-wave init --repo <owner/repo> --dry-run`.
+6. **Execute com os parâmetros coletados:**
+   ```bash
+   npx spec-wave init --repo <owner/repo> --project-title "<título>"
+   ```
+   Use `--skip-project` / `--skip-labels` / `--skip-files` **apenas** para re-rodar uma fase específica que falhou antes.
+7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
+8. **Adapte o `tech_context.yml`**: o scaffold vem com dados de exemplo. Ofereça ajustá-lo à stack real do repo seguindo a seção **Tech Context** (perto do comando `/spec-wave plan`) — isso melhora muito a qualidade do `plan.md`.
+9. Instrua o usuário a adicionar a chave de IA como secret no repositório (Settings → Secrets → Actions): `ANTHROPIC_API_KEY` (Anthropic) ou `OPENROUTER_API_KEY` (OpenRouter), conforme o provider escolhido no `init`.
+
+---
+
+### `/spec-wave issue <tipo> <descrição>` · `/spec-wave initiative <descrição>` · `/spec-wave feature <descrição>`
+
+Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado ao board em **📥 Backlog**, opcionalmente como sub-issue de um parent.
+
+**Hierarquia típica:** Initiative → Epic → Feature → Story → Task. A **Initiative** é o nó raiz e agrupa Epics. Use `--parent <n>` para criar como sub-issue do nível acima (ex.: um Epic filho de uma Initiative, ou uma Story filha de uma Feature). O GitHub mostra o parent na issue filha e vice-versa; a CLI ainda grava `Parent: #N` no corpo.
+
+**Passos:**
+1. Pergunte ao usuário: tipo (initiative/epic/feature/story/task/...), título (sem prefixo), descrição, área, prioridade, e se há uma issue **pai** (número).
+2. Execute o comando com os parâmetros coletados:
+   ```bash
+   npx spec-wave issue \
+     --type "<tipo>" \
+     --title "<título>" \
+     --body "<descrição>" \
+     --area "<área>" \
+     --priority "<prioridade>" \
+     --parent "<número-do-pai>"   # opcional
+   ```
+   Para Features, pode usar o atalho `npx spec-wave feature --title ...` (equivale a `--type feature`).
+   A CLI cria a issue (label de tipo + prioridade), vincula como sub-issue do parent, adiciona ao Project e define Etapa = 📥 Backlog + Work Item Type + Priority + Area. **Não use `gh issue create`** (não adiciona ao board nem vincula o parent).
+3. Informe o número criado e o vínculo com o pai (se houver).
+4. Para Features: "Quando quiser iniciar, mova para **📋 Spec** e use `/spec-wave spec <número>` para gerar a especificação funcional (o plano técnico vem depois)".
+
+---
+
+### `/spec-wave uninstall`
+
+Remove a configuração do spec-wave do repositório (labels, arquivos `.github`, `.spec-wave.json`). **Não apaga o GitHub Project.**
+
+**Passos:**
+1. Confirme com o usuário que ele quer remover (a ação remove labels e faz commits removendo os workflows).
+2. Mostre antes o que será removido com `npx spec-wave uninstall --dry-run`.
+3. Execute `npx spec-wave uninstall` (a CLI pede confirmação; use `--yes` só se o usuário já confirmou).
+4. Lembre o usuário de excluir o **GitHub Project** manualmente, se desejar — a CLI não o apaga de propósito.
+
+---
+
+### `/spec-wave spec <número-da-issue>`
+
+Inicia a geração da **especificação funcional** para uma Feature. É o **primeiro** passo do ciclo de documentos (antes do plano técnico).
+
+**Passos:**
+1. Adicione a label de gatilho:
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:spec"
+   ```
+2. Informe: "Label `spec-wave:spec` adicionada. O GitHub Action `generate-spec.yml` irá gerar o `spec.md` automaticamente."
+3. Após a conclusão, ofereça revisar o spec.md gerado em `docs/features/<slug>/spec.md`.
+4. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
+
+---
+
+### `/spec-wave plan <número-da-issue>`
+
+Inicia a geração do **plano técnico** para uma Feature, derivado da especificação. É o **segundo** passo (a spec deve existir antes).
+
+O plano técnico 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. Para desvios pontuais, adicione uma seção `## Tech Override` no corpo da issue (RFC-002 §4.3).
+
+**Passos:**
+1. Verifique se `spec.md` já existe em `docs/features/<slug>/` (o plano usa a especificação funcional como contexto). Se não existir, gere a spec primeiro com `/spec-wave spec <número>`.
+2. **Garanta o `tech_context`** (a qualidade do plano depende disso). Verifique se `.github/config/tech_context.yml` existe no repo (use Read). **Se não existir, ajude a criar AGORA** seguindo a seção **Tech Context** abaixo (logo após este comando) — e garanta que esteja **commitado e pushado** antes de adicionar 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 GitHub Action `generate-plan.yml` irá gerar o `plan.md` automaticamente. Acompanhe em: Actions → Generate Plan."
+5. Após a conclusão (cheque comentários na issue ou aguarde confirmação do usuário), ofereça revisar o plan.md gerado em `docs/features/<slug>/plan.md`.
+6. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
+
+---
+
+### 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/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx spec-wave 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 (quando não existir):**
+
+1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, apenas 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):
+   - `package.json` → backend/frontend e libs (ex.: `@nestjs/core`, `next`, `react`, `@prisma/client`, `express`).
+   - `pom.xml` / `build.gradle` (Java), `requirements.txt` / `pyproject.toml` (Python), `go.mod` (Go).
+   - `prisma/schema.prisma` ou pasta `migrations/` → tabelas e colunas para `database_schemas`.
+   - `Dockerfile` / `docker-compose.yml` / charts Helm → `infra`.
+   - Procure papéis/roles (enum de RBAC) no código para `security.rbac_roles`.
+3. **Rascunhe** o YAML seguindo EXATAMENTE este schema (preencha só o que conseguir confirmar; deixe `# TODO` no que faltar — não invente):
+   ```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 repo). Sugira ao usuário rodar, via prefixo `!`:
+   ```bash
+   !git add .github/config/tech_context.yml && git commit -m "chore: tech_context.yml [spec-wave]" && git push
+   ```
+
+**Desvios pontuais:** para uma Feature específica usar algo fora do padrão (ex.: "usar DynamoDB só aqui"), oriente a adicionar uma seção `## Tech Override` no corpo da issue, com um bloco YAML que será mesclado (deep-merge) sobre o `tech_context.yml`:
+
+````markdown
+## Tech Override
+```yaml
+system_info:
+  stack:
+    database: "DynamoDB"
+```
+````
+
+---
+
+### `/spec-wave ready <número-da-issue>`
+
+Valida que spec.md e plan.md estão completos e a Feature pode avançar.
+
+**Passos:**
+1. Adicione a label de validação:
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:ready"
+   ```
+2. Informe: "Validação iniciada. O workflow verificará se spec.md e plan.md contêm todas as seções obrigatórias."
+3. Se a validação falhar, o workflow comentará os problemas na issue e adicionará automaticamente `spec-wave:spec`. Informe o usuário para corrigir e tentar novamente.
+4. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e depois para **📋 Backlog Técnico** para iniciar a decomposição."
+
+---
+
+### `/spec-wave decompose <número-da-issue>`
+
+Decompõe uma Feature em Stories e Tasks automaticamente.
+
+**Passos:**
+1. Confirme que a Feature está em **✅ Ready** (spec.md e plan.md validados)
+2. Adicione a label de decomposição:
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:decompose"
+   ```
+3. Informe: "Decomposição iniciada. O workflow gerará Stories e Tasks baseados em spec.md e plan.md."
+4. Após a conclusão, as issues filhas aparecerão como comentário na Feature pai.
+
+---
+
+### `/spec-wave implement <número-da-issue>`
+
+Aciona o spec-kit para implementar uma **Story** (todas as suas Tasks) ou uma **Task** isolada. Comando **local** (etapa 🚧 Desenvolvimento) — não usa label/Action.
+
+**Pré-requisitos:** o repositório atual precisa estar inicializado (`.spec-wave.json` presente) e a issue deve ser do tipo Story ou Task. Para executar de fato (fora do `--dry-run`), o spec-kit precisa estar configurado via `specKit.command` no `.spec-wave.json` ou a env `SPEC_WAVE_IMPLEMENT_CMD`.
+
+**Passos:**
+1. Confirme que há `.spec-wave.json` no repo (senão, oriente `/spec-wave setup`).
+2. **Sempre comece com `--dry-run`** para inspecionar o que será feito — detecção do tipo, lista de Tasks coletadas (no caso de Story) e o comando do spec-kit que seria executado:
+   ```bash
+   npx spec-wave implement <número> --dry-run
+   ```
+3. Mostre ao usuário o contexto montado em `.spec-wave/implement-<número>.md` e o comando.
+4. Se o usuário aprovar e o spec-kit estiver configurado, rode sem `--dry-run`:
+   ```bash
+   npx spec-wave implement <número>
+   ```
+   - Se o spec-kit **não** estiver configurado, o comando só monta o contexto e mostra como configurar (`specKit.command` / `SPEC_WAVE_IMPLEMENT_CMD`). Ajude o usuário a definir o template (placeholders: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`).
+   - Use `--feature-dir docs/features/<slug>` se a resolução automática da Feature falhar (a skill avisa com warning) e você quiser anexar `spec.md`/`plan.md` como contexto.
+5. Se a issue **não** for Story nem Task (ex.: Feature, Bug), o comando recusa — oriente o usuário: Features se decompõem (`/spec-wave decompose`); implemente as Stories/Tasks resultantes.
+6. Após implementar: oriente revisar as mudanças, abrir o PR e mover o card para **👀 Code Review**.
+
+---
+
+### `/spec-wave rfc <tópico>`
+
+Crie um documento RFC seguindo a estrutura do RFC-001.
+
+**Passos:**
+1. Entreviste o usuário sobre: objetivo, problema atual, solução proposta, princípios, stakeholders afetados
+2. Escreva o RFC em português com as seções:
+   - 1. Objetivo
+   - 2. Princípios
+   - 3. Papéis e Responsabilidades
+   - 4. Estrutura de Trabalho
+   - 5. Fluxo de Trabalho
+   - 6. Automação
+   - 7. Métricas
+   - 8. Riscos e Mitigações
+3. Salve em `rfc/rfc-<slug-do-tópico>.md` usando o Write tool
+4. Crie uma issue de RFC:
+   ```bash
+   gh issue create --title "[RFC] <título>" --label "[RFC]"
+   ```
+
+---
+
+### `/spec-wave fix-pr <número-do-pr>`
+
+Audita um Pull Request e corrige automaticamente os problemas encontrados — segurança, arquitetura, infraestrutura e qualidade de código. 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.
+   - Colete todos os review comments (inline) e reviews gerais.
+
+3. **Fazer checkout no branch do PR**
+   ```bash
+   gh pr checkout <número>
+   ```
+
+4. **Varredura de problemas** — para cada categoria abaixo, 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 o agente `caveman:cavecrew-reviewer` para detecção automatizada:
+   ```
+   Agent(caveman:cavecrew-reviewer) → diff do PR + arquivos alterados
+   ```
+
+5. **Para cada problema encontrado:**
+   a. Leia o(s) arquivo(s) afetado(s) com Read
+   b. Aplique o fix com Edit
+   c. Faça commit separado:
+      ```bash
+      git add <arquivo>
+      git commit -m "fix: <problema> (issue #<N>)
+
+      <causa raiz>
+
+      Solution: <descrição do fix>"
+      ```
+   d. Push ao branch do PR:
+      ```bash
+      git push
+      ```
+
+6. **Responder aos review comments** — para cada comment inline do PR:
+   ```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. **Comentário de sumário no PR**
+   ```bash
+   gh pr comment <número> --body "<sumário>"
+   ```
+   Formato do sumário:
+   ```
+   ## 🔍 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).
+   ```
+
+**Output esperado:**
+- Lista de issues (severidade + impacto)
+- Lista de commits criados (hash + mensagem)
+- Confirmação de replies postadas nos review comments
+- Estado final do PR
+
+**Severidade:**
+- 🔴 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
+
+---
+
+## Estrutura de arquivos gerados
+
+```
+docs/
+  features/
+    <slug-da-feature>/
+      spec.md    ← gerado pelo GitHub Action quando spec-wave:spec é adicionado (1º)
+      plan.md    ← gerado pelo GitHub Action quando spec-wave:plan é adicionado (2º, usa a spec)
+```
+
+O slug é gerado a partir do título da issue: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`