@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/test/pi-installer.test.mjs

@@ -0,0 +1,371 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { installPi } from "../bin/installers/pi.mjs";
+
+// Real repo root — used by the integration smoke test to prove the installer
+// works against the canonical sources (agents/, skills/, token-map.json).
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const TOOL_MAP = {
+  bash: { pi: "bash" },
+  view: { pi: "read" },
+  create: { pi: "write" },
+  glob: { pi: "find" },
+  ask_user: { pi: null },
+  skill: { pi: null },
+  task: { pi: "task" },
+};
+
+function tokenMap(extra = {}) {
+  return {
+    name: "fixture token map",
+    version: 1,
+    harnesses: ["pi"],
+    tools: { ...TOOL_MAP },
+    paths: {
+      plugin_root: { pi: "~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex" },
+      skills_dir: { pi: { base: "plugin_root", relative: "skills" } },
+      agents_dir: { pi: { base: "plugin_root", relative: "agents" } },
+    },
+    ...extra,
+  };
+}
+
+function makeFixture() {
+  const root = mkdtempSync(join(tmpdir(), "pi-installer-"));
+  const output = join(root, "out");
+  return {
+    root,
+    output,
+    cleanup: () => rmSync(root, { recursive: true, force: true }),
+  };
+}
+
+function writeFixture(fx, relPath, content) {
+  const p = join(fx.root, relPath);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+
+/** Seed a minimal but realistic package tree (agents + token-map + skills). */
+function seedPackage(fx, opts = {}) {
+  const { agents = {}, skills = {}, tokenMap: map, version } = opts;
+  writeFixture(fx, "token-map.json", JSON.stringify(map ?? tokenMap(version ? { version } : {})));
+  for (const [name, def] of Object.entries(agents)) {
+    writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
+    writeFixture(
+      fx,
+      `agents/${name}/pi/frontmatter.json`,
+      JSON.stringify(
+        def.frontmatter ?? {
+          name: `agent-cortex:${name}`,
+          description: `Description of ${name}`,
+          tools: ["bash", "view"],
+          argumentHint: `Hint for ${name}`,
+        },
+      ),
+    );
+    for (const [section, content] of Object.entries(def.sections ?? {})) {
+      writeFixture(fx, `agents/${name}/pi/${section}.md`, content);
+    }
+  }
+  for (const [path, content] of Object.entries(skills)) {
+    writeFixture(fx, `skills/${path}`, content);
+  }
+}
+
+function listFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFiles(p).map((f) => join(entry.name, f)));
+    else out.push(entry.name);
+  }
+  return out;
+}
+
+// ─── Agent composition ───────────────────────────────────────────────────────
+
+describe("installPi — agent composition", () => {
+  it("writes one .agent.md per composable agent dir with pi frontmatter and no leftover tokens", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, {
+        agents: {
+          alpha: {
+            body: "# alpha\nUse {{TOOL:view}} to read.\n{{SECTION:polling}}\nRead {{PATH:skills_dir}}.",
+            sections: { polling: "Spawn with {{TOOL:task}}." },
+            frontmatter: {
+              name: "agent-cortex:alpha",
+              description: "Reads things.",
+              tools: ["bash", "view", "glob", "ask_user"],
+              argumentHint: "Read something",
+            },
+          },
+        },
+      });
+
+      const result = installPi({ root: fx.root, output: fx.output });
+
+      const file = join(fx.output, "agents", "alpha.agent.md");
+      assert.ok(existsSync(file), "agent file written");
+      const content = readFileSync(file, "utf-8");
+      assert.ok(content.startsWith("---\n"), "yaml frontmatter");
+      assert.match(content, /name: "agent-cortex:alpha"/);
+      assert.match(content, /description: "Reads things\."/);
+      assert.match(content, /tools: "bash read find"/, "tools translated to pi names, ask_user omitted");
+      assert.match(content, /argument-hint: "Read something"/);
+      assert.ok(content.includes("Use read to read."), "{{TOOL:view}} substituted");
+      assert.ok(content.includes("Spawn with task."), "{{SECTION:polling}} composed from pi/polling.md");
+      assert.ok(!/{{/.test(content), "no literal tokens remain");
+      assert.equal(result.agents.length, 1);
+      assert.deepEqual(result.agents[0], { name: "alpha", filePath: file });
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("drops null-mapped tool tokens in prose and reports a warning", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, {
+        agents: {
+          alpha: { body: "# alpha\nAsk the user with {{TOOL:ask_user}}, then use {{TOOL:bash}}." },
+        },
+      });
+
+      const result = installPi({ root: fx.root, output: fx.output });
+      const content = readFileSync(join(fx.output, "agents", "alpha.agent.md"), "utf-8");
+
+      assert.ok(!content.includes("ask_user"), "null-mapped token dropped from prose");
+      assert.ok(content.includes("use bash"), "mapped token substituted");
+      assert.ok(!/{{/.test(content));
+      assert.ok(result.warnings.some((w) => w.includes("{{TOOL:ask_user}}")), "drop reported as warning");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("throws on an unknown tool token", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, { agents: { alpha: { body: "# alpha\nUse {{TOOL:nope}} now." } } });
+      assert.throws(() => installPi({ root: fx.root, output: fx.output }), /unknown tool token {{TOOL:nope}}/);
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("throws when a section file referenced by {{SECTION:...}} is missing", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, { agents: { alpha: { body: "# alpha\n{{SECTION:missing}}" } } });
+      assert.throws(() => installPi({ root: fx.root, output: fx.output }), /missing section "missing"/);
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("resolves named and relative {{PATH:...}} tokens against the plugin root", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, {
+        agents: {
+          alpha: {
+            body: "# alpha\nNamed: {{PATH:skills_dir}}\nRelative: {{PATH:skills/x/SKILL.md}}",
+          },
+        },
+      });
+
+      const result = installPi({ root: fx.root, output: fx.output });
+      const content = readFileSync(join(fx.output, "agents", "alpha.agent.md"), "utf-8");
+
+      assert.ok(
+        content.includes("Named: ~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex/skills"),
+        "named path resolves through token-map paths table",
+      );
+      assert.ok(
+        content.includes("Relative: ~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex/skills/x/SKILL.md"),
+        "relative path resolves against plugin root",
+      );
+      assert.equal(result.warnings.length, 0);
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("honours the --plugin-root override for path resolution", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, {
+        agents: {
+          alpha: { body: "# alpha\n{{PATH:skills/x/SKILL.md}}" },
+        },
+      });
+
+      const pluginRoot = join(fx.root, "checkout");
+      installPi({ root: fx.root, output: fx.output, pluginRoot });
+      const content = readFileSync(join(fx.output, "agents", "alpha.agent.md"), "utf-8");
+      assert.ok(content.includes(join(pluginRoot, "skills", "x", "SKILL.md")), "plugin root override used");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("rejects token-map.json versions newer than the implemented contract", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, {
+        version: 99,
+        agents: { alpha: { body: "# alpha" } },
+      });
+      assert.throws(() => installPi({ root: fx.root, output: fx.output }), /version 99/);
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── Skills ──────────────────────────────────────────────────────────────────
+
+describe("installPi — skills", () => {
+  it("copies skills into <output>/skills preserving the grouped layout with substituted tokens", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, {
+        agents: { alpha: { body: "# alpha" } },
+        skills: {
+          "engineering/echo/SKILL.md":
+            "---\nname: echo\ndescription: Echoes {{TOOL:view}}.\n---\n\nUse {{TOOL:view}} to read and {{TOOL:skill}} for help.\nOpen {{PATH:skills/echo/SKILL.md}}.",
+          "engineering/echo/scripts/run.sh": "#!/bin/sh\necho hi\n",
+        },
+      });
+
+      installPi({ root: fx.root, output: fx.output });
+
+      const skillFile = join(fx.output, "skills", "engineering", "echo", "SKILL.md");
+      assert.ok(existsSync(skillFile), "skill copied");
+      const content = readFileSync(skillFile, "utf-8");
+      assert.ok(content.includes("description: Echoes read."), "token substituted in skill frontmatter");
+      assert.ok(content.includes("Use read to read and  for help."), "null-mapped {{TOOL:skill}} dropped");
+      assert.ok(
+        content.includes(
+          "Open ~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex/skills/echo/SKILL.md.",
+        ),
+        "relative path resolved against plugin root",
+      );
+      assert.ok(!/{{/.test(content), "no literal tokens remain in skill");
+
+      const script = readFileSync(join(fx.output, "skills", "engineering", "echo", "scripts", "run.sh"), "utf-8");
+      assert.equal(script, "#!/bin/sh\necho hi\n", "non-md files copied verbatim");
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── Output / dry-run ────────────────────────────────────────────────────────
+
+describe("installPi — output & dry-run", () => {
+  it("dry-run writes nothing but reports the planned output", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, {
+        agents: { alpha: { body: "# alpha" } },
+        skills: { "engineering/echo/SKILL.md": "---\nname: echo\ndescription: d\n---\n\nBody." },
+      });
+
+      const result = installPi({ root: fx.root, output: fx.output, dryRun: true });
+
+      assert.equal(result.dryRun, true);
+      assert.equal(listFiles(fx.output).length, 0, "no files written in dry-run");
+      assert.equal(result.agents.length, 1);
+      assert.equal(result.agents[0].name, "alpha");
+      assert.equal(result.skills.skills, 1);
+      // Planned paths are still reported so the user can see what would happen.
+      assert.ok(result.agents[0].filePath.startsWith(fx.output));
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("creates the output directory hierarchy when needed", () => {
+    const fx = makeFixture();
+    try {
+      seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      const deep = join(fx.output, "nested", "deep");
+      installPi({ root: fx.root, output: deep });
+      assert.ok(existsSync(join(deep, "agents", "alpha.agent.md")));
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── Integration against the real repo ───────────────────────────────────────
+
+describe("installPi — real repo integration", () => {
+  it("installs every canonical agent with pi tool names and no leftover tokens", () => {
+    const fx = makeFixture();
+    try {
+      const result = installPi({ root: REPO_ROOT, output: fx.output });
+
+      const names = result.agents.map((a) => a.name).sort();
+      assert.deepEqual(names, ["plan", "ralph", "ralph-plan", "strategy"]);
+
+      // ralph pi frontmatter: ["bash", "view", "rg", "glob", "task", "read_agent", "wait_for_agents"]
+      const ralph = readFileSync(join(fx.output, "agents", "ralph.agent.md"), "utf-8");
+      assert.match(ralph, /name: "agent-cortex:ralph"/);
+      assert.match(ralph, /tools: "bash read grep find task read_agent wait_for_agents"/);
+      assert.ok(ralph.includes("## Spawning subagents (PI)"), "{{SECTION:polling}} composed from pi/polling.md");
+      const bodyTokens = ralph.split("---\n").slice(2).join("---\n");
+      assert.ok(!/{{/.test(bodyTokens), "no literal tokens in ralph body");
+
+      // plan body carries the relative {{PATH:...}} resolved against the plugin root
+      const plan = readFileSync(join(fx.output, "agents", "plan.agent.md"), "utf-8");
+      assert.match(plan, /tools: "bash read edit write grep find task read_agent"/);
+      assert.ok(
+        plan.includes("~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex/skills/workflow/plan/SKILL.md"),
+        "plan PATH token resolved against token-map plugin root",
+      );
+
+      // ralph-plan prose {{TOOL:ask_user}} is dropped (null for pi)
+      const ralphPlan = readFileSync(join(fx.output, "agents", "ralph-plan.agent.md"), "utf-8");
+      assert.ok(!ralphPlan.includes("ask_user"), "null-mapped tool omitted from ralph-plan body");
+      assert.ok(
+        result.warnings.some((w) => w.includes("ask_user")),
+        "ralph-plan null tool dropped with a warning",
+      );
+
+      // strategy: web_fetch → fetch_content; ask_user/skill omitted
+      const strategy = readFileSync(join(fx.output, "agents", "strategy.agent.md"), "utf-8");
+      assert.match(strategy, /tools: "bash read grep find fetch_content edit write"/);
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("substitutes tokens in every installed skill markdown", () => {
+    const fx = makeFixture();
+    try {
+      const result = installPi({ root: REPO_ROOT, output: fx.output });
+      assert.ok(result.skills.skills > 20, `expected the full skill tree, got ${result.skills.skills}`);
+
+      const files = listFiles(join(fx.output, "skills")).filter((f) => f.endsWith(".md"));
+      assert.ok(files.length > 0);
+      for (const f of files) {
+        const content = readFileSync(join(fx.output, "skills", f), "utf-8");
+        assert.ok(!/{{/.test(content), `no literal tokens in skill ${f}`);
+      }
+    } finally {
+      fx.cleanup();
+    }
+  });
+});

package/token-map.README.md

@@ -0,0 +1,130 @@
+# token-map.json — multi-harness token substitution
+
+`token-map.json` is the central, single-source mapping of **tool names**, **paths**, and
+**agent naming conventions** across the three harnesses this repo ships to. It is the
+foundation for the install-time generation system: each harness installer (`agent-cortex
+install <harness>`) reads the map and substitutes `{{TOOL:...}}` / `{{PATH:...}}` tokens in
+the files it generates.
+
+**The substitution contract lives inside `token-map.json`** (the `contract` section) — that
+file is the single reference installers must implement. This README explains the design
+decisions behind the map.
+
+## Harnesses
+
+| id | Platform | Agent format | Plugin root |
+|---|---|---|---|
+| `copilot` | GitHub Copilot CLI | `agents/<name>/` composable dirs → generated `agents/*.agent.md` | `~/.copilot/installed-plugins/_direct/agent-cortex` |
+| `pi` | pi coding agent | `agents/<name>/` composable dirs (composed at runtime by agent-modes, or installed install-time by `agent-cortex install pi`) | `~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex` |
+| `claude` | Claude Code | `claude/agents/*.md` (generated) | `${CLAUDE_PLUGIN_ROOT}` (env var) |
+
+The harness ids match the values accepted by `agent-cortex install <harness>` in
+`lib/cli.mjs` (`SUPPORTED_HARNESSES`). The pi `plugin_root` row is the npm-layout
+literal that `agent-cortex install pi` uses by default; local checkout and symlinked
+installs pass `--plugin-root <dir>` to override it (see README "Pi harness agents &
+skills").
+
+## Design decisions
+
+### 1. Token naming convention: `{{TOOL:name}}`, not `{{tool.name}}`
+
+`agents/README.md` (ADR #63) already standardised `{{TOOL:name}}`, `{{PATH:name}}`, and
+`{{SECTION:name}}` for the composable agent directory format. The map adopts that grammar
+rather than inventing a dotted form:
+
+- **The convention is established** — skill authors and the ADR already write tokens this
+  way; the map should not fork the language.
+- **Upper-case type prefix disambiguates** — `{{TOOL:read}}` (a tool) can never collide with
+  `{{PATH:read}}` (a path) in the same document.
+- **One namespace per type** — tool keys, path keys, and section names never share a lookup
+  table, so a tool called `skills_dir` would not shadow the path key.
+- **Greppable and schema-friendly** — simple `{{TYPE:NAME}}` is trivially matched by a
+  regex; delimiters make unbalanced/typo'd tokens visible.
+
+### 2. What is mapped
+
+- **`tools`** — the twelve canonical tool names as authored in `agents/<name>/agent.md`
+  (copilot names are the authoring names). Each row gives the equivalent tool name per
+  harness. Source of truth for the copilot → claude half is `token-map.json`'s own claude
+  column, consumed by `bin/installers/claude.mjs` (the install-time generator — PR #91, #92); the pi column is grounded
+  in pi's documented built-in tool surface (`read`, `bash`, `edit`, `write`, `grep`, `find`,
+  `ls`) plus `task` / `read_agent` / `wait_for_agents` subagent tools.
+- **`paths`** — `plugin_root`, `agents_dir`, and `skills_dir`. These are the install-time
+  variables that differ per harness. `plugin_root` is the anchor; the other two resolve
+  relative to it (`{base, relative}` specs) so a harness only overrides the single root it
+  actually installs into.
+- **`agents`** — the `agent-cortex:` name-prefix convention per harness (claude strips the
+  prefix during conversion) and the deferred-agent exception (claude's `ralph` is authored
+  natively, never generated). Agent names themselves do not get per-row mappings because
+  the prefix rule covers all of them; the deferred list captures the only structural
+  difference.
+- **Deliberately not mapped:** hook patterns, MCP servers, and tool descriptions. Those
+  differ *structurally* per harness (different hook event names, different config files),
+  not by a single substitutable token; each installer already hardcodes its own shape. The
+  map records them in `notes` where a tool differs in behaviour (`read_agent`, `skill`,
+  `ask_user`).
+
+### 3. Null mappings
+
+A null value means **"this harness has no equivalent"** — not "empty string" and not "leave
+the token as-is". The contract defines the two contexts:
+
+- **Prose** (e.g. `Use {{TOOL:read_agent}} to poll`): the token is dropped and the
+  installer warns. Dangling sentences after a drop are the author's responsibility — the
+  warning exists so the installer surfaces them.
+- **Tool-list frontmatter** (e.g. `tools: [..., "read_agent"]`): the entry is omitted from
+  the array.
+
+Unknown (unmapped) tokens are a **hard error**, not a null — a silently-passed-through
+token is exactly the bug the map exists to prevent, and mirrors the build script's
+`unknown tool "x"` throw.
+
+The pi install-time installer (`bin/installers/pi.mjs`) follows the strict contract above.
+One consumer deviates deliberately: the pi `agent-modes` extension reads the map at
+**runtime** (not install time) to compose agent prompts from the composable agents
+format. For it, an unmapped tool name passes through unchanged — it may be a
+native PI tool — while a mapped-null tool (`ask_user`, `skill`) is omitted with a
+warning. See `extensions/agent-modes/README.md`.
+
+### 4. Token substitution contract
+
+The full contract is embedded in `token-map.json` under `contract`. In summary, installers:
+
+1. Bind a harness id (`copilot` | `claude` | `pi`).
+2. Substitute in order: `SECTION` (left for the composer), then `TOOL`, then `PATH`.
+3. For `TOOL`: look up the canonical key, replace with the harness name; null → drop/omit;
+   unknown → throw.
+4. For `PATH`: named key → resolve from `paths`; anything else → resolve relative to
+   `plugin_root`; `${ENV_VAR}` values pass through verbatim for runtime expansion.
+5. Reject a map `version` they do not implement.
+
+## Authoring guidance
+
+- Write tokens with the **canonical (copilot) names**: `Use {{TOOL:task}} to spawn
+  subagents`, `Read {{PATH:skills/workflow/plan/SKILL.md}}`.
+- Never embed a harness-specific name in the canonical sources (`agents/<name>/agent.md`,
+  `skills/**/SKILL.md`) — that defeats the map. The generated `claude/` subtree, the
+  generated `agents/*.agent.md` files, and any installed copies are the only places
+  substituted names appear.
+- When you add a new tool to an agent's frontmatter, add a row to `tools` in
+  `token-map.json` in the same change — the contract treats unknown tools as errors, so a
+  missing row breaks the install pipeline loudly instead of silently.
+
+## Related
+
+- `agents/README.md` — composable agent directory format (ADR #63), defines the token
+  grammar the map implements.
+- `scripts/build-copilot-agents.mjs` / `bin/installers/copilot.mjs` — the copilot
+  harness token composer (scripts/lib/compose-agent.mjs) resolves `{{TOOL:...}}` /
+  `{{PATH:...}}` against the map and `{{SECTION:...}}` from the per-harness section
+  files; `bin/installers/copilot.mjs` is the shared generator both `pnpm build:copilot`
+  and `agent-cortex install copilot` run.
+- `bin/installers/claude.mjs` — the single Claude generator, behind plain
+  `agent-cortex install claude` (which also registers the plugin with Claude Code) and
+  its generate-only `pnpm build:claude` alias (`install claude --output claude`; no
+  build-time counterpart — the committed `claude/` subtree is regenerated by it and
+  drift-checked).
+- `bin/installers/pi.mjs` — the pi harness installer (`agent-cortex install pi`), an
+  install-time consumer of the map's contract.
+- `lib/cli.mjs` — `SUPPORTED_HARNESSES`, the install command surface the harness ids come
+  from.

package/token-map.json

@@ -0,0 +1,106 @@
+{
+  "name": "agent-cortex token map",
+  "description": "Central mapping of tool names, paths, and agent naming conventions across the copilot, claude, and pi harnesses. Single source of truth for install-time token substitution. See token-map.README.md for the design rationale.",
+  "version": 1,
+  "harnesses": ["copilot", "claude", "pi"],
+  "token_format": {
+    "convention": "{{TYPE:NAME}}",
+    "decision": "Adopt the {{TOOL:name}} / {{PATH:name}} / {{SECTION:name}} grammar already standardised by ADR #63 (agents/README.md) rather than a dotted {{tool.name}} form. The uppercase type prefix disambiguates token kinds at a glance, keeps tool/path/section names in one namespace collision-free, and matches the token grammar skills are already written against.",
+    "types": {
+      "TOOL": "{{TOOL:<canonical tool key>}} — replaced at install time with the bound harness's tool name (see tools).",
+      "PATH": "{{PATH:<path key or relative path>}} — replaced at install time with the harness-resolved path (see paths).",
+      "SECTION": "{{SECTION:<name>}} — replaced by the agent composer with <harness>/<name>.md section content. Not a global substitution; out of scope for token-map.json (see contract)."
+    }
+  },
+  "tools": {
+    "bash": { "copilot": "bash", "claude": "Bash", "pi": "bash" },
+    "view": { "copilot": "view", "claude": "Read", "pi": "read" },
+    "edit": { "copilot": "edit", "claude": "Edit", "pi": "edit" },
+    "create": { "copilot": "create", "claude": "Write", "pi": "write" },
+    "grep": { "copilot": "grep", "claude": "Grep", "pi": "grep" },
+    "rg": { "copilot": "rg", "claude": "Grep", "pi": "grep" },
+    "glob": { "copilot": "glob", "claude": "Glob", "pi": "find" },
+    "ask_user": { "copilot": "ask_user", "claude": "AskUserQuestion", "pi": null },
+    "web_fetch": { "copilot": "web_fetch", "claude": "WebFetch", "pi": "fetch_content" },
+    "skill": { "copilot": "skill", "claude": "Skill", "pi": null },
+    "task": { "copilot": "task", "claude": "Task", "pi": "task" },
+    "read_agent": { "copilot": "read_agent", "claude": null, "pi": "read_agent" },
+    "wait_for_agents": { "copilot": null, "claude": null, "pi": "wait_for_agents" }
+  },
+  "paths": {
+    "plugin_root": {
+      "copilot": "~/.copilot/installed-plugins/_direct/agent-cortex",
+      "claude": "${CLAUDE_PLUGIN_ROOT}",
+      "pi": "~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex"
+    },
+    "agents_dir": {
+      "copilot": { "base": "plugin_root", "relative": "agents" },
+      "claude": { "base": "plugin_root", "relative": "agents" },
+      "pi": { "base": "plugin_root", "relative": "agents" }
+    },
+    "skills_dir": {
+      "copilot": { "base": "plugin_root", "relative": "skills" },
+      "claude": { "base": "plugin_root", "relative": "skills" },
+      "pi": { "base": "plugin_root", "relative": "skills" }
+    }
+  },
+  "agents": {
+    "prefix": {
+      "copilot": "agent-cortex:",
+      "claude": "",
+      "pi": "agent-cortex:"
+    },
+    "deferred": {
+      "ralph": ["claude"]
+    },
+    "sources": {
+      "copilot": "agents/<name>/ composable dirs (canonical) — composed to agents/*.agent.md by scripts/build-copilot-agents.mjs",
+      "pi": "agents/<name>/ composable dirs (canonical) — composed at runtime by the agent-modes extension",
+      "claude": "agents/<name>/ composable dirs (canonical) — composed by bin/installers/claude.mjs (install-time generator; pnpm build:claude aliases it), plus agents-native/*.md for deferred agents"
+    }
+  },
+  "notes": {
+    "tools": {
+      "rg": "Copilot alias for grep. Claude and pi collapse it onto their single search tool (Grep / grep) — same collapse rule as the build script.",
+      "glob": "Claude has a dedicated Glob tool. pi's built-in pattern-search tool is find (hypa_find when the pi-hypa extension is installed).",
+      "ask_user": "Copilot (ask_user) and Claude (AskUserQuestion) prompt the user mid-run. pi intentionally ships no permission-popup/ask tool (per pi docs 'it intentionally does not include permission popups'), so the mapping is null.",
+      "web_fetch": "pi's fetch_content comes from the pi-web-access package (declared in pi/settings.json).",
+      "skill": "Copilot (skill) and Claude (Skill) expose skills as a tool. pi discovers skills but the agent loads them via read and /skill:<name> commands — there is no dedicated tool, so the mapping is null.",
+      "read_agent": "Claude's Task returns results inline — there is no separate read step, so read_agent drops on claude (null). Copilot uses the task + read_agent poll loop; pi blocks on wait_for_agents and keeps read_agent as a fallback.",
+      "wait_for_agents": "PI-only blocking wait over background subagent runs (the task tool): returns the results of completed agents and STILL RUNNING for the rest. Copilot has no equivalent tool (its task + read_agent poll loop stays) and Claude's Task delivers results inline with no wait step — both null."
+    },
+    "paths": {
+      "pi": "plugin_root defaults to the npm-package install layout (~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex). Local-checkout installs (pi/settings.json packages entry referencing a local src path) or symlinked installs differ — installers must compute plugin_root from the actual resolution and can override it."
+    },
+    "agents": {
+      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): copilot/pi agents are agent-cortex:<slug>, claude agents are <slug>.",
+      "deferred": "ralph has no generated claude counterpart — it is authored natively as agents-native/ralph.md (its event-driven orchestration cannot be produced by section composition from the polling copilot source)."
+    }
+  },
+  "contract": {
+    "version": 1,
+    "summary": "Installers substitute {{TOOL:...}}, {{PATH:...}}, and {{SECTION:...}} tokens in generated harness files using this map. This contract is the single reference installers must implement; token-map.json is the data those rules operate on.",
+    "harness_ids": ["copilot", "claude", "pi"],
+    "binding": "The harness id is the same value the installer is invoked with (agent-cortex install <harness>). Each harness reads its own column from the tools, paths, and agents sections.",
+    "substitution_order": ["SECTION", "TOOL", "PATH"],
+    "rules": [
+      "TOOL: replace {{TOOL:<key>}} with tools.<key>.<harness>. Canonical keys are exact, case-sensitive strings (the copilot tool names, which are the authoring names in agents/<name>/agent.md).",
+      "TOOL null: a null value means the harness has no equivalent. In prose, remove the token (and emit a warning). In a tool-list context (frontmatter tools: [...]), omit the entry. Do not substitute an empty string.",
+      "TOOL unknown: a {{TOOL:<key>}} with no entry in tools is a hard error — the map must be extended. This mirrors the generators (scripts/build-copilot-agents.mjs, bin/installers/claude.mjs), which throw on unknown tools.",
+      "PATH named key: replace {{PATH:<key>}} with the resolved value of paths.<key>.<harness>.",
+      "PATH relative: replace {{PATH:<relative>}} with plugin_root + '/' + <relative> (e.g. {{PATH:skills/workflow/plan/SKILL.md}}).",
+      "PATH resolution: a value may be a literal string, an ${ENV_VAR} token, or a {base, relative} spec. Resolve {base, relative} by joining relative onto the resolved base. Leave ${ENV_VAR} values verbatim — the harness expands them at runtime (claude's ${CLAUDE_PLUGIN_ROOT}).",
+      "PATH unknown base: a {base, relative} spec whose base is not a key in paths is a hard error.",
+      "SECTION: {{SECTION:<name>}} is resolved by the agent composer from <agents_dir>/<harness>/<name>.md; token-map.json does not substitute it. Installers must leave SECTION tokens untouched for the composer.",
+      "Contract version: installers must reject token-map.json versions higher than the contract version they implement.",
+      "Case sensitivity: all token arguments and map keys are case-sensitive."
+    ],
+    "error_handling": {
+      "unknown_tool": "throw — the map must stay complete",
+      "unknown_path_base": "throw — the map must stay complete",
+      "null_tool_in_prose": "warn and drop the token",
+      "null_tool_in_tool_list": "omit the entry from the array",
+      "unsupported_version": "throw with the supported version range"
+    }
+  }
+}