harness-everything 0.2.2 → 0.3.6

package/scripts/lib/advisory-text.js

@@ -15,7 +15,7 @@ const advisoryInstructions = [
   ``,
   `## 🚦 MANDATORY ENTRY TRIAGE & ROUTING (ALWAYS RUN FIRST)`,
   `Every time you receive a new prompt, you MUST load the \`harness-everything\` skill and immediately do the following:`,
-  `1. Run the Tier Router script: \`node harness-everything/scripts/tier-router.js "<Brief summary of user's prompt>"\` (or simulate its routing logic if terminal is not initialized yet).`,
+  `1. Run \`npx github:dyphn1/Harness-everything next "<Brief summary of user's prompt>"\` (this prints the same routing recommendation tier-router.js produces - it works from any directory and does not depend on where a local copy of the skill was installed). If the terminal is not available yet, simulate its routing logic from the rules below instead of skipping this step.`,
   `2. Output a clear, stylized routing checkpoint block at the VERY BEGINNING of your response to the user:`,
   `   \`\`\`markdown`,
   `   ## 🚦 Harness OS Routing Checkpoint`,
@@ -28,7 +28,8 @@ const advisoryInstructions = [
   `## 🤖 COGNITIVE COMPLIANCE (NO SILENT DEGRADES FOR NEW FEATURES)`,
   `- **Newly Added Features / Extensions**: Copilot is highly prone to treating new feature requests as Tier 1 direct edits. If a task introduces *any* new logic, a new API endpoint, or a new file/module, you **MUST NOT** treat it as Tier 1. It **MUST** be treated as a **Tier 2 (Standard Task)** or **Tier 3 (Macro Task)**.`,
   `- **Tier 2 Activation**: Initialize the \`todo-driven-workflow\` checklist first. Summon Domain Experts based on tech stack. Load and execute the \`tdd\` (Test-Driven Development) skill (write tests first, implement, refactor).`,
-  `- **Tier 3 Activation**: Initialize the \`todo-driven-workflow\` checklist, load \`fable-mode\` and \`fable-discipline\`, run sub-agents via \`create-agent-launcher\`, and write global docs using \`repo-docs\`.`,
+  `- **Tier 3 Activation**: Initialize the \`todo-driven-workflow\` checklist, load \`fable-mode\` and \`fable-discipline\`, run sub-agents via \`multi-agent-workspace\`, and write global docs using \`repo-docs\`.`,
+  `- **Pre-Completion Verification Gate**: Before telling the human the task is done, run \`npx github:dyphn1/Harness-everything verify\` in the project root. If it exits non-zero, fix the failures and run it again before declaring completion. On Claude Code this same check is mechanically enforced by a stop hook; here nothing blocks you from skipping it, so treat it as a real requirement, not a suggestion.`,
   `- **Memory Summarization (Self-Evolve)**: Upon task completion, you **MUST** run the \`self-evolve\` skill (running \`node self-evolve/scripts/self-regression.js\` or writing memories) to record key insights, lessons learned, and error boundaries so your context builds across sessions.`,
   `- **Environment Discovery**: Discover the environment (OS, shell, package manager) before running commands - don't assume.`,
   `- **Rule of 3**: If the same error repeats 3 times in a row, STOP retrying. Explain what's failing and ask the human for direction instead of continuing to guess.`,
@@ -142,8 +143,11 @@ function buildCodexGlobalContent() {
     `these as strong defaults, not guarantees.`,
     ``,
     `- Discover the environment (OS, shell, package manager) before running commands - don't assume.`,
-    `- Triage tasks: trivial fixes need no plan; standard features need tests; large refactors need`,
-    `  an explicit plan reviewed with the human before implementation.`,
+    `- Triage tasks: run \`npx github:dyphn1/Harness-everything next "<summary>"\` for a routing recommendation`,
+    `  (trivial fixes need no plan; standard features need tests; large refactors need an explicit plan`,
+    `  reviewed with the human before implementation).`,
+    `- Before declaring a task done, run \`npx github:dyphn1/Harness-everything verify\` and fix any failures`,
+    `  it reports - nothing here blocks you from skipping this, so treat it as a real requirement.`,
     `- If the same error repeats 3 times in a row, STOP retrying. Explain what's failing and ask the`,
     `  human for direction instead of continuing to guess.`,
     `- Prefer editing over rewriting; commit logically complete chunks rather than one giant diff.`,

package/scripts/lib/claude-hooks.js

@@ -3,12 +3,25 @@
 const fs = require('fs');
 
 // Every hook this package ships is namespaced "harness:<phase>:<name>" (see
-// hooks/hooks.json) specifically so removal can match on that prefix alone -
-// never on loose text like "does the command mention harness", which could
-// false-positive on someone else's unrelated hook (e.g. a script whose path
-// or name happens to contain "harness").
+// hooks/hooks.json) specifically so removal can match on that prefix alone.
+// To handle legacy installations (pre-0.3.0 or older) where hooks were installed
+// without an "id" field, we also check if any command contains keywords like
+// "harness-everything" or "harness-skills".
 function isHarnessHook(hook) {
-  return !!(hook && hook.id && hook.id.startsWith('harness:'));
+  if (!hook) return false;
+  if (hook.id && hook.id.startsWith('harness:')) {
+    return true;
+  }
+  if (Array.isArray(hook.hooks)) {
+    return hook.hooks.some(h => {
+      return h && typeof h.command === 'string' && (
+        h.command.includes('harness-everything') ||
+        h.command.includes('harness-skills') ||
+        h.command.includes('harness-state')
+      );
+    });
+  }
+  return false;
 }
 
 function mergeHarnessHooks(claudeConfig, resolvedHooks) {

package/scripts/lib/gitignore.js

@@ -1,80 +1,199 @@
-const fs = require('fs');
-const path = require('path');
-
-function ensureWorkspaceGitignorePatterns(wsRoot, patterns) {
-  const gitignorePath = path.join(wsRoot, '.gitignore');
-  try {
-    let content = '';
-    if (fs.existsSync(gitignorePath)) {
-      content = fs.readFileSync(gitignorePath, 'utf8');
-    }
-
-    const lines = content.split(/\r?\n/);
-    const addedPatterns = [];
-
-    for (const pattern of patterns) {
-      const isIgnored = lines.some(line => {
-        const trimmed = line.trim();
-        return trimmed === pattern ||
-               trimmed === pattern.slice(0, -1) ||
-               (pattern === '.claude/harness-state/' && (trimmed === '.claude/' || trimmed === '.claude'));
-      });
-
-      if (!isIgnored) {
-        addedPatterns.push(pattern);
-      }
-    }
-
-    // Same read-then-append shape as ensureHarnessStateIgnored() in
-    // hooks/scripts/lib/harness-state.js, which runs once per hook
-    // invocation and can race across concurrent processes to leave an
-    // exact-duplicate line behind - see the comment there. Collapsing
-    // duplicates here too keeps both writers self-healing the same file.
-    const seen = new Set();
-    let sawDuplicate = false;
-    const dedupedLines = lines.filter(line => {
-      const trimmed = line.trim();
-      if (trimmed === '' || trimmed.startsWith('#')) return true;
-      if (seen.has(trimmed)) {
-        sawDuplicate = true;
-        return false;
-      }
-      seen.add(trimmed);
-      return true;
-    });
-
-    if (addedPatterns.length > 0 || sawDuplicate) {
-      while (dedupedLines.length > 0 && dedupedLines[dedupedLines.length - 1] === '') {
-        dedupedLines.pop();
-      }
-      const finalLines = dedupedLines.concat(addedPatterns);
-      fs.writeFileSync(gitignorePath, finalLines.join('\n') + '\n', 'utf8');
-      if (addedPatterns.length > 0) {
-        console.log(`  ✅ Added auto-generated directories to .gitignore: ${addedPatterns.join(', ')}`);
-      }
-    }
-  } catch (err) {
-    console.warn(`  ⚠️ Failed to update .gitignore: ${err.message}`);
-  }
-}
-
-// Only ever deletes a directory that is genuinely empty, and never recurses
-// past one of `stopDirs` (workspace root / user home / filesystem root) - so
-// this can only ever tidy up directories Harness itself just emptied out,
-// never reach into a parent that still holds unrelated content.
-function cleanEmptyDirs(dir, stopDirs) {
-  if (!fs.existsSync(dir)) return;
-  if ((stopDirs || []).includes(dir) || dir === path.parse(dir).root) return;
-  try {
-    const files = fs.readdirSync(dir);
-    if (files.length === 0) {
-      fs.rmdirSync(dir);
-      console.log(`  ✅ Cleaned up empty directory: ${dir}`);
-      cleanEmptyDirs(path.dirname(dir), stopDirs);
-    }
-  } catch (e) {
-    // ignore
-  }
-}
-
-module.exports = { ensureWorkspaceGitignorePatterns, cleanEmptyDirs };
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Checks if a target pattern is already covered by a line in an ignore file.
+ * Handles exact matches, trailing slash differences, and parent directory subsumption
+ * (e.g. `.claude/` or `.claude` subsumes `.claude/harness-everything/state/`).
+ */
+function isPatternCoveredByLine(pattern, gitignoreLine) {
+  const normPattern = pattern.trim().replace(/\\/g, '/');
+  const normLine = gitignoreLine.trim().replace(/\\/g, '/');
+
+  if (!normLine || normLine.startsWith('#') || normLine.startsWith('!')) {
+    return false;
+  }
+
+  const cleanLine = normLine.endsWith('/') ? normLine.slice(0, -1) : normLine;
+  const cleanPattern = normPattern.endsWith('/') ? normPattern.slice(0, -1) : normPattern;
+
+  // Exact match or slash variant (e.g. '.claude' vs '.claude/')
+  if (cleanLine === cleanPattern) {
+    return true;
+  }
+
+  // Parent directory check: e.g. '.claude' covers '.claude/harness-everything/'
+  if (cleanPattern.startsWith(cleanLine + '/')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Resolves the real git directory for a workspace. `.git` is usually a
+ * directory, but in submodules and worktrees it is a FILE containing
+ * `gitdir: <path>` - resolve that pointer so info/exclude lands in the right
+ * place. Returns null when the workspace has no git repository.
+ */
+function resolveGitDir(wsRoot) {
+  const dotGit = path.join(wsRoot, '.git');
+  if (!fs.existsSync(dotGit)) return null;
+  try {
+    if (fs.statSync(dotGit).isDirectory()) return dotGit;
+    const content = fs.readFileSync(dotGit, 'utf8');
+    const m = content.match(/gitdir:\s*(.+)/);
+    if (!m) return null;
+    let gitdir = m[1].trim();
+    if (!path.isAbsolute(gitdir)) gitdir = path.resolve(wsRoot, gitdir);
+    return fs.existsSync(gitdir) ? gitdir : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+const EXCLUDE_BANNER_BEGIN = '# --- Harness OS state (auto-managed; local only) ---';
+const EXCLUDE_BANNER_END = '# --- end Harness OS state ---';
+// Legacy marker written by older installers straight into .gitignore.
+const LEGACY_GITIGNORE_BANNER = '# Harness OS Auto-generated Ignore Rules';
+
+function readExcludeLines(gitDir) {
+  try {
+    return fs.readFileSync(path.join(gitDir, 'info', 'exclude'), 'utf8').split(/\r?\n/);
+  } catch (e) {
+    return null; // no exclude file yet - treat as empty but writable
+  }
+}
+
+function writeExcludeSection(gitDir, patterns) {
+  const infoDir = path.join(gitDir, 'info');
+  fs.mkdirSync(infoDir, { recursive: true });
+  const excludePath = path.join(infoDir, 'exclude');
+  let lines = [];
+  try {
+    lines = fs.readFileSync(excludePath, 'utf8').split(/\r?\n/);
+  } catch (e) {}
+
+  // Drop our previous section (if any), then rebuild it from the requested
+  // patterns - so removals from getIgnorePatterns() propagate on reinstall.
+  const beginIdx = lines.indexOf(EXCLUDE_BANNER_BEGIN);
+  const endIdx = lines.indexOf(EXCLUDE_BANNER_END);
+  if (beginIdx !== -1 && endIdx !== -1) {
+    lines.splice(beginIdx, endIdx - beginIdx + 1);
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+
+  const section = ['', EXCLUDE_BANNER_BEGIN, ...patterns, EXCLUDE_BANNER_END, ''];
+  fs.writeFileSync(excludePath, lines.concat(section).join('\n'), 'utf8');
+}
+
+/**
+ * Idempotently records Harness state directories as LOCAL-ONLY ignores.
+ *
+ * Patterns go to `<gitdir>/info/exclude`, never the working tree's
+ * .gitignore - installing or self-healing must not produce a diff in the
+ * user's project. Also migrates away the legacy banner block that old
+ * versions appended to .gitignore.
+ */
+function ensureWorkspaceGitignorePatterns(wsRoot, patterns) {
+  const wanted = (patterns || []).filter(Boolean);
+
+  // Migration: strip the legacy banner + its pattern lines from .gitignore.
+  const gitignorePath = path.join(wsRoot, '.gitignore');
+  try {
+    if (fs.existsSync(gitignorePath)) {
+      const content = fs.readFileSync(gitignorePath, 'utf8');
+      if (content.includes(LEGACY_GITIGNORE_BANNER)) {
+        const lines = content.split(/\r?\n/);
+        const start = lines.findIndex(l => l.trim() === LEGACY_GITIGNORE_BANNER);
+        let end = start;
+        // The legacy block ran until the first non-pattern line (blank/comment/other rule).
+        for (let i = start + 1; i < lines.length; i++) {
+          const t = lines[i].trim();
+          if (t === '' || t.startsWith('#')) break;
+          end = i;
+        }
+        lines.splice(start, end - start + 1);
+        while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+        fs.writeFileSync(gitignorePath, lines.join('\n') + '\n', 'utf8');
+      }
+    }
+  } catch (err) {
+    console.warn(`  ⚠️ Failed to migrate legacy .gitignore entries: ${err.message}`);
+  }
+
+  const gitDir = resolveGitDir(wsRoot);
+  if (!gitDir) {
+    // No git repo -> nothing local-only to write into. State dirs are gated
+    // elsewhere (bootstrap refuses unmanaged workspaces), so this is fine.
+    return;
+  }
+
+  try {
+    const existing = readExcludeLines(gitDir) || [];
+    // Skip the write entirely when every wanted pattern is already inside our
+    // managed section OR covered by any ignore line (user's own broader rule).
+    const outside = existing.filter(
+      l => l !== EXCLUDE_BANNER_BEGIN && l !== EXCLUDE_BANNER_END
+    );
+    const missing = wanted.filter(p => !outside.some(line => isPatternCoveredByLine(p, line)));
+    const currentSection =
+      beginEnd(existing).start === -1
+        ? []
+        : existing.slice(beginEnd(existing).start + 1, beginEnd(existing).end);
+    const sameSet =
+      currentSection.filter(l => l.trim() && !l.trim().startsWith('#')).join('\n') ===
+      wanted.join('\n');
+    if (missing.length === 0 && sameSet) return;
+
+    writeExcludeSection(gitDir, wanted);
+    console.log(`  ✅ Recorded local-only ignore rules in .git/info/exclude: ${wanted.join(', ')}`);
+  } catch (err) {
+    console.warn(`  ⚠️ Failed to update .git/info/exclude: ${err.message}`);
+  }
+}
+
+function beginEnd(lines) {
+  return { start: lines.indexOf(EXCLUDE_BANNER_BEGIN), end: lines.indexOf(EXCLUDE_BANNER_END) };
+}
+
+/**
+ * Removes Harness's section from .git/info/exclude (uninstall cleanup).
+ * Never touches user-authored exclude rules.
+ */
+function removeWorkspaceExcludePatterns(wsRoot) {
+  const gitDir = resolveGitDir(wsRoot);
+  if (!gitDir) return;
+  try {
+    const excludePath = path.join(gitDir, 'info', 'exclude');
+    const lines = fs.readFileSync(excludePath, 'utf8').split(/\r?\n/);
+    const { start, end } = beginEnd(lines);
+    if (start === -1 || end === -1) return;
+    lines.splice(start, end - start + 1);
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+    fs.writeFileSync(excludePath, lines.join('\n') + '\n', 'utf8');
+  } catch (err) {
+    // Best-effort
+  }
+}
+
+// Only ever deletes a directory that is genuinely empty, and never recurses
+// past one of `stopDirs` (workspace root / user home / filesystem root) - so
+// this can only ever tidy up directories Harness itself just emptied out,
+// never reach into a parent that still holds unrelated content.
+function cleanEmptyDirs(dir, stopDirs) {
+  if (!fs.existsSync(dir)) return;
+  if ((stopDirs || []).includes(dir) || dir === path.parse(dir).root) return;
+  try {
+    const files = fs.readdirSync(dir);
+    if (files.length === 0) {
+      fs.rmdirSync(dir);
+      console.log(`  ✅ Cleaned up empty directory: ${dir}`);
+      cleanEmptyDirs(path.dirname(dir), stopDirs);
+    }
+  } catch (e) {
+    // ignore
+  }
+}
+
+module.exports = { ensureWorkspaceGitignorePatterns, removeWorkspaceExcludePatterns, resolveGitDir, cleanEmptyDirs };

package/scripts/lib/manifest.js

@@ -3,6 +3,14 @@
 // hold content from other tools, the user's own manual additions, or
 // self-evolve's locally-generated skills.
 //
+// Deliberately does NOT track find-skills' third-party downloads the same
+// way: generated[] works because Harness owns the full lifecycle (authored,
+// quality-gated, and status-tracked by self-evolve/skill-creator). A skill
+// fetched via `npx skills add` is unaudited content Harness doesn't own or
+// control the lifecycle of - the `skills` CLI's own lock file is already the
+// live record of what's installed, so find-skills queries that directly
+// (`npx skills list`) instead of caching a second, driftable copy here.
+//
 // The manifest always lives at <platform-home>/harness-everything/manifest.json
 // - e.g. .claude/harness-everything/manifest.json, .cursor/harness-everything/
 // manifest.json, or (global scope) ~/.agents/harness-everything/manifest.json.
@@ -15,7 +23,7 @@ const fs = require('fs');
 const path = require('path');
 
 const PACKAGE_NAME = 'harness-everything';
-const HARNESS_AUTHOR = 'Miya Daniel | Harness Core Team';
+const HARNESS_AUTHOR = 'Miya Daniel';
 const HARNESS_DIR_NAME = 'harness-everything';
 
 function getHarnessDir(homeDir) {
@@ -28,14 +36,15 @@ function getManifestPath(homeDir) {
 
 function readManifest(manifestPath) {
   if (!fs.existsSync(manifestPath)) {
-    return { package: PACKAGE_NAME, skills: [] };
+    return { package: PACKAGE_NAME, skills: [], agents: [] };
   }
   try {
     const data = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
     if (!Array.isArray(data.skills)) data.skills = [];
+    if (!Array.isArray(data.agents)) data.agents = [];
     return data;
   } catch (e) {
-    return { package: PACKAGE_NAME, skills: [] };
+    return { package: PACKAGE_NAME, skills: [], agents: [] };
   }
 }
 
@@ -56,13 +65,64 @@ function recordSkillInstall(manifestPath, packageVersion, skillId, dirPath) {
   writeManifest(manifestPath, data);
 }
 
+function recordAgentInstall(manifestPath, packageVersion, agentId, filePath) {
+  const data = readManifest(manifestPath);
+  data.package = PACKAGE_NAME;
+  data.version = packageVersion;
+  data.updatedAt = new Date().toISOString();
+  const idx = data.agents.findIndex(agent => agent.filePath === filePath);
+  const entry = { id: agentId, filePath, installedAt: new Date().toISOString() };
+  if (idx !== -1) data.agents[idx] = entry;
+  else data.agents.push(entry);
+  writeManifest(manifestPath, data);
+}
+
+function recordGeneratedSkill(manifestPath, skillId, dirPath, description, triggers = []) {
+  const data = readManifest(manifestPath);
+  if (!Array.isArray(data.generated)) data.generated = [];
+  
+  data.updatedAt = new Date().toISOString();
+  const idx = data.generated.findIndex(s => s.dirPath === dirPath || s.id === skillId);
+  const entry = {
+    id: skillId,
+    dirPath,
+    description,
+    triggers: Array.isArray(triggers) ? triggers : [],
+    generatedAt: new Date().toISOString()
+  };
+  
+  if (idx !== -1) data.generated[idx] = { ...data.generated[idx], ...entry };
+  else data.generated.push(entry);
+  
+  writeManifest(manifestPath, data);
+}
+
+function removeGeneratedSkill(manifestPath, dirPath) {
+  if (!fs.existsSync(manifestPath)) return;
+  const data = readManifest(manifestPath);
+  if (!Array.isArray(data.generated)) return;
+  data.generated = data.generated.filter(s => s.dirPath !== dirPath);
+  writeManifest(manifestPath, data);
+}
+
 // Removes one skill entry, and - once no skills remain in it - deletes the
 // manifest file itself rather than leaving an empty bookkeeping file behind.
 function removeSkillFromManifest(manifestPath, dirPath) {
   if (!fs.existsSync(manifestPath)) return;
   const data = readManifest(manifestPath);
   data.skills = data.skills.filter(s => s.dirPath !== dirPath);
-  if (data.skills.length === 0) {
+  if (data.skills.length === 0 && (!data.generated || data.generated.length === 0) && (!data.agents || data.agents.length === 0)) {
+    fs.unlinkSync(manifestPath);
+  } else {
+    writeManifest(manifestPath, data);
+  }
+}
+
+function removeAgentFromManifest(manifestPath, filePath) {
+  if (!fs.existsSync(manifestPath)) return;
+  const data = readManifest(manifestPath);
+  data.agents = data.agents.filter(agent => agent.filePath !== filePath);
+  if (data.skills.length === 0 && (!data.generated || data.generated.length === 0) && data.agents.length === 0) {
     fs.unlinkSync(manifestPath);
   } else {
     writeManifest(manifestPath, data);
@@ -78,5 +138,9 @@ module.exports = {
   readManifest,
   writeManifest,
   recordSkillInstall,
+  recordAgentInstall,
+  recordGeneratedSkill,
+  removeGeneratedSkill,
   removeSkillFromManifest,
+  removeAgentFromManifest,
 };

package/scripts/lib/prompts.js

@@ -159,7 +159,7 @@ function interactiveSingleSelect(items) {
       readline.cursorTo(process.stdout, 0);
       for (let i = 0; i < items.length; i++) {
         const item = items[i];
-        const isSelected = item.checked ? '(o)' : '( )';
+        const isSelected = item.checked ? '[x]' : '[ ]';
         const isCurrent = i === cursor ? '> ' : '  ';
         readline.clearLine(process.stdout, 0);
         process.stdout.write(`${isCurrent}${isSelected} ${item.name}\n`);

package/scripts/lib/skills.js

@@ -42,7 +42,21 @@ function parseFrontmatter(skillMdPath) {
       const m = yaml.match(new RegExp(`^${key}:\\s*(.*)$`, 'm'));
       return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : '';
     };
-    return { name: get('name'), description: get('description'), author: get('author'), version: get('version') };
+    // Spec-compliant skills carry author/version under `metadata:`; older
+    // installs (pre-0.3.4 copies already sitting in user workspaces) keep
+    // them at the top level, so read both and prefer the nested form.
+    const getMeta = (key) => {
+      // Only keys nested under `metadata:` are indented in frontmatter,
+      // so matching the indented key directly is unambiguous.
+      const m = yaml.match(new RegExp(`^[ \\t]+${key}:\\s*(.*)$`, 'm'));
+      return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : '';
+    };
+    return {
+      name: get('name'),
+      description: get('description'),
+      author: getMeta('author') || get('author'),
+      version: getMeta('version') || get('version'),
+    };
   } catch (e) {
     return null;
   }
@@ -70,6 +84,15 @@ function isHarnessSkillDir(dirPath) {
 function installSkillsToTargets({ chosenSkills, targetDirs, harnessSourceDir, packageVersion }) {
   for (const target of targetDirs) {
     fs.mkdirSync(target.path, { recursive: true });
+    
+    // Copy references directory
+    const refSrc = path.join(harnessSourceDir, 'references');
+    if (fs.existsSync(refSrc)) {
+      const refDest = path.join(path.dirname(target.manifestPath), 'references');
+      if (fs.existsSync(refDest)) fs.rmSync(refDest, { recursive: true, force: true });
+      copyDir(refSrc, refDest);
+    }
+
     for (const skillName of chosenSkills) {
       const src = path.join(harnessSourceDir, skillName);
       const dest = path.join(target.path, skillName);
@@ -83,6 +106,39 @@ function installSkillsToTargets({ chosenSkills, targetDirs, harnessSourceDir, pa
   }
 }
 
+function installAgentsToTarget({ target, harnessSourceDir, packageVersion }) {
+  const sourceDir = path.join(harnessSourceDir, 'fable-mode', 'agents');
+  if (!fs.existsSync(sourceDir) || !target || !target.path || !target.manifestPath) return;
+
+  fs.mkdirSync(target.path, { recursive: true });
+  const trackedPaths = new Set(
+    (manifest.readManifest(target.manifestPath).agents || []).map(agent => agent.filePath)
+  );
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destPath = path.join(target.path, entry.name);
+    if (fs.existsSync(destPath)) {
+      const source = fs.readFileSync(sourcePath, 'utf8');
+      const existing = fs.readFileSync(destPath, 'utf8');
+      if (source !== existing) {
+        console.warn(`  ⚠️ Preserved existing agent without overwrite: ${destPath}`);
+        continue;
+      }
+      if (!trackedPaths.has(destPath)) {
+        console.warn(`  ⚠️ Preserved pre-existing identical agent without claiming ownership: ${destPath}`);
+        continue;
+      }
+    } else {
+      fs.copyFileSync(sourcePath, destPath);
+      console.log(`  ✅ Installed agent: ${target.label}${entry.name}`);
+    }
+    const agentInfo = parseFrontmatter(sourcePath);
+    const agentName = (agentInfo && agentInfo.name) || entry.name.replace(/\.md$/i, '');
+    manifest.recordAgentInstall(target.manifestPath, packageVersion, agentName, destPath);
+  }
+}
+
 function manifestTrackedSkills(manifestPath, scopeLabel) {
   const data = manifest.readManifest(manifestPath);
   const results = [];
@@ -154,6 +210,24 @@ function getInstalledSkills(workspaceRoot, userHome) {
   return results;
 }
 
+function getInstalledAgents(workspaceRoot, userHome) {
+  const homes = [
+    { home: path.join(workspaceRoot, '.claude'), scope: 'local (Claude)' },
+    { home: path.join(userHome, '.claude'), scope: 'global (Claude)' },
+  ];
+  const results = [];
+  for (const { home, scope } of homes) {
+    const manifestPath = manifest.getManifestPath(home);
+    const data = manifest.readManifest(manifestPath);
+    for (const entry of data.agents || []) {
+      if (entry.filePath && fs.existsSync(entry.filePath)) {
+        results.push({ ...entry, scope, manifestPath });
+      }
+    }
+  }
+  return results;
+}
+
 function removeSkill(entry) {
   if (fs.existsSync(entry.dirPath)) {
     fs.rmSync(entry.dirPath, { recursive: true, force: true });
@@ -163,12 +237,24 @@ function removeSkill(entry) {
   }
 }
 
+function removeAgent(entry) {
+  if (entry.filePath && fs.existsSync(entry.filePath)) {
+    fs.unlinkSync(entry.filePath);
+  }
+  if (entry.manifestPath) {
+    manifest.removeAgentFromManifest(entry.manifestPath, entry.filePath);
+  }
+}
+
 module.exports = {
   copyDir,
   getAvailableSkills,
   getSkillInfo,
   isHarnessSkillDir,
   installSkillsToTargets,
+  installAgentsToTarget,
   getInstalledSkills,
+  getInstalledAgents,
   removeSkill,
+  removeAgent,
 };