@spec-wave/cli 0.14.0 → 0.16.0

package/src/commands/generate-bug.mjs

@@ -0,0 +1,195 @@
+// Gera o bug.md (RFC-004 §5) — espelho do generate-spec, com três diferenças
+// que vêm da natureza do artefato:
+//
+//  1. O relato mora nos COMENTÁRIOS, não só no corpo. Nas origens "reprovação
+//     de QA" e "suporte", o corpo da issue é uma linha e o que descreve o
+//     defeito vem depois, em comentário. Por isso eles entram no payload.
+//  2. A crítica adversarial recebe o relato original junto do documento: a
+//     pergunta que ela responde é se a causa raiz proposta explica OS SINTOMAS
+//     RELATADOS — sem o relato, ela só avalia coerência interna.
+//  3. Escreve em docs/bugs/<slug>/, fora de docs/features/.
+import { execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
+} from '../api/github-rest.mjs';
+import { generateDocument } from '../lib/claude.mjs';
+import { recordUsage } from '../lib/usage-report.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { bugDocPaths } from '../lib/bug-doc.mjs';
+import {
+  runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
+} from '../lib/critique.mjs';
+import {
+  LABEL_BUG, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, REQUIRED_BUG_SECTIONS,
+  TARGET_LANGUAGE, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+} from '../config.mjs';
+
+// Relato = corpo + comentários humanos, na ordem cronológica. Comentários do
+// próprio spec-wave são ruído aqui (críticas anteriores, relatórios de uso):
+// realimentá-los faria o modelo auditar a si mesmo em vez do defeito.
+function buildReport(issue, comments) {
+  const parts = [`### Descrição da issue\n\n${issue.body || '(sem descrição)'}`];
+  const humanos = (comments || []).filter(c => !isSpecWaveComment(c.body));
+  for (const c of humanos) {
+    const autor = c.user?.login || 'desconhecido';
+    parts.push(`### Comentário de @${autor}\n\n${c.body}`);
+  }
+  return parts.join('\n\n');
+}
+
+function isSpecWaveComment(body) {
+  const t = String(body || '');
+  return t.includes('<!-- spec-wave:') || t.includes('**(spec-wave)**') || t.includes('(spec-wave)');
+}
+
+export async function generateBug({ issueNumber }) {
+  const token = await resolveToken();
+  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { root } = loadConfig();
+  const n = parseInt(issueNumber, 10);
+
+  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-bug --issue-number 1'
+    );
+  }
+
+  console.log(`Buscando issue #${n}...`);
+  const issue = await getIssue(token, owner, repo, n);
+
+  // Guarda invertida em relação ao generate-spec: aqui só Bug passa.
+  const type = detectIssueType(issue);
+  if (type !== 'Bug') {
+    console.log(`Issue #${n} é ${type}: bug.md é gerado só para Bug.`);
+    await removeLabel(token, owner, repo, n, LABEL_BUG);
+    await commentOnIssue(
+      token, owner, repo, n,
+      `ℹ️ **bug.md não gerado:** o tipo **${type}** não usa esse artefato. ` +
+      'Nenhum arquivo foi criado.'
+    ).catch(() => {});
+    return;
+  }
+
+  const issueLabels = labelNames(issue);
+  if (issueLabels.includes(LABEL_NEEDS_HUMAN)) {
+    console.log(`Issue #${n} está com ${LABEL_NEEDS_HUMAN}: geração bloqueada.`);
+    await removeLabel(token, owner, repo, n, LABEL_BUG);
+    return;
+  }
+
+  const { slug, dirRel, fileRel, dirAbs, fileAbs } = bugDocPaths(issue.title, root);
+
+  const comments = await listIssueComments(token, owner, repo, n).catch(() => []);
+  const report = buildReport(issue, comments);
+
+  const payload = {
+    metadata: {
+      bug_title: issue.title,
+      labels: issueLabels,
+      required_sections: REQUIRED_BUG_SECTIONS,
+    },
+    report: { raw: report },
+  };
+  const userContent =
+    `Gere o bug.md a partir deste payload JSON:\n\n${JSON.stringify(payload, null, 2)}`;
+
+  const usageEntries = [];
+  try {
+    console.log(`Gerando bug.md para: ${issue.title}`);
+    const systemPrompt = toolFreeSystemPrompt(loadPrompt('bug', { cwd: root }));
+    const { content } = await generateDocument(systemPrompt, userContent, {
+      action: 'bug',
+      labels: issueLabels,
+      lint: { lang: TARGET_LANGUAGE },
+      withReport: true,
+      usage: usageEntries,
+    });
+
+    mkdirSync(dirAbs, { recursive: true });
+    writeFileSync(fileAbs, content, 'utf-8');
+
+    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 "${fileAbs}"`);
+    git(`git commit -m "docs: generate bug.md for ${slug} [spec-wave]"`);
+    git('git pull --rebase');
+    git('git push');
+
+    await removeLabel(token, owner, repo, n, LABEL_BUG);
+
+    // Crítica adversarial: NÃO fatal. Um bug.md gerado e criticado como grave
+    // ainda é melhor que nenhum — o portão é a label, verificada na triagem.
+    const critique = await critiqueBugDoc({
+      token, owner, repo, issueNumber: n, issue,
+      bugDoc: content, report, labels: issueLabels, cwd: root, usage: usageEntries,
+    });
+
+    await commentOnIssue(
+      token, owner, repo, n,
+      '🐞 **bug.md gerado automaticamente!**\n\n' +
+      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+      'Revise a **causa raiz** e o **teste de regressão** — são as duas seções que decidem se ' +
+      'a correção ataca o defeito ou o sintoma. Quando estiver pronto, valide com:\n' +
+      `\`\`\`\ngh issue edit ${n} --add-label "spec-wave:ready"\n\`\`\`` +
+      (critique?.blocked ? '\n\n⛔ A crítica adversarial encontrou problemas graves (acima).' : '')
+    );
+
+    console.log(`bug.md criado em: ${fileRel} (dir: ${dirRel})`);
+  } catch (err) {
+    // Mesmo motivo do generate-spec: sem remover a label, re-aplicá-la não
+    // emite evento e a issue vira beco sem saída.
+    await removeLabel(token, owner, repo, n, LABEL_BUG).catch(() => {});
+    await commentOnIssue(
+      token, owner, repo, n,
+      '❌ **Falha ao gerar o bug.md**\n\n' +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `A label \`${LABEL_BUG}\` foi removida para destravar o gatilho — ` +
+      'adicione-a de novo para tentar outra vez.'
+    ).catch(() => {});
+    throw err;
+  } finally {
+    await recordUsage({ token, owner, repo, issueNumber: n, entries: usageEntries });
+  }
+}
+
+// Roda a crítica e reflete o veredito em labels/comentário. Best-effort: uma
+// falha da crítica não invalida o documento já commitado.
+async function critiqueBugDoc({
+  token, owner, repo, issueNumber, issue, bugDoc, report, labels, cwd, usage,
+}) {
+  try {
+    const comments = await listIssueComments(token, owner, repo, issueNumber).catch(() => []);
+    const { attempt, blocked } = resolveCritiqueAttempt({
+      comments, labels, kind: 'bug', maxAttempts: DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+    });
+
+    if (blocked) {
+      await addLabel(token, owner, repo, issueNumber, LABEL_NEEDS_HUMAN);
+      await commentOnIssue(
+        token, owner, repo, issueNumber,
+        renderNeedsHumanComment({ kind: 'bug', maxAttempts: DEFAULT_MAX_CRITIQUE_ATTEMPTS })
+      );
+      return { blocked: true };
+    }
+
+    const result = await runCritique({
+      kind: 'bug', bugDoc, bugReport: report, attempt, labels, usage, cwd,
+    });
+    await commentOnIssue(token, owner, repo, issueNumber, result.markdown);
+    if (result.grave) {
+      await addLabel(token, owner, repo, issueNumber, LABEL_CRITIQUE_FAILED);
+      return { blocked: true };
+    }
+    return { blocked: false };
+  } catch (err) {
+    console.error(`Crítica do bug.md falhou (não fatal): ${err.message}`);
+    return { blocked: false };
+  }
+}

package/src/commands/generate-plan.mjs

@@ -18,6 +18,7 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { loadConfig, resolveFromRoot } from '../lib/project-root.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.
@@ -186,7 +171,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 },

package/src/commands/generate-spec.mjs

@@ -7,6 +7,7 @@ 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 { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
   allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE, labelNames,
@@ -23,27 +24,9 @@ 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();
@@ -103,7 +86,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 },

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] || ''}`
   );
 }