@spec-wave/cli 0.15.0 → 0.16.0

package/src/commands/decompose.mjs

@@ -33,6 +33,7 @@ import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 import {
   renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
 } from '../lib/decomposition-doc.mjs';
@@ -207,60 +208,17 @@ function commitFile(filePath, content, message) {
   git('git push');
 }
 
-const FEATURE_SYSTEM_PROMPT = `Você é um Tech Lead experiente em decomposição de trabalho ágil.
-A partir da Feature fornecida (com spec.md e plan.md), gere uma lista de Stories e Tasks.
-
-Responda APENAS com JSON válido neste formato:
-{
-  "stories": [
-    {
-      "title": "Título curto da story (apenas a parte 'quero', sem prefixo)",
-      "userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
-      "body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
-      "dependsOn": [0],
-      "tasks": [
-        {
-          "title": "Título técnico curto da task (sem prefixo)",
-          "body": "Descrição técnica detalhada"
-        }
-      ]
-    }
-  ]
-}
-
-Regras:
-- "title" deve ser CURTO (máx. ~60 caracteres): apenas a parte "quero" da user story, sem o "Como" nem o "para", e sem prefixo. Ex.: "visualizar meus repositórios em layout responsivo"
-- "userStory" deve trazer a user story completa no formato "Como <perfil>, quero <objetivo>, para <benefício>"
-- "body" é texto complementar (contexto, critérios de aceite); não repita o título
-- Cada Story deve ter 2–5 Tasks associadas
-- Tasks devem ser atividades técnicas concretas, com "title" curto e "body" detalhado
-- Gere entre 3 e 7 Stories por Feature
-- Ordene as stories na sequência de implementação — a ORDEM da lista importa
-- "dependsOn" (opcional): índices 0-based das stories ANTERIORES na lista das quais esta story depende. Referencie apenas índices menores que o da própria story. Use [] quando a story puder ser feita em paralelo (sem dependências); se omitido, assume-se dependência da story anterior (sequencial)`;
-
-const RFC_SYSTEM_PROMPT = `Você é um Tech Lead experiente. A partir do RFC fornecido (proposta técnica/de processo), gere a lista de Tasks técnicas concretas necessárias para implementá-lo.
-
-Responda APENAS com JSON válido neste formato:
-{
-  "tasks": [
-    {
-      "title": "Título técnico curto da task (sem prefixo)",
-      "body": "Descrição técnica detalhada (o que fazer, áreas/arquivos afetados, critério de pronto)"
-    }
-  ]
-}
-
-Regras:
-- "title" CURTO (máx. ~60 caracteres), sem prefixo.
-- "body" detalhado e acionável.
-- Gere entre 3 e 10 Tasks concretas que, juntas, cubram o RFC.`;
+// Os prompts vivem em `src/plugin/skills/decompose/model-prompt.{feature,rfc}.md`
+// (sobrescrevíveis em `.spec-wave/prompts/decompose.feature.md`). O contrato JSON é o
+// `json.shape` do frontmatter — quem parseia a saída e quem instrui o modelo
+// passam a ler a MESMA declaração, em vez de duas cópias que podiam divergir.
 
 // ---------------------------------------------------------------------------
 // Etapa 1: rascunho (label spec-wave:decompose)
 // ---------------------------------------------------------------------------
 
 async function draftDecomposition(ctx) {
-  const { token, owner, repo, issue, issueNumber, type, labels, usage, docDir, docPath, docRel } = ctx;
+  const { token, owner, repo, issue, issueNumber, type, labels, usage, root, docDir, docPath, docRel } = ctx;
   const number = parseInt(issueNumber, 10);
   const kind = DECOMPOSE_TARGETS[type]; // Feature → 'stories'; RFC → 'tasks'
   const blobUrl = `https://github.com/${owner}/${repo}/blob/main/${docRel}`;
@@ -292,8 +250,12 @@ async function draftDecomposition(ctx) {
           `\n## plan.md\n${planContent || '(plan.md não encontrado)'}`,
         ].join('\n');
 
+    const decomposePrompt = loadPrompt(
+      type === 'RFC' ? 'decompose/rfc' : 'decompose/feature',
+      { cwd: root },
+    );
     const generated = parseModelJson(await generateDocument(
-      type === 'RFC' ? RFC_SYSTEM_PROMPT : FEATURE_SYSTEM_PROMPT,
+      toolFreeSystemPrompt(decomposePrompt),
       userContent,
       { action: 'decompose', labels, usage }
     ));

package/src/commands/dev-agent.mjs

@@ -19,7 +19,7 @@ import {
 import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CONFIG_FILE } from '../config.mjs';
+import { CONFIG_FILE, LABEL_DEV_AGENT } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
@@ -82,7 +82,7 @@ export function renderAgentConfig({ owner, repo }) {
 # Schema completo: https://github.com/${AGENT_REPO}#configuração
 
 repo = "${owner}/${repo}"
-queue_label = "spec-wave:dev-agent"
+queue_label = "${LABEL_DEV_AGENT}"
 
 # Defaults do agente (descomente para ajustar):
 #poll_interval_secs = 60       # consulta à fila quando ocioso
@@ -412,7 +412,7 @@ async function finishSetup({ cfg, home, binPath, configPath, options, configActi
   p.outro(
     `${chalk.green('✓')} Agente pronto.\n` +
     `  Rodar agora:  ${chalk.cyan('spec-wave dev-agent --run')}\n` +
-    '  Enfileirar:   aplique a label spec-wave:dev-agent numa issue [FEATURE] já decomposta.'
+    `  Enfileirar:   aplique a label ${LABEL_DEV_AGENT} numa issue [FEATURE] já decomposta.`
   );
 }
 

package/src/commands/doctor.mjs

@@ -12,7 +12,8 @@ import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
-  ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX, DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+  RETIRED_STAGES, ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
+  DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS,
 } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import {
@@ -284,7 +285,12 @@ async function checkConfig(ctx) {
 export function inspectBoardHygiene({ boardStages = null, repoLabels = null } = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
-  const unknownStages = boardStages ? boardStages.filter(s => !known.has(s)) : [];
+  const retired = new Map(RETIRED_STAGES.map(s => [s.name, s]));
+  const foreign = boardStages ? boardStages.filter(s => !known.has(s)) : [];
+  // Uma etapa aposentada também é "fora do fluxo", mas a orientação ao usuário
+  // é diferente da de uma coluna inventada — por isso saem em listas separadas.
+  const retiredStages = foreign.filter(s => retired.has(s)).map(s => retired.get(s));
+  const unknownStages = foreign.filter(s => !retired.has(s));
   const missingStages = boardStages ? canonical.filter(s => !boardStages.includes(s)) : [];
 
   const knownLabels = new Set(ALL_LABELS.map(l => l.name));
@@ -294,7 +300,29 @@ export function inspectBoardHygiene({ boardStages = null, repoLabels = null } =
   const missingLabels = repoLabels
     ? ALL_LABELS.map(l => l.name).filter(n => !repoLabels.includes(n))
     : [];
-  return { unknownStages, missingStages, orphanLabels, missingLabels };
+  return { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels };
+}
+
+/**
+ * O board comporta a trilha do Bug? (função PURA)
+ *
+ * Um Bug percorre 🐞 Triagem → ✅ Ready → … → 🚀 Deploy → 🎉 Done (RFC-004 §4).
+ * Se o board não tem alguma dessas colunas, o item não tem onde parar: o campo
+ * "Etapa" só aceita as opções que existem, então a escrita falha em silêncio e
+ * o bug fica sem etapa — invisível em toda tela que filtra por etapa.
+ *
+ * Só reporta quando há Bug aberto: um board sem bugs não precisa da trilha.
+ *
+ * @param {object} params
+ * @param {string[]|null} [params.boardStages] opções do campo Etapa
+ * @param {number} [params.openBugCount] bugs abertos no repositório
+ * @returns {{ missingTrackStages: string[] }}
+ */
+export function inspectBugTrack({ boardStages = null, openBugCount = 0 } = {}) {
+  if (!boardStages || openBugCount <= 0) return { missingTrackStages: [] };
+  return {
+    missingTrackStages: STAGE_TRACKS.Bug.filter(s => !boardStages.includes(s)),
+  };
 }
 
 async function checkBoardHygiene(ctx) {
@@ -315,6 +343,7 @@ async function checkBoardHygiene(ctx) {
   }
 
   let repoLabels = null;
+  let openBugCount = 0;
   if (ctx.token && cfg.owner && cfg.repo) {
     try {
       const res = await makeOctokit(ctx.token)
@@ -323,9 +352,17 @@ async function checkBoardHygiene(ctx) {
     } catch {
       // labels não verificáveis agora — segue só com o board
     }
+    try {
+      const bugs = await makeOctokit(ctx.token).paginate('GET /repos/{owner}/{repo}/issues', {
+        owner: cfg.owner, repo: cfg.repo, labels: '[BUG]', state: 'open', per_page: 100,
+      });
+      openBugCount = bugs.filter(i => !i.pull_request).length;
+    } catch {
+      // sem acesso às issues — o check da trilha do Bug fica de fora
+    }
   }
 
-  const { unknownStages, missingStages, orphanLabels, missingLabels } =
+  const { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels } =
     inspectBoardHygiene({ boardStages, repoLabels });
 
   const notes = [];
@@ -343,10 +380,32 @@ async function checkBoardHygiene(ctx) {
       'Mova os itens para uma etapa do fluxo e remova a coluna.'
     );
   }
+  for (const stage of retiredStages) {
+    status = 'warn';
+    notes.push(
+      `Etapa descontinuada ainda no board: ${stage.name} (removida do fluxo na v${stage.removedIn}). ` +
+      `Mova os itens dela para ${stage.replacedBy} e apague a coluna nas configurações do campo ` +
+      '"Etapa"; depois rode `refresh --config` para tirar o id do .spec-wave.json.'
+    );
+  }
   if (missingStages.length > 0) {
     status = 'warn';
-    notes.push(`Etapas do RFC-001 ausentes no board: ${missingStages.join(', ')} — rode \`refresh\`.`);
+    notes.push(
+      `Etapas do RFC-001 ausentes no board: ${missingStages.join(', ')} — rode ` +
+      '`refresh --stages --dry-run` para ver o plano, ou crie a coluna à mão nas configurações ' +
+      'do campo "Etapa" e rode `refresh --config`.'
+    );
+  }
+  const { missingTrackStages } = inspectBugTrack({ boardStages, openBugCount });
+  if (missingTrackStages.length > 0) {
+    status = 'warn';
+    notes.push(
+      `${openBugCount} Bug(s) aberto(s), mas o board não tem: ${missingTrackStages.join(', ')}. ` +
+      'Um Bug movido para uma etapa inexistente fica SEM Etapa e some das telas — ' +
+      'rode `refresh --stages`.'
+    );
   }
+
   if (repoLabels) {
     if (orphanLabels.length > 0) {
       status = 'warn';
@@ -504,10 +563,22 @@ async function checkAi(ctx) {
     );
   } else {
     notes.push(
-      `Saída estruturada da crítica: ${provider.value === 'anthropic' ? 'tool call forçado' : 'response_format json_schema'} ` +
+      `Saída estruturada da crítica: tool call forçado (${provider.value}) ` +
       `· strict=${supportsStrictSchema(critiqueModel) ? 'sim' : 'não'} neste modelo.`
     );
   }
+  // O backend anthropic não chama a API — sobe o Claude Code CLI como
+  // subprocesso, que não existe no runner dos workflows (só há setup-node).
+  if (provider.value === 'anthropic') {
+    problems.push(
+      'O provider `anthropic` NÃO roda nos GitHub Actions: ele sobe o Claude Code CLI como ' +
+      'subprocesso, ausente no runner. As Actions de spec/plan/decompose vão falhar. ' +
+      'Troque para `"provider": "openrouter"` no .spec-wave.json (e adicione o secret ' +
+      'OPENROUTER_API_KEY), ou instale o Claude Code no workflow e defina ' +
+      'SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1. Localmente o anthropic funciona.'
+    );
+  }
+
   if (process.env[provider.secret]) {
     notes.push(`${provider.secret} presente no ambiente local.`);
   } else {

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 },