@spec-wave/cli 0.14.0 → 0.16.0

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/pr-branch.mjs

@@ -0,0 +1,267 @@
+// Regras PURAS do modo `--branch` do update (arquivos do repo via Pull Request).
+//
+// Até aqui o `update` era a única exceção ao fluxo de PR: commitava os arquivos
+// do repo direto na branch default, um commit por arquivo. Em repositório com
+// proteção de branch isso falha no meio da execução e deixa parte aplicada; e
+// mesmo sem proteção, contorna a revisão que todo o resto do fluxo tem.
+//
+// Tudo aqui é puro de propósito. A suíte não tem nenhuma infraestrutura de mock
+// de HTTP, então a única forma de testar o modo PR é manter as DECISÕES (nome da
+// branch, o que entra no PR, o que o corpo do PR conta a quem revisa) separadas
+// das chamadas de rede, que ficam em api/github-rest.mjs.
+
+import { CLI_VERSION } from './templates.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+
+/**
+ * Nome automático da branch quando `--branch` vem sem valor.
+ *
+ * Deliberadamente SEM timestamp: rodar o update duas vezes para a MESMA versão
+ * da CLI tem que reaproveitar o mesmo PR, não espalhar uma branch nova por
+ * tentativa. O bump de versão é o que separa uma atualização da próxima, e ele
+ * já está no nome.
+ *
+ * @param {string} [version]
+ * @returns {string}
+ */
+export function autoBranchName(version = CLI_VERSION) {
+  return `spec-wave/update-v${version}`;
+}
+
+// Proibições de `git check-ref-format` para refs/heads/<nome>: caractere
+// de controle e espaço (\u0000-\u0020), DEL (\u007f) e os
+// metacaracteres de revisão. Escapes explícitos de propósito: caractere de
+// controle literal no fonte é invisível e não sobrevive a copiar/colar.
+const REF_FORBIDDEN = /[\u0000-\u0020\u007f~^:?*[\\]/;
+
+const MAX_BRANCH_LENGTH = 200;
+
+/**
+ * Resolve e VALIDA o nome da branch (função PURA).
+ *
+ * Validar aqui, antes de qualquer chamada de rede, evita o pior desperdício
+ * possível: gastar meia dúzia de requisições de comparação e só descobrir no
+ * `createRef` que o nome tinha um espaço — com a mensagem crua da API, longe da
+ * causa.
+ *
+ * Mesmo contrato de `resolveStageName` em lib/board.mjs: `{valor, error}`.
+ *
+ * @param {string|boolean|undefined|null} value valor de `options.branch` — o
+ *        commander entrega `true` para `--branch` sem valor
+ * @param {object} [opts]
+ * @param {string} [opts.version] versão usada no nome automático
+ * @returns {{ branch: string|null, error: string|null }}
+ */
+export function resolveBranchName(value, { version = CLI_VERSION } = {}) {
+  if (value === true || value === undefined || value === null || String(value).trim() === '') {
+    return { branch: autoBranchName(version), error: null };
+  }
+
+  let branch = String(value).trim();
+  // Erro comum: colar o ref completo em vez do nome. Corrigir é mais útil que recusar.
+  if (branch.startsWith('refs/heads/')) branch = branch.slice('refs/heads/'.length);
+
+  const bad = (why) => ({ branch: null, error: `Nome de branch inválido ("${branch}"): ${why}.` });
+
+  if (!branch) return bad('nome vazio');
+  if (branch.length > MAX_BRANCH_LENGTH) {
+    return bad(`nome longo demais (máximo ${MAX_BRANCH_LENGTH} caracteres)`);
+  }
+  if (REF_FORBIDDEN.test(branch)) {
+    return bad('não pode conter espaço, caractere de controle ou ~ ^ : ? * [ \\');
+  }
+  if (branch.includes('..')) return bad('não pode conter ".."');
+  if (branch.includes('@{')) return bad('não pode conter "@{"');
+  if (branch === '@') return bad('não pode ser apenas "@"');
+  if (branch.startsWith('/') || branch.endsWith('/')) return bad('não pode começar nem terminar com "/"');
+  if (branch.includes('//')) return bad('não pode conter "//"');
+  if (branch.startsWith('-')) return bad('não pode começar com "-"');
+  if (branch.endsWith('.')) return bad('não pode terminar com "."');
+  if (branch.toUpperCase() === 'HEAD') return bad('"HEAD" é reservado');
+  for (const part of branch.split('/')) {
+    if (part.startsWith('.')) return bad('nenhum componente pode começar com "."');
+    if (part.endsWith('.lock')) return bad('nenhum componente pode terminar com ".lock"');
+  }
+  return { branch, error: null };
+}
+
+/**
+ * Título do PR — e assunto do commit único (função PURA).
+ *
+ * A mesma frase nos dois lugares de propósito: no modo PR existe um commit só, e
+ * ver textos diferentes para a mesma mudança na lista de commits e no título do
+ * PR só gera dúvida.
+ */
+export function composePrTitle({ version = CLI_VERSION } = {}) {
+  return `chore(spec-wave): atualiza arquivos do repo para v${version}`;
+}
+
+/**
+ * Mensagem do commit ÚNICO (função PURA).
+ *
+ * O corpo lista arquivo + motivo porque este é o único commit da branch: ele
+ * precisa se explicar sozinho num `git log` feito seis meses depois, sem o PR
+ * aberto ao lado.
+ *
+ * @param {object} [a]
+ * @param {string} [a.version]
+ * @param {Array<{path: string, reason: string}>} [a.files]
+ * @returns {string}
+ */
+export function buildCommitMessage({ version = CLI_VERSION, files = [] } = {}) {
+  const subject = composePrTitle({ version });
+  if (!files.length) return `${subject}\n`;
+  return `${subject}\n\n${files.map(f => `- ${f.path} (${f.reason})`).join('\n')}\n`;
+}
+
+/**
+ * Corpo do PR (função PURA).
+ *
+ * Quem revisa precisa saber DUAS coisas que o diff não mostra:
+ *  • as labels já foram aplicadas direto na base — label é metadado do
+ *    repositório, não existe forma de versioná-la num PR, então ela mudou ANTES
+ *    de alguém revisar isto;
+ *  • a skill dos agentes foi atualizada em máquina local, fora do repositório.
+ * Sem esses dois blocos o PR parece ser a totalidade do que o update fez — e não é.
+ *
+ * @param {object} [a]
+ * @param {Array<{path: string, reason: string}>} [a.files] arquivos que ENTRARAM no commit
+ * @param {{included: boolean, reason: string}|null} [a.config] decisão sobre o .spec-wave.json
+ * @param {{created: string[], updated: string[], removed: string[]}|null} [a.labels]
+ *        labels EFETIVAMENTE aplicadas (não o diff detectado — o corpo não pode
+ *        prometer o que falhou)
+ * @param {string[]} [a.skill] nomes dos agentes cuja skill foi atualizada localmente
+ * @returns {string} markdown
+ */
+export function composePrBody({
+  version = CLI_VERSION, base = '?', branch = '?',
+  files = [], config = null, labels = null, skill = [],
+} = {}) {
+  const l = [];
+  l.push(`Atualização gerada por \`spec-wave update\` (CLI v${version}).`);
+  l.push('');
+  l.push(`Base: \`${base}\` · Branch: \`${branch}\``);
+  l.push('');
+  l.push('## Arquivos do repositório');
+  l.push('');
+  if (files.length) for (const f of files) l.push(`- \`${f.path}\` — ${f.reason}`);
+  else l.push('_Nenhum._');
+
+  if (config) {
+    l.push('');
+    l.push(`## ${CONFIG_FILE}`);
+    l.push('');
+    l.push(config.included
+      ? `Incluído neste PR — ${config.reason}.`
+      : `**Fora** deste PR — ${config.reason}.`);
+  }
+
+  const labelTotal = labels
+    ? labels.created.length + labels.updated.length + labels.removed.length
+    : 0;
+  if (labelTotal) {
+    l.push('');
+    l.push(`## Labels — JÁ aplicadas em \`${base}\`, fora deste PR`);
+    l.push('');
+    l.push(
+      'Label é metadado do repositório e não pode ser versionada: estas mudanças já ' +
+      'valem, com ou sem o merge deste PR.'
+    );
+    l.push('');
+    if (labels.created.length) l.push(`- criadas: ${labels.created.map(n => `\`${n}\``).join(', ')}`);
+    if (labels.updated.length) l.push(`- atualizadas: ${labels.updated.map(n => `\`${n}\``).join(', ')}`);
+    if (labels.removed.length) l.push(`- removidas (descontinuadas): ${labels.removed.map(n => `\`${n}\``).join(', ')}`);
+  }
+
+  if (skill.length) {
+    l.push('');
+    l.push('## Skill dos agentes — fora deste PR');
+    l.push('');
+    l.push(
+      `Atualizada localmente em: ${skill.map(n => `\`${n}\``).join(', ')}. ` +
+      'Não faz parte do repositório.'
+    );
+  }
+
+  l.push('');
+  l.push('---');
+  l.push(`Depois do merge, \`npx @spec-wave/cli@${version} update --dry-run\` deve reportar tudo em dia.`);
+  return `${l.join('\n')}\n`;
+}
+
+/**
+ * O .spec-wave.json entra no PR? (função PURA)
+ *
+ * Política herdada do init (ver o comentário em commands/init.mjs): o config é
+ * gravado LOCAL de propósito. Quem não o commitou escolheu mantê-lo fora do
+ * versionamento, e passar a versioná-lo é decisão de projeto — não pode ser
+ * efeito colateral de um `update`. Logo: só entra se JÁ estiver versionado na
+ * base. `--config-in-pr` / `--no-config-in-pr` forçam os dois lados.
+ *
+ * Cobre também o caso em que o config NÃO está desatualizado pela versão mas o
+ * arquivo local difere do que está na base (alguém regenerou e esqueceu de
+ * commitar): entra igual, porque é exatamente para isso que o PR serve.
+ *
+ * @param {object} [a]
+ * @param {string|null|undefined} [a.remote] conteúdo do config na base (null/undefined = não versionado)
+ * @param {string|null} [a.desired] conteúdo que deveria estar lá
+ * @param {boolean} [a.willRegenerate] o conteúdo ainda vai ser regenerado (no
+ *        resumo e no dry-run ele não existe); o regenerado SEMPRE difere do
+ *        remoto, porque `refreshedAt` muda a cada execução
+ * @param {boolean|undefined} [a.force] undefined | true (--config-in-pr) | false (--no-config-in-pr)
+ * @returns {{ included: boolean, reason: string }}
+ */
+export function decideConfigInPr({ remote, desired, willRegenerate = false, force } = {}) {
+  const versioned = remote !== null && remote !== undefined;
+  if (force === false) return { included: false, reason: '--no-config-in-pr' };
+  if (!desired && !willRegenerate) {
+    return { included: false, reason: 'sem conteúdo local para enviar' };
+  }
+  if (force === true) {
+    return versioned
+      ? { included: true, reason: '--config-in-pr' }
+      : { included: true, reason: `--config-in-pr (passa a versionar o ${CONFIG_FILE})` };
+  }
+  if (!versioned) {
+    return {
+      included: false,
+      reason: 'não está versionado na base, segue apenas local ' +
+        '(use --config-in-pr para versioná-lo)',
+    };
+  }
+  if (!willRegenerate && remote === desired) {
+    return { included: false, reason: 'já idêntico na base' };
+  }
+  return { included: true, reason: 'versionado na base e divergente do local' };
+}
+
+/**
+ * Traduz o erro cru da Git Data API para uma dica acionável (função PURA).
+ *
+ * Sem isto o usuário vê "Not Found" num POST e conclui que o repositório não
+ * existe, quando o problema é um token sem escrita em Contents — e "Resource not
+ * accessible" não diz QUAL permissão falta.
+ *
+ * @param {{status?: number, message?: string}} err
+ * @returns {string}
+ */
+export function explainGitWriteError(err) {
+  const msg = err?.message || 'erro desconhecido';
+  switch (err?.status) {
+    case 401:
+      return `${msg} — token inválido ou expirado.`;
+    case 403:
+      return `${msg} — o token não tem permissão de escrita. Precisa de "Contents: write" e ` +
+        '"Pull requests: write" (fine-grained) ou do escopo `repo` (classic).';
+    case 404:
+      return `${msg} — repositório ou branch inexistente, OU token sem acesso a este ` +
+        'repositório (o GitHub responde 404 em vez de 403 para não revelar repos privados).';
+    case 409:
+      return `${msg} — repositório vazio (sem nenhum commit): rode \`spec-wave init\` antes.`;
+    case 422:
+      return `${msg} — o GitHub recusou a operação. Causas comuns: regra de proteção/ruleset ` +
+        'na branch (commits da API não são assinados) ou branch já em dia.';
+    default:
+      return msg;
+  }
+}

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() };
+}