@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

package/src/lib/validators/shared/issue-counter.js

@@ -1,18 +1,14 @@
-/**
- * Shared issue counting utility for validators
- *
- * Consolidates duplicate implementations from:
- * - blazor-validator.js
- * - blazor-state-validator.js
- * - blazor-concurrency-analyzer.js
- *
- * @param {Array} issues - Array of validation issues with type property
- * @returns {{errors: number, warnings: number, infos: number}} Count by type
- */
-export function countIssues(issues) {
-  return {
-    errors: issues.filter((i) => i.type === 'error').length,
-    warnings: issues.filter((i) => i.type === 'warning').length,
-    infos: issues.filter((i) => i.type === 'info').length,
-  };
-}
+/**
+ * Shared issue counting utility for validators
+ *
+ *
+ * @param {Array} issues - Array of validation issues with type property
+ * @returns {{errors: number, warnings: number, infos: number}} Count by type
+ */
+export function countIssues(issues) {
+  return {
+    errors: issues.filter((i) => i.type === 'error').length,
+    warnings: issues.filter((i) => i.type === 'warning').length,
+    infos: issues.filter((i) => i.type === 'info').length,
+  };
+}

package/src/lib/validators/validation-runner.js

@@ -14,10 +14,9 @@ import { loadState } from '../../core/state/state-manager.js';
 import { getAbsoluteOutputPath, resolveContractsOutputType } from '../../core/paths/output-schema.js';
 import { getStackProfile } from '../stack/stack-profile.js';
 
