@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/src/utils/agents-installer.js

@@ -1,447 +1,224 @@
-/**
- * Agents Installer
- *
- * Converts MORPH-SPEC tier-1 and tier-2 agents from agents.json into
- * native Claude Code subagent markdown files in .claude/agents/.
- *
- * Each file has YAML frontmatter (name, description, model, tools,
- * maxTurns, skills, memory) followed by the agent's spawn prompt as the body.
- */
-
-import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';
-import { join } from 'path';
-import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
-
-/**
- * Installs tier-1 and tier-2 morph agents as native Claude Code subagents
- * in .claude/agents/ with YAML frontmatter.
- *
- * @param {string} projectDir - Target project directory
- * @param {string} frameworkDir - Path to morph-spec framework/ directory
- * @param {object} options - Optional settings
- * @param {string|null} options.projectStack - Detected project stack (e.g. 'nextjs', 'blazor')
- */
-export async function installAgents(projectDir, frameworkDir = 'framework', options = {}) {
-  const { projectTags = [] } = options;
-
-  const agentsJsonPath = join(frameworkDir, 'agents.json');
-  const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
-
-  // Support both object map and array formats
-  const agentsRaw = agentsJson.agents ?? agentsJson;
-  const agents = Array.isArray(agentsRaw)
-    ? agentsRaw
-    : Object.entries(agentsRaw)
-        .filter(([key]) => !key.startsWith('_comment'))
-        .map(([id, data]) => ({ id, ...data }));
-
-  const targetDir = join(projectDir, '.claude', 'agents');
-  mkdirSync(targetDir, { recursive: true });
-
-  const eligible = agents.filter(a => {
-    if (a.tier < 1 || a.tier > 4) return false;
-    // Must have a teammate with spawn_prompt (except tier-1 orchestrators which always have one)
-    if (a.tier >= 3 && !a.teammate?.spawn_prompt) return false;
-    // Filter by stacks if the agent declares them
-    const stacks = a.stacks ?? [];
-    if (!shouldInstall(stacks, projectTags)) return false;
-    return true;
-  });
-
-  let tier1 = 0;
-  let tier2 = 0;
-  let tier3 = 0;
-  let tier4 = 0;
-  const installed = new Set();
-
-  // Build the full set of possible filenames for orphan cleanup
-  const allPossible = new Set();
-  for (const a of agents) {
-    if (a.tier < 1 || a.tier > 4) continue;
-    const slug = a.id ?? a.name?.toLowerCase().replace(/\s+/g, '-');
-    const prefix = a.tier === 4 ? 'morph-validator-' : 'morph-';
-    allPossible.add(`${prefix}${slug}.md`);
-  }
-
-  for (const agent of eligible) {
-    const slug = agent.id ?? agent.name?.toLowerCase().replace(/\s+/g, '-');
-    const prefix = agent.tier === 4 ? 'morph-validator-' : 'morph-';
-    const filename = `${prefix}${slug}.md`;
-    const targetPath = join(targetDir, filename);
-
-    const description = buildDescription(agent);
-    const body = buildBody(agent);
-
-    const frontmatter = buildFrontmatter(agent, description);
-    const content = `---\n${frontmatter}---\n\n${body}\n`;
-    writeFileSync(targetPath, content, 'utf-8');
-    installed.add(filename);
-
-    if (agent.tier === 1) tier1++;
-    else if (agent.tier === 2) tier2++;
-    else if (agent.tier === 3) tier3++;
-    else if (agent.tier === 4) tier4++;
-  }
-
-  // Cleanup orphan morph-* / morph-validator-* files that were filtered out
-  for (const file of readdirSync(targetDir)) {
-    if (allPossible.has(file) && !installed.has(file)) {
-      unlinkSync(join(targetDir, file));
-    }
-    // Remove morph-domain-{name}.md when morph-{name}.md was installed from agents.json
-    if (file.startsWith('morph-domain-')) {
-      const suffix = file.slice('morph-domain-'.length);
-      if (installed.has(`morph-${suffix}`)) {
-        unlinkSync(join(targetDir, file));
-      }
-    }
-  }
-
-  return { tier1, tier2, tier3, tier4 };
-}
-
-/**
- * Tier-based defaults for Claude Code subagent frontmatter fields.
- *
- * Tier 1 (Orchestrators): opus model, can spawn subagents via Agent tool, 30 turns, project memory, high effort.
- * Tier 2 (Domain Leaders): sonnet model, coordinate specialists, 20 turns, local memory, medium effort.
- * Tier 3 (Specialists): sonnet model, implementation focus, 15 turns, local memory, medium effort.
- * Tier 4 (Validators): haiku model, read-only scanning, 10 turns, background execution, low effort.
- */
-const TIER_DEFAULTS = {
-  1: {
-    model: 'opus',
-    tools: 'Read, Grep, Glob, Bash, Agent, Write, Edit',
-    maxTurns: 30,
-    skills: ['morph-checklist'],
-    memory: 'project',
-    effort: 'high',
-    permissionMode: 'acceptEdits',
-    background: false,
-  },
-  2: {
-    model: 'sonnet',
-    tools: 'Read, Write, Edit, Bash, Glob, Grep',
-    maxTurns: 20,
-    skills: ['morph-checklist'],
-    memory: 'local',
-    effort: 'medium',
-    permissionMode: 'acceptEdits',
-    background: false,
-  },
-  3: {
-    model: 'sonnet',
-    tools: 'Read, Write, Edit, Bash, Glob, Grep',
-    maxTurns: 15,
-    skills: [],
-    memory: 'local',
-    effort: 'medium',
-    permissionMode: 'default',
-    background: false,
-  },
-  4: {
-    model: 'haiku',
-    tools: 'Read, Glob, Grep',
-    maxTurns: 10,
-    skills: [],
-    memory: 'project',
-    effort: 'low',
-    permissionMode: 'plan',
-    background: true,
-  },
-};
-
-/**
- * Builds the YAML frontmatter content (without --- delimiters) for an agent file.
- * Returns a string ending with a blank line.
- *
- * @param {object} agent - Agent definition from agents.json
- * @param {string} description - Pre-built description string
- * @returns {string}
- */
-function buildFrontmatter(agent, description) {
-  const defaults = TIER_DEFAULTS[agent.tier] ?? TIER_DEFAULTS[2];
-  const name = agent.title ?? agent.name;
-
-  // Allow per-agent overrides from teammate config
-  const tools = agent.teammate?.tools ?? defaults.tools;
-  const maxTurns = agent.teammate?.maxTurns ?? defaults.maxTurns;
-  const effort = agent.teammate?.effort ?? defaults.effort;
-  const permissionMode = agent.teammate?.permissionMode ?? defaults.permissionMode;
-  const background = agent.teammate?.background ?? defaults.background;
-  // color is a top-level field on the agent (not inside teammate)
-  const color = agent.color;
-
-  const lines = [
-    `name: ${name}`,
-    `description: ${description}`,
-    `model: ${defaults.model}`,
-    `tools: ${tools}`,
-    `maxTurns: ${maxTurns}`,
-  ];
-
-  if (color) lines.push(`color: ${color}`);
-  if (effort) lines.push(`effort: ${effort}`);
-  if (permissionMode && permissionMode !== 'default') lines.push(`permissionMode: ${permissionMode}`);
-  if (background) lines.push(`background: true`);
-
-  if (defaults.skills.length > 0) {
-    const skillsList = defaults.skills.map(s => `  - ${s}`).join('\n');
-    lines.push(`skills:`, skillsList);
-  }
-
-  lines.push(`memory: ${defaults.memory}`, '');
-  return lines.join('\n');
-}
-
-/** Maps agent group to task categories for routing hints in description */
-const GROUP_TO_CATEGORIES = {
-  'backend': 'Domain, Infrastructure, Application',
-  'frontend': 'Presentation',
-  'domain-analysis': 'Architecture, Cross-cutting',
-  'testing': 'Tests',
-  'infra': 'Infra, DevOps',
-  'ai': 'AI, Automation',
-};
-
-function buildDescription(agent) {
-  const role = agent.teammate?.role ?? `Handles ${(agent.domains ?? []).join(', ')}`;
-  const triggers = agent.teammate?.triggers;
-  const categories = GROUP_TO_CATEGORIES[agent.group];
-
-  let desc = role;
-  if (triggers) {
-    desc += `. Use proactively when: ${triggers}`;
-  } else if (categories) {
-    desc += ` | Tasks: ${categories}`;
-  }
-
-  // Truncate to 200 chars for settings display
-  return desc.length > 200 ? desc.slice(0, 197) + '...' : desc;
-}
-
-/**
- * Serialize an AgentStandard to a readable markdown line.
- *
- * @param {string|{id: string, scope?: string, priority?: string}} standard
- * @returns {string} e.g., "- core-coding (all, required)" or "- core-coding"
- */
-export function formatStandardRef(standard) {
-  if (typeof standard === 'string') return `- ${standard}`;
-  const id = standard.id || String(standard);
-  const parts = [standard.scope, standard.priority].filter(Boolean);
-  return parts.length > 0 ? `- ${id} (${parts.join(', ')})` : `- ${id}`;
-}
-
-function buildBody(agent) {
-  const lines = [];
-  if (agent.teammate?.spawn_prompt) {
-    lines.push(agent.teammate.spawn_prompt);
-  } else {
-    lines.push(`You are the ${agent.title} agent in the MORPH-SPEC framework.`);
-    if (agent.domains?.length) {
-      lines.push(`\n## Domains\n${agent.domains.map(d => `- ${d}`).join('\n')}`);
-    }
-  }
-
-  // Task routing — tells the agent which task categories it handles
-  const categories = GROUP_TO_CATEGORIES[agent.group];
-  if (categories) {
-    lines.push(`\n## Task Routing\nHandle tasks categorized as: ${categories}`);
-  }
-
-  // Key standards — @ references for upfront awareness
-  if (agent.standards?.length) {
-    lines.push(`\n## Key Standards\n${agent.standards.map(formatStandardRef).join('\n')}`);
-  }
-  return lines.join('\n');
-}
-
-/**
- * Parses YAML frontmatter from a skill markdown file.
- * Handles both inline values and YAML block scalars (>).
- *
- * @param {string} rawContent - Raw file content
- * @returns {{ name: string|null, description: string|null, allowedTools: string, color: string|null, effort: string|null, permissionMode: string|null, background: boolean, stacks: string[], body: string }}
- */
-export function parseSkillFile(rawContent) {
-  // Normalize CRLF to LF for consistent parsing on Windows
-  const content = rawContent.replace(/\r\n/g, '\n');
-  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) return { name: null, description: null, allowedTools: 'Read, Write, Edit, Bash, Glob, Grep', color: null, effort: null, permissionMode: null, background: false, body: rawContent };
-
-  const fm = match[1];
-  const body = match[2];
-
-  const name = (fm.match(/^name:\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
-  const allowedTools = (fm.match(/^allowed-tools:\s*(.+)$/m) ?? [])[1]?.trim() ?? 'Read, Write, Edit, Bash, Glob, Grep';
-  const color = (fm.match(/^color:\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
-  const effort = (fm.match(/^effort:\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
-  const permissionMode = (fm.match(/^permissionMode:\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
-  const background = (fm.match(/^background:\s*(.+)$/m) ?? [])[1]?.trim() === 'true';
-
-  let description = null;
-  const blockMatch = fm.match(/^description:\s*>\s*\n((?:[ \t]+.*\n?)*)/m);
-  if (blockMatch) {
-    description = blockMatch[1].trim().replace(/\s+/g, ' ');
-  } else {
-    const inlineMatch = fm.match(/^description:\s*(.+)$/m);
-    if (inlineMatch) description = inlineMatch[1].trim();
-  }
-
-  const stacks = parseStacks(rawContent);
-  return { name, description, allowedTools, color, effort, permissionMode, background, stacks, body };
-}
-
-/**
- * Recursively collects all .md skill files from a directory, excluding README.md.
- *
- * @param {string} dir - Directory to walk
- * @returns {string[]} Absolute paths to skill .md files
- */
-export function collectSkillFiles(dir) {
-  const results = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      results.push(...collectSkillFiles(fullPath));
-    } else if (entry.name.endsWith('.md') && entry.name !== 'README.md') {
-      results.push(fullPath);
-    }
-  }
-  return results;
-}
-
-/**
- * Installs domain agent files as native Claude Code subagents
- * in .claude/agents/ with memory:project, model:sonnet, maxTurns:20.
- * Supports optional CC-native fields (color, effort, permissionMode, background)
- * declared in each domain file's YAML frontmatter.
- *
- * @param {string} projectDir - Target project directory
- * @param {string} frameworkDir - Path to morph-spec framework/ directory
- */
-export async function installDomainAgents(projectDir, frameworkDir = 'framework', { projectTags = [] } = {}) {
-  const domainsDir = join(frameworkDir, 'agents');
-  if (!existsSync(domainsDir)) return { specialists: 0 };
-
-  const targetDir = join(projectDir, '.claude', 'agents');
-  mkdirSync(targetDir, { recursive: true });
-
-  let specialists = 0;
-  const installed = new Set();
-  for (const filePath of collectSkillFiles(domainsDir)) {
-    const raw = readFileSync(filePath, 'utf-8');
-    const { name, description, allowedTools, color, effort, permissionMode, background, stacks, body } = parseSkillFile(raw);
-    if (!name) continue;
-    if (!shouldInstall(stacks, projectTags)) continue;
-
-    const desc = description ?? `MORPH-SPEC domain agent: ${name}`;
-    const lines = [
-      `name: ${name}`,
-      `description: ${desc}`,
-      `model: sonnet`,
-      `tools: ${allowedTools}`,
-      `maxTurns: 20`,
-    ];
-    if (color) lines.push(`color: ${color}`);
-    if (effort) lines.push(`effort: ${effort}`);
-    if (permissionMode && permissionMode !== 'default') lines.push(`permissionMode: ${permissionMode}`);
-    if (background) lines.push(`background: true`);
-    lines.push(`memory: project`, '');
-    const frontmatter = lines.join('\n');
-
-    // If agents.json already generated morph-{name}.md, append domain content there
-    const agentsJsonFile = `morph-${name}.md`;
-    const agentsJsonPath = join(targetDir, agentsJsonFile);
-    if (existsSync(agentsJsonPath)) {
-      appendFileSync(agentsJsonPath, `\n\n---\n\n## Domain Knowledge\n\n${body.trimStart()}`, 'utf-8');
-      specialists++;
-    } else {
-      const filename = `morph-domain-${name}.md`;
-      const targetPath = join(targetDir, filename);
-      writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body.trimStart()}`, 'utf-8');
-      installed.add(filename);
-      specialists++;
-    }
-  }
-
-  // Cleanup orphan morph-domain-* files
-  for (const file of readdirSync(targetDir)) {
-    if (file.startsWith('morph-domain-') && !installed.has(file)) {
-      unlinkSync(join(targetDir, file));
-    }
-  }
-
-  return { specialists };
-}
-
-/**
- * Check which agents SHOULD be installed but are NOT.
- * Returns a list of missing agent names with their source (agents.json or domain).
- *
- * @param {string} projectDir - Target project directory
- * @param {string} frameworkDir - Path to morph-spec framework/ directory
- * @param {string[]} projectTags - Stack + integration tags
- * @returns {{ missing: Array<{ name: string, stacks: string[], source: string }>, installed: number, expected: number }}
- */
-export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
-  const targetDir = join(projectDir, '.claude', 'agents');
-  const installedFiles = new Set();
-  if (existsSync(targetDir)) {
-    for (const f of readdirSync(targetDir)) installedFiles.add(f);
-  }
-
-  const missing = [];
-  let expected = 0;
-
-  // Check tier 1/2/4 from agents.json
-  const agentsJsonPath = join(frameworkDir, 'agents.json');
-  if (existsSync(agentsJsonPath)) {
-    const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
-    const agentsRaw = agentsJson.agents ?? agentsJson;
-    const agents = Array.isArray(agentsRaw)
-      ? agentsRaw
-      : Object.entries(agentsRaw)
-          .filter(([key]) => !key.startsWith('_comment'))
-          .map(([id, data]) => ({ id, ...data }));
-
-    for (const a of agents) {
-      if (a.tier < 1 || a.tier > 4) continue;
-      if (a.tier >= 3 && !a.teammate?.spawn_prompt) continue;
-      const stacks = a.stacks ?? [];
-      if (!shouldInstall(stacks, projectTags)) continue;
-
-      expected++;
-      const slug = a.id ?? a.name?.toLowerCase().replace(/\s+/g, '-');
-      const prefix = a.tier === 4 ? 'morph-validator-' : 'morph-';
-      const filename = `${prefix}${slug}.md`;
-      if (!installedFiles.has(filename)) {
-        missing.push({ name: a.title ?? slug, stacks, source: `tier-${a.tier}` });
-      }
-    }
-  }
-
-  // Check domain agents (skip if merged into agents.json entry)
-  const domainsDir = join(frameworkDir, 'agents');
-  if (existsSync(domainsDir)) {
-    for (const filePath of collectSkillFiles(domainsDir)) {
-      const raw = readFileSync(filePath, 'utf-8');
-      const { name, stacks } = parseSkillFile(raw);
-      if (!name) continue;
-      if (!shouldInstall(stacks, projectTags)) continue;
-
-      // If agents.json has morph-{name}.md, domain content is merged there
-      const agentsJsonFile = `morph-${name}.md`;
-      if (installedFiles.has(agentsJsonFile)) continue;
-
-      expected++;
-      const filename = `morph-domain-${name}.md`;
-      if (!installedFiles.has(filename)) {
-        missing.push({ name, stacks, source: 'domain' });
-      }
-    }
-  }
-
-  return { missing, installed: installedFiles.size, expected };
-}
+/**
+ * Agents Installer (v5)
+ *
+ * Installs morph-spec domain personas as native Claude Code subagents
+ * in .claude/agents/morph-{id}.md.
+ *
+ * In v5 the harness has 7 domain personas (no tiers) — each persona is a
+ * subagent the Specialist (Claude in implementer role) can dispatch when
+ * working in that domain. The 3 roles (Orchestrator/Specialist/Evaluator)
+ * are assumed by Claude itself per MORPH.md, not as separate agents.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'path';
+import { shouldInstall } from '../lib/stack-filter.js';
+
+/**
+ * Install morph-spec domain personas as native Claude Code subagents.
+ *
+ * @param {string} projectDir - Target project directory
+ * @param {string} frameworkDir - Path to morph-spec framework/ directory
+ * @param {object} options
+ * @param {string[]} [options.projectTags=[]] - Stack tags from config (e.g. ['dotnet', 'nextjs'])
+ * @returns {Promise<{ installed: number }>}
+ */
+export async function installAgents(projectDir, frameworkDir = 'framework', options = {}) {
+  const { projectTags = [] } = options;
+
+  const agentsJsonPath = join(frameworkDir, 'agents.json');
+  const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
+
+  const agentsRaw = agentsJson.agents ?? {};
+  const agents = Object.entries(agentsRaw)
+    .filter(([key]) => !key.startsWith('_comment'))
+    .map(([id, data]) => ({ id, ...data }));
+
+  const targetDir = join(projectDir, '.claude', 'agents');
+  mkdirSync(targetDir, { recursive: true });
+
+  // Filter by stack
+  const eligible = agents.filter(a => {
+    const stack = a.stack ?? ['*'];
+    return shouldInstall(stack, projectTags);
+  });
+
+  // Build set of all possible filenames for orphan cleanup
+  const allPossible = new Set(agents.map(a => `morph-${a.id}.md`));
+
+  let installed = 0;
+  const installedFilenames = new Set();
+
+  for (const agent of eligible) {
+    const filename = `morph-${agent.id}.md`;
+    const targetPath = join(targetDir, filename);
+
+    const description = buildDescription(agent);
+    const body = buildBody(agent);
+    const frontmatter = buildFrontmatter(agent, description);
+
+    writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body}\n`, 'utf-8');
+    installedFilenames.add(filename);
+    installed++;
+  }
+
+  // Cleanup orphan morph-* files filtered out by stack
+  for (const file of readdirSync(targetDir)) {
+    if (allPossible.has(file) && !installedFilenames.has(file)) {
+      unlinkSync(join(targetDir, file));
+    }
+  }
+
+  return { installed };
+}
+
+function buildFrontmatter(agent, description) {
+  const lines = [
+    `name: ${agent.id}`,
+    `description: ${description}`,
+    `model: sonnet`,
+    `tools: Read, Write, Edit, Bash, Glob, Grep`,
+    `maxTurns: 20`,
+  ];
+  if (agent.color) lines.push(`color: ${agent.color}`);
+  lines.push(`memory: project`, '');
+  return lines.join('\n');
+}
+
+function buildDescription(agent) {
+  const role = agent.title ?? agent.id;
+  const domains = (agent.domains ?? []).join(', ');
+  const desc = domains ? `${role} — domains: ${domains}` : role;
+  return desc.length > 200 ? desc.slice(0, 197) + '...' : desc;
+}
+
+function buildBody(agent) {
+  const lines = [
+    `# ${agent.title ?? agent.id}`,
+    '',
+    agent.persona ?? `You are the ${agent.title} persona for morph-spec.`,
+    '',
+  ];
+
+  if (agent.domains?.length) {
+    lines.push('## Domains', ...agent.domains.map(d => `- ${d}`), '');
+  }
+
+  if (agent.standards?.length) {
+    lines.push('## Standards to consult on demand');
+    for (const s of agent.standards) lines.push(`- ${s}`);
+    lines.push('');
+  }
+
+  lines.push(
+    '## How you operate',
+    '',
+    'You are a domain persona dispatched per task. Read the spec/mandate/tasks/standards passed to you, do the work, and return a concise summary plus an auto-score 0-10. Refer to MORPH.md section 6 for the dispatch contract.',
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Compatibility shim for older callers that expected installDomainAgents.
+ * In v5 there is no separate "domain" install step — installAgents handles
+ * everything from agents.json.
+ */
+export async function installDomainAgents(projectDir, frameworkDir, options) {
+  // No-op: domain content is now defined inline in agents.json (persona field).
+  return { specialists: 0 };
+}
+
+/**
+ * Check which agents SHOULD be installed but are NOT.
+ *
+ * @param {string} projectDir
+ * @param {string} frameworkDir
+ * @param {string[]} projectTags
+ * @returns {{ missing: Array<{ name: string, stacks: string[] }>, installed: number, expected: number }}
+ */
+export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
+  const targetDir = join(projectDir, '.claude', 'agents');
+  const installedFiles = new Set();
+  if (existsSync(targetDir)) {
+    for (const f of readdirSync(targetDir)) installedFiles.add(f);
+  }
+
+  const agentsJsonPath = join(frameworkDir, 'agents.json');
+  if (!existsSync(agentsJsonPath)) {
+    return { missing: [], installed: installedFiles.size, expected: 0 };
+  }
+
+  const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
+  const agentsRaw = agentsJson.agents ?? {};
+  const agents = Object.entries(agentsRaw)
+    .filter(([key]) => !key.startsWith('_comment'))
+    .map(([id, data]) => ({ id, ...data }));
+
+  const missing = [];
+  let expected = 0;
+
+  for (const a of agents) {
+    const stack = a.stack ?? ['*'];
+    if (!shouldInstall(stack, projectTags)) continue;
+    expected++;
+    const filename = `morph-${a.id}.md`;
+    if (!installedFiles.has(filename)) {
+      missing.push({ name: a.title ?? a.id, stacks: stack });
+    }
+  }
+
+  return { missing, installed: installedFiles.size, expected };
+}
+
+/**
+ * Compatibility export — kept so existing tests/CLI code that imports
+ * formatStandardRef or parseSkillFile / collectSkillFiles still work,
+ * but they are no-ops (will be removed in v5.1).
+ */
+export function formatStandardRef(standard) {
+  if (typeof standard === 'string') return `- ${standard}`;
+  const id = standard.id || String(standard);
+  const parts = [standard.scope, standard.priority].filter(Boolean);
+  return parts.length > 0 ? `- ${id} (${parts.join(', ')})` : `- ${id}`;
+}
+
+export function parseSkillFile(rawContent) {
+  const content = rawContent.replace(/\r\n/g, '\n');
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    return {
+      name: null, description: null, allowedTools: 'Read, Write, Edit, Bash, Glob, Grep',
+      color: null, effort: null, permissionMode: null, background: false, stacks: [],
+      body: rawContent,
+    };
+  }
+  const fm = match[1];
+  const body = match[2];
+  const name = (fm.match(/^name:\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
+  const allowedTools = (fm.match(/^allowed-tools:\s*(.+)$/m) ?? [])[1]?.trim() ?? 'Read, Write, Edit, Bash, Glob, Grep';
+  const color = (fm.match(/^color:\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
+  let description = null;
+  const blockMatch = fm.match(/^description:\s*>\s*\n((?:[ \t]+.*\n?)*)/m);
+  if (blockMatch) {
+    description = blockMatch[1].trim().replace(/\s+/g, ' ');
+  } else {
+    const inlineMatch = fm.match(/^description:\s*(.+)$/m);
+    if (inlineMatch) description = inlineMatch[1].trim();
+  }
+  return { name, description, allowedTools, color, effort: null, permissionMode: null, background: false, stacks: [], body };
+}
+
+export function collectSkillFiles(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectSkillFiles(fullPath));
+    } else if (entry.name.endsWith('.md') && entry.name !== 'README.md') {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}