@spec-wave/cli 0.15.0 → 0.16.0

package/src/lib/critique.mjs

@@ -22,6 +22,7 @@ import { generateStructured } from './claude.mjs';
 import {
   LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
 } from '../config.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from './prompt-loader.mjs';
 
 // Severidades aceitas — enum FECHADO. O teste de prefixo /^grave/i sobre texto
 // livre que existia aqui aceitava "gravíssimo" e rebaixava "critical"/"high"
@@ -41,21 +42,11 @@ const MAX_FINDING_CHARS = 800;
 export const CRITIQUE_TOOL_NAME = 'registrar_findings';
 
 // Rótulo do artefato auditado, por contexto — usado no cabeçalho do comentário.
-const KIND_LABEL = { plan: 'plan.md', stories: 'decomposition.md' };
-
-// Redação específica por tipo de auditoria. 'plan' audita o plan.md contra a
-// spec; 'stories' audita a decomposição proposta contra spec + plan.
-const KIND_FOCUS = {
-  plan:
-    'Audite o plan.md contra o spec.md, as regras de negócio e o tech_context fornecidos. ' +
-    'Procure decisões técnicas que contradizem ou ignoram requisitos da spec e ' +
-    'tecnologias/serviços fora do tech_context.',
-  stories:
-    'Audite a decomposição proposta (documento Markdown com Stories e suas Tasks) contra o ' +
-    'spec.md e o plan.md fornecidos. Procure Stories que contradizem, invertem ou ignoram ' +
-    'requisitos da spec ou decisões do plan, critérios de aceite incompatíveis com as regras ' +
-    'de negócio, e Tasks que não sustentam a Story a que pertencem.',
-};
+const KIND_LABEL = { plan: 'plan.md', stories: 'decomposition.md', bug: 'bug.md' };
+
+// Prompt por tipo de auditoria. 'plan' audita o plan.md contra a spec;
+// 'stories' audita a decomposição proposta contra spec + plan.
+const KIND_PROMPT = { plan: 'plan/critique', stories: 'decompose/critique', bug: 'bug/critique' };
 
 // A decomposição virou arquivo revisável (decomposition.md): um finding só é
 // acionável se disser ONDE está o problema. Os títulos "## Story N" e
@@ -67,28 +58,39 @@ const ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho audita
 - "geral" quando o problema for da decomposição como um todo (ex.: requisito da spec que nenhuma Story cobre).
 Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "### Task N.M — ..." do documento.`;
 
-function buildSystemPrompt(kind) {
-  const focus = KIND_FOCUS[kind] || KIND_FOCUS.plan;
+/**
+ * Monta o system prompt da crítica: corpo editável + contrato de máquina.
+ *
+ * A divisão não é estética. O CORPO (`model-prompt.critique.md` da skill do comando) é a redação
+ * — foco da auditoria, o que conta como achado, a barra de rigor — e o time
+ * pode sobrescrevê-lo em `.spec-wave/prompts/` para apertar ou afrouxar o
+ * critério. O CONTRATO abaixo é acoplado a `critiqueJsonSchema()` e a
+ * `validateCritiquePayload()`: o enum de `severity`, a âncora `Story N` /
+ * `Task N.M` e a obrigação de chamar a tool. Ele é anexado por ÚLTIMO
+ * justamente para que um override de projeto não consiga anulá-lo — um payload
+ * fora do contrato falha alto, e não vale deixar isso na mão do texto.
+ *
+ * @param {'plan'|'stories'} kind
+ * @param {string} [cwd] raiz do repositório (resolve o override do projeto)
+ */
+function buildSystemPrompt(kind, cwd) {
+  const prompt = loadPrompt(KIND_PROMPT[kind] || KIND_PROMPT.plan, ...(cwd ? [{ cwd }] : []));
   const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}` : '';
-  return `Você é um revisor técnico CÉTICO e adversarial. Seu papel é encontrar problemas, não elogiar.
 
-${focus}
-
-Liste:
-- contradições diretas entre os documentos;
-- inversões de requisito (ex.: consentimento→persistência invertidos: a spec exige consentimento ANTES de persistir e o documento persiste antes de pedir consentimento);
-- violações de restrições explícitas (ex.: minimização de dados LGPD, limites de retenção, campos proibidos);
-- itens que contradizem ou ignoram a spec.
+  const contract = `## Contrato de saída
 
 Classifique cada finding no campo "severity", usando EXATAMENTE um destes dois valores:
 - "grave": contradiz um requisito ou regra explícita — causaria implementação errada;
 - "menor": inconsistência, omissão ou ambiguidade que merece atenção mas não inverte requisito.
 