-/** Validators that only make sense for .NET/Blazor projects. */
+/** Validators that only make sense for .NET projects. */
 const DOTNET_ONLY_VALIDATORS = new Set([
-  'architecture', 'packages', 'blazor', 'blazor-concurrency',
-  'blazor-state', 'contract-compliance'
+  'architecture', 'packages', 'contract-compliance'
 ]);
 
 /**
@@ -26,7 +25,7 @@ const DOTNET_ONLY_VALIDATORS = new Set([
  */
 const HEAVY_VALIDATORS = new Set([
   'architecture', 'packages', 'contract-compliance',
-  'blazor-concurrency', 'css', 'design-system'
+  'css', 'design-system'
 ]);
 
 /**
@@ -228,21 +227,6 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
       return await validateContrast(projectPath, options);
     }
 
-    case 'blazor': {
-      const { validateBlazorPatterns } = await import('./blazor/blazor-validator.js');
-      return await validateBlazorPatterns(projectPath, options);
-    }
-
-    case 'blazor-concurrency': {
-      const { validateConcurrencyFiles } = await import('./blazor/blazor-concurrency-analyzer.js');
-      return await validateConcurrencyFiles(projectPath, options);
-    }
-
-    case 'blazor-state': {
-      const { validateState } = await import('./blazor/blazor-state-validator.js');
-      return await validateState(projectPath, options);
-    }
-
     case 'css': {
       const { validateCss } = await import('./css/css-validator.js');
       return await validateCss(projectPath, options);

package/src/scripts/setup-infra.js

@@ -141,7 +141,7 @@ export async function setupInfra(targetPath, { _exec = execSync } = {}) {
   const contextReadmePath = join(contextDir, 'README.md');
   if (!(await pathExists(contextReadmePath))) {
     const dirName = targetPath.split(/[\/]/).pop();
-    const readmeContent = `# ${dirName} — Project Context\n\nRun /morph-init to generate project context.\n`;
+    const readmeContent = `# ${dirName} — Project Context\n\nRun \`morph-spec context refresh\` to generate architecture context.\n`;
     await writeFile(contextReadmePath, readmeContent);
   }
 

package/src/utils/agents-installer.js

@@ -103,23 +103,31 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 /**
  * Tier-based defaults for Claude Code subagent frontmatter fields.
  *
- * Tier 1 (Orchestrators): can spawn subagents via Task tool, 30 turns, project memory.
- * Tier 2 (Domain Leaders): coordinate specialists but do not spawn subagents, 20 turns, local memory.
+ * 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: 'inherit',
-    tools: 'Read, Grep, Glob, Bash, Task, Write, Edit',
+    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: 'inherit',
+    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',
@@ -127,6 +135,9 @@ const TIER_DEFAULTS = {
     maxTurns: 15,
     skills: [],
     memory: 'local',
+    effort: 'medium',
+    permissionMode: 'default',
+    background: false,
   },
   4: {
     model: 'haiku',
@@ -134,6 +145,9 @@ const TIER_DEFAULTS = {
     maxTurns: 10,
     skills: [],
     memory: 'project',
+    effort: 'low',
+    permissionMode: 'plan',
+    background: true,
   },
 };
 
@@ -149,10 +163,14 @@ function buildFrontmatter(agent, description) {
   const defaults = TIER_DEFAULTS[agent.tier] ?? TIER_DEFAULTS[2];
   const name = agent.title ?? agent.name;
 
-  // Allow per-agent tool overrides (e.g., morph-spec-validator needs Bash for npm test)
+  // Allow per-agent overrides from teammate config
   const tools = agent.teammate?.tools ?? defaults.tools;
-  // Allow per-agent maxTurns override
   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}`,
@@ -162,6 +180,11 @@ function buildFrontmatter(agent, description) {
     `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);
@@ -171,10 +194,30 @@ function buildFrontmatter(agent, description) {
   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 base = agent.teammate?.role ?? `Handles ${(agent.domains ?? []).join(', ')}`;
+  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 base.length > 200 ? base.slice(0, 197) + '...' : base;
+  return desc.length > 200 ? desc.slice(0, 197) + '...' : desc;
 }
 
 /**
@@ -200,8 +243,16 @@ function buildBody(agent) {
       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## Standards to Reference\n${agent.standards.map(formatStandardRef).join('\n')}`);
+    lines.push(`\n## Key Standards\n${agent.standards.map(formatStandardRef).join('\n')}`);
   }
   return lines.join('\n');
 }

package/src/utils/file-copier.js

@@ -149,6 +149,7 @@ export async function updateGitignore(projectPath) {
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
     '.worktrees/',
+    '.playwright-mcp/',
     'docs/superpowers/',
     ''
   ];

package/src/utils/hooks-installer.js

@@ -15,7 +15,7 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 
 /** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '2.13.0';
+const HOOKS_VERSION = '2.14.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -70,6 +70,16 @@ const MORPH_HOOKS = [
     }]
   },
 
+  // === SessionStart: resume only — orientation context ===
+  {
+    event: 'SessionStart',
+    matcher: 'resume',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/session-start/resume-context.js'
+    }]
+  },
+
   // === UserPromptSubmit ===
   {
     event: 'UserPromptSubmit',
@@ -138,14 +148,6 @@ Otherwise respond: {"ok": true}`
         type: 'command',
         command: 'node framework/hooks/claude-code/post-tool-use/dispatch.js'
       },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/post-tool-use/context-refresh.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/post-tool-use/skill-reminder.js'
-      },
       {
         type: 'command',
         command: 'node framework/hooks/claude-code/post-tool-use/validator-feedback.js'
@@ -184,16 +186,6 @@ Otherwise respond: {"ok": true}`
     }]
   },
 
-  // === Notification ===
-  {
-    event: 'Notification',
-    matcher: 'idle_prompt',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/notification/approval-reminder.js'
-    }]
-  },
-
   // === TeammateIdle ===
   // Fires when an Agent Team teammate finishes and is about to go idle.
   // Exit 2 = send feedback to teammate to continue working (validation failed).

package/src/utils/skills-installer.js

@@ -1,178 +1,178 @@
-/**
- * Skills Installer
- *
- * Copies framework skills to .claude/skills/ during morph-spec init.
- * Installs level-0-meta and level-1-workflows skills using the native Claude Code
- * subdirectory format: .claude/skills/{skill-name}/SKILL.md (plus optional
- * scripts/, references/, and assets/ subdirectories).
- * Level-2 domain specialists are installed as native subagents via installDomainAgents().
- * Level-3 and level-4 only contain README.md placeholder files and are skipped.
- *
- * Source skills can be either:
- *   - Directory-based: framework/skills/{level}/{skill-name}/SKILL.md  (preferred)
- *   - Flat file: framework/skills/{level}/{skill-name}.md               (legacy, still supported)
- *
- * Directory-based skills have their entire directory copied (scripts/, references/,
- * assets/) so Claude Code can execute scripts and load references on demand.
- */
-
-import { mkdirSync, copyFileSync, existsSync, readdirSync, statSync, readFileSync, rmSync } from 'fs';
-import { join } from 'path';
-import { fileURLToPath } from 'url';
-import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
-
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
-const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
-
-/**
- * Skill levels to install in .claude/skills/.
- * Level-0 meta skills (planning, reviewing) and level-1 workflow skills
- * (phase-design, phase-implement, etc.) are installed. Level-2 domain
- * specialists are installed as native subagents via installDomainAgents()
- * instead. Level-3 and level-4 are skipped (no content yet).
- */
-const SKILL_LEVELS_TO_INSTALL = ['level-0-meta', 'level-1-workflows'];
-
-/**
- * Check if a skill should be installed based on its stacks: frontmatter.
- * @param {string} skillContent - Raw SKILL.md content
- * @param {string[]} projectTags - Stack tags from config
- * @returns {boolean}
- */
-export function shouldInstallSkill(skillContent, projectTags) {
-  return shouldInstall(parseStacks(skillContent), projectTags);
-}
-
-/**
- * Recursively copy a directory tree from src to dest.
- * Creates dest if it doesn't exist. Skips README.md files.
- *
- * @param {string} src - Source directory path
- * @param {string} dest - Destination directory path
- */
-function copyDirectory(src, dest) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    if (entry === 'README.md') continue;
-    const srcPath = join(src, entry);
-    const destPath = join(dest, entry);
-    if (statSync(srcPath).isDirectory()) {
-      copyDirectory(srcPath, destPath);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-/**
- * Walk srcDir and install skills into destDir.
- *
- * Handles two source formats:
- *   1. Directory-based skill: srcDir/{skill-name}/SKILL.md
- *      → copies entire directory (SKILL.md + scripts/ + references/ + assets/)
- *      → destDir/{skill-name}/
- *
- *   2. Flat .md skill (legacy): srcDir/{skill-name}.md
- *      → destDir/{skill-name}/SKILL.md
- *
- * Level directories (level-0-meta, level-1-workflows, sub-categories) are
- * traversed recursively. A directory is recognized as a skill directory when
- * it contains a SKILL.md file.
- *
- * @param {string} srcDir - Source directory to walk
- * @param {string} destDir - Destination base directory (.claude/skills/)
- */
-function installSkillsFromDir(srcDir, destDir, projectTags) {
-  const entries = readdirSync(srcDir);
-  for (const entry of entries) {
-    const srcPath = join(srcDir, entry);
-    const stat = statSync(srcPath);
-
-    if (stat.isDirectory()) {
-      const skillMdPath = join(srcPath, 'SKILL.md');
-      if (existsSync(skillMdPath)) {
-        // Directory-based skill — check stack filter before copying
-        const content = readFileSync(skillMdPath, 'utf-8');
-        if (!shouldInstallSkill(content, projectTags)) continue;
-        const skillDestDir = join(destDir, entry);
-        copyDirectory(srcPath, skillDestDir);
-      } else {
-        // Level/category directory — recurse
-        installSkillsFromDir(srcPath, destDir, projectTags);
-      }
-    } else if (entry.endsWith('.md') && entry !== 'README.md') {
-      // Legacy flat .md skill — check stack filter before copying
-      const content = readFileSync(srcPath, 'utf-8');
-      if (!shouldInstallSkill(content, projectTags)) continue;
-      const skillName = entry.slice(0, -3);
-      const skillDir = join(destDir, skillName);
-      mkdirSync(skillDir, { recursive: true });
-      copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
-    }
-  }
-}
-
-function collectSourceSkillNames() {
-  const names = new Set();
-  for (const level of SKILL_LEVELS_TO_INSTALL) {
-    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
-    if (!existsSync(levelDir)) continue;
-    collectNamesFromDir(levelDir, names);
-  }
-  return names;
-}
-
-function collectNamesFromDir(dir, names) {
-  for (const entry of readdirSync(dir)) {
-    const fullPath = join(dir, entry);
-    if (!statSync(fullPath).isDirectory()) continue;
-    if (existsSync(join(fullPath, 'SKILL.md'))) {
-      names.add(entry);
-    } else {
-      collectNamesFromDir(fullPath, names);
-    }
-  }
-}
-
-/**
- * Install morph framework skills to .claude/skills/ in the target project.
- * Skills are copied into subdirectories as SKILL.md files so Claude Code can
- * discover them natively via /<skill-name> syntax (e.g., /phase-design,
- * /blazor-builder). Directory-based skills also get their scripts/,
- * references/, and assets/ subdirectories copied for on-demand loading.
- *
- * Stack filtering: if projectTags is provided, only skills whose `stacks:`
- * frontmatter matches the project tags are installed. Skills without a
- * `stacks:` field are always installed (universal).
- *
- * @param {string} projectDir - Target project root directory
- * @param {Object} [options]
- * @param {string[]} [options.projectTags=[]] - Stack tags from config
- */
-export async function installSkills(projectDir, { projectTags = [] } = {}) {
-  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
-  mkdirSync(claudeSkillsDir, { recursive: true });
-
-  for (const level of SKILL_LEVELS_TO_INSTALL) {
-    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
-    if (!existsSync(levelDir)) continue;
-    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags);
-  }
-
-  // Collect installed morph-* skill names
-  const installed = new Set();
-  for (const entry of readdirSync(claudeSkillsDir)) {
-    if (existsSync(join(claudeSkillsDir, entry, 'SKILL.md'))) {
-      installed.add(entry);
-    }
-  }
-
-  // Cleanup orphan morph-* skill dirs that exist in source but were filtered out
-  const allSourceSkills = collectSourceSkillNames();
-  for (const entry of readdirSync(claudeSkillsDir)) {
-    if (!entry.startsWith('morph-')) continue;
-    if (!installed.has(entry) && allSourceSkills.has(entry)) {
-      rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
-    }
-  }
-}
+/**
+ * Skills Installer
+ *
+ * Copies framework skills to .claude/skills/ during morph-spec init.
+ * Installs level-0-meta and level-1-workflows skills using the native Claude Code
+ * subdirectory format: .claude/skills/{skill-name}/SKILL.md (plus optional
+ * scripts/, references/, and assets/ subdirectories).
+ * Level-2 domain specialists are installed as native subagents via installDomainAgents().
+ * Level-3 and level-4 only contain README.md placeholder files and are skipped.
+ *
+ * Source skills can be either:
+ *   - Directory-based: framework/skills/{level}/{skill-name}/SKILL.md  (preferred)
+ *   - Flat file: framework/skills/{level}/{skill-name}.md               (legacy, still supported)
+ *
+ * Directory-based skills have their entire directory copied (scripts/, references/,
+ * assets/) so Claude Code can execute scripts and load references on demand.
+ */
+
+import { mkdirSync, copyFileSync, existsSync, readdirSync, statSync, readFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
+
+/**
+ * Skill levels to install in .claude/skills/.
+ * Level-0 meta skills (planning, reviewing) and level-1 workflow skills
+ * (phase-design, phase-implement, etc.) are installed. Level-2 domain
+ * specialists are installed as native subagents via installDomainAgents()
+ * instead. Level-3 and level-4 are skipped (no content yet).
+ */
+const SKILL_LEVELS_TO_INSTALL = ['level-0-meta', 'level-1-workflows'];
+
+/**
+ * Check if a skill should be installed based on its stacks: frontmatter.
+ * @param {string} skillContent - Raw SKILL.md content
+ * @param {string[]} projectTags - Stack tags from config
+ * @returns {boolean}
+ */
+export function shouldInstallSkill(skillContent, projectTags) {
+  return shouldInstall(parseStacks(skillContent), projectTags);
+}
+
+/**
+ * Recursively copy a directory tree from src to dest.
+ * Creates dest if it doesn't exist. Skips README.md files.
+ *
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ */
+function copyDirectory(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    if (entry === 'README.md') continue;
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Walk srcDir and install skills into destDir.
+ *
+ * Handles two source formats:
+ *   1. Directory-based skill: srcDir/{skill-name}/SKILL.md
+ *      → copies entire directory (SKILL.md + scripts/ + references/ + assets/)
+ *      → destDir/{skill-name}/
+ *
+ *   2. Flat .md skill (legacy): srcDir/{skill-name}.md
+ *      → destDir/{skill-name}/SKILL.md
+ *
+ * Level directories (level-0-meta, level-1-workflows, sub-categories) are
+ * traversed recursively. A directory is recognized as a skill directory when
+ * it contains a SKILL.md file.
+ *
+ * @param {string} srcDir - Source directory to walk
+ * @param {string} destDir - Destination base directory (.claude/skills/)
+ */
+function installSkillsFromDir(srcDir, destDir, projectTags) {
+  const entries = readdirSync(srcDir);
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      const skillMdPath = join(srcPath, 'SKILL.md');
+      if (existsSync(skillMdPath)) {
+        // Directory-based skill — check stack filter before copying
+        const content = readFileSync(skillMdPath, 'utf-8');
+        if (!shouldInstallSkill(content, projectTags)) continue;
+        const skillDestDir = join(destDir, entry);
+        copyDirectory(srcPath, skillDestDir);
+      } else {
+        // Level/category directory — recurse
+        installSkillsFromDir(srcPath, destDir, projectTags);
+      }
+    } else if (entry.endsWith('.md') && entry !== 'README.md') {
+      // Legacy flat .md skill — check stack filter before copying
+      const content = readFileSync(srcPath, 'utf-8');
+      if (!shouldInstallSkill(content, projectTags)) continue;
+      const skillName = entry.slice(0, -3);
+      const skillDir = join(destDir, skillName);
+      mkdirSync(skillDir, { recursive: true });
+      copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
+    }
+  }
+}
+
+function collectSourceSkillNames() {
+  const names = new Set();
+  for (const level of SKILL_LEVELS_TO_INSTALL) {
+    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
+    if (!existsSync(levelDir)) continue;
+    collectNamesFromDir(levelDir, names);
+  }
+  return names;
+}
+
+function collectNamesFromDir(dir, names) {
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    if (!statSync(fullPath).isDirectory()) continue;
+    if (existsSync(join(fullPath, 'SKILL.md'))) {
+      names.add(entry);
+    } else {
+      collectNamesFromDir(fullPath, names);
+    }
+  }
+}
+
+/**
+ * Install morph framework skills to .claude/skills/ in the target project.
+ * Skills are copied into subdirectories as SKILL.md files so Claude Code can
+ * discover them natively via /<skill-name> syntax (e.g., /phase-design,
+ * /nextjs-expert). Directory-based skills also get their scripts/,
+ * references/, and assets/ subdirectories copied for on-demand loading.
+ *
+ * Stack filtering: if projectTags is provided, only skills whose `stacks:`
+ * frontmatter matches the project tags are installed. Skills without a
+ * `stacks:` field are always installed (universal).
+ *
+ * @param {string} projectDir - Target project root directory
+ * @param {Object} [options]
+ * @param {string[]} [options.projectTags=[]] - Stack tags from config
+ */
+export async function installSkills(projectDir, { projectTags = [] } = {}) {
+  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
+  mkdirSync(claudeSkillsDir, { recursive: true });
+
+  for (const level of SKILL_LEVELS_TO_INSTALL) {
+    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
+    if (!existsSync(levelDir)) continue;
+    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags);
+  }
+
+  // Collect installed morph-* skill names
+  const installed = new Set();
+  for (const entry of readdirSync(claudeSkillsDir)) {
+    if (existsSync(join(claudeSkillsDir, entry, 'SKILL.md'))) {
+      installed.add(entry);
+    }
+  }
+
+  // Cleanup orphan morph-* skill dirs that exist in source but were filtered out
+  const allSourceSkills = collectSourceSkillNames();
+  for (const entry of readdirSync(claudeSkillsDir)) {
+    if (!entry.startsWith('morph-')) continue;
+    if (!installed.has(entry) && allSourceSkills.has(entry)) {
+      rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
+    }
+  }
+}