@jaybeeuu/agent-cortex 1.42.0 → 2.0.0

package/test/release-gates.test.mjs

@@ -0,0 +1,190 @@
+// Behaviour tests for the release gates that keep `main` from re-publishing a
+// version: the inverted PR changeset gate and the no-publish release gate.
+// The decision logic is pure; the two CLI adapters are exercised through their
+// process boundary because that is the contract CI depends on.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  PUBLISH_COMMAND,
+  NO_PUBLISH_COMMAND,
+  evaluateChangesetGate,
+  parseNameStatus,
+  resolvePublishCommand,
+} from "../scripts/lib/release-gates.mjs";
+
+const CHECK_CHANGESET = fileURLToPath(new URL("../scripts/check-changeset.mjs", import.meta.url));
+const RESOLVE_PUBLISH = fileURLToPath(
+  new URL("../scripts/resolve-publish-command.mjs", import.meta.url),
+);
+
+function runScript(script, { args = [], env = {}, stdin = "" } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      env: { ...process.env, ...env },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.stdin.end(stdin);
+  });
+}
+
+describe("parseNameStatus", () => {
+  it("parses added and modified paths from git diff --name-status output", () => {
+    const changes = parseNameStatus("M\tpackage.json\nA\t.changeset/fix-release.md\n");
+
+    assert.deepEqual(changes, [
+      { status: "M", path: "package.json" },
+      { status: "A", path: ".changeset/fix-release.md" },
+    ]);
+  });
+
+  it("uses the new path for a rename", () => {
+    const changes = parseNameStatus("R087\t.changeset/old.md\t.changeset/new.md\n");
+
+    assert.deepEqual(changes, [{ status: "R", path: ".changeset/new.md" }]);
+  });
+
+  it("returns no changes for empty output", () => {
+    assert.deepEqual(parseNameStatus(""), []);
+  });
+});
+
+describe("evaluateChangesetGate", () => {
+  it("passes a PR that adds a changeset", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "A", path: ".changeset/fix-release.md" }],
+      labels: [],
+      headRef: "fix/release-gate",
+      actor: "jaybeeuu",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "changeset-added" });
+  });
+
+  it("fails a CI-only change that adds no changeset", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: ".github/workflows/ci.yml" }],
+      labels: [],
+      headRef: "chore/bump-pnpm",
+      actor: "jaybeeuu",
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, "missing-changeset");
+  });
+
+  it("fails a PR that only modifies an existing changeset", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: ".changeset/pending.md" }],
+      labels: [],
+      headRef: "chore/edit-changeset",
+      actor: "jaybeeuu",
+    });
+
+    assert.equal(result.ok, false);
+  });
+
+  it("fails a PR that only adds the changeset README", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "A", path: ".changeset/README.md" }],
+      labels: [],
+      headRef: "docs/changesets",
+      actor: "jaybeeuu",
+    });
+
+    assert.equal(result.ok, false);
+  });
+
+  it("passes an unlabelled-change PR carrying the no-publish label", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: ".github/workflows/ci.yml" }],
+      labels: ["no-publish"],
+      headRef: "chore/bump-pnpm",
+      actor: "jaybeeuu",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "no-publish-label" });
+  });
+
+  it("passes the Version Packages PR by head branch", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: "package.json" }],
+      labels: [],
+      headRef: "changeset-release/main",
+      actor: "jaybeeuu",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "version-packages-pr" });
+  });
+
+  it("passes a PR opened by the GitHub Actions bot", () => {
+    const result = evaluateChangesetGate({
+      changes: [{ status: "M", path: "package.json" }],
+      labels: [],
+      headRef: "automation/some-branch",
+      actor: "github-actions[bot]",
+    });
+
+    assert.deepEqual(result, { ok: true, reason: "version-packages-pr" });
+  });
+});
+
+describe("resolvePublishCommand", () => {
+  it("publishes by default when the merged PR has no labels", () => {
+    assert.equal(resolvePublishCommand([]), PUBLISH_COMMAND);
+  });
+
+  it("publishes when the merged PR carries unrelated labels", () => {
+    assert.equal(resolvePublishCommand(["bug", "priority:p2"]), PUBLISH_COMMAND);
+  });
+
+  it("refuses to publish when the merged PR carries the no-publish label", () => {
+    assert.equal(resolvePublishCommand(["bug", "no-publish"]), NO_PUBLISH_COMMAND);
+  });
+
+  it("matches the label exactly, not as a substring", () => {
+    assert.equal(resolvePublishCommand(["no-publish-ci"]), PUBLISH_COMMAND);
+  });
+});
+
+describe("check-changeset CLI", () => {
+  it("exits 0 for a no-publish PR with no diff", async () => {
+    const { code } = await runScript(CHECK_CHANGESET, {
+      env: { PR_LABELS: '["no-publish"]', PR_HEAD_REF: "chore/bump-pnpm", PR_ACTOR: "jaybeeuu" },
+    });
+
+    assert.equal(code, 0);
+  });
+
+  it("exits 1 and explains the no-publish escape hatch for a changeset-less PR", async () => {
+    const { code, stderr } = await runScript(CHECK_CHANGESET, {
+      stdin: "M\tpackage.json\n",
+      env: { PR_LABELS: "[]", PR_HEAD_REF: "chore/bump-pnpm", PR_ACTOR: "jaybeeuu" },
+    });
+
+    assert.equal(code, 1);
+    assert.match(stderr, /no-publish/);
+  });
+});
+
+describe("resolve-publish-command CLI", () => {
+  it("prints the noop command for a no-publish label set", async () => {
+    const { code, stdout } = await runScript(RESOLVE_PUBLISH, {
+      args: ['["no-publish"]'],
+    });
+
+    assert.equal(code, 0);
+    assert.equal(stdout.trim(), NO_PUBLISH_COMMAND);
+  });
+});