-NÃO invente problemas: se os documentos estiverem consistentes, retorne a lista vazia.
 Escreva os findings em português (pt-BR), em uma frase objetiva cada.${anchor}
 
 Registre o resultado chamando a ferramenta \`${CRITIQUE_TOOL_NAME}\`. Nunca responda em texto livre.
 Se os documentos estiverem consistentes, chame-a com "findings": [].`;
+
+  // Sem tool loop de leitura aqui: `generateStructured` faz UMA chamada, com a
+  // tool de saída estruturada como única ferramenta.
+  return toolFreeSystemPrompt(prompt, contract);
 }
 
 function critiqueJsonSchema(kind) {
@@ -338,6 +340,11 @@ const KIND_TRAILER = {
       `\`decomposition.md\` (as âncoras acima apontam para ele), remova a label ` +
       `\`${LABEL_CRITIQUE_FAILED}\` e reaplique \`spec-wave:decompose\` para uma nova crítica.`
     : '_Findings menores não bloqueiam a decomposição._'),
+  bug: (graves) => (graves
+    ? `⛔ Há findings **graves**: a label \`${LABEL_CRITIQUE_FAILED}\` bloqueia a triagem ` +
+      'até ser removida. Um bug com causa raiz errada produz correção errada — corrija o ' +
+      '`bug.md` e reaplique `spec-wave:bug`.'
+    : '_Findings menores não bloqueiam a triagem._'),
 };
 
 /**
@@ -406,11 +413,13 @@ export function renderCritiqueMarkdown({
  * chamador decidir entre seguir com aviso e abortar.
  *
  * @param {object} params
- * @param {'plan'|'stories'} params.kind o que está sendo auditado
+ * @param {'plan'|'stories'|'bug'} params.kind o que está sendo auditado
  * @param {string} [params.spec] conteúdo do spec.md
  * @param {string} [params.plan] conteúdo do plan.md
  * @param {string} [params.techContextYaml] tech_context serializado em YAML
  * @param {string} [params.decomposition] conteúdo do decomposition.md
+ * @param {string} [params.bugDoc] conteúdo do bug.md
+ * @param {string} [params.bugReport] relato original (corpo da issue + comentários)
  * @param {number} [params.attempt] tentativa em curso (cabeçalho e marcador)
  * @param {number} [params.maxAttempts]
  * @param {string} [params.model] modelo imposto (escalada); undefined = cadeia normal
@@ -419,9 +428,9 @@ export function renderCritiqueMarkdown({
  * @returns {Promise<{grave, findings, markdown, attempt, model}>}
  */
 export async function runCritique({
-  kind, spec, plan, techContextYaml, decomposition,
+  kind, spec, plan, techContextYaml, decomposition, bugDoc, bugReport,
   attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
-  model, labels = [], usage,
+  model, labels = [], usage, cwd,
 } = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
@@ -434,9 +443,13 @@ export async function runCritique({
       `## Decomposição proposta (decomposition.md)\n\n\`\`\`\`markdown\n${decomposition}\n\`\`\`\``
     );
   }
+  // O relato é a fonte contra a qual o bug.md é auditado: a causa raiz proposta
+  // tem que explicar OS SINTOMAS RELATADOS, não sintomas plausíveis quaisquer.
+  if (bugReport) sections.push(`## Relato original (issue e comentários)\n\n${bugReport}`);
+  if (bugDoc) sections.push(`## bug.md\n\n${bugDoc}`);
   const userContent = sections.join('\n\n') || '(nenhum documento fornecido)';
 
-  const report = await generateStructured(buildSystemPrompt(kind), userContent, {
+  const report = await generateStructured(buildSystemPrompt(kind, cwd), userContent, {
     action: 'critique',
     temperature: 0,
     schema: {

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/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.0",
+  "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"
+  ]
+}