@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

package/test/pi-packages.test.mjs

@@ -0,0 +1,295 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm, chmod } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  loadRequiredPackages,
+  npmSourceName,
+  planPackageInstalls,
+  provisionPiPackages,
+  runPiInstall,
+} from "../lib/pi-packages.mjs";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+async function makePiRoot({ declared = [], installed = [], settingsRaw } = {}) {
+  const root = await mkdtemp(join(tmpdir(), "pi-packages-"));
+  if (settingsRaw !== undefined) {
+    await writeFile(join(root, "settings.json"), settingsRaw);
+  } else if (declared.length > 0) {
+    await writeFile(join(root, "settings.json"), JSON.stringify({ packages: declared }));
+  }
+  for (const name of installed) {
+    await mkdir(join(root, "npm", "node_modules", name), { recursive: true });
+  }
+  return { root, cleanup: async () => rm(root, { recursive: true, force: true }) };
+}
+
+/** A runner that records every source it is asked to install. */
+function recordingRunner({ results = {} } = {}) {
+  const calls = [];
+  const runner = async (source) => {
+    calls.push(source);
+    return results[source] ?? { ok: true, error: null };
+  };
+  return { runner, calls };
+}
+
+/** Run `fn` with PATH set to `pathValue`, restoring the previous PATH afterwards. */
+async function withPath(pathValue, fn) {
+  const original = process.env.PATH;
+  process.env.PATH = pathValue;
+  try {
+    return await fn();
+  } finally {
+    process.env.PATH = original;
+  }
+}
+
+/** Write an executable `pi` stub with the given shell body; returns its dir and cleanup. */
+async function makePiStub(body) {
+  const dir = await mkdtemp(join(tmpdir(), "pi-stub-"));
+  const file = join(dir, "pi");
+  await writeFile(file, `#!/bin/sh\n${body}\n`);
+  await chmod(file, 0o755);
+  return { dir, cleanup: async () => rm(dir, { recursive: true, force: true }) };
+}
+
+/** A directory with nothing on PATH, so any external command lookup fails. */
+async function makeEmptyPathDir() {
+  const dir = await mkdtemp(join(tmpdir(), "pi-stub-empty-"));
+  return { dir, cleanup: async () => rm(dir, { recursive: true, force: true }) };
+}
+
+// ─── Manifest ────────────────────────────────────────────────────────────────
+
+describe("loadRequiredPackages", () => {
+  it("reads the declared pi packages from the package manifest", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-packages-manifest-"));
+    try {
+      await writeFile(
+        join(root, "package.json"),
+        JSON.stringify({ name: "x", pi: { extensions: ["./extensions"], packages: ["npm:pi-questions"] } }),
+      );
+      assert.deepEqual(await loadRequiredPackages(root), ["npm:pi-questions"]);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("returns no packages when the manifest does not declare any", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-packages-manifest-"));
+    try {
+      await writeFile(join(root, "package.json"), JSON.stringify({ name: "x", pi: { skills: ["./skills"] } }));
+      assert.deepEqual(await loadRequiredPackages(root), []);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── Source parsing ──────────────────────────────────────────────────────────
+
+describe("npmSourceName", () => {
+  it("extracts the package name from npm sources, including scoped and pinned specs", () => {
+    assert.equal(npmSourceName("npm:pi-questions"), "pi-questions");
+    assert.equal(npmSourceName("npm:pi-web-access@0.10.7"), "pi-web-access");
+    assert.equal(npmSourceName("npm:@scope/pkg@1.2.3"), "@scope/pkg");
+  });
+
+  it("returns null for non-npm sources it cannot verify locally", () => {
+    assert.equal(npmSourceName("git:github.com/user/repo"), null);
+    assert.equal(npmSourceName("./local/path"), null);
+  });
+});
+
+// ─── Install plan ────────────────────────────────────────────────────────────
+
+describe("planPackageInstalls", () => {
+  it("plans nothing when every required package is declared and installed", () => {
+    assert.deepEqual(
+      planPackageInstalls(["npm:pi-questions"], {
+        declaredSources: ["npm:pi-questions"],
+        installedNames: ["pi-questions"],
+      }),
+      [],
+    );
+  });
+
+  it("plans a package that is declared but not installed", () => {
+    assert.deepEqual(
+      planPackageInstalls(["npm:pi-web-access@0.10.7"], {
+        declaredSources: ["npm:pi-web-access@0.10.7"],
+        installedNames: [],
+      }),
+      ["npm:pi-web-access@0.10.7"],
+    );
+  });
+
+  it("plans a package that is installed but not declared, so pi will load it", () => {
+    assert.deepEqual(
+      planPackageInstalls(["npm:pi-questions"], {
+        declaredSources: [],
+        installedNames: ["pi-questions"],
+      }),
+      ["npm:pi-questions"],
+    );
+  });
+});
+
+// ─── Provisioning ────────────────────────────────────────────────────────────
+
+describe("runPiInstall", () => {
+  it("degrades to a result when the pi CLI is not on PATH", async () => {
+    const empty = await makeEmptyPathDir();
+    try {
+      const result = await withPath(empty.dir, () => runPiInstall("npm:pi-questions"));
+      assert.deepEqual(result, { ok: false, error: "pi CLI not found on PATH" });
+    } finally {
+      await empty.cleanup();
+    }
+  });
+
+  it("maps a successful pi install to ok", async () => {
+    const stub = await makePiStub("exit 0");
+    try {
+      const result = await withPath(stub.dir, () => runPiInstall("npm:pi-questions"));
+      assert.deepEqual(result, { ok: true, error: null });
+    } finally {
+      await stub.cleanup();
+    }
+  });
+
+  it("maps a failing pi install to its stderr", async () => {
+    const stub = await makePiStub('echo "offline: no registry" >&2\nexit 1');
+    try {
+      const result = await withPath(stub.dir, () => runPiInstall("npm:pi-questions"));
+      assert.deepEqual(result, { ok: false, error: "offline: no registry" });
+    } finally {
+      await stub.cleanup();
+    }
+  });
+});
+
+describe("provisionPiPackages", () => {
+  it("installs missing packages and skips the ones already present", async () => {
+    const fx = await makePiRoot({ declared: ["npm:pi-questions"], installed: ["pi-questions"] });
+    try {
+      const { runner, calls } = await recordingRunner();
+
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+        piRoot: fx.root,
+        runInstall: runner,
+      });
+
+      assert.deepEqual(calls, ["npm:pi-web-access@0.10.7"], "only the missing package is installed");
+      assert.deepEqual(result.installed, ["npm:pi-web-access@0.10.7"]);
+      assert.deepEqual(result.failed, []);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("is idempotent — a second run with everything present installs nothing", async () => {
+    const fx = await makePiRoot({
+      declared: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+      installed: ["pi-questions", "pi-web-access"],
+    });
+    try {
+      const { runner, calls } = await recordingRunner();
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+        piRoot: fx.root,
+        runInstall: runner,
+      });
+      assert.deepEqual(calls, []);
+      assert.deepEqual(result.installed, []);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("reports a failed install and continues with the rest", async () => {
+    const fx = await makePiRoot();
+    try {
+      const warnings = [];
+      const { runner, calls } = await recordingRunner({
+        results: { "npm:pi-questions": { ok: false, error: "offline" } },
+      });
+
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+        piRoot: fx.root,
+        runInstall: runner,
+        warn: (msg) => warnings.push(msg),
+      });
+
+      assert.deepEqual(calls, ["npm:pi-questions", "npm:pi-web-access@0.10.7"], "failure does not abort the rest");
+      assert.deepEqual(result.installed, ["npm:pi-web-access@0.10.7"]);
+      assert.deepEqual(result.failed, [{ source: "npm:pi-questions", error: "offline" }]);
+      assert.ok(warnings.some((w) => w.includes("npm:pi-questions")), "failure is surfaced as a warning");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("uses the pi CLI runner by default and warns when it is missing", async () => {
+    const fx = await makePiRoot();
+    const empty = await makeEmptyPathDir();
+    try {
+      const warnings = [];
+      const result = await withPath(empty.dir, () =>
+        provisionPiPackages({
+          required: ["npm:pi-questions"],
+          piRoot: fx.root,
+          warn: (msg) => warnings.push(msg),
+        }),
+      );
+
+      assert.deepEqual(result.failed, [{ source: "npm:pi-questions", error: "pi CLI not found on PATH" }]);
+      assert.ok(
+        warnings.some((w) => w.includes("pi CLI not found on PATH")),
+        "missing CLI is surfaced as a warning, not a thrown error",
+      );
+    } finally {
+      await empty.cleanup();
+      await fx.cleanup();
+    }
+  });
+
+  it("dry-run reports the plan without installing anything", async () => {
+    const fx = await makePiRoot();
+    try {
+      const { runner, calls } = await recordingRunner();
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions"],
+        piRoot: fx.root,
+        runInstall: runner,
+        dryRun: true,
+      });
+      assert.deepEqual(calls, []);
+      assert.deepEqual(result.planned, ["npm:pi-questions"]);
+      assert.deepEqual(result.installed, []);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("treats an unreadable settings file as no declarations rather than failing the install", async () => {
+    const fx = await makePiRoot({ settingsRaw: "{ not json" });
+    try {
+      const { runner, calls } = await recordingRunner();
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions"],
+        piRoot: fx.root,
+        runInstall: runner,
+      });
+      assert.deepEqual(calls, ["npm:pi-questions"], "still attempts the install");
+      assert.deepEqual(result.installed, ["npm:pi-questions"]);
+    } finally {
+      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,11 +129,12 @@ 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 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/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
+  `~/.claude/settings.json`, and registers it with Claude Code; `--output <dir>` is the
+  generate-only form (tests/CI structural checks). The only committed `claude/` file is the
+  settings template.
 - `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 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.",
       "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.",
+      "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."
     },
     "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.39.0",
-  "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.

package/claude/agents/ralph-plan.md

@@ -1,121 +0,0 @@
----
-# GENERATED from agents/ralph-plan/ by bin/installers/claude.mjs — DO NOT EDIT.
-name: ralph-plan
-description: "Plans changes by exploring codebases and creating beads to track the work. Use when you want to scope a feature, bug fix, or refactor — the agent reads, reasons, grills the user, writes a high-level plan into the top-level bead, then files child beads ready for ralph."
-tools: Bash, Read, Edit, Write, Grep, Glob, AskUserQuestion
----
-
-# ralph-plan — planning agent for ralph
-
-You are a planning agent. Your job is to understand a task, explore the codebase, grill the user until the design is clear, write a concise implementation plan, and file beads for ralph to implement. You **must not** modify any source code or tracked documentation — your writes are limited to `.agent-cortex/working-docs/` and bead fields.
-
-## Permitted writes
-
-| Location | Purpose |
-|---|---|
-| `.agent-cortex/working-docs/` | Research notes, decision records, exploration findings — gitignored, never committed |
-| Bead `description` / `design` fields | High-level plan (≤100 lines) written via MCP tools |
-
-Do **not** write anywhere else. No source files, no READMEs, no tracked docs, no commits.
-
-## .agent-cortex/working-docs conventions
-
-- Create `.agent-cortex/working-docs/` if it doesn't exist.
-- One file per concern: `exploration-<area>.md`, `decisions.md`, `open-questions.md`, etc.
-- Sub-agents write their findings here; they do not update beads.
-- Keep files focused — a few hundred lines max each.
-- The directory is gitignored; treat it as a scratchpad, not a deliverable.
-
-## Workflow
-
-### 1. Load context
-Invoke the **beads** skill (set workspace root, run `bd prime`). Hold the output in memory.
-
-If the input looks like a PRD (product requirements document), invoke the **prd-to-tasks** skill first — it handles exploration, user quizzing, and creates epics and task beads directly. Then continue from step 7 (Agree with the user).
-
-### 2. Understand the request
-If the request is ambiguous or incomplete, use AskUserQuestion to resolve blockers before exploring. One question at a time.
-
-If the domain language is unclear or inconsistent, invoke the **grill-with-docs** skill to extract canonical terms. It updates `CONTEXT.md` inline and surfaces ambiguities.
-
-### 3. Explore the codebase
-Dispatch parallel **explore** sub-agents — one per independent research area. Tell each sub-agent to write its findings to a named file in `.agent-cortex/working-docs/` and **not** to modify any beads or source files. Provide each sub-agent with the full `bd prime` output.
-
-- If the task involves a bug or regression, investigate the root cause directly before exploring broader context: trace the code path, check recent changes with `git log`, attempt to reproduce, and classify the failure (regression / missing edge case / design flaw). Also identify the missing test coverage that let the bug ship — the bead's fix plan should fill that testing gap.
-- If the task involves architectural change, invoke **improve-codebase-architecture** to surface structural concerns.
-- If the task requires designing a new module API or interface, invoke **design-an-interface** to generate and compare options. Write the output to `.agent-cortex/working-docs/interface-design.md`.
-
-### 4. Grill the user
-After reviewing exploration findings, invoke the **grill-me** skill to surface and resolve outstanding design questions. Keep grilling until there are no open questions that would block implementation. Record answers in `.agent-cortex/working-docs/decisions.md`.
-
-### 5. Write the plan
-Update the top-level bead's `design` field with a high-level implementation plan. Invoke the **style-comms** skill first so the plan matches the project's communication style.
-
-- **≤100 lines**. Link to `.agent-cortex/working-docs/` files for any detail that would push it over.
-- Structure: Goal → Key decisions → Ordered workstreams → Risks / out-of-scope
-- No line-by-line code guidance — just what, not how.
-
-### 6. Decompose into tasks
-For large workstreams (multiple distinct areas) invoke the **prd-to-tasks** skill. For a single self-contained task invoke **create-task**. Pass the full `bd prime` output and any relevant design context from the `design` field to each skill.
-
-For each new feature bead and each new task bead, create a HITL planning gate before handoff. The feature/task bead depends on this gate and stays blocked until the user explicitly confirms planning is sufficient **for that specific feature/task**.
-
-Every planning gate description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
-
-```bash
-gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>")
-bd tag <planning-gate-id> implementation-type:hitl
-bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on planning gate (gate blocks implementation)
-```
-
-Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature/task is ready to implement; leave all unconfirmed gates open and blocking.
-
-Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field.
-
-Tag every bead created in this step with `workflow:ralph`:
-
-```bash
-bd tag <id> workflow:ralph
-```
-
-Tag every bead with a priority using the unified scale:
-
-```bash
-bd tag <id> priority:<p0|p1|p2|p3|p4|p5>
-```
-
-| Priority | When | Examples |
-|---|---|---|
-| P0 | Drop everything | Crash, data loss, security breach |
-| P1 | Fix before next feature | Major bug, no workaround |
-| P2 | Fix soon, still before features | Minor bug, workaround exists |
-| P3 | Core feature, blocks others | Feature that unlocks downstream work |
-| P4 | Feature, important | Valuable but doesn't block others |
-| P5 | Nice-to-have | Polish, cosmetic, improvement |
-
-Bugs naturally outrank features on this scale (P0-P2 are always bugs). Calibrate each
-bead against the full backlog — a P3 feature that blocks others may need a higher
-explicit priority than a standalone P4 feature.
-
-### 7. Agree with the user
-Present the bead list (IDs, titles, one-line rationale each) plus planning gate status for each item using `✅` (confirmed/closed) or `⏳` (awaiting confirmation/open). Ask the user to confirm or request changes before finishing.
-
-If any planning gates remain open, include an explicit warning that those features/tasks are still blocked and cannot be handed off to ralph yet. Iterate until approved.
-
-### 8. Hand off to ralph
-Once approved, report: "Plan complete — `bd ready` will show the first tasks for ralph."
-
-## Exploration sub-agent instructions
-
-Every explore sub-agent prompt must include:
-1. The full `bd prime` output as context.
-2. The specific area to investigate.
-3. The path to write findings to (e.g. `.agent-cortex/working-docs/exploration-auth.md`).
-4. The instruction: **"Write your findings to the file above. Do not modify any beads, source files, or tracked documentation."**
-
-## Guardrails
-
-- Never assume — verify by reading actual code before creating a bead.
-- Never write outside `.agent-cortex/working-docs/` or bead fields.
-- Never make commits, open PRs, or run shell commands that modify the repo.
-- Use Bash only for read-only commands (`git log`, `find`, `cat`, etc.).