@jaybeeuu/agent-cortex 1.37.1 → 1.38.1

package/bin/agent-cortex.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-import { parseArgs, buildHelpText, validateHarness, SUPPORTED_HARNESSES } from "../lib/cli.mjs";
+import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
+import { installPi } from "./installers/pi.mjs";
 
 const argv = process.argv.slice(2);
 const parsed = parseArgs(argv);
@@ -16,12 +17,78 @@ if (parsed.command === "unknown") {
 }
 
 if (parsed.command === "install") {
+  if (parsed.optionError) {
+    process.stderr.write(`${parsed.optionError}\n`);
+    process.exit(1);
+  }
+
   const check = validateHarness(parsed.harness);
   if (!check.ok) {
     process.stderr.write(`${check.error}\nRun "agent-cortex --help" for usage.\n`);
     process.exit(1);
   }
 
+  if (parsed.harness === "pi") {
+    try {
+      const result = installPi({
+        dryRun: parsed.dryRun ?? false,
+        warn: () => {}, // warnings surface once in the printed summary
+        ...(parsed.output ? { output: parsed.output } : {}),
+        ...(parsed.pluginRoot ? { pluginRoot: parsed.pluginRoot } : {}),
+      });
+      printPiInstall(result);
+    } catch (err) {
+      process.stderr.write(`Install failed: ${err.message}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
   process.stdout.write(`Installing agent-cortex for "${parsed.harness}" harness…\n`);
+
+  // claude is the first wired harness: generates the plugin subtree from the
+  // canonical sources (agents/, agents-native/, skills/, hooks/claude/) via the
+  // shared installClaude generator — `pnpm build:claude` is an alias of this
+  // invocation, so there is no separate build-time code path.
+  if (parsed.harness === "claude") {
+    // Avoid loading the installer on the help/summary paths and for other harnesses.
+    const { installClaude } = await import("./installers/claude.mjs");
+    try {
+      installClaude({ output: parsed.output, dryRun: parsed.dryRun });
+      process.exit(0);
+    } catch (err) {
+      process.stderr.write(`Install failed: ${err.message}\n`);
+      process.exit(1);
+    }
+  }
+
+  // copilot regenerates the flat agents/*.agent.md files the Copilot plugin
+  // loads via plugin.json ("agents": "agents/") — the same code path
+  // `pnpm build:copilot` runs.
+  if (parsed.harness === "copilot") {
+    const { installCopilot } = await import("./installers/copilot.mjs");
+    try {
+      installCopilot({ output: parsed.output, dryRun: parsed.dryRun });
+      process.exit(0);
+    } catch (err) {
+      process.stderr.write(`Install failed: ${err.message}\n`);
+      process.exit(1);
+    }
+  }
+
   process.exit(0);
 }
+
+function printPiInstall(result) {
+  process.stdout.write(`Installing agent-cortex for "pi" harness…\n`);
+  for (const agent of result.agents) {
+    process.stdout.write(`  ✓ ${agent.name}.agent.md → ${agent.filePath}\n`);
+  }
+  process.stdout.write(`  ✓ Substituted ${result.skills.md} markdown file(s) across ${result.skills.skills} skill(s) → ${result.skills.dir}\n`);
+  for (const warning of result.warnings) {
+    process.stdout.write(`  ⚠ ${warning}\n`);
+  }
+  if (result.dryRun) {
+    process.stdout.write("(dry-run — nothing written)\n");
+  }
+}

package/bin/installers/claude.mjs

@@ -0,0 +1,262 @@
+// Install-time generator for the Claude Code plugin subtree — the ONLY code path
+// for producing claude/ from the canonical sources. There is no build-time
+// generator: the package script `pnpm build:claude` is a pure alias of the CLI
+// (`node bin/agent-cortex.mjs install claude`), so regenerating the committed
+// subtree and installing the plugin run exactly the same code:
+//
+//   node bin/agent-cortex.mjs install claude   `pnpm build:claude` (regenerates
+//                              the committed claude/ subtree in place; `--output
+//                              <dir>` targets another dir, `--dry-run` plans
+//                              without writing)
+//
+// claude/ stays committed (not gitignored): the marketplace install flow
+// (`claude plugin marketplace add <repo>` → `claude plugin install
+// agent-cortex@jaybeeuu`) reads the subtree straight from the working tree, so a
+// fresh clone installs as-is with no generation step. CI regenerates it via the
+// same installer and runs `git diff --exit-code claude/...` — byte-for-byte
+// validation that the committed output equals installer output, catching stale
+// output and hand-edits to generated files alike.
+//
+// Generated from:
+//   claude/agents/<slug>.md          agents/<name>/agent.md +
+//                                    agents/<name>/claude/frontmatter.json +
+//                                    agents/<name>/claude/<section>.md ({{SECTION:...}}),
+//                                    with {{TOOL:...}}/{{PATH:...}} substituted against
+//                                    the claude column of token-map.json. Agents in the
+//                                    DEFER set ship instead from agents-native/<name>.md.
+//   claude/skills/<name>             symlinks to the grouped skills/<group>/<name> dirs
+//                                    (single source — Claude scans skills one level deep)
+//   claude/.claude-plugin/plugin.json  name/version/description from package.json
+//                                    (version tracks the package — never stale)
+//   claude/hooks.json                copied from hooks/claude/hooks.json when present
+//   claude/hooks/<scripts>           copied from hooks/claude/ (support files bundled
+//                                    alongside hooks.json, referenced via ${CLAUDE_PLUGIN_ROOT})
+//
+// The claude/ subtree stays committed and CI drift-checks it (build:claude +
+// git diff --exit-code), so a fresh clone remains installable as-is. Hand-authored
+// support files under claude/ (claude/.mcp.json, claude/scripts/) are left untouched.
+//
+// Zero dependencies so it runs on the CI Node and local Node alike.
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync, symlinkSync, statSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = join(MODULE_DIR, "..", "..");
+
+// Agents NOT transformed from the composable sources. `ralph` is authored natively for Claude
+// instead (agents-native/ralph.md) — its event-driven orchestration can't be produced by
+// section composition from the poll-loop sources.
+const DEFER = new Set(["ralph"]);
+
+// Ralph-coupled Copilot skills that don't apply to the lean Claude Ralph (and carry dead
+// ~/.copilot orchestration paths). Not symlinked into the Claude plugin.
+const SKILL_EXCLUDE = new Set(["ralph", "run-pipeline-stage"]);
+
+const NAME_PREFIX = "agent-cortex:";
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function byName(a, b) {
+  return a.localeCompare(b);
+}
+
+/** Compose agents from agents/<name>/; DEFERed agents come from agents-native/ instead. */
+function buildAgents(root) {
+  const files = [];
+  const skipped = [];
+  const entries = readdirSync(join(root, "agents"), { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(root, "agents", entry.name);
+    if (!isFile(join(dir, "agent.md")) || !isFile(join(dir, "claude", "frontmatter.json"))) continue;
+
+    if (DEFER.has(entry.name)) {
+      skipped.push(entry.name);
+      continue;
+    }
+
+    const fm = composeAgent(root, entry.name, "claude");
+    const slug = fm.name.startsWith(NAME_PREFIX) ? fm.name.slice(NAME_PREFIX.length) : fm.name;
+    const header =
+      `---\n` +
+      `# GENERATED from agents/${entry.name}/ by bin/installers/claude.mjs — DO NOT EDIT.\n` +
+      `name: ${slug}\n` +
+      `description: ${JSON.stringify(fm.description)}\n` +
+      `tools: ${fm.tools.join(", ")}\n` +
+      `---\n`;
+    files.push({ file: `${slug}.md`, content: `${header}\n${fm.body}\n` });
+  }
+  return { files, skipped };
+}
+
+/** Copy hand-authored Claude-native agents into claude/agents/ verbatim. */
+function buildNatives(root, nativeSrc) {
+  const files = [];
+  if (!existsSync(nativeSrc)) return files;
+  for (const file of readdirSync(nativeSrc).filter((f) => f.endsWith(".md")).sort(byName)) {
+    files.push({ file, content: readFileSync(join(nativeSrc, file), "utf-8") });
+  }
+  return files;
+}
+
+/** Flatten grouped skills (skills/<group>/<name>/) into claude/skills/ as relative symlinks. */
+function buildSkills(root) {
+  const links = [];
+  const seen = new Map();
+  for (const group of readdirSync(join(root, "skills")).sort(byName)) {
+    const groupDir = join(root, "skills", group);
+    if (!statSync(groupDir).isDirectory()) continue;
+    for (const name of readdirSync(groupDir).sort(byName)) {
+      const skillDir = join(groupDir, name);
+      if (!isFile(join(skillDir, "SKILL.md"))) continue;
+      if (SKILL_EXCLUDE.has(name)) continue;
+      if (seen.has(name)) {
+        throw new Error(`duplicate skill name "${name}" (${seen.get(name)} and ${group}) — names must be unique when flattened`);
+      }
+      seen.set(name, group);
+      links.push({ name, target: skillDir });
+    }
+  }
+  return links;
+}
+
+/** plugin.json manifest; version tracks the package so it can never go stale. */
+function buildPluginJson(root) {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+  return (
+    JSON.stringify(
+      {
+        name: "agent-cortex",
+        version: pkg.version,
+        description: "Personal Claude Code plugin with custom agents and skills",
+        author: { name: "jaybeeuu" },
+        license: pkg.license ?? "MIT",
+        repository: pkg.repository,
+        hooks: "./hooks.json",
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}
+
+/**
+ * Hook support files (hooks/claude/ except hooks.json) bundled into
+ * claude/hooks/ so hook commands can reference them via ${CLAUDE_PLUGIN_ROOT}.
+ * hooks.json itself is special-cased to the plugin root (claude/hooks.json).
+ */
+function buildHookFiles(root) {
+  const files = [];
+  const srcDir = join(root, "hooks", "claude");
+  if (!existsSync(srcDir)) return files;
+  const walk = (dir, rel) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => byName(a.name, b.name))) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full, join(rel, entry.name));
+      else if (entry.name !== "hooks.json")
+        files.push({ rel: join(rel, entry.name), content: readFileSync(full, "utf-8") });
+    }
+  };
+  walk(srcDir, "");
+  return files;
+}
+
+/**
+ * Generate the Claude Code plugin subtree.
+ *
+ * @param {object} options
+ * @param {string} [options.root]   Package root (contains agents/, skills/, token-map.json, …).
+ *                                  Defaults to the repo containing this module.
+ * @param {string} [options.output] Target directory (default: <root>/claude).
+ * @param {boolean} [options.dryRun] Plan and report without writing anything.
+ * @returns {{ output: string, agents: string[], natives: string[], skills: string[], hooks: boolean, dryRun: boolean }}
+ */
+export function installClaude({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
+  const out = output ?? join(root, "claude");
+
+  const agents = buildAgents(root);
+  const natives = buildNatives(root, join(root, "agents-native"));
+  const skills = buildSkills(root);
+  const pluginJson = buildPluginJson(root);
+  const hooksSrc = join(root, "hooks", "claude", "hooks.json");
+  const hooksJson = isFile(hooksSrc) ? readFileSync(hooksSrc, "utf-8") : null;
+  const hookFiles = buildHookFiles(root);
+
+  const summary = {
+    output: out,
+    agents: agents.files.map((f) => f.file.replace(/\.md$/, "")),
+    natives: natives.map((f) => f.file.replace(/\.md$/, "")),
+    skills: skills.map((l) => l.name),
+    hooks: hooksJson !== null,
+    hookFiles: hookFiles.map((f) => f.rel),
+    dryRun,
+  };
+
+  if (agents.skipped.length) console.log(`Skipped composable source(s): ${agents.skipped.join(", ")}`);
+
+  if (dryRun) {
+    console.log(`DRY-RUN — would generate into ${out}, no files written:`);
+    console.log(`  agents: ${summary.agents.join(", ")}`);
+    if (summary.natives.length) console.log(`  native agents: ${summary.natives.join(", ")}`);
+    console.log(`  skills: ${summary.skills.length} symlink(s)`);
+    console.log(`  .claude-plugin/plugin.json (version ${JSON.parse(pluginJson).version})`);
+    if (summary.hooks) console.log("  hooks.json (from hooks/claude/hooks.json)");
+    if (summary.hookFiles.length)
+      console.log(`  hook scripts: ${summary.hookFiles.join(", ")} (bundled into claude/hooks/)`);
+    return summary;
+  }
+
+  // Generated subsets only — hand-authored support files (.mcp.json, scripts/)
+  // under output are left untouched.
+  const agentOut = join(out, "agents");
+  rmSync(agentOut, { recursive: true, force: true });
+  mkdirSync(agentOut, { recursive: true });
+  for (const { file, content } of [...agents.files, ...natives]) {
+    writeFileSync(join(agentOut, file), content);
+  }
+  console.log(`Generated ${summary.agents.length} Claude agent(s): ${summary.agents.join(", ")}`);
+  if (summary.natives.length) console.log(`Copied ${summary.natives.length} native Claude agent(s): ${summary.natives.join(", ")}`);
+
+  const skillOut = join(out, "skills");
+  rmSync(skillOut, { recursive: true, force: true });
+  mkdirSync(skillOut, { recursive: true });
+  for (const { name, target } of skills) {
+    symlinkSync(relative(skillOut, target), join(skillOut, name));
+  }
+  console.log(`Linked ${summary.skills.length} skill(s) into ${skillOut}`);
+
+  mkdirSync(join(out, ".claude-plugin"), { recursive: true });
+  writeFileSync(join(out, ".claude-plugin", "plugin.json"), pluginJson);
+  console.log(`Wrote ${join(out, ".claude-plugin", "plugin.json")}`);
+
+  if (summary.hooks) {
+    writeFileSync(join(out, "hooks.json"), hooksJson);
+    console.log(`Wrote ${join(out, "hooks.json")} (from ${hooksSrc})`);
+
+    if (hookFiles.length > 0) {
+      const hookOut = join(out, "hooks");
+      rmSync(hookOut, { recursive: true, force: true });
+      mkdirSync(hookOut, { recursive: true });
+      for (const { rel, content } of hookFiles) {
+        const dest = join(hookOut, rel);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, content);
+      }
+      console.log(`Bundled ${hookFiles.length} hook support file(s) into ${hookOut}`);
+    }
+  } else {
+    console.log(`Skipped hooks.json — ${hooksSrc} not found (existing file left untouched)`);
+  }
+
+  return summary;
+}

package/bin/installers/copilot.mjs

@@ -0,0 +1,129 @@
+// Install-time generator for the Copilot CLI flat agent files (agents/*.agent.md).
+// This is the single code path for producing those files from the canonical
+// composable sources — both entry points below call installCopilot(), so
+// install-time and build-time output can never diverge:
+//
+//   - bin/agent-cortex.mjs          `agent-cortex install copilot` (install-time;
+//                                   `--output <dir>` overrides the target,
+//                                   `--dry-run` plans without writing)
+//   - scripts/build-copilot-agents.mjs  `pnpm build:copilot` (dev/CI: regenerates
+//                                   the committed agents/*.agent.md files in place)
+//
+// Output lands in <root>/agents/ (the default `output`) because that is the
+// directory the Copilot plugin actually loads: plugin.json declares
+// "agents": "agents/", which scans for *.agent.md files. The generated flat
+// files therefore share the agents/ directory with the canonical composable
+// dirs they are composed from (agents/<name>/) — only flat *.agent.md files are
+// written, nothing is deleted, so a generated file can never clobber a
+// composable source. `--output` exists for the same preview/test contract as the
+// claude and pi installers: point it at a scratch dir and inspect the output.
+//
+//   agents/<name>.agent.md    composed from agents/<name>/agent.md +
+//                             agents/<name>/copilot/frontmatter.json +
+//                             agents/<name>/copilot/<section>.md ({{SECTION:...}}),
+//                             with {{TOOL:...}}/{{PATH:...}} substituted against
+//                             the copilot column of token-map.json.
+//
+// The flat files stay committed and CI drift-checks them (build:copilot +
+// git diff --exit-code -- 'agents/*.agent.md'), so a fresh clone (or a direct
+// path plugin install) ships the plugin read-ready.
+//
+// Zero dependencies so it runs on the CI Node and local Node alike.
+
+import { writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = join(MODULE_DIR, "..", "..");
+
+function isDirectory(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function byName(a, b) {
+  return a.localeCompare(b);
+}
+
+/**
+ * Serialise the flat-file YAML frontmatter. Field order and names mirror the
+ * pre-migration flat sources (description, name, tools, argument-hint) so
+ * Copilot CLI sees the same agent metadata. The GENERATED comment references
+ * scripts/build-copilot-agents.mjs — the committed entry point — so the
+ * generated bytes are identical whichever of the two entry points ran.
+ */
+function frontmatterYaml(name, fm) {
+  const lines = [
+    "---",
+    `# GENERATED from agents/${name}/ by scripts/build-copilot-agents.mjs — DO NOT EDIT.`,
+    `description: ${JSON.stringify(fm.description)}`,
+    `name: ${JSON.stringify(fm.name)}`,
+    `tools: [${fm.tools.map((t) => JSON.stringify(t)).join(", ")}]`,
+  ];
+  if (fm.argumentHint) lines.push(`argument-hint: ${JSON.stringify(fm.argumentHint)}`);
+  lines.push("---");
+  return lines.join("\n");
+}
+
+/** Compose agents from agents/<name>/; every composable dir must ship a copilot harness. */
+function buildAgents(root) {
+  const files = [];
+  const entries = readdirSync(join(root, "agents"), { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files and README
+    const dir = join(root, "agents", entry.name);
+    if (!existsSync(join(dir, "agent.md"))) continue; // not a composable agent dir
+    if (!isDirectory(join(dir, "copilot")) || !existsSync(join(dir, "copilot", "frontmatter.json"))) {
+      throw new Error(`agent "${entry.name}": composable directory without copilot/frontmatter.json — define the copilot harness or exclude the agent`);
+    }
+
+    const fm = composeAgent(root, entry.name, "copilot");
+    files.push({
+      name: entry.name,
+      file: `${entry.name}.agent.md`,
+      content: `${frontmatterYaml(entry.name, fm)}\n\n${fm.body}\n`,
+    });
+  }
+  return files;
+}
+
+/**
+ * Generate the Copilot CLI flat agent files.
+ *
+ * @param {object} options
+ * @param {string} [options.root]   Package root (contains agents/, token-map.json, …).
+ *                                  Defaults to the repo containing this module.
+ * @param {string} [options.output] Directory to write the flat *.agent.md files into
+ *                                  (default: <root>/agents — the dir plugin.json's
+ *                                  "agents": "agents/" scans for the plugin).
+ * @param {boolean} [options.dryRun] Plan and report without writing anything.
+ * @returns {{ output: string, agents: string[], dryRun: boolean }}
+ */
+export function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
+  const out = output ?? join(root, "agents");
+  const files = buildAgents(root);
+  const summary = {
+    output: out,
+    agents: files.map((f) => f.name),
+    dryRun,
+  };
+
+  if (dryRun) {
+    console.log(`DRY-RUN — would generate into ${out}, no files written:`);
+    console.log(`  agents: ${summary.agents.join(", ")}`);
+    return summary;
+  }
+
+  mkdirSync(out, { recursive: true });
+  for (const { file, content } of files) {
+    writeFileSync(join(out, file), content);
+  }
+  console.log(`Generated ${files.length} Copilot agent file(s): ${summary.agents.join(", ")}`);
+  return summary;
+}

package/bin/installers/pi.mjs

@@ -0,0 +1,197 @@
+// Pi harness installer: agent-cortex install pi
+//
+// Materialises the agent-cortex package into the pi runtime's user scope:
+//
+//   <output>/agents/<slug>.agent.md   composed agents (default ~/.pi/agent/agents)
+//   <output>/skills/<group>/<name>/   token-substituted skill copies (default ~/.pi/agent/skills)
+//
+// Composition per the token-map.json contract:
+//   1. {{SECTION:name}} is resolved from the agent's pi/<name>.md section file
+//      (shared composer, scripts/lib/compose-agent.mjs).
+//   2. {{TOOL:key}} is substituted with the pi column; a null mapping drops the
+//      token from prose with a warning (pi has no ask_user/skill tool).
+//   3. {{PATH:key}} named keys resolve through the paths table; bare relative
+//      paths resolve against the plugin root (default: token-map.json's pi value,
+//      overridable with --plugin-root for checkout/symlinked installs).
+// Frontmatter tool lists are translated the same way agent-modes does at runtime:
+// canonical → pi column, null → omitted, unknown (native pi tool) → pass through.
+// Skill markdown files get the same TOOL/PATH substitution so pi never serves
+// literal token syntax; other skill files are copied verbatim.
+//
+// Skills install into ~/.pi/agent/skills (pi's user-global skill dir), which pi
+// loads before package skills, so the substituted copies shadow the raw package
+// skills of the same name (pi dedupes by name, user wins).
+//
+// Zero dependencies so it runs on the CI Node and local Node alike.
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { composeAgent, loadTokenMap, substituteTokens, translateToolList } from "../../scripts/lib/compose-agent.mjs";
+
+const PI = "pi";
+
+// The token-map contract version this installer implements (token-map.json
+// "version" field). A higher map version is rejected: the contract must be
+// extended before this installer can trust it.
+const CONTRACT_VERSION = 1;
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const DEFAULT_OUTPUT = join(homedir(), ".pi", "agent");
+
+const DEFAULT_WARN = (msg) => console.warn(`[pi-installer] ${msg}`);
+
+function isDirectory(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install the agent-cortex pi harness into the pi runtime.
+ *
+ * @param {object} options
+ * @param {string} [options.root]        Package root (defaults to this file's repo)
+ * @param {string} [options.output]      Pi user-scope dir; agents go to
+ *                                       <output>/agents, skills to <output>/skills
+ *                                       (default ~/.pi/agent)
+ * @param {boolean} [options.dryRun]     Compute and report without writing anything
+ * @param {string} [options.pluginRoot]  Override plugin_root used for {{PATH:...}}
+ *                                       resolution (default: token-map pi value)
+ * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`
+ * @returns {{ agents: {name:string, filePath:string}[], skills: {skills:number, md:number, files:number, dir:string},
+ *             warnings: string[], dryRun: boolean, agentsDir: string, skillsDir: string }}
+ */
+export function installPi(options = {}) {
+  const root = options.root ?? REPO_ROOT;
+  const output = options.output ?? DEFAULT_OUTPUT;
+  const dryRun = options.dryRun ?? false;
+  const warnings = [];
+  const warn = (msg) => {
+    warnings.push(msg);
+    (options.warn ?? DEFAULT_WARN)(msg);
+  };
+
+  const tokenMap = loadTokenMap(root);
+  if (typeof tokenMap.version === "number" && tokenMap.version > CONTRACT_VERSION) {
+    throw new Error(
+      `token-map.json version ${tokenMap.version} is newer than the contract version ${CONTRACT_VERSION} this installer implements — upgrade agent-cortex`,
+    );
+  }
+
+  const pluginRoot = options.pluginRoot ?? tokenMap.paths.plugin_root?.[PI];
+  const agentsDir = join(output, "agents");
+  const skillsDir = join(output, "skills");
+
+  const agents = installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
+  const skills = installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
+
+  return { agents, skills, warnings, dryRun, agentsDir, skillsDir };
+}
+
+// ─── Agents ──────────────────────────────────────────────────────────────────
+
+function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn }) {
+  const written = [];
+  const agentsSrc = join(root, "agents");
+  for (const entry of readdirSync(agentsSrc, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files
+    const dir = join(agentsSrc, entry.name);
+    if (!isFile(join(dir, "agent.md"))) continue; // not a composable agent dir
+    if (!isDirectory(join(dir, PI)) || !isFile(join(dir, PI, "frontmatter.json"))) {
+      throw new Error(`agent "${entry.name}": composable directory without pi/frontmatter.json — define the pi harness or exclude the agent`);
+    }
+
+    const fm = composeAgent(root, entry.name, PI, {
+      dropNullTools: true,
+      pluginRoot,
+      resolveRelativePaths: true,
+      warn,
+    });
+    const tools = translateToolList(fm.tools, tokenMap, PI, { warn });
+    const content = renderPiAgent(entry.name, fm, tools);
+    const filePath = join(agentsDir, `${entry.name}.agent.md`);
+    if (!dryRun) {
+      mkdirSync(agentsDir, { recursive: true });
+      writeFileSync(filePath, content);
+    }
+    written.push({ name: entry.name, filePath });
+  }
+  return written;
+}
+
+function renderPiAgent(name, fm, tools) {
+  const lines = [
+    "---",
+    `# GENERATED from agents/${name}/ by bin/installers/pi.mjs — DO NOT EDIT.`,
+    `name: ${JSON.stringify(fm.name)}`,
+    `description: ${JSON.stringify(fm.description)}`,
+    `tools: ${JSON.stringify(tools.join(" "))}`,
+  ];
+  if (fm.model) lines.push(`model: ${JSON.stringify(fm.model)}`);
+  if (fm.argumentHint) lines.push(`argument-hint: ${JSON.stringify(fm.argumentHint)}`);
+  lines.push("---");
+  return `${lines.join("\n")}\n\n${fm.body}\n`;
+}
+
+// ─── Skills ──────────────────────────────────────────────────────────────────
+
+function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn }) {
+  const skillsSrc = join(root, "skills");
+  if (!isDirectory(skillsSrc)) return { skills: 0, md: 0, files: 0, dir: skillsDir };
+
+  const transform = (content) =>
+    substituteTokens(content, PI, tokenMap, { dropNullTools: true, pluginRoot, resolveRelativePaths: true, warn });
+
+  if (!dryRun) mkdirSync(skillsDir, { recursive: true });
+  let skills = 0;
+  let md = 0;
+  let files = 0;
+  for (const group of readdirSync(skillsSrc).sort()) {
+    const groupDir = join(skillsSrc, group);
+    if (!isDirectory(groupDir)) continue;
+    for (const name of readdirSync(groupDir).sort()) {
+      if (!isFile(join(groupDir, name, "SKILL.md"))) continue;
+      skills += 1;
+      const stats = copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
+      md += stats.md;
+      files += stats.files;
+    }
+  }
+  return { skills, md, files, dir: skillsDir };
+}
+
+/** Recursively copy a tree; transform .md file contents, copy everything else verbatim. */
+function copyTree(src, dest, transform, dryRun) {
+  let md = 0;
+  let files = 0;
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = join(src, entry.name);
+    const to = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      const stats = copyTree(from, to, transform, dryRun);
+      md += stats.md;
+      files += stats.files;
+    } else if (entry.isFile()) {
+      files += 1;
+      if (entry.name.endsWith(".md")) md += 1;
+      if (dryRun) continue;
+      mkdirSync(dest, { recursive: true });
+      if (entry.name.endsWith(".md")) writeFileSync(to, transform(readFileSync(from, "utf-8")));
+      else copyFileSync(from, to);
+    }
+  }
+  return { md, files };
+}

package/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-cortex",
-  "version": "1.31.2",
+  "version": "1.38.1",
   "description": "Personal Claude Code plugin with custom agents and skills",
   "author": {
     "name": "jaybeeuu"