@jaybeeuu/agent-cortex 1.38.1 → 1.39.0

package/AGENTS.md

@@ -67,7 +67,9 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   `agent-cortex install copilot` and `scripts/build-copilot-agents.mjs` (thin wrapper), and
   committed for Copilot CLI (plugin.json `agents: "agents/"` scans for `*.agent.md`); never edit
   them by hand. The `claude/` subtree is generated by the install-time generator
-  `bin/installers/claude.mjs` (`pnpm build:claude` aliases `agent-cortex install claude`; `ralph`
+  `bin/installers/claude.mjs` (a plain `agent-cortex install claude` also registers the plugin
+  with Claude Code via the `claude plugin` CLI; `pnpm build:claude` is the generate-only alias,
+  running `agent-cortex install claude --output claude`; `ralph`
   is authored natively in `agents-native/` and copied verbatim; the other agents compose from their
   `claude/` harness dirs).
 - Keep orchestration logic in the agent file; extract shared per-task workflow into a skill

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.39.0
+
+### Minor Changes
+
+- 5d4159f: Handoff documents now end with a `## Starter prompt` section: a ready-to-paste first-message prompt pointing the next session at the handoff doc by absolute path and the artifacts it references, telling it to read those before acting, asking it to clean up any provisional artifacts unless the handoff says otherwise, and staying under ~150 words.
+- 5351ae9: agent-cortex install claude now fully installs agent-cortex into Claude Code: it regenerates the claude/ subtree and registers it with the Claude Code runtime via the claude plugin CLI (--dry-run prints the plan without writing; --output <dir> generates only).
+
+### Patch Changes
+
+- adb5f84: Add optional ASCII workflow diagram guidance (inclusion rules, style guide, template example) to the skill anatomy and reference it from write-a-skill
+- 5d4159f: Fix create-chores to resolve `bd` via PATH by default instead of a machine-specific hardcoded path. The BD_PATH env override is retained for machines where bd is not on PATH.
+- 3e8b6e7: Refactor the `hitl-collab` skill to the canonical anatomy template: added When to use / When NOT to use boundaries, Red Flags, Common Rationalizations, a worked handoff-doc example, and a verification checklist; switched bead updates to `--append-notes` so existing notes are preserved.
+- b33d9ef: Refactor the improve-codebase-architecture skill to the anatomy template: add when-to-use / when-not-to-use boundaries, red flags, common rationalizations, philosophy, phase-gate checklists, cross-skill references, a worked example, and a verification checklist.
+- da1e3dd: Add `bd dep add` line to the init-beads skill's embedded AGENTS.md quick-reference template so it matches the repo template and stops re-propagating the drift
+- 358509f: Prune stale doc-contract prose assertions from the run-pipeline-stage progress test; re-enable the skills-script test suites in the pnpm workspace so they actually run in CI.
+- 32b33ac: Refactor the record-idea skill to the anatomy template: add when-to-use boundaries, red flags, rationale, and a verification checklist; move the idea-record scaffold to FORMAT.md to match the generator script.
+- 662cea5: Refactor the `classify-bead` skill to the anatomy template: adds when-not-to-use boundaries, red flags, common rationalizations, philosophy, and a verification checklist.
+- bb01fd6: Refactor create-task skill to the anatomy template: adds When to use / When NOT to use, Red Flags, Common Rationalizations, verification checklist, and moves the bead-property contract detail to REFERENCE.md. No behavioural change — the create-chores script invocation contract is preserved exactly.
+- 876e5cc: Refactor design-an-interface skill to the anatomy template: adds When to use, When NOT to use, verification checklist, phase gates, and rationalization sections while keeping the parallel sub-agent design workflow intact
+- 00c4238: Refactor grill-with-docs to the anatomy template: add when-to-use boundaries, numbered workflow, red flags, common rationalizations, examples, and a verification checklist; consolidate the previously-dangling CONTEXT.md/ADR format links into REFERENCE.md.
+- fd5f787: Refactor init-beads skill to the anatomy template: adds When to use / When NOT to use, Red Flags, Common Rationalizations, Cross-skill references, Examples, and a verification checklist. No behavioural change — the `bd init --quiet --stealth` invocation, install-method preference order, and AGENTS.md quick-reference block are preserved exactly.
+- 608fb58: Refactor maintain-agent-docs skill to the canonical anatomy template: added When NOT to use, Philosophy, Red Flags, Common Rationalizations, Phase-gate checklist, Cross-skill references, Examples, and a concrete Verification checklist; tightened the description to the two-sentence format with quoted trigger phrases.
+- 027431c: Refactor the `prd-to-tasks` skill to the canonical anatomy template: condensed the 5-phase workflow, moved the epic/task body templates into `REFERENCE.md`, added Examples and Phase-gate checklists, and aligned section ordering and voice with `docs/skills/skill-anatomy.md`.
+- e80246a: Refactor the ralph skill to the canonical skill anatomy: add When to use / When NOT to use, Red Flags, Common Rationalizations, Philosophy, phase-gate checklists, cross-skill references, and a verification checklist; align the skill docs with the ralph agent definition (state.json for poll-timer and agent-ID→bead bookkeeping, parent-keyed stage log files, stage runners self-serving `bd prime`, and the single-feature-epic one-hop branching shortcut).
+- d917afb: Refactor request-refactor-plan SKILL.md to the anatomy template; move the refactor plan template into FORMAT.md.
+- d6d33ec: Refactor technical-direction skill to the canonical anatomy template, adding when-to-use/not-to-use boundaries, red flags, common rationalizations, cross-skill references, an examples section, and a verification checklist. The decision-memo template moves to FORMAT.md.
+- 67a668f: Refactor the write-a-prd skill to the anatomy template: adds when-to-use/when-not-to-use boundaries, red flags, common rationalizations, phase gates, cross-skill references, an example, and a verification checklist; the PRD template moves to FORMAT.md.
+- bedd373: Refactor the write-a-ticket skill to the canonical anatomy template: added when-to-use and when-not-to-use boundaries, red flags, common rationalizations, philosophy, cross-skill references, worked examples, and a verification checklist. The ticket template and per-section guidance are preserved.
+- fd95ffe: Refactor run-pipeline-stage SKILL.md to the canonical anatomy template: add `When to use`, `When NOT to use`, `Workflow`, `Red Flags`, `Common Rationalizations`, `Cross-skill references`, `Examples`, `Philosophy / rationale`, and a `Verification checklist`; add quoted trigger phrases to the description; tokenize subagent dispatch as {{TOOL:task}}. No behavioural change to the stage pipeline — all playbooks, prompts, dispatch rules, and path references are preserved.
+
 ## 1.38.1
 
 ### Patch Changes

package/README.md

@@ -38,7 +38,7 @@ agent-cortex/
 │   ├── agent-cortex.mjs      # CLI entrypoint
 │   └── installers/
 │       ├── copilot.mjs       # shared generator: agent-cortex install copilot + scripts/build-copilot-agents.mjs
-│       └── claude.mjs        # install-time generator — agent-cortex install claude (pnpm build:claude aliases it)
+│       └── claude.mjs        # install-time generator + Claude Code registrar (pnpm build:claude = generate-only --output form)
 ├── scripts/
 │   └── build-copilot-agents.mjs  # thin wrapper over bin/installers/copilot.mjs (regenerates agents/*.agent.md)
 └── claude/                   # Self-contained Claude Code plugin (GENERATED — do not hand-edit)
@@ -62,9 +62,11 @@ The `{{TOOL:...}}` / `{{PATH:...}}` tokens written in agent and skill files are
 per harness at install time from `token-map.json`, the single source of truth for
 canonical tool/path/agent names (see `token-map.README.md` and the `contract` section).
 The `claude/` subtree is **generated** by the install-time generator
-(`bin/installers/claude.mjs`) — `pnpm build:claude` is a pure alias of
-`agent-cortex install claude`, so there is no separate build-time code path, and the
-committed subtree can never diverge from a real install. CI regenerates it and checks
+(`bin/installers/claude.mjs`). A plain `agent-cortex install claude` regenerates the
+subtree AND registers it with Claude Code by driving the `claude plugin` CLI (marketplace
+add → install → marketplace update → plugin update). `pnpm build:claude` is the pure,
+generate-only alias — it passes `--output claude`, so CI and release drift-checks never
+spawn the claude CLI or touch `~/.claude`. CI regenerates it and checks
 it is never stale:
 
 - **Skills** stay single-source — `claude/skills/<name>` are symlinks into the grouped
@@ -193,14 +195,14 @@ change the sources:
 
 ```sh
 pnpm build:copilot   # or: node scripts/build-copilot-agents.mjs (regenerates agents/*.agent.md)
-pnpm build:claude    # or: node bin/agent-cortex.mjs install claude (same generator)
+pnpm build:claude    # or: node bin/agent-cortex.mjs install claude --output claude (generate-only)
 # or the install-time entry (same generator, less typing):
 node bin/agent-cortex.mjs install copilot          # regenerates agents/*.agent.md in place
 node bin/agent-cortex.mjs install copilot --dry-run       # plan only, no writes
 node bin/agent-cortex.mjs install copilot --output /tmp/x # preview the flat files elsewhere
-node bin/agent-cortex.mjs install claude           # regenerates ./claude in place
-node bin/agent-cortex.mjs install claude --dry-run       # plan only, no writes
-node bin/agent-cortex.mjs install claude --output /tmp/x # write the subtree elsewhere
+node bin/agent-cortex.mjs install claude           # regenerates ./claude AND registers it with Claude Code
+node bin/agent-cortex.mjs install claude --dry-run       # plan generation + registration, no writes/spawns
+node bin/agent-cortex.mjs install claude --output /tmp/x # generate only — no registration
 ```
 
 #### Try it for one session
@@ -217,8 +219,20 @@ claude --plugin-dir /path/to/agent-cortex/claude plugin details agent-cortex
 #### Install persistently (recommended)
 
 The repo ships a marketplace manifest (`.claude-plugin/marketplace.json`) that exposes the
-`claude/` subtree. Register it by **absolute path** (a bare `.` is rejected — use an absolute
-path or a `./`-prefixed one), then install:
+`claude/` subtree. A plain `agent-cortex install claude` does both halves in one step: it
+regenerates `claude/` and registers the plugin with Claude Code by driving the `claude
+plugin` CLI (marketplace add → install → marketplace update → plugin update), pointing it
+at this checkout's manifest. This requires the `claude` plugin CLI (Claude Code v2+):
+
+```sh
+git clone https://github.com/jaybeeuu/agent-cortex   # first time (or git pull to update)
+agent-cortex install claude                          # regenerate + register (user scope)
+```
+
+`--dry-run` prints the full plan without spawning the claude CLI or writing anything;
+`--output <dir>` regenerates only, with no registration. The equivalent manual registration
+(e.g. on a Claude Code build without the plugin CLI) adds the checkout by **absolute path**
+(a bare `.` is rejected):
 
 ```sh
 claude plugin marketplace add /path/to/agent-cortex
@@ -232,16 +246,18 @@ flag, and Ralph is just `claude --agent agent-cortex:ralph`.
 
 #### Update
 
-The marketplace source is your local checkout, so after pulling changes you must rebuild the
-`claude/` subtree and refresh the plugin:
+The marketplace source is your local checkout, so after pulling changes re-run the installer —
+it rebuilds the `claude/` subtree and refreshes the registered plugin (marketplace update →
+plugin update) in one step:
 
 ```sh
 git pull
-pnpm build:claude                          # alias of agent-cortex install claude
-claude plugin marketplace update jaybeeuu
-claude plugin update agent-cortex          # restart Claude Code to apply
+agent-cortex install claude                # rebuild + refresh (restart Claude Code to apply)
 ```
 
+`pnpm build:claude` only regenerates the subtree (no registration), so on its own it won't
+refresh an installed plugin.
+
 #### Uninstall
 
 ```sh
@@ -300,7 +316,9 @@ per-harness frontmatter/sections, auto-composed by `scripts/build-copilot-agents
 the install-time generator `bin/installers/claude.mjs`), `agents-native/*.md` (Claude-only
 agents like `ralph` — the canonical bodies the installer copies verbatim), `skills/**`,
 `hooks/claude/hooks.json` (hook config), and `package.json` (plugin
-version) — then run `pnpm build:claude` (an alias of `agent-cortex install claude`). Never hand-edit
+version) — then run `pnpm build:claude` (the generate-only alias of `agent-cortex install
+claude --output claude`; run the plain install instead if you also want the plugin
+re-registered with Claude Code). Never hand-edit
 anything under `claude/` except the hand-authored `claude/.mcp.json` and `claude/scripts/`
 files, or the generated `agents/*.agent.md` files, `claude/agents/`, `claude/skills/`,
 `claude/.claude-plugin/plugin.json`, and `claude/hooks.json`. CI runs

package/agents/README.md

@@ -209,8 +209,9 @@ flat `agents/*.agent.md` files are built from them:
 - `scripts/build-copilot-agents.mjs` (`pnpm build:copilot`) composes `agents/*.agent.md` from
   each agent's `copilot/` harness dir — committed for Copilot CLI, which loads `*.agent.md`
   from `plugin.json`'s `agents: "agents/"` path.
-- `bin/installers/claude.mjs` (`agent-cortex install claude`; `pnpm build:claude` is a pure
-  alias) composes `claude/agents/*.md` from each agent's `claude/` harness dir (except
+- `bin/installers/claude.mjs` (plain `agent-cortex install claude` also registers the plugin
+  with Claude Code; `pnpm build:claude` is its generate-only alias, running `install claude
+  --output claude`) composes `claude/agents/*.md` from each agent's `claude/` harness dir (except
   `ralph`, which ships natively from `agents-native/ralph.md`, copied verbatim).
 - The pi harness delivers two ways: the `agent-modes` extension composes `agent.md` +
   `pi/frontmatter.json` at runtime against `token-map.json`, and `agent-cortex install pi`
@@ -219,9 +220,10 @@ flat `agents/*.agent.md` files are built from them:
 
 Never edit the generated flat/claude files by hand — edit the composable directory. CI
 regenerates both outputs and fails on drift. Generation is install-time: `claude` ships
-via `bin/installers/claude.mjs`, the single generator behind both `agent-cortex install
-claude` and the `pnpm build:claude` alias (the committed `claude/` subtree is regenerated
-by it and drift-checked, so it can never be stale); `copilot` ships via
+via `bin/installers/claude.mjs`, the 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`) — the committed `claude/` subtree
+is regenerated by it and drift-checked, so it can never be stale; `copilot` ships via
 `bin/installers/copilot.mjs`, the shared code path behind both `agent-cortex install
 copilot` and `scripts/build-copilot-agents.mjs`; `pi` ships via
 `bin/installers/pi.mjs`, which materialises composed agents + token-substituted skills

package/agents/ralph-plan/agent.md

@@ -63,7 +63,7 @@ bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on p
 
 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.
 
-After creating each bead, invoke **classify-bead** to ensure it has an `implementation-type` label before handing off.
+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`:
 

package/agents/ralph-plan.agent.md

@@ -71,7 +71,7 @@ bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on p
 
 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.
 
-After creating each bead, invoke **classify-bead** to ensure it has an `implementation-type` label before handing off.
+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`:
 

package/bin/agent-cortex.mjs

@@ -46,15 +46,23 @@ if (parsed.command === "install") {
 
   process.stdout.write(`Installing agent-cortex for "${parsed.harness}" harness…\n`);
 
-  // claude is the first wired harness: generates the plugin subtree from the
-  // canonical sources (agents/, agents-native/, skills/, hooks/claude/) via the
-  // shared installClaude generator — `pnpm build:claude` is an alias of this
-  // invocation, so there is no separate build-time code path.
+  // claude is the first wired harness: a plain `agent-cortex install claude`
+  // regenerates the plugin subtree from the canonical sources (agents/,
+  // agents-native/, skills/, hooks/claude/) via the shared installClaude
+  // generator AND registers it with Claude Code (marketplace add → install →
+  // update) — `pnpm build:claude` is the generate-only alias of this
+  // invocation (it passes `--output claude`), so there is no separate
+  // build-time code path and CI drift-checks never touch ~/.claude.
   if (parsed.harness === "claude") {
     // Avoid loading the installer on the help/summary paths and for other harnesses.
-    const { installClaude } = await import("./installers/claude.mjs");
+    const { installClaude, registerClaude } = await import("./installers/claude.mjs");
     try {
       installClaude({ output: parsed.output, dryRun: parsed.dryRun });
+      // Runtime registration happens only for the plain install — `--output`
+      // keeps generating only (documented in --help).
+      if (parsed.output === undefined) {
+        registerClaude({ dryRun: parsed.dryRun });
+      }
       process.exit(0);
     } catch (err) {
       process.stderr.write(`Install failed: ${err.message}\n`);

package/bin/installers/claude.mjs

@@ -1,19 +1,24 @@
-// Install-time generator for the Claude Code plugin subtree — the ONLY code path
-// for producing claude/ from the canonical sources. There is no build-time
-// generator: the package script `pnpm build:claude` is a pure alias of the CLI
-// (`node bin/agent-cortex.mjs install claude`), so regenerating the committed
-// subtree and installing the plugin run exactly the same code:
+// Install-time generator + registrar for the Claude Code plugin. Producing
+// claude/ from the canonical sources is the ONLY code path — there is no
+// separate build-time generator: the package script `pnpm build:claude` runs
+// the same command as the CLI with `--output` (`node bin/agent-cortex.mjs
+// install claude --output claude`), so the committed subtree and installer
+// output can never diverge:
 //
-//   node bin/agent-cortex.mjs install claude   `pnpm build:claude` (regenerates
-//                              the committed claude/ subtree in place; `--output
-//                              <dir>` targets another dir, `--dry-run` plans
-//                              without writing)
+//   node bin/agent-cortex.mjs install claude        regenerates claude/ in place
+//                               AND registers the plugin with Claude Code via
+//                               the `claude plugin` CLI (marketplace add →
+//                               install → marketplace update → plugin update)
+//   node bin/agent-cortex.mjs install claude --output <dir>
+//                               generates only — no runtime registration
+//   node bin/agent-cortex.mjs install claude --dry-run
+//                               plans generation + registration without writing
 //
-// claude/ stays committed (not gitignored): the marketplace install flow
-// (`claude plugin marketplace add <repo>` → `claude plugin install
-// agent-cortex@jaybeeuu`) reads the subtree straight from the working tree, so a
-// fresh clone installs as-is with no generation step. CI regenerates it via the
-// same installer and runs `git diff --exit-code claude/...` — byte-for-byte
+// claude/ stays committed (not gitignored): registration points Claude Code's
+// marketplace at this checkout (`.claude-plugin/marketplace.json` exposes
+// ./claude), so the plugin content is the working tree and a fresh clone
+// installs as-is with no generation step. CI regenerates claude/ via
+// `--output` and runs `git diff --exit-code claude/...` — byte-for-byte
 // validation that the committed output equals installer output, catching stale
 // output and hand-edits to generated files alike.
 //
@@ -39,7 +44,8 @@
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
 import { readFileSync, writeFileSync, mkdirSync, rmSync, symlinkSync, statSync, existsSync, readdirSync } from "node:fs";
-import { join, dirname, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { join, dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
 
@@ -258,5 +264,113 @@ export function installClaude({ root = DEFAULT_ROOT, output, dryRun = false } =
     console.log(`Skipped hooks.json — ${hooksSrc} not found (existing file left untouched)`);
   }
 
+  return summary;
+}
+
+// ─── Claude Code registration ────────────────────────────────────────────────
+
+// The `claude` CLI on PATH. Overridable in tests via the claudeBin option.
+const DEFAULT_CLAUDE_BIN = "claude";
+
+/**
+ * Read the marketplace manifest that exposes this checkout's claude/ subtree
+ * (`.claude-plugin/marketplace.json`); returns the marketplace and plugin
+ * names that `claude plugin` commands address. Registration is only possible
+ * from a checkout carrying the manifest.
+ */
+function readMarketplaceManifest(root) {
+  const manifestPath = join(root, ".claude-plugin", "marketplace.json");
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  } catch (err) {
+    throw new Error(
+      `no Claude marketplace manifest at ${manifestPath} (${err.message}) — ` +
+        `"agent-cortex install claude" registers the plugin by pointing Claude Code at this checkout`,
+    );
+  }
+  const marketplace = manifest.name;
+  const plugin = manifest.plugins?.[0]?.name;
+  if (typeof marketplace !== "string" || typeof plugin !== "string") {
+    throw new Error(
+      `unparsable marketplace manifest at ${manifestPath}: expected { name, plugins: [{ name }] }`,
+    );
+  }
+  return { marketplace, plugin };
+}
+
+/** Run one claude plugin command, inheriting its output; throws on failure. */
+function runClaudeCommand(claudeBin, args) {
+  const label = `${claudeBin} ${args.join(" ")}`;
+  const result = spawnSync(claudeBin, args, { stdio: "inherit" });
+  if (result.error) {
+    throw new Error(`failed to run "${label}": ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`"${label}" exited ${result.status}`);
+  }
+}
+
+/**
+ * Register the freshly generated claude/ subtree with Claude Code by driving
+ * the `claude plugin` CLI against this checkout as the marketplace source:
+ *
+ *   1. `claude plugin marketplace add <root>`        (idempotent: already on disk)
+ *   2. `claude plugin install <plugin>@<market> -y`  (idempotent: already installed)
+ *   3. `claude plugin marketplace update <market>`   (re-validate the directory source)
+ *   4. `claude plugin update <plugin> -y`            (refresh the cache on version bumps)
+ *
+ * Requires a Claude Code binary whose `plugin` subcommand exists (v2+); older
+ * CLIs treat the args as a chat prompt, so support is probed first. In
+ * --dry-run mode nothing is spawned — the commands are reported as a plan.
+ *
+ * @param {object} options
+ * @param {string} [options.root]      Checkout root carrying .claude-plugin/marketplace.json
+ *                                     (defaults to the repo containing this module)
+ * @param {string} [options.claudeBin] The `claude` executable (default: `claude` from PATH)
+ * @param {boolean} [options.dryRun]   Plan and report without running or writing
+ * @returns {{ marketplace: string, plugin: string, commands: string[][], dryRun: boolean }}
+ */
+export function registerClaude({ root = DEFAULT_ROOT, claudeBin = DEFAULT_CLAUDE_BIN, dryRun = false } = {}) {
+  const { marketplace, plugin } = readMarketplaceManifest(root);
+  const pluginId = `${plugin}@${marketplace}`;
+  const commands = [
+    ["plugin", "marketplace", "add", resolve(root)],
+    ["plugin", "install", pluginId, "-y"],
+    ["plugin", "marketplace", "update", marketplace],
+    ["plugin", "update", plugin, "-y"],
+  ];
+
+  const summary = { marketplace, plugin, commands, dryRun };
+  console.log(`Registering plugin "${pluginId}" with Claude Code (via ${claudeBin})…`);
+
+  if (dryRun) {
+    for (const args of commands) console.log(`  would run: ${claudeBin} ${args.join(" ")}`);
+    console.log("(dry-run — no Claude Code state written)");
+    return summary;
+  }
+
+  // Older Claude Code builds treat `claude plugin …` as a chat prompt; reject
+  // them up-front instead of letting the registration appear to succeed.
+  const probe = spawnSync(claudeBin, ["plugin", "--help"], { stdio: "ignore" });
+  if (probe.error) {
+    throw new Error(
+      `cannot run "${claudeBin}" (${probe.error.message}) — is Claude Code installed and on PATH?`,
+    );
+  }
+  if (probe.status !== 0) {
+    throw new Error(
+      `"${claudeBin}" lacks the "plugin" subcommand — its Claude Code build predates plugin support; ` +
+        `update to a build with the plugin CLI (v2+), e.g. "pnpm add -g @anthropic-ai/claude-code@latest", and re-run`,
+    );
+  }
+
+  for (const args of commands) {
+    console.log(`  ${claudeBin} ${args.join(" ")}`);
+    runClaudeCommand(claudeBin, args);
+  }
+  console.log(
+    `Installed — verify with "claude plugin list" / "claude plugin details ${plugin}" (restart Claude Code to apply).`,
+  );
   return summary;
 }

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

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

package/claude/agents/ralph-plan.md

@@ -70,7 +70,7 @@ bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on p
 
 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.
 
-After creating each bead, invoke **classify-bead** to ensure it has an `implementation-type` label before handing off.
+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`:
 

package/docs/ideas/extension-manifests.md

@@ -0,0 +1,75 @@
+# Idea: extension-manifests
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-08-25
+
+## Problem
+PI extensions and Claude/Copilot plugins are installed individually (`pi install <ext>`) and
+live implicit in the machine's state (`~/.pi/agent/extensions/`) with no declared manifest of
+what the author uses or where it came from. A fresh machine, clean `~/.pi`, or a failed update
+leaves the environment without the expected extensions. The toolset isn't reproducible and
+isn't documented anywhere in the author's repos. Experimenting with an extension (install, try,
+remove) is also all manual, and there's no way to uninstall cleanly.
+
+## Who benefits
+The author. Installing/updating agent-cortex becomes a reliable way to restore a known PI +
+Claude environment (agent-cortex + declared extensions in one step). The manifests document and
+reproduce the toolset across machines. A prune CLI makes extension experimentation fast and safe.
+
+## Proposed outcome
+agent-cortex ships **committed extension manifests** (reviewed and stored on GitHub) declaring
+which extensions to install — **per harness**: one manifest for PI extensions, one for
+Claude/Copilot plugins. On install or update of agent-cortex, it reads the manifests and
+installs the declared extensions. The manifests are the single source of truth.
+
+Key decisions from the interview:
+
+1. **No monitoring** — nothing observes installs, and the CLI never writes the manifests.
+   Adding an extension = edit the manifest, commit it, ship it. This keeps the source of truth
+   in GitHub where it belongs (and gets the usual PR/review flow).
+2. **Per-harness manifests** — separate records for the pi harness vs the Claude harness, each
+   carrying the extension source (git URL / package name) for that harness's installer. The
+   install-on-update path handles each harness with its own mechanism.
+3. **Prune CLI with a TUI** — a CLI command (e.g. `agent-cortex ext prune`) opens an interactive
+   TUI listing locally-installed extensions; selecting one **uninstalls** it from the local
+   environment. Removing from the manifest is done manually on GitHub. This supports the
+   experimentation loop: install → try → prune locally, then curate the manifest separately.
+
+agent-cortex's own bundled extensions (auto-discovered via `pi install`, e.g. `skill-stats`)
+are deliberately excluded from the manifests — only third-party extensions are declared.
+
+## Validity check
+- Evidence we already have: agent-cortex already has an install surface to hang this on
+  (`pi install` package discovery for the pi harness, plus the existing `bin/agent-cortex.mjs`
+  install command and `postinstall` script). The repo already carries a `plugin.json` (Claude
+  harness) alongside `package.json` (pi harness), showing the per-harness split is natural.
+- Riskiest assumption: that an automated install-on-update of declared extensions is safe and
+  desirable (auto-installing on every update could surprise, or fail mid-flight on a new
+  machine lacking auth/network). Also, the TUI prune needs the local extension store's shape
+  (`~/.pi/agent/extensions/` for pi; whatever Claude uses) to be introspectable.
+- What would invalidate this idea: if auto-install-on-update proves too disruptive (better as
+  an explicit `agent-cortex ext install` command), or if the pi/Claude installers don't expose
+  the store in a way that supports listing + uninstall for the TUI.
+
+## Constraints
+- Manifests live in this repo, committed via the normal PR flow — the CLI never edits them.
+- Install-on-update must be idempotent and safe to skip/fail gracefully (no hard breakage of
+  agent-cortex's own install on extension failure).
+- Follow the repo's extension conventions where relevant (lightweight, no internal LLM calls).
+- If any local data is persisted (e.g. prune history), write to `~/.pi/agent-cortex/`.
+
+## Next validation step
+Confirm the install surface for each harness: how `pi install <source>` works for the pi side,
+and how Claude/Copilot plugins get installed, plus whether each store can be listed and
+uninstalled programmatically (needed for the prune TUI). Then prototype the manifest + one
+harness's install-on-update path.
+
+## Notes
+Recorded 2026-08-25. The idea was refined during the interview: initially framed as
+"record the extensions I use" (observer-based), corrected to a **committed manifest** model —
+recording happens by editing + committing, not by monitoring. Prune uninstalls locally only;
+the manifest stays GitHub-managed. This idea is adjacent to `record-ideas-as-beads`: both make
+agent-cortex the declared source of truth for the author's environment and workflow.

package/docs/ideas/record-ideas-as-beads.md

@@ -0,0 +1,115 @@
+# Idea: record-ideas-as-beads
+
+## Status
+Fleshed out 2026-08-25 — design decisions locked in an interview; not yet implemented.
+
+## Created
+2026-08-25
+
+## Problem
+Ideas currently live as loose markdown files in `docs/ideas/`. This sits awkwardly alongside
+the rest of the workflow, which is almost entirely bead-based (bd). Because ideas aren't beads,
+they can't be searched with `bd label`, can't express relationships/dependencies to real tasks,
+can't be given priority that surfaces alongside other work, and can't sync to remote via
+`bd dolt push`. There's no clean promotion path from "idea" to "epic" to "executable task".
+
+## Who benefits
+The author's daily planning loop. Ideas are the beginning of epics, so making them first-class
+beads gives a single coherent backlog where an idea can grow relationships to the tasks it
+spawns. The plan/agent-nexus agents benefit too: agent-nexus will eventually schedule work
+through planning stages (not just execution), and a beads-native idea record gives it a clean
+input to plan against.
+
+## Proposed outcome
+Record ideas as beads labelled `kind:idea`, replacing `docs/ideas/*.md` entirely (bead-only —
+files deleted after migration). `bd` already supports labels natively (`bd create -l`,
+`bd label add/list`). An idea bead maps directly to an epic; promoting it means spawning task
+beads as children and letting the idea bead become the epic node.
+
+## Fleshed-out design (decided 2026-08-25)
+
+### Label & identification
+- **`kind:idea` label** marks idea beads. Ideas do NOT use `deferred` status — they stay
+  `open` so they're visible to idea tooling; hiding from actionable work is done by exclusion,
+  not status.
+- **ralph excludes them**: ready queries use `bd ready --exclude-label kind:idea`
+  (verified: `bd ready` supports `--exclude-label`). Idea beads never appear as claimable work.
+- Optional companion labels: `priority:<0-4>`, `epic:<id>` once promoted.
+
+### Flesh-out workflow (the skill that consumes them)
+There should be a **flesh-out skill** (e.g. `flesh-out-idea`) that answers: *"which idea beads
+are ready to be fleshed out?"* This is `bd ready -l kind:idea` — the blocker-aware ready query
+scoped to ideas. Because `bd ready` already respects dependencies, an idea bead that
+`depends-on` in-flight work (e.g. "needs unified-ci-pipeline landed first") naturally shows as
+*not ready* until its deps close. That's exactly the semantics wanted:
+- `bd ready -l kind:idea` → list & pick an idea ready for fleshing.
+- The skill runs the record-idea-style interview (why / how / when / priority) at deeper depth,
+  updating the bead's description/design/notes as the idea ripens.
+- Once fleshed out enough, the idea can be promoted (below).
+
+### Promotion path: idea → epic → tasks
+Parent-child hierarchy (chosen over labels+deps only):
+1. Idea bead starts with `kind:idea`, type defaulted appropriately (still `task` type, or set
+   `epic` type on promotion).
+2. On promotion: `bd label add <idea> epic:<idea-id>` (or flip to an epic label), then spawn
+   task beads with `--parent <idea-id>` — children inherit the epic relationship natively.
+3. The idea bead becomes the epic node; its children are the executable tasks. Closing the
+   children resolves to the epic closing.
+
+### Content model (bead fields)
+Map the current idea-template sections onto bd fields:
+| md template field | bd field |
+|---|---|
+| Title | `--title` |
+| Problem / Why | `--description` |
+| How we might do it | `--design` |
+| When / Priority / Validity / Constraints / Notes | `--notes` (structured, keep section markers) |
+| anything referential | `--context` |
+
+Multiple sections per field use explicit markers (`## Validity check`, etc.) inside the field
+so the flesh-out interview can find/update them later.
+
+### Skill changes
+- **`record-idea`**: replace scaffold-file flow (`new-idea.sh` → `docs/ideas/x.md`) with bead
+  creation: interview → `bd create "<title>" -l kind:idea -d "<why>" --design "<how>"
+  --notes "<when/priority/validity>"`. Keep the interview; drop the markdown scaffold script.
+- New **`flesh-out-idea`** skill (see above) — validates readiness (`bd ready -l kind:idea`),
+  picks an idea, drives the deepening interview, updates the bead, optionally promotes.
+
+### Migration
+- Bulk-migrate the existing `docs/ideas/*.md` records to beads: read each file, map sections to
+  bd fields, `bd create -l kind:idea`, preserve priority. Run as a one-off (manual or scripted).
+- Then **delete `docs/ideas/`** — bead-only going forward.
+- Update `AGENTS.md` + any stale references that point at `docs/ideas/`.
+- The `record-idea` skill itself must unlearn the docs/ideas path.
+
+## Validity check
+- Evidence we already have: `bd ready --exclude-label` and `bd ready -l` both exist and compose
+  (label filtering + blocker-aware ready semantics) — the two core mechanisms this idea needs
+  are native, no feature build. `--parent` exists for the hierarchy. 9-10 idea files exist to
+  migrate; the record-idea skill and its script are the only two consumers of the file flow.
+- Riskiest assumption: that keeping ideas `open` (not `deferred`) + label exclusion is
+  discoverable enough — ralph, plan agents, and the author must remember the exclusion. The
+  `bd-tool` skill's labels table needs `kind:idea` documented with the exclusion convention.
+- What would invalidate this idea: if label-based exclusion leaks idea beads into `bd ready`
+  via some path (e.g. `bd ready` without the exclude flag), or if losing the scannable
+  `docs/ideas/` directory hurts occasional review more than bead queries help it.
+
+## Constraints
+- Ideas stay quick to scan: `bd list -l kind:idea` + `bd show <id>` should be a comfortable
+  replacement for opening the directory.
+- Idea beads must never appear in ralph's actionable-ready view.
+- `record-idea` and `bd-tool` skills stay consistent — no stale references to docs/ideas.
+- Priority of ideas uses the same P0-P4 scale as tasks (P4 = backlog default for ideas).
+
+## Next validation step
+Prototype one idea as a labelled bead: create it with `-l kind:idea`, confirm `bd ready`
+excludes it by default and `bd ready -l kind:idea` surfaces it; then promote it (add epic label,
+spawn a child task) to confirm the hierarchy reads correctly. If the prototype passes, do the
+bulk migration + skill updates.
+
+## Notes
+Interview on 2026-08-25 locked: labels over status (kind:idea + ralph exclusion), bead-only
+content (files deleted), parent-child promotion, and record-idea skill rewritten to create
+beads. Agent-nexus is the planned consumer. Once this lands, this very record becomes an
+idea-bead (and then this file is deleted — the migration eats its own tail).