@spec-wave/cli 0.15.0 → 0.16.1

package/src/lib/implement-board.mjs

@@ -20,6 +20,7 @@ import {
  * @param {'start'|'success'} phase
  * @param {{ feature?: {nodeId:string,number:number}|null,
  *           story?:   {nodeId:string,number:number}|null,
+ *           bug?:     {nodeId:string,number:number}|null,
  *           tasks?:   Array<{nodeId?:string,number:number}> }} refs
  * @returns {Array<{nodeId:string, label:string, stage:string, status:string,
  *                  statusFallback:boolean}>}
@@ -28,7 +29,7 @@ import {
  *   (ex.: Feature já em Desenvolvimento volta a mostrar In Progress).
  */
 export function planBoardMoves(phase, {
-  feature = null, story = null, tasks = [],
+  feature = null, story = null, bug = null, tasks = [],
   // Status das Tasks na fase start: Todo quando enfileiradas atrás de uma
   // Story; In Progress quando a própria Task é o item sendo implementado.
   tasksStartStatus = PROGRESS_TODO,
@@ -43,6 +44,12 @@ export function planBoardMoves(phase, {
       moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`,
                    stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
     }
+    // Bug é folha e não tem Feature-pai a arrastar: um defeito em correção não
+    // deve puxar a Feature inteira de volta para Desenvolvimento.
+    if (bug?.nodeId) {
+      moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`,
+                   stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
+    }
     for (const t of tasks) {
       if (!t?.nodeId) continue;
       moves.push({ nodeId: t.nodeId, label: `Task #${t.number}`,
@@ -59,6 +66,10 @@ export function planBoardMoves(phase, {
       moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`,
                    stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
     }
+    if (bug?.nodeId) {
+      moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`,
+                   stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
+    }
   }
   return moves;
 }

package/src/lib/plugin-skills.mjs

@@ -0,0 +1,122 @@
+// Enumeração e renderização das skills do PLUGIN — uma skill por comando.
+//
+// Há duas famílias de skill neste pacote, e elas não se misturam:
+//
+//  • `src/plugin/skills/<nome>/model-prompt*.md` — textos que a CLI ENVIA a um
+//    modelo (ver `prompt-loader.mjs`). Moram DENTRO da skill do comando a que
+//    pertencem, mas não são instalados em agente nenhum: dizem o oposto do
+//    `SKILL.md` vizinho (um gera a spec.md, o outro proíbe gerá-la à mão).
+//  • `src/plugin/skills/<nome>/SKILL.md` — as skills que o USUÁRIO instala no
+//    agente de código dele. É o que este módulo enumera.
+//
+// O plugin existe porque o `templates/skill/SKILL.md` monolítico (~800 linhas)
+// entra inteiro no contexto para qualquer pergunta, mesmo trivial. Quebrado em
+// uma skill por comando, o agente carrega só a instrução do comando invocado —
+// e ganha um `/spec-wave:<comando>` por ação em vez de um sub-comando textual.
+//
+// O MESMO diretório serve os dois destinos, porque o formato SKILL.md é comum:
+//  • Claude Code → instalado como plugin (`.claude-plugin/plugin.json`), com as
+//    skills namespaced em `/spec-wave:<pasta>`;
+//  • Codex → copiado para `.agents/skills/<nome>/`, onde não há namespace — daí
+//    o `name:` do frontmatter ser `spec-wave-<comando>` e não só `<comando>`.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+
+/** Raiz do plugin empacotado (publicado via `"files": ["src"]`). */
+export const PLUGIN_DIR = path.join(__dir, '..', 'plugin');
+
+/** Diretório das skills dentro do plugin. */
+export const PLUGIN_SKILLS_DIR = path.join(PLUGIN_DIR, 'skills');
+
+// Arquivos que moram na skill mas NÃO são instalados no agente: os prompts que a
+// CLI envia a um modelo. Instalá-los entregaria ao agente de código a instrução
+// contrária à do SKILL.md ao lado — "gere a spec.md" vs. "nunca gere à mão".
+const INSTALL_EXCLUDE_RE = /(^|\/)model-prompt(\.[\w-]+)?\.md$/;
+
+/** True se o arquivo da skill deve ir para o agente (função PURA). */
+export function isInstallableSkillFile(relPath) {
+  return !INSTALL_EXCLUDE_RE.test(relPath);
+}
+
+// Lista os arquivos de um diretório recursivamente, em caminhos relativos a ele
+// e em ordem estável — a ordem entra na comparação de "está atualizado?", então
+// precisa ser determinística entre plataformas.
+function walk(dir, prefix = '') {
+  const out = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const abs = path.join(dir, entry);
+    const rel = prefix ? `${prefix}/${entry}` : entry;
+    if (statSync(abs).isDirectory()) out.push(...walk(abs, rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * Enumera as skills do plugin (função de I/O, mas sem efeitos colaterais).
+ *
+ * @param {string} [skillsDir]
+ * @returns {Array<{ name: string, dir: string, files: string[] }>}
+ *   `files` são caminhos relativos ao diretório da skill, incluindo o SKILL.md
+ *   e quaisquer arquivos de apoio (ex.: `reference/tech-context.md`).
+ */
+export function listPluginSkills(skillsDir = PLUGIN_SKILLS_DIR) {
+  if (!existsSync(skillsDir)) return [];
+  return readdirSync(skillsDir)
+    .sort()
+    .map((name) => ({ name, dir: path.join(skillsDir, name) }))
+    .filter((s) => statSync(s.dir).isDirectory() && existsSync(path.join(s.dir, 'SKILL.md')))
+    .map((s) => ({ ...s, files: walk(s.dir).filter(isInstallableSkillFile) }));
+}
+
+/**
+ * Conteúdo desejado de um arquivo de skill no destino (função PURA).
+ *
+ * Só o `SKILL.md` recebe o banner de versão — arquivos de apoio são copiados
+ * verbatim. O banner entra depois do frontmatter, no topo do corpo, que é onde
+ * o agente o lê ao carregar a skill.
+ *
+ * @param {string} relPath caminho relativo dentro da skill
+ * @param {string} raw conteúdo original
+ * @param {string} version versão da CLI
+ * @param {(v: string) => string} banner
+ * @returns {string}
+ */
+export function renderPluginSkillFile(relPath, raw, version, banner) {
+  if (relPath !== 'SKILL.md') return raw;
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return `${banner(version)}\n\n${raw.trim()}\n`;
+  return `---\n${match[1]}\n---\n\n${banner(version)}\n\n${match[2].trim()}\n`;
+}
+
+/**
+ * Plano de gravação de todas as skills do plugin num diretório de destino.
+ *
+ * Devolve pares `{ path, content }` já renderizados, sem tocar no disco — quem
+ * chama decide gravar, comparar (para detectar desatualização) ou só listar
+ * (`--dry-run`).
+ *
+ * @param {string} destDir ex.: `<repo>/.agents/skills`
+ * @param {string} version
+ * @param {(v: string) => string} banner
+ * @param {string} [skillsDir]
+ * @returns {Array<{ path: string, content: string, skill: string }>}
+ */
+export function planPluginSkillFiles(destDir, version, banner, skillsDir = PLUGIN_SKILLS_DIR) {
+  const out = [];
+  for (const skill of listPluginSkills(skillsDir)) {
+    for (const rel of skill.files) {
+      const raw = readFileSync(path.join(skill.dir, rel), 'utf-8');
+      out.push({
+        skill: skill.name,
+        path: path.join(destDir, skill.name, ...rel.split('/')),
+        content: renderPluginSkillFile(rel, raw, version, banner),
+      });
+    }
+  }
+  return out;
+}

package/src/lib/project-root.mjs

@@ -76,12 +76,19 @@ export function resolveFromRoot(root, ...parts) {
  *
  * Era o mesmo bloco copiado em story/task/order/qa/code-review/validate.
  *
+ * `env` é INJETÁVEL, e precisa ser: ler `process.env` aqui dentro tornava
+ * impossível testar o caminho local. Quem chamava com `env: {}` para simular
+ * "sem GITHUB_REPOSITORY" recebia o valor real assim mesmo — o teste passava na
+ * máquina do dev (onde a env não existe) e falhava no GitHub Actions (onde o
+ * runner a define).
+ *
  * @param {string} [cwd=process.cwd()]
+ * @param {object} [env=process.env] ambiente; injetável para teste
  * @returns {{ owner: string|undefined, repo: string|undefined,
  *             root: string|null, config: object|null, error: string|null }}
  */
-export function resolveRepoContext(cwd = process.cwd()) {
-  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+export function resolveRepoContext(cwd = process.cwd(), env = process.env) {
+  const [envOwner, envRepo] = (env.GITHUB_REPOSITORY || '').split('/');
   const { config, root, error } = loadConfig(cwd);
   return {
     owner: envOwner || config?.owner,

package/src/lib/prompt-loader.mjs

@@ -0,0 +1,257 @@
+// Carregador dos prompts de IA — a fonte dos textos que a CLI ENVIA a um modelo.
+//
+// Antes, cada ação carregava seu prompt como template string no próprio comando
+// (`generate-spec.mjs`, `generate-plan.mjs`, `decompose.mjs`, `critique.mjs`),
+// amarrando três coisas que mudam em ritmos diferentes: o texto do prompt, o
+// contrato de saída e o encanamento do GitHub.
+//
+// Hoje os prompts moram DENTRO da skill do comando a que pertencem, como
+// arquivo de apoio ao lado do `SKILL.md`:
+//
+//   src/plugin/skills/spec/SKILL.md                    ← o agente LÊ (dirige a CLI)
+//   src/plugin/skills/spec/model-prompt.md             ← a CLI ENVIA a um modelo
+//   src/plugin/skills/plan/model-prompt.critique.md    ← variante `plan/critique`
+//
+// Um diretório por comando, com as duas pontas do handoff lado a lado. Os dois
+// arquivos dizem coisas OPOSTAS de propósito — o `SKILL.md` de `spec` manda
+// nunca gerar a spec.md à mão, e o `model-prompt.md` é justamente quem a gera —
+// e é por isso que continuam sendo arquivos separados em vez de um só.
+//
+// Arquivo de apoio não entra sozinho no contexto de um agente: o Claude Code e o
+// Codex carregam o `SKILL.md`, e só leem o resto se a instrução mandar. Então o
+// `model-prompt.md` fica inerte para quem instala o plugin, e o `install-skill`
+// nem o copia (ver `plugin-skills.mjs`).
+//
+// Precedência: um `.spec-wave/prompts/<id>.md` versionado no repositório do
+// usuário vence o prompt empacotado. É assim que um time ajusta o tom de uma
+// spec, ou aperta o critério da crítica, sem fork da CLI.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSkill } from './skill-file.mjs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+
+/** Skills empacotadas — os prompts moram dentro delas. */
+export const BUNDLED_SKILLS_DIR = path.join(__dir, '..', 'plugin', 'skills');
+
+/** Override por projeto, relativo à raiz do repositório do usuário. */
+export const PROJECT_PROMPTS_DIR = path.join('.spec-wave', 'prompts');
+
+/** Prefixo dos arquivos de prompt dentro de uma skill. */
+export const MODEL_PROMPT_PREFIX = 'model-prompt';
+
+/**
+ * Resolve o id de um prompt no arquivo dentro da skill (função PURA).
+ *
+ * `spec`             → skills/spec/model-prompt.md
+ * `plan/critique`    → skills/plan/model-prompt.critique.md
+ * `decompose/feature`→ skills/decompose/model-prompt.feature.md
+ *
+ * @param {string} id
+ * @returns {{ skill: string, file: string }}
+ */
+export function resolvePromptId(id) {
+  const [skill, variant] = String(id).split('/');
+  if (!skill) throw new Error(`Id de prompt inválido: "${id}".`);
+  const file = variant
+    ? `${MODEL_PROMPT_PREFIX}.${variant}.md`
+    : `${MODEL_PROMPT_PREFIX}.md`;
+  return { skill, file };
+}
+
+// Somente leitura por padrão. Um prompt que precise escrever declara `tools`
+// explicitamente E recebe `allowedWritePaths` de quem o executa — o motor nega
+// qualquer Write fora dessa lista. Deixar Write no default transformaria um
+// prompt mal calibrado em escrita arbitrária no repo.
+export const DEFAULT_PROMPT_TOOLS = ['Read', 'Glob', 'Grep'];
+
+// Teto de turnos. Alto o bastante para explorar um repositório de verdade
+// (Glob → Grep → vários Read) antes de produzir o documento, e baixo o
+// bastante para um loop degenerado morrer em vez de queimar orçamento.
+export const DEFAULT_PROMPT_MAX_TURNS = 30;
+
+/**
+ * Caminhos candidatos de um prompt, em ordem de precedência (função PURA).
+ *
+ * @param {string} name nome do prompt (ex.: 'decompose-feature')
+ * @param {string} [cwd] raiz do repositório do usuário
+ * @returns {Array<{ source: 'project'|'bundled', path: string }>}
+ */
+export function promptCandidates(name, cwd = process.cwd()) {
+  const { skill, file } = resolvePromptId(name);
+  return [
+    // Override achatado: `.spec-wave/prompts/plan.critique.md`. Um caminho só,
+    // sem recriar a árvore de skills num repositório que não tem plugin nenhum.
+    { source: 'project', path: path.join(cwd, PROJECT_PROMPTS_DIR, `${String(name).replace('/', '.')}.md`) },
+    { source: 'bundled', path: path.join(BUNDLED_SKILLS_DIR, skill, file) },
+  ];
+}
+
+// Aceita inteiro positivo vindo de YAML (que pode entregar string ou lixo);
+// qualquer outra coisa cai no default em vez de virar NaN lá na frente.
+function positiveInt(value) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
+// Normaliza `tools`: aceita lista YAML ou string separada por vírgula.
+function normalizeTools(value) {
+  const raw = Array.isArray(value)
+    ? value
+    : typeof value === 'string'
+      ? value.split(',')
+      : null;
+  if (!raw) return undefined;
+  const tools = raw.map(t => String(t).trim()).filter(Boolean);
+  return tools.length > 0 ? tools : undefined;
+}
+
+/**
+ * Valida e normaliza um prompt já lido do disco (função PURA — testável sem fs).
+ *
+ * Um corpo vazio é erro, não default: um prompt sem instrução produziria uma
+ * chamada de modelo sem propósito, e o custo só apareceria depois.
+ *
+ * @param {object} params
+ * @param {string} params.name
+ * @param {object} [params.meta] frontmatter já parseado
+ * @param {string} [params.body] corpo markdown (a instrução)
+ * @param {'project'|'bundled'} [params.source]
+ * @param {string} [params.path]
+ * @returns {{ name: string, action: string|null, prompt: string, tools: string[],
+ *            maxTurns: number, json: { shape: string, retries: number }|null,
+ *            source: string, path: string, meta: object }}
+ */
+export function normalizePrompt({ name, meta = {}, body = '', source = 'bundled', path: filePath = '' } = {}) {
+  const prompt = (body || '').trim();
+  if (!prompt) {
+    throw new Error(
+      `Prompt "${name}" está sem corpo (${filePath || 'origem desconhecida'}). ` +
+      'O corpo do model-prompt é a instrução enviada ao modelo — sem ele não há o que executar.'
+    );
+  }
+
+  // `json.shape` é o contrato de saída mostrado ao modelo verbatim; quando
+  // presente, quem executa exige JSON parseável e re-pede em caso de falha.
+  let json = null;
+  if (meta.json && typeof meta.json === 'object') {
+    const shape = typeof meta.json.shape === 'string' ? meta.json.shape.trim() : '';
+    if (!shape) {
+      throw new Error(
+        `Prompt "${name}" declara \`json\` sem \`shape\` (${filePath}). ` +
+        'Informe o formato esperado ou remova o bloco `json`.'
+      );
+    }
+    json = { shape, retries: positiveInt(meta.json.retries) ?? 1 };
+  }
+
+  return {
+    name,
+    action: typeof meta.action === 'string' ? meta.action : null,
+    prompt,
+    tools: normalizeTools(meta.tools) ?? [...DEFAULT_PROMPT_TOOLS],
+    maxTurns: positiveInt(meta.maxTurns) ?? DEFAULT_PROMPT_MAX_TURNS,
+    json,
+    source,
+    path: filePath,
+    meta,
+  };
+}
+
+/**
+ * Encontra e carrega um prompt, respeitando o override do projeto.
+ *
+ * @param {string} name
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @returns {ReturnType<typeof normalizePrompt>}
+ */
+export function loadPrompt(name, { cwd = process.cwd() } = {}) {
+  const candidates = promptCandidates(name, cwd);
+  const found = candidates.find(c => existsSync(c.path));
+  if (!found) {
+    throw new Error(
+      `Prompt "${name}" não encontrado. Procurei em:\n` +
+      candidates.map(c => `  - ${c.path} (${c.source})`).join('\n')
+    );
+  }
+  const { meta, body } = parseSkill(readFileSync(found.path, 'utf-8'));
+  return normalizePrompt({ name, meta, body, source: found.source, path: found.path });
+}
+
+// Delimitadores da orientação que só faz sentido com ferramentas de leitura.
+const REQUIRES_TOOLS_RE = /<!--\s*requires-tools\s*-->[\s\S]*?<!--\s*\/requires-tools\s*-->\n?/g;
+
+/**
+ * Texto de sistema para um runtime SEM ferramentas (função PURA).
+ *
+ * `generateDocument`/`generateStructured` fazem UMA chamada de completions: não
+ * há loop de tool use, então o modelo não tem `Read`/`Glob`/`Grep` por mais que
+ * o frontmatter os declare. Um prompt que afirme possuir ferramentas nesse
+ * runtime mente para o modelo — e o resultado típico é uma seção inventada
+ * "conforme verifiquei no repositório".
+ *
+ * Por isso o corpo marca a orientação dependente de ferramentas entre
+ * `<!-- requires-tools -->` e `<!-- /requires-tools -->`, e este recorte a
+ * remove. O mesmo arquivo serve os dois runtimes sem manter duas versões.
+ *
+ * @param {ReturnType<typeof normalizePrompt>} prompt
+ * @param {string} [appendInstruction] regra que a CLI precisa garantir; vem por
+ *   ÚLTIMO de propósito — um prompt sobrescrito pelo projeto não pode anulá-la
+ * @returns {string}
+ */
+export function toolFreeSystemPrompt(prompt, appendInstruction = '') {
+  const stripped = prompt.prompt
+    .replace(REQUIRES_TOOLS_RE, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+  return [stripped, (appendInstruction || '').trim()].filter(Boolean).join('\n\n');
+}
+
+/**
+ * Converte um prompt em `AgentRunOptions` do `@spec-wave/agent` (função PURA).
+ *
+ * O corpo vira `systemPromptAppend` — no backend anthropic ele é anexado ao
+ * preset `claude_code`, preservando a competência de uso de tools do harness em
+ * vez de substituí-la. Aqui o bloco `requires-tools` é PRESERVADO: esse runtime
+ * de fato entrega as ferramentas.
+ *
+ * @param {ReturnType<typeof normalizePrompt>} prompt
+ * @param {object} run
+ * @param {string} run.model
+ * @param {string} run.sessionId
+ * @param {string} run.userId
+ * @param {boolean} [run.verbose]
+ * @param {string[]} [run.allowedWritePaths] quando presente, Write só é
+ *   permitido nestes caminhos (e `Write` entra na tool surface)
+ * @param {string} [run.appendInstruction] instrução controlada pela CLI,
+ *   anexada DEPOIS do corpo do prompt (ex.: o caminho exato do arquivo de saída)
+ * @param {string[]} [run.extraTags] tags extras da trace
+ * @returns {object} AgentRunOptions
+ */
+export function buildPromptRunOptions(prompt, run) {
+  const tools = run.allowedWritePaths?.length && !prompt.tools.includes('Write')
+    ? [...prompt.tools, 'Write']
+    : [...prompt.tools];
+
+  const systemPromptAppend = [prompt.prompt, run.appendInstruction]
+    .map(part => (part || '').trim())
+    .filter(Boolean)
+    .join('\n\n');
+
+  return {
+    model: run.model,
+    sessionId: run.sessionId,
+    userId: run.userId,
+    ...(run.verbose === undefined ? {} : { verbose: run.verbose }),
+    tools,
+    systemPromptAppend,
+    maxTurns: prompt.maxTurns,
+    ...(run.allowedWritePaths?.length
+      ? { allowedWritePaths: [...run.allowedWritePaths] }
+      : {}),
+    extraTags: ['spec-wave', prompt.name, ...(run.extraTags ?? [])],
+  };
+}

package/src/lib/skill-file.mjs

@@ -0,0 +1,35 @@
+// Formato de arquivo das skills: frontmatter YAML + corpo markdown.
+//
+// Duas famílias de skill usam o MESMO formato e por isso o mesmo parser:
+//  • a skill de orquestração (`src/templates/skill/SKILL.md`), instalada nos
+//    agentes de código pelo `install-skill`;
+//  • os prompts de IA (`src/plugin/skills/<nome>/model-prompt*.md`), que a CLI
+//    envia a um modelo — ver `prompt-loader.mjs`.
+//
+// Vivia dentro de `commands/install-skill.mjs`; foi movido para cá quando o
+// loader passou a precisar dele, para não haver duas implementações do mesmo
+// recorte de frontmatter.
+
+import yaml from 'js-yaml';
+
+/**
+ * Separa o frontmatter YAML do corpo do markdown (função PURA — testável).
+ *
+ * Tolerante por contrato: arquivo sem frontmatter devolve `meta` vazio e o
+ * texto inteiro como corpo; YAML inválido devolve `meta` vazio em vez de
+ * lançar. Quem precisa de um campo obrigatório valida depois.
+ *
+ * @param {string} raw conteúdo do arquivo
+ * @returns {{ meta: object, frontmatter: string, body: string }}
+ */
+export function parseSkill(raw) {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, frontmatter: '', body: raw.trim() };
+  let meta = {};
+  try {
+    meta = yaml.load(match[1]) || {};
+  } catch {
+    meta = {};
+  }
+  return { meta, frontmatter: match[1], body: match[2].trim() };
+}

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

@@ -0,0 +1,20 @@
+{
+  "name": "spec-wave",
+  "displayName": "Spec Wave",
+  "version": "0.16.1",
+  "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`).