@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

package/test/pi-installer.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, readdirSync } from "node:fs";
+import { mkdtemp, mkdir, writeFile, rm, readFile, readdir, stat } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -10,6 +10,16 @@ import { installPi } from "../bin/installers/pi.mjs";
 // works against the canonical sources (agents/, skills/, token-map.json).
 const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── Fixtures ────────────────────────────────────────────────────────────────
 
 const TOOL_MAP = {
@@ -37,29 +47,29 @@ function tokenMap(extra = {}) {
   };
 }
 
-function makeFixture() {
-  const root = mkdtempSync(join(tmpdir(), "pi-installer-"));
+async function makeFixture() {
+  const root = await mkdtemp(join(tmpdir(), "pi-installer-"));
   const output = join(root, "out");
   return {
     root,
     output,
-    cleanup: () => rmSync(root, { recursive: true, force: true }),
+    cleanup: async () => rm(root, { recursive: true, force: true }),
   };
 }
 
-function writeFixture(fx, relPath, content) {
+async function writeFixture(fx, relPath, content) {
   const p = join(fx.root, relPath);
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, content);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, content);
 }
 
 /** Seed a minimal but realistic package tree (agents + token-map + skills). */
-function seedPackage(fx, opts = {}) {
+async function seedPackage(fx, opts = {}) {
   const { agents = {}, skills = {}, tokenMap: map, version } = opts;
-  writeFixture(fx, "token-map.json", JSON.stringify(map ?? tokenMap(version ? { version } : {})));
+  await 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(
+    await writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
+    await writeFixture(
       fx,
       `agents/${name}/pi/frontmatter.json`,
       JSON.stringify(
@@ -72,20 +82,20 @@ function seedPackage(fx, opts = {}) {
       ),
     );
     for (const [section, content] of Object.entries(def.sections ?? {})) {
-      writeFixture(fx, `agents/${name}/pi/${section}.md`, content);
+      await writeFixture(fx, `agents/${name}/pi/${section}.md`, content);
     }
   }
   for (const [path, content] of Object.entries(skills)) {
-    writeFixture(fx, `skills/${path}`, content);
+    await writeFixture(fx, `skills/${path}`, content);
   }
 }
 
-function listFiles(dir) {
-  if (!existsSync(dir)) return [];
+async function listFiles(dir) {
+  if (!(await pathExists(dir))) return [];
   const out = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
     const p = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...listFiles(p).map((f) => join(entry.name, f)));
+    if (entry.isDirectory()) out.push(...(await listFiles(p)).map((f) => join(entry.name, f)));
     else out.push(entry.name);
   }
   return out;
@@ -94,10 +104,10 @@ function listFiles(dir) {
 // ─── 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();
+  it("writes one .agent.md per composable agent dir with pi frontmatter and no leftover tokens", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, {
+      await seedPackage(fx, {
         agents: {
           alpha: {
             body: "# alpha\nUse {{TOOL:view}} to read.\n{{SECTION:polling}}\nRead {{PATH:skills_dir}}.",
@@ -112,11 +122,11 @@ describe("installPi — agent composition", () => {
         },
       });
 
-      const result = installPi({ root: fx.root, output: fx.output });
+      const result = await 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(await pathExists(file), "agent file written");
+      const content = await readFile(file, "utf-8");
       assert.ok(content.startsWith("---\n"), "yaml frontmatter");
       assert.match(content, /name: "agent-cortex:alpha"/);
       assert.match(content, /description: "Reads things\."/);
@@ -128,55 +138,55 @@ describe("installPi — agent composition", () => {
       assert.equal(result.agents.length, 1);
       assert.deepEqual(result.agents[0], { name: "alpha", filePath: file });
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("drops null-mapped tool tokens in prose and reports a warning", () => {
-    const fx = makeFixture();
+  it("drops null-mapped tool tokens in prose and reports a warning", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, {
+      await 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");
+      const result = await installPi({ root: fx.root, output: fx.output });
+      const content = await readFile(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();
+      await fx.cleanup();
     }
   });
 
-  it("throws on an unknown tool token", () => {
-    const fx = makeFixture();
+  it("throws on an unknown tool token", async () => {
+    const fx = await 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}}/);
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha\nUse {{TOOL:nope}} now." } } });
+      await assert.rejects(installPi({ root: fx.root, output: fx.output }), /unknown tool token {{TOOL:nope}}/);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("throws when a section file referenced by {{SECTION:...}} is missing", () => {
-    const fx = makeFixture();
+  it("throws when a section file referenced by {{SECTION:...}} is missing", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, { agents: { alpha: { body: "# alpha\n{{SECTION:missing}}" } } });
-      assert.throws(() => installPi({ root: fx.root, output: fx.output }), /missing section "missing"/);
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha\n{{SECTION:missing}}" } } });
+      await assert.rejects(installPi({ root: fx.root, output: fx.output }), /missing section "missing"/);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("resolves named and relative {{PATH:...}} tokens against the plugin root", () => {
-    const fx = makeFixture();
+  it("resolves named and relative {{PATH:...}} tokens against the plugin root", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, {
+      await seedPackage(fx, {
         agents: {
           alpha: {
             body: "# alpha\nNamed: {{PATH:skills_dir}}\nRelative: {{PATH:skills/x/SKILL.md}}",
@@ -184,8 +194,8 @@ describe("installPi — agent composition", () => {
         },
       });
 
-      const result = installPi({ root: fx.root, output: fx.output });
-      const content = readFileSync(join(fx.output, "agents", "alpha.agent.md"), "utf-8");
+      const result = await installPi({ root: fx.root, output: fx.output });
+      const content = await readFile(join(fx.output, "agents", "alpha.agent.md"), "utf-8");
 
       assert.ok(
         content.includes("Named: ~/.pi/agent/npm/node_modules/@jaybeeuu/agent-cortex/skills"),
@@ -197,38 +207,38 @@ describe("installPi — agent composition", () => {
       );
       assert.equal(result.warnings.length, 0);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("honours the --plugin-root override for path resolution", () => {
-    const fx = makeFixture();
+  it("honours the --plugin-root override for path resolution", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, {
+      await 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");
+      await installPi({ root: fx.root, output: fx.output, pluginRoot });
+      const content = await readFile(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();
+      await fx.cleanup();
     }
   });
 
-  it("rejects token-map.json versions newer than the implemented contract", () => {
-    const fx = makeFixture();
+  it("rejects token-map.json versions newer than the implemented contract", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, {
+      await seedPackage(fx, {
         version: 99,
         agents: { alpha: { body: "# alpha" } },
       });
-      assert.throws(() => installPi({ root: fx.root, output: fx.output }), /version 99/);
+      await assert.rejects(installPi({ root: fx.root, output: fx.output }), /version 99/);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -236,10 +246,10 @@ describe("installPi — agent composition", () => {
 // ─── Skills ──────────────────────────────────────────────────────────────────
 
 describe("installPi — skills", () => {
-  it("copies skills into <output>/skills preserving the grouped layout with substituted tokens", () => {
-    const fx = makeFixture();
+  it("copies skills into <output>/skills preserving the grouped layout with substituted tokens", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, {
+      await seedPackage(fx, {
         agents: { alpha: { body: "# alpha" } },
         skills: {
           "engineering/echo/SKILL.md":
@@ -248,11 +258,11 @@ describe("installPi — skills", () => {
         },
       });
 
-      installPi({ root: fx.root, output: fx.output });
+      await 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(await pathExists(skillFile), "skill copied");
+      const content = await readFile(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(
@@ -263,10 +273,10 @@ describe("installPi — skills", () => {
       );
       assert.ok(!/{{/.test(content), "no literal tokens remain in skill");
 
-      const script = readFileSync(join(fx.output, "skills", "engineering", "echo", "scripts", "run.sh"), "utf-8");
+      const script = await readFile(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();
+      await fx.cleanup();
     }
   });
 });
@@ -274,37 +284,37 @@ describe("installPi — skills", () => {
 // ─── Output / dry-run ────────────────────────────────────────────────────────
 
 describe("installPi — output & dry-run", () => {
-  it("dry-run writes nothing but reports the planned output", () => {
-    const fx = makeFixture();
+  it("dry-run writes nothing but reports the planned output", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, {
+      await 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 });
+      const result = await 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((await 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();
+      await fx.cleanup();
     }
   });
 
-  it("creates the output directory hierarchy when needed", () => {
-    const fx = makeFixture();
+  it("creates the output directory hierarchy when needed", async () => {
+    const fx = await makeFixture();
     try {
-      seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await 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")));
+      await installPi({ root: fx.root, output: deep });
+      assert.ok(await pathExists(join(deep, "agents", "alpha.agent.md")));
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -312,60 +322,66 @@ describe("installPi — output & dry-run", () => {
 // ─── 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();
+  it("installs every canonical agent with pi tool names and no leftover tokens", async () => {
+    const fx = await makeFixture();
     try {
-      const result = installPi({ root: REPO_ROOT, output: fx.output });
+      const result = await 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");
+      const ralph = await readFile(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"/);
+      // plan body carries the relative {{PATH:...}} resolved against the plugin root.
+      // Tool list preserves authoring order (composer translateToolList, unlike the
+      // runtime agent-modes translateTools which sorts): ask_user → ask_questions,
+      // skill → read (last position).
+      const plan = await readFile(join(fx.output, "agents", "plan.agent.md"), "utf-8");
+      assert.match(plan, /tools: "bash read edit write grep find ask_questions task read_agent read"/);
       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");
+      // ralph-plan prose {{TOOL:ask_user}} now substitutes to ask_questions
+      const ralphPlan = await readFile(join(fx.output, "agents", "ralph-plan.agent.md"), "utf-8");
+      assert.ok(!ralphPlan.includes("ask_user"), "ask_user never appears in ralph-plan body");
+      assert.ok(ralphPlan.includes("ask_questions"), "{{TOOL:ask_user}} substituted to ask_questions");
       assert.ok(
-        result.warnings.some((w) => w.includes("ask_user")),
-        "ralph-plan null tool dropped with a warning",
+        !result.warnings.some((w) => w.includes("ask_user")),
+        "no null-tool warning for ralph-plan (ask_user now maps to ask_questions)",
       );
 
-      // 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"/);
+      // strategy: web_fetch → fetch_content; ask_user → ask_questions; skill → read
+      // (authoring order preserved: bash, view→read, rg→grep, glob→find, ask_user→
+      // ask_questions, web_fetch→fetch_content, skill→read, edit, create)
+      const strategy = await readFile(join(fx.output, "agents", "strategy.agent.md"), "utf-8");
+      assert.match(strategy, /tools: "bash read grep find ask_questions fetch_content read edit write"/);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("substitutes tokens in every installed skill markdown", () => {
-    const fx = makeFixture();
+  it("substitutes tokens in every installed skill markdown", async () => {
+    const fx = await makeFixture();
     try {
-      const result = installPi({ root: REPO_ROOT, output: fx.output });
+      const result = await 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"));
+      const files = (await 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");
+        const content = await readFile(join(fx.output, "skills", f), "utf-8");
         assert.ok(!/{{/.test(content), `no literal tokens in skill ${f}`);
       }
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });

package/token-map.README.md

@@ -16,7 +16,7 @@ decisions behind the map.
 |---|---|---|---|
 | `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) |
+| `claude` | Claude Code | `~/.agent-cortex/claude/agents/*.md` (materialised home install) | `${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
@@ -48,11 +48,19 @@ rather than inventing a dotted form:
   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.
+  `ls`) plus `ask_questions` — added by the pi-questions package (mapped from
+  `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools; `skill` maps
+  to `read` (skills load by reading the listed SKILL.md path).
 - **`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.
+  Claude's `plugin_root` stays the `${CLAUDE_PLUGIN_ROOT}` env-var token, never a literal
+  `~/.agent-cortex/claude`: Claude Code **copies** marketplace-installed plugins — including
+  local directory sources like `~/.agent-cortex/claude` — into its own cache, so only the
+  runtime env var (expanded per context by Claude Code) points at wherever the plugin
+  actually runs from. A literal home path in substituted files would break under
+  cache-copy, so the installer passes the env form through verbatim.
 - **`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
@@ -83,8 +91,10 @@ The pi install-time installer (`bin/installers/pi.mjs`) follows the strict contr
 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`.
+native PI tool — while a mapped-null tool is omitted with a warning. The pi column
+currently maps every canonical tool (`ask_user` → `ask_questions`, `skill` → `read`),
+so the warn-and-omit path applies only to future null entries. See
+`extensions/agent-modes/README.md`.
 
 ### 4. Token substitution contract
 
@@ -103,9 +113,9 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
 - 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.
+  `skills/**/SKILL.md`) — that defeats the map. The materialised Claude plugin
+  (`~/.agent-cortex/claude`), 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.
@@ -119,9 +129,10 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
   `{{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 both
-  `agent-cortex install claude` and the `pnpm build:claude` alias (no build-time
-  counterpart; the committed `claude/` subtree is regenerated by it and drift-checked).
+- `bin/installers/claude.mjs` — the single Claude generator: plain
+  `agent-cortex install claude` materialises the plugin into `~/.agent-cortex/claude`
+  with token-substituted skills and registers it with Claude Code; `--output <dir>` is the
+  generate-only form (tests/CI structural checks). The repo commits no `claude/` output.
 - `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

package/token-map.json

@@ -20,9 +20,9 @@
     "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 },
+    "ask_user": { "copilot": "ask_user", "claude": "AskUserQuestion", "pi": "ask_questions" },
     "web_fetch": { "copilot": "web_fetch", "claude": "WebFetch", "pi": "fetch_content" },
-    "skill": { "copilot": "skill", "claude": "Skill", "pi": null },
+    "skill": { "copilot": "skill", "claude": "Skill", "pi": "read" },
     "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" }
@@ -56,21 +56,22 @@
     "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"
+      "claude": "agents/<name>/ composable dirs (canonical) — composed by bin/installers/claude.mjs (install-time generator, the only generator — the repo commits no claude/ output), 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.",
+      "ask_user": "Copilot (ask_user) and Claude (AskUserQuestion) prompt the user mid-run. pi's equivalent is ask_questions, provided by the pi-questions package (pi install npm:pi-questions; declared in pi/settings.json) — the genuine interactive-questioning tool, restoring grilling in plan/ralph-plan/strategy modes. Like fetch_content (pi-web-access), it is only present when its package is installed, so the mapping depends on that package (see the extension-manifests idea). pi still intentionally ships no permission popups; ask_questions is the interactive mid-run question tool, not a popup.",
       "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.",
+      "skill": "Copilot (skill) and Claude (Skill) expose skills as a tool. pi has no dedicated skill tool — skills are surfaced in the always-present 'Available skills' context block and loaded by reading the listed SKILL.md path ({{PATH:<skill>/SKILL.md}}). The pi mapping is read, the tool used to load a skill's file; a dedicated skill tool is a follow-on design candidate if prompting proves insufficient.",
       "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."
+      "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.",
+      "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim."
     },
     "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>.",

package/.claude-plugin/marketplace.json

@@ -1,16 +0,0 @@
-{
-  "name": "jaybeeuu",
-  "owner": {
-    "name": "jaybeeuu"
-  },
-  "metadata": {
-    "description": "jaybeeuu's personal Claude Code plugins."
-  },
-  "plugins": [
-    {
-      "name": "agent-cortex",
-      "source": "./claude",
-      "description": "Personal Claude Code plugin with custom agents and skills"
-    }
-  ]
-}

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

@@ -1,11 +0,0 @@
-{
-  "name": "agent-cortex",
-  "version": "1.38.1",
-  "description": "Personal Claude Code plugin with custom agents and skills",
-  "author": {
-    "name": "jaybeeuu"
-  },
-  "license": "MIT",
-  "repository": "https://github.com/jaybeeuu/agent-cortex",
-  "hooks": "./hooks.json"
-}

package/claude/agents/plan.md

@@ -1,58 +0,0 @@
----
-# GENERATED from agents/plan/ by bin/installers/claude.mjs — DO NOT EDIT.
-name: plan
-description: "Guide a feature from first discussion through PRD and task breakdown to classified beads ready for ralph execution. Full end-to-end planning workflow using the plan skill. Use when starting a new feature, scoping work to hand off to ralph, or saying 'plan this'."
-tools: Bash, Read, Edit, Write, Grep, Glob, AskUserQuestion, Task, Skill
----
-
-# plan — end-to-end feature planning agent
-
-You are a planning agent. Your job is to guide a feature from first discussion through PRD and task breakdown to classified beads ready for ralph execution.
-
-You follow the **plan** skill workflow. The skill is defined in `skills/workflow/plan/SKILL.md`. Read it now to load the full instructions.
-
-## Workflow summary
-
-### Phase 1 — Understand and specify
-1. Ask the user to describe the problem, goal, or feature.
-2. Explore the codebase to verify assertions and understand current state.
-3. Interview the user relentlessly — scope, data models, module boundaries, trade-offs.
-4. Sketch major modules.
-5. Draft a PRD using the `write-a-prd` template.
-6. Present the PRD for user approval.
-7. Create an epic bead from the approved PRD.
-
-### Phase 2 — Break into tasks
-8. Review PRD stories and identify vertical-slice phases.
-9. Define each phase (title, stories, what to build, acceptance criteria).
-10. Create epics for multi-phase work.
-11. Present the breakdown for user approval.
-
-### Phase 3 — Create and classify beads
-13. Create task beads via `create-task` for each task.
-14. Tag parent epics with aggregate classification.
-15. Present the full bead tree.
-
-### Phase 4 — Prepare handoff to ralph
-16. Determine the handoff bead (epic or meta-epic).
-17. Tag it `workflow:ralph`.
-18. Push bead state with `bd dolt push`.
-19. Present the handoff summary.
-
-## Permitted writes
-
-| Location | Purpose |
-|---|---|
-| `.agent-cortex/working-docs/` | Research notes, decisions, exploration findings — gitignored |
-| Bead fields (`description`, `design`) | Plans and specifications |
-| `docs/prd/<topic>.md` | PRD documents |
-
-Do **not** modify source code or tracked documentation outside these locations.
-
-## Constraints
-
-- Never modify source code.
-- Always get user approval before moving between phases.
-- Each phase has a gate — do not skip it.
-- Work in `.agent-cortex/working-docs/` for scratchpad notes.
-- Use `bd` commands for all bead operations.