@spec-wave/cli 0.15.0 → 0.16.1

package/src/commands/generate-plan.mjs

@@ -1,6 +1,5 @@
-import { execSync } from 'node:child_process';
 import path from 'node:path';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import {
   getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
@@ -16,8 +15,10 @@ import {
 } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { loadConfig, resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 
 // Aviso anexado ao comentário quando o lint de idioma ainda reprova após o
 // retry automático do generateDocument (excertos ao redor de cada vazamento).
@@ -30,25 +31,9 @@ function formatLintWarning(lintFindings) {
   return `\n\n⚠️ possíveis artefatos de idioma no documento: ${excerpts}`;
 }
 
-const SYSTEM_PROMPT = `Você é um Tech Lead experiente. Gere um plano técnico (plan.md) completo e detalhado, baseado ESTRITAMENTE no spec.md fornecido.
-
-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.
-- Responda APENAS com o conteúdo do plan.md, sem texto adicional.`;
+// O prompt vive em `src/plugin/skills/plan/model-prompt.md` (sobrescrevível pelo
+// projeto em `.spec-wave/prompts/plan.md`). `toolFreeSystemPrompt` remove a orientação que
+// assume Read/Glob/Grep: aqui a geração é UMA chamada, sem tool loop.
 
 /**
  * Roda a crítica do plan e aplica as labels de bloqueio.
@@ -124,16 +109,9 @@ async function critiquePlan({
 
 export async function generatePlan({ issueNumber }) {
   const token = await resolveToken();
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const { config, root } = loadConfig();
-
-  if (!owner || !repo) {
-    throw new Error(
-      'GITHUB_REPOSITORY env var não definida.\n' +
-      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
-      '  GITHUB_REPOSITORY=owner/repo spec-wave generate-plan --issue-number 1'
-    );
-  }
+  // Roda nos dois modos: no Action (disparado por label) e na sessão local.
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-plan' });
+  console.log(`Modo de execução: ${mode}`);
 
   console.log(`Buscando issue #${issueNumber}...`);
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
@@ -186,7 +164,8 @@ export async function generatePlan({ issueNumber }) {
   const usageEntries = [];
   try {
     console.log(`Gerando plan.md para: ${issue.title}`);
-    const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
+    const systemPrompt = toolFreeSystemPrompt(loadPrompt('plan', { cwd: root }));
+    const { content, lintFindings } = await generateDocument(systemPrompt, userContent, {
       action: 'plan',
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
@@ -194,17 +173,13 @@ export async function generatePlan({ issueNumber }) {
       usage: usageEntries,
     });
 
-    mkdirSync(featureDir, { recursive: true });
-    writeFileSync(filePath, content, 'utf-8');
-
-    // Commit and push
-    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-    git(`git config user.email "spec-wave[bot]@github.com"`);
-    git(`git config user.name "spec-wave[bot]"`);
-    git(`git add "${filePath}"`);
-    git(`git commit -m "docs: generate plan.md for ${slug} [spec-wave]"`);
-    git('git pull --rebase');
-    git('git push');
+    const published = commitGenerated({
+      filePath,
+      content,
+      message: `docs: generate plan.md for ${slug} [spec-wave]`,
+      mode,
+    });
+    if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
     // Remove trigger label
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan');

package/src/commands/generate-spec.mjs

@@ -1,12 +1,12 @@
-import { execSync } from 'node:child_process';
 import path from 'node:path';
-import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { loadConfig, resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
   allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE, labelNames,
@@ -23,40 +23,15 @@ function formatLintWarning(lintFindings) {
   return `\n\n⚠️ possíveis artefatos de idioma no documento: ${excerpts}`;
 }
 
-const SYSTEM_PROMPT = `Você é um Product Manager experiente. Gere uma especificação funcional (spec.md) completa para a Feature descrita pelo usuário.
-
-O spec deve conter EXATAMENTE estas seções em português, nesta ordem:
-# Visão Geral
-  - Objetivo, Personas e Critérios de Sucesso como bullets.
-# Regras de Negócio
-# Fluxos
-  - Subseções: ## Fluxo Principal (Happy Path), ## Fluxos Alternativos, ## Cenários de Erro.
-  - O Fluxo Principal DEVE conter, além da descrição passo a passo, um diagrama de sequência Mermaid (bloco \`\`\`mermaid iniciado com sequenceDiagram) mostrando a interação entre as personas (actor) e o sistema (participant). Rotule mensagens e notas em português.
-  - Cubra os Fluxos Alternativos e Cenários de Erro relevantes no mesmo diagrama usando blocos alt/opt/break — ou, se ficarem complexos, em um segundo diagrama na subseção correspondente.
-# Critérios de Aceite
-  - OBRIGATORIAMENTE no formato Gherkin, dentro de um bloco \`\`\`gherkin com Given/When/Then. Um cenário por critério.
-# Dependências
-  - Subdivida em Internas e Externas.
-# Requisitos Não-Funcionais
-  - Performance, Segurança e Usabilidade.
-
-Regras:
-- NÃO invente regras de negócio. Se faltar informação, marque explicitamente com "[TODO: requer esclarecimento do PO]".
-- Seja específico e detalhado em cada seção.
-- Responda APENAS com o conteúdo do spec.md, sem texto adicional.`;
+// O prompt vive em `src/plugin/skills/spec/model-prompt.md` (sobrescrevível pelo
+// projeto em `.spec-wave/prompts/spec.md`). `toolFreeSystemPrompt` remove a orientação que assume
+// Read/Glob/Grep: aqui a geração é UMA chamada de completions, sem tool loop.
 
 export async function generateSpec({ issueNumber }) {
   const token = await resolveToken();
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const { root } = loadConfig();
-
-  if (!owner || !repo) {
-    throw new Error(
-      'GITHUB_REPOSITORY env var não definida.\n' +
-      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
-      '  GITHUB_REPOSITORY=owner/repo spec-wave generate-spec --issue-number 1'
-    );
-  }
+  // Roda nos dois modos: no Action (disparado por label) e na sessão local.
+  const { owner, repo, root, mode } = resolveFlowContext({ command: 'generate-spec' });
+  console.log(`Modo de execução: ${mode}`);
 
   console.log(`Buscando issue #${issueNumber}...`);
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
@@ -103,7 +78,8 @@ export async function generateSpec({ issueNumber }) {
   const usageEntries = [];
   try {
     console.log(`Gerando spec.md para: ${issue.title}`);
-    const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
+    const systemPrompt = toolFreeSystemPrompt(loadPrompt('spec', { cwd: root }));
+    const { content, lintFindings } = await generateDocument(systemPrompt, userContent, {
       action: 'spec',
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
@@ -111,17 +87,13 @@ export async function generateSpec({ issueNumber }) {
       usage: usageEntries,
     });
 
-    mkdirSync(featureDir, { recursive: true });
-    writeFileSync(filePath, content, 'utf-8');
-
-    // Commit and push
-    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-    git(`git config user.email "spec-wave[bot]@github.com"`);
-    git(`git config user.name "spec-wave[bot]"`);
-    git(`git add "${filePath}"`);
-    git(`git commit -m "docs: generate spec.md for ${slug} [spec-wave]"`);
-    git('git pull --rebase');
-    git('git push');
+    const published = commitGenerated({
+      filePath,
+      content,
+      message: `docs: generate spec.md for ${slug} [spec-wave]`,
+      mode,
+    });
+    if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
     // Remove trigger label
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');

package/src/commands/implement.mjs

@@ -6,11 +6,13 @@ import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import {
   CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE, STAGE_ORDER,
-  PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
+  PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE, labelNames,
 } from '../config.mjs';
 import { getIssue, listIssueComments, listBlockedBy } from '../api/github-rest.mjs';
 import { listSubIssues, getIssueParent, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
+import { bugDocPaths } from '../lib/bug-doc.mjs';
+import { buildBugContext } from '../lib/bug-context.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
 import { loadProjectConfig, resolveField } from '../lib/board.mjs';
@@ -360,6 +362,102 @@ function renderCommand(template, vars) {
 // Modo Feature: avalia as Stories da Feature (dependências + Etapa no board),
 // pula as já implementadas (Code Review+) e monta UM contexto único com todas
 // as pendentes em ordem topológica — spec-kit acionado uma vez.
+/**
+ * Modo Bug (RFC-004 §7.1): sem tasks, sem spec/plan, sem Feature-pai a arrastar.
+ *
+ * O bug.md, quando existe, entra como HIPÓTESE — foi escrito por IA sem
+ * executar código, e o contexto diz isso explicitamente ao executor. Quando não
+ * existe (o caso do P0, que dispensa o documento), o contexto assume a
+ * investigação inteira.
+ */
+async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot }) {
+  const issueNumber = bug.number;
+  const severity = (labelNames(bug).find(n => /^P[0-3]$/.test(n))) || null;
+
+  // Item afetado (best-effort): dá ao executor o contexto do que quebrou. O pai
+  // de um Bug pode ser Feature OU Story — o tipo vem do prefixo do título.
+  let parent = null;
+  try {
+    const p0 = await getIssueParent(token, bug.node_id);
+    if (p0?.number) {
+      parent = { number: p0.number, title: p0.title, kind: detectIssueType(p0) || 'Item' };
+    }
+  } catch {
+    // sem pai legível — bug órfão é caso previsto (reporte de suporte)
+  }
+
+  // bug.md do repositório, se já foi gerado.
+  const { fileAbs, fileRel } = bugDocPaths(bug.title, repoRoot);
+  let bugDoc = null;
+  if (existsSync(fileAbs)) {
+    bugDoc = readFileSync(fileAbs, 'utf-8');
+    p.log.info(`bug.md encontrado em ${chalk.cyan(fileRel)}.`);
+  } else {
+    p.log.warn(`Sem bug.md em ${fileRel} — o contexto assume a investigação inteira.`);
+  }
+
+  // Board: Bug → Desenvolvimento (In Progress). Não move a Feature-pai.
+  await applyBoardMoves({
+    token,
+    moves: planBoardMoves('start', { bug: { nodeId: bug.node_id, number: issueNumber } }),
+    cwd: repoRoot || process.cwd(),
+    dryRun,
+  });
+
+  const comments = [];
+  const all = await listIssueComments(token, owner, repo, issueNumber).catch(() => []);
+  if (all.length > 0) {
+    const items = all.slice(-MAX_COMMENTS_PER_ISSUE).map(c => ({
+      ...c,
+      body: c.body.length > MAX_COMMENT_CHARS
+        ? `${c.body.slice(0, MAX_COMMENT_CHARS)}…[truncado]`
+        : c.body,
+    }));
+    comments.push({ issueNumber, kind: 'Bug', total: all.length, items });
+  }
+
+  let codeDigest = null;
+  try {
+    codeDigest = await buildCodeDigest({ sinceIso: bug.created_at || null, paths: [] });
+  } catch {
+    codeDigest = null;
+  }
+
+  const blockedByWarnings = [];
+  try {
+    const blocked = await listBlockedBy(token, owner, repo, issueNumber).catch(() => []);
+    for (const b of blocked) {
+      if (b?.state !== 'closed') blockedByWarnings.push(`#${b.number} — ${b.title}`);
+    }
+  } catch {
+    // dependências não legíveis — segue
+  }
+
+  const context = buildBugContext({
+    bug: { number: issueNumber, title: bug.title, body: bug.body || '' },
+    bugDoc, parent, comments, codeDigest, blockedByWarnings, severity,
+  });
+
+  await writeContextAndRunSpecKit({
+    config,
+    issueNumber,
+    type: 'Bug',
+    title: bug.title,
+    specPlan: { spec: null, plan: null, specPath: null, planPath: null },
+    context,
+    dryRun,
+    outroSuccess: `Bug #${issueNumber} corrigido — abra o PR com \`Fixes #${issueNumber}\`.`,
+    onSuccess: async () => {
+      await applyBoardMoves({
+        token,
+        moves: planBoardMoves('success', { bug: { nodeId: bug.node_id, number: issueNumber } }),
+        cwd: repoRoot || process.cwd(),
+        dryRun,
+      });
+    },
+  });
+}
+
 async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot }) {
   // F1. Stories (sub-issues) da Feature.
   const subs = await listSubIssues(token, feature.node_id).catch(() => []);
@@ -630,9 +728,14 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     // Modo Feature: Stories pendentes em ordem de dependência, contexto único.
     await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun, repoRoot });
     return;
+  } else if (type === 'Bug') {
+    // Modo Bug: sem tasks e sem spec/plan — o trabalho é investigar antes de
+    // corrigir, e o contexto impõe essa ordem.
+    await implementBug({ token, owner, repo, config, bug: issue, dryRun, repoRoot });
+    return;
   } else {
     p.log.error(
-      `implement só aceita Feature, Story ou Task. Issue #${issueNumber} é do tipo ${type || 'desconhecido'}.`
+      `implement aceita Feature, Story, Task ou Bug. Issue #${issueNumber} é do tipo ${type || 'desconhecido'}.`
     );
     process.exitCode = 1;
     return;

package/src/commands/init.mjs

@@ -9,7 +9,7 @@ import { setupProject } from '../setup/project.mjs';
 import { setupLabels } from '../setup/labels.mjs';
 import { setupFiles } from '../setup/files.mjs';
 import { getFileContent } from '../api/github-rest.mjs';
-import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES } from '../config.mjs';
+import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, STATUS_OPTIONS, ALL_LABELS } from '../config.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
@@ -143,7 +143,7 @@ export async function init(options) {
     labelSpinner.start('Criando labels...');
     try {
       await setupLabels(token, owner, repo, labelSpinner);
-      labelSpinner.stop('Labels criadas (16 labels)');
+      labelSpinner.stop(`Labels criadas (${ALL_LABELS.length} labels)`);
     } catch (err) {
       labelSpinner.stop('');
       p.log.error(`Erro ao criar labels: ${err.message}`);
@@ -204,7 +204,7 @@ export async function init(options) {
   }
 
   p.note(
-    'As 12 colunas do RFC-001 foram criadas no campo "Etapa".\n' +
+    `As ${STATUS_OPTIONS.length} colunas do RFC-001 foram criadas no campo "Etapa".\n` +
     'Para usá-las como colunas do board:\n' +
     '  1. Abra o projeto no GitHub\n' +
     '  2. Clique em "..." → "Settings" da view de Board\n' +

package/src/commands/install-skill.mjs

@@ -1,10 +1,11 @@
 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';
+import { parseSkill } from '../lib/skill-file.mjs';
+import { listPluginSkills, planPluginSkillFiles } from '../lib/plugin-skills.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 // Fonte única da skill, publicada via "files": ["src"] no package.json.
@@ -33,6 +34,17 @@ export const TARGETS = [
     project: '.claude/skills/spec-wave/SKILL.md',
     global: '.claude/skills/spec-wave/SKILL.md',
   },
+  {
+    key: 'codex',
+    name: 'Codex CLI',
+    // Codex não tem conceito de plugin: ele varre diretórios de skills. Então o
+    // MESMO conteúdo do plugin é copiado skill a skill para `.agents/skills`,
+    // que é o caminho que o Codex lê no repo (e `~/.agents/skills` no usuário).
+    format: 'skills-dir',
+    detect: ['.codex', '.agents'],
+    project: path.join('.agents', 'skills'),
+    global: path.join('.agents', 'skills'),
+  },
   {
     key: 'opencode',
     name: 'opencode',
@@ -86,22 +98,14 @@ export const TARGETS = [
 
 const TARGET_BY_KEY = new Map(TARGETS.map((t) => [t.key, t]));
 
-// Separa o frontmatter YAML do corpo do SKILL.md. Retorna { meta, body }.
-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() };
-}
+// Separa o frontmatter YAML do corpo do SKILL.md. Implementação em
+// `lib/skill-file.mjs` (compartilhada com o loader das skills de IA);
+// re-exportada aqui porque `update.mjs` e os testes a importam deste módulo.
+export { parseSkill };
 
 // Banner de versão inserido no topo do corpo da skill instalada. O agente lê
 // esta linha e, se `npx @spec-wave/cli@latest --version` for maior, orienta reinstalar.
-function versionBanner(version) {
+export function versionBanner(version) {
   return (
     `> ⚙️ **spec-wave skill v${version}** — esta skill é uma cópia estática. ` +
     'Se `npx @spec-wave/cli@latest --version` indicar uma versão maior, ela está ' +
@@ -182,6 +186,20 @@ export function isDetected(target, baseDir) {
 // 'ausente' | 'bloco ausente' | 'desatualizada' — ou null se está em dia com a
 // versão empacotada na CLI. Compartilhado entre `update` e `info`.
 export function skillCopyReason(dest, parsed) {
+  // `skills-dir` não é um arquivo só: o destino é um diretório com uma pasta
+  // por skill. Diretório inteiro ausente conta como 'ausente'; qualquer arquivo
+  // faltando ou divergente conta como 'desatualizada' (é o mesmo remédio —
+  // reinstalar —, então não vale distinguir os dois casos).
+  if (dest.format === 'skills-dir') {
+    if (!existsSync(dest.path)) return 'ausente';
+    const files = planPluginSkillFiles(dest.path, CLI_VERSION, versionBanner);
+    if (!files.length) return null;
+    const stale = files.some(
+      (f) => !existsSync(f.path) || readFileSync(f.path, 'utf-8') !== f.content,
+    );
+    return stale ? 'desatualizada' : null;
+  }
+
   const desired = renderContent(dest.format, parsed, CLI_VERSION);
   const existing = existsSync(dest.path) ? readFileSync(dest.path, 'utf-8') : null;
   if (existing === null) return 'ausente';
@@ -312,7 +330,12 @@ export async function installSkill(options = {}) {
   if (options.dryRun) {
     p.note(
       jobs
-        .map((j) => `${chalk.dim(j.target.name.padEnd(20))} ${j.dest.path}  ${chalk.dim(`(${j.dest.format})`)}`)
+        .map((j) => {
+          const head = `${chalk.dim(j.target.name.padEnd(20))} ${j.dest.path}  ${chalk.dim(`(${j.dest.format})`)}`;
+          if (j.dest.format !== 'skills-dir') return head;
+          const names = listPluginSkills().map((s) => s.name);
+          return `${head}\n${chalk.dim(`  ${names.length} skills: ${names.join(', ')}`)}`;
+        })
         .join('\n'),
       `Dry-run — nada será gravado (escopo: ${scopeLabel})`,
     );
@@ -323,6 +346,34 @@ export async function installSkill(options = {}) {
   // 4) Gravar cada destino.
   const written = [];
   for (const { target, dest } of jobs) {
+    // `skills-dir` grava N arquivos (uma pasta por skill do plugin) em vez de
+    // um. Sobrescrever aqui é seguro sem confirmar por arquivo: o destino é um
+    // diretório inteiro do spec-wave, não um arquivo que o usuário mantém.
+    if (dest.format === 'skills-dir') {
+      const files = planPluginSkillFiles(dest.path, pkg.version, versionBanner);
+      if (!files.length) {
+        p.log.error(`${target.name}: nenhuma skill encontrada no plugin empacotado — pulado.`);
+        continue;
+      }
+      if (existsSync(dest.path) && !options.force && !options.yes) {
+        const ok = await p.confirm({
+          message: `${target.name}: ${dest.path} já existe. Sobrescrever as skills do spec-wave?`,
+          initialValue: true,
+        });
+        if (p.isCancel(ok) || !ok) {
+          p.log.info(`${target.name}: mantido (não sobrescrito).`);
+          continue;
+        }
+      }
+      for (const file of files) {
+        mkdirSync(path.dirname(file.path), { recursive: true });
+        writeFileSync(file.path, file.content, 'utf-8');
+      }
+      const count = new Set(files.map((f) => f.skill)).size;
+      written.push({ target, dest, count });
+      continue;
+    }
+
     const content =
       dest.format === 'agents'
         ? mergeAgentsFile(dest.path, renderContent('agents', parsed, pkg.version))
@@ -352,7 +403,12 @@ export async function installSkill(options = {}) {
   }
 
   p.note(
-    written.map((w) => `${chalk.green('✓')} ${chalk.bold(w.target.name)}\n  ${chalk.dim(w.dest.path)}`).join('\n'),
+    written
+      .map((w) => {
+        const suffix = w.count ? chalk.dim(`  (${w.count} skills)`) : '';
+        return `${chalk.green('✓')} ${chalk.bold(w.target.name)}${suffix}\n  ${chalk.dim(w.dest.path)}`;
+      })
+      .join('\n'),
     `Skill v${pkg.version} instalada (escopo: ${scopeLabel})`,
   );
   p.outro(

package/src/commands/issue.mjs

@@ -2,13 +2,11 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
-import { CONFIG_FILE, STATUS_OPTIONS, PRIORITY_LABELS, WORK_ITEM_TYPES } from '../config.mjs';
+import { CONFIG_FILE, PRIORITY_LABELS, WORK_ITEM_TYPES, initialStageForType } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import { createIssue, getIssue } from '../api/github-rest.mjs';
 import { addProjectItem, setItemSingleSelect, getSingleSelectField, addSubIssue } from '../api/github-graphql.mjs';
 
-// Etapa inicial de todo work item recém-criado (📥 Backlog).
-const INITIAL_STAGE = STATUS_OPTIONS[0].name;
 const VALID_PRIORITIES = PRIORITY_LABELS.map(l => l.name);
 
 // Resolve o tipo informado (case-insensitive) para o nome canônico (ex.: "Feature").
@@ -160,18 +158,22 @@ export async function issue(options) {
     return;
   }
 
+  // Etapa de nascimento: Backlog para quase todo tipo, 🐞 Triagem para Bug
+  // (✅ Ready quando o Bug já nasce P0). Ver initialStageForType.
+  const initialStage = initialStageForType(type, options.priority || null);
+
   const boardSpinner = p.spinner();
   boardSpinner.start('Adicionando ao Project...');
   try {
     const itemId = await addProjectItem(token, project.id, created.nodeId);
 
-    const stageOk = await setField(token, project, itemId, 'Etapa', INITIAL_STAGE);
+    const stageOk = await setField(token, project, itemId, 'Etapa', initialStage);
     const typeOk = await setField(token, project, itemId, 'Work Item Type', type);
     if (options.priority) await setField(token, project, itemId, 'Priority', options.priority);
     if (options.area) await setField(token, project, itemId, 'Area', options.area);
 
-    boardSpinner.stop(`Adicionada ao Project${stageOk ? ` em "${INITIAL_STAGE}"` : ''}.`);
-    if (!stageOk) p.log.warn(`Não foi possível definir a Etapa "${INITIAL_STAGE}" (campo não encontrado).`);
+    boardSpinner.stop(`Adicionada ao Project${stageOk ? ` em "${initialStage}"` : ''}.`);
+    if (!stageOk) p.log.warn(`Não foi possível definir a Etapa "${initialStage}" (campo não encontrado).`);
     if (!typeOk) p.log.warn(`Não foi possível definir o Work Item Type "${type}" (campo não encontrado).`);
   } catch (err) {
     boardSpinner.stop('');
@@ -185,7 +187,7 @@ export async function issue(options) {
     Epic: `Próximo: crie Features sob este Epic com \`spec-wave feature --parent ${created.number} --title "..."\`.`,
   };
   p.outro(
-    `${chalk.green('✓')} ${type} #${created.number} criado em "${INITIAL_STAGE}"${parentLine}.\n` +
+    `${chalk.green('✓')} ${type} #${created.number} criado em "${initialStage}"${parentLine}.\n` +
     `  ${hints[type] || ''}`
   );
 }

package/src/commands/move.mjs

@@ -20,7 +20,7 @@ import { loadProjectConfig, resolveField, advanceToStage, resolveStageName } fro
 import { loadConfig } from '../lib/project-root.mjs';
 import {
   CONFIG_FILE, PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
-  isManualStageType, MANUAL_STAGE_TYPES,
+  isManualStageType, MANUAL_STAGE_TYPES, isStageInTrack, STAGE_TRACKS,
 } from '../config.mjs';
 
 const PROGRESS_VALUES = [PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE];
@@ -116,6 +116,16 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
     return;
   }
 
+  // Aviso, não bloqueio: a trilha por tipo é convenção (RFC-004 §7.1); a regra
+  // dura continua sendo "a Etapa só avança". Um caso legítimo fora da trilha
+  // (um Bug que o time decidiu homologar) não deve exigir escape hatch.
+  if (type && !isStageInTrack(type, stage)) {
+    p.log.warn(
+      `${type} normalmente não passa por ${stage} — a trilha do tipo é: ` +
+      `${STAGE_TRACKS[type].join(' → ')}.`
+    );
+  }
+
   const { project, error: projectError } = loadProjectConfig({ cwd: root || process.cwd() });
   if (projectError) {
     p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);

package/src/commands/qa.mjs

@@ -78,6 +78,27 @@ export async function qa({ prNumber }) {
   const updated = [];
 
   for (const num of issueNums) {
+    // Bug é unidade própria: vai para 🧪 QA sozinho, sem arrastar a Feature-pai
+    // (que pode ter Stories ainda em desenvolvimento).
+    const issue = await getIssue(token, owner, repo, num).catch(() => null);
+    if (issue && detectIssueType(issue) === 'Bug') {
+      if (seen.has(issue.number)) continue;
+      seen.add(issue.number);
+      try {
+        const moved = await advanceToStage(
+          projectToken, project, etapaField, statusField, issue.node_id, QA_STAGE, TODO_STATUS);
+        if (moved) {
+          updated.push(`#${issue.number} ${issue.title} (bug)`);
+          console.log(`Bug #${issue.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);
+        } else {
+          console.log(`Bug #${issue.number} já está em "${QA_STAGE}" ou etapa posterior — mantido.`);
+        }
+      } catch (err) {
+        console.warn(`Falha ao atualizar Bug #${issue.number}: ${err.message}`);
+      }
+      continue;
+    }
+
     const feature = await resolveFeatureIssue(token, owner, repo, num);
     if (!feature || seen.has(feature.number)) continue;
     seen.add(feature.number);
@@ -99,10 +120,10 @@ export async function qa({ prNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(prNumber, 10),
       `🧪 **PR aprovado — QA iniciado**\n\n` +
-      `Feature(s) movida(s) para **${QA_STAGE}**:\n\n` +
+      `Item(ns) movido(s) para **${QA_STAGE}**:\n\n` +
       updated.map(f => `- ${f}`).join('\n')
     ).catch(() => {});
   }
 
-  console.log(`qa: ${updated.length} feature(s) atualizada(s).`);
+  console.log(`qa: ${updated.length} item(ns) atualizado(s).`);
 }