package/test/verify-worker-tree.test.mjs

@@ -0,0 +1,120 @@
+// Integration tests for scripts/lib/verify-worker-tree.mjs. The module exists to
+// tell a worker that delivered from one that only said it did, so each case runs
+// a real git repository and asserts the verdict — no mocking of git, because git
+// is the thing whose state the verdict is about.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { verifyWorkerTree } from "../scripts/lib/verify-worker-tree.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/** Run a git command in `cwd`. */
+async function git(cwd, args) {
+  await execFileAsync("git", args, { cwd });
+}
+
+/** A repository with one base commit; returns its directory and that commit. */
+async function createRepo() {
+  const dir = await mkdtemp(join(tmpdir(), "verify-worker-tree-"));
+  await git(dir, ["init", "--quiet"]);
+  await git(dir, ["config", "user.email", "t@example.com"]);
+  await git(dir, ["config", "user.name", "T"]);
+  // A developer's global config may enable commit signing; the fixture must not
+  // depend on a secret key being present.
+  await git(dir, ["config", "commit.gpgsign", "false"]);
+  await writeFile(join(dir, "README.md"), "base\n");
+  await git(dir, ["add", "-A"]);
+  await git(dir, ["commit", "-m", "base"]);
+  const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: dir });
+  return { dir, base: stdout.trim() };
+}
+
+/** Commit a file in the repo, as a delivering worker would. */
+async function commitWork(dir) {
+  await writeFile(join(dir, "worker-output.txt"), "delivered\n");
+  await git(dir, ["add", "-A"]);
+  await git(dir, ["commit", "-m", "worker: deliver"]);
+}
+
+describe("verifyWorkerTree", () => {
+  it("passes a worker that committed and left a clean tree", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await commitWork(dir);
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.deepEqual(verdict, { ok: true, reasons: [], commitsAhead: 1 });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("fails a worker that reported success but left its work uncommitted", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await writeFile(join(dir, "left-behind.txt"), "uncommitted\n");
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, false);
+      assert.equal(verdict.reasons[0], "worktree is dirty: 1 uncommitted path(s)");
+      assert.equal(verdict.commitsAhead, 0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("fails a worker that left a clean tree with nothing committed", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, false);
+      assert.equal(verdict.reasons.length, 1);
+      assert.match(verdict.reasons[0], /^no commit ahead of base [0-9a-f]{7}$/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("reports a dirty tree and a missing commit together", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await writeFile(join(dir, "partial.txt"), "half done\n");
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, false);
+      assert.equal(verdict.reasons.length, 2);
+      assert.equal(verdict.reasons[0], "worktree is dirty: 1 uncommitted path(s)");
+      assert.match(verdict.reasons[1], /^no commit ahead of base [0-9a-f]{7}$/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("counts every commit the worker made, not just the last", async () => {
+    const { dir, base } = await createRepo();
+    try {
+      await commitWork(dir);
+      await writeFile(join(dir, "second.txt"), "more\n");
+      await git(dir, ["add", "-A"]);
+      await git(dir, ["commit", "-m", "worker: second"]);
+
+      const verdict = await verifyWorkerTree({ worktree: dir, base });
+
+      assert.equal(verdict.ok, true);
+      assert.equal(verdict.commitsAhead, 2);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/token-map.README.md

@@ -1,7 +1,7 @@
 # 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
+**agent naming conventions** across the two 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.
@@ -14,15 +14,14 @@ decisions behind the map.
 
 | 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` |
+| `pi` | pi coding agent | `agents/<name>/` composable dirs (composed at runtime by agent-modes, or rendered install-time by `agent-cortex install pi`) | `~/.agent-cortex/pi` |
 | `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
-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").
+`lib/cli.mjs` (`SUPPORTED_HARNESSES`). The pi `plugin_root` row is the staged package
+directory `agent-cortex install pi` materialises, which pi then loads by path; checkout
+and symlinked installs pass `--plugin-root <dir>` to override it (see README "Pi package
+staging (`agent-cortex install pi`)").
 
 ## Design decisions
 
@@ -44,12 +43,13 @@ rather than inventing a dotted form:
 ### 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
+  (the canonical authoring names). Each row gives the equivalent tool name per harness.
+  The claude column is 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 `ask_questions` — added by the pi-questions package (mapped from
-  `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools; `skill` maps
+  `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools, the last three
+  supplied by this repo's own `extensions/subagent` rather than by pi; `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
@@ -100,7 +100,7 @@ so the warn-and-omit path applies only to future null entries. See
 
 The full contract is embedded in `token-map.json` under `contract`. In summary, installers:
 
-1. Bind a harness id (`copilot` | `claude` | `pi`).
+1. Bind a harness id (`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.
@@ -110,7 +110,7 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
 
 ## Authoring guidance
 
-- Write tokens with the **canonical (copilot) names**: `Use {{TOOL:task}} to spawn
+- Write tokens with the **canonical authoring 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 materialised Claude plugin
@@ -124,11 +124,9 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
 
 - `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.
+- `scripts/lib/compose-agent.mjs` — the shared token composer: resolves `{{TOOL:...}}` /
+  `{{PATH:...}}` against the map and `{{SECTION:...}}` from the per-harness section files
+  for `bin/installers/claude.mjs` and `bin/installers/pi.mjs`.
 - `bin/installers/claude.mjs` — the single Claude generator: plain
   `agent-cortex install claude` materialises the plugin into `~/.agent-cortex/claude`
   with token-substituted skills, merges the committed `claude/settings.json` into

package/token-map.json

@@ -1,8 +1,8 @@
 {
   "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.",
+  "description": "Central mapping of tool names, paths, and agent naming conventions across the 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"],
+  "harnesses": ["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.",
@@ -13,40 +13,36 @@
     }
   },
   "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": "ask_questions" },
-    "web_fetch": { "copilot": "web_fetch", "claude": "WebFetch", "pi": "fetch_content" },
-    "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" }
+    "bash": { "claude": "Bash", "pi": "bash" },
+    "view": { "claude": "Read", "pi": "read" },
+    "edit": { "claude": "Edit", "pi": "edit" },
+    "create": { "claude": "Write", "pi": "write" },
+    "grep": { "claude": "Grep", "pi": "grep" },
+    "rg": { "claude": "Grep", "pi": "grep" },
+    "glob": { "claude": "Glob", "pi": "find" },
+    "ask_user": { "claude": "AskUserQuestion", "pi": "ask_questions" },
+    "web_fetch": { "claude": "WebFetch", "pi": "fetch_content" },
+    "skill": { "claude": "Skill", "pi": "read" },
+    "task": { "claude": "Task", "pi": "task" },
+    "read_agent": { "claude": null, "pi": "read_agent" },
+    "wait_for_agents": { "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"
+      "pi": "~/.agent-cortex/pi"
     },
     "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:"
     },
@@ -54,40 +50,40 @@
       "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, the only generator — the generated claude/ plugin subtree is not committed), 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.",
+      "rg": "Canonical alias for grep. Claude and pi collapse it onto their single search tool (Grep / grep).",
       "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's equivalent is ask_questions, provided by the pi-questions package (declared in the package manifest — package.json pi.packages — and provisioned by agent-cortex install pi; also declared in pi/settings.json for the symlinked checkout) — 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 the package manifest — package.json pi.packages — and provisioned by agent-cortex install pi).",
-      "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."
+      "ask_user": "Claude (AskUserQuestion) prompts the user mid-run. pi's equivalent is ask_questions, provided by the pi-questions package (an ordinary runtime dependency of this package that `agent-cortex install pi` bundles into the staged package's node_modules) — 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 (an ordinary runtime dependency of this package that `agent-cortex install pi` bundles into the staged package's node_modules).",
+      "skill": "Claude (Skill) exposes 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). pi exposes read_agent as a fallback to wait_for_agents.",
+      "task": "Claude provides a subagent tool natively. On pi it is supplied by this repo's own extensions/subagent extension (which also registers read_agent and wait_for_agents), not by pi itself — a pi session started before that extension was installed has no dispatch tool at all. Skills must therefore stop and report a missing subagent tool rather than improvising a backgrounded CLI run, which has no completion signal.",
+      "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. Claude's Task delivers results inline with no wait step — null on claude."
     },
     "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 is the staged package `agent-cortex install pi` materialises at ~/.agent-cortex/pi; pi loads that directory by path and the shipped extensions resolve their own resources relative to it (agent-modes computes plugin_root from its actual install location). A checkout or symlinked install differs — installers compute plugin_root from the actual resolution and can override it (--plugin-root).",
       "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>.",
-      "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)."
+      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): 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 pi 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"],
+    "harness_ids": ["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: replace {{TOOL:<key>}} with tools.<key>.<harness>. Canonical keys are exact, case-sensitive strings (the names the canonical sources in agents/<name>/agent.md are authored with).",
       "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.",
+      "TOOL unknown: a {{TOOL:<key>}} with no entry in tools is a hard error — the map must be extended. This mirrors the generators (bin/installers/claude.mjs, bin/installers/pi.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}).",

package/agents/plan/copilot/frontmatter.json

@@ -1,6 +0,0 @@
-{
-  "name": "agent-cortex: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", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill"],
-  "argumentHint": "Plan <feature or change description>"
-}

package/agents/plan.agent.md

@@ -1,59 +0,0 @@
----
-# GENERATED from agents/plan/ by scripts/build-copilot-agents.mjs — DO NOT EDIT.
-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'."
-name: "agent-cortex:plan"
-tools: ["bash", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill"]
-argument-hint: "Plan <feature or change description>"
----
-
-# 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.

package/agents/ralph/copilot/frontmatter.json

@@ -1,6 +0,0 @@
-{
-  "name": "agent-cortex:ralph",
-  "description": "Use when running all pending beads end-to-end: finds the next available beads (dependencies met), runs the full implement → review → fix cycle for each feature in its own worktree, opens and reports PRs immediately, then waits for human merges before continuing.",
-  "tools": ["bash", "view", "rg", "glob", "task", "read_agent"],
-  "argumentHint": "Run all pending beads"
-}