@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/bin/installers/pi.mjs

@@ -0,0 +1,197 @@
+// Pi harness installer: agent-cortex install pi
+//
+// Materialises the agent-cortex package into the pi runtime's user scope:
+//
+//   <output>/agents/<slug>.agent.md   composed agents (default ~/.pi/agent/agents)
+//   <output>/skills/<group>/<name>/   token-substituted skill copies (default ~/.pi/agent/skills)
+//
+// Composition per the token-map.json contract:
+//   1. {{SECTION:name}} is resolved from the agent's pi/<name>.md section file
+//      (shared composer, scripts/lib/compose-agent.mjs).
+//   2. {{TOOL:key}} is substituted with the pi column; a null mapping drops the
+//      token from prose with a warning (pi has no ask_user/skill tool).
+//   3. {{PATH:key}} named keys resolve through the paths table; bare relative
+//      paths resolve against the plugin root (default: token-map.json's pi value,
+//      overridable with --plugin-root for checkout/symlinked installs).
+// Frontmatter tool lists are translated the same way agent-modes does at runtime:
+// canonical → pi column, null → omitted, unknown (native pi tool) → pass through.
+// Skill markdown files get the same TOOL/PATH substitution so pi never serves
+// literal token syntax; other skill files are copied verbatim.
+//
+// Skills install into ~/.pi/agent/skills (pi's user-global skill dir), which pi
+// loads before package skills, so the substituted copies shadow the raw package
+// skills of the same name (pi dedupes by name, user wins).
+//
+// Zero dependencies so it runs on the CI Node and local Node alike.
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { composeAgent, loadTokenMap, substituteTokens, translateToolList } from "../../scripts/lib/compose-agent.mjs";
+
+const PI = "pi";
+
+// The token-map contract version this installer implements (token-map.json
+// "version" field). A higher map version is rejected: the contract must be
+// extended before this installer can trust it.
+const CONTRACT_VERSION = 1;
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const DEFAULT_OUTPUT = join(homedir(), ".pi", "agent");
+
+const DEFAULT_WARN = (msg) => console.warn(`[pi-installer] ${msg}`);
+
+function isDirectory(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install the agent-cortex pi harness into the pi runtime.
+ *
+ * @param {object} options
+ * @param {string} [options.root]        Package root (defaults to this file's repo)
+ * @param {string} [options.output]      Pi user-scope dir; agents go to
+ *                                       <output>/agents, skills to <output>/skills
+ *                                       (default ~/.pi/agent)
+ * @param {boolean} [options.dryRun]     Compute and report without writing anything
+ * @param {string} [options.pluginRoot]  Override plugin_root used for {{PATH:...}}
+ *                                       resolution (default: token-map pi value)
+ * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`
+ * @returns {{ agents: {name:string, filePath:string}[], skills: {skills:number, md:number, files:number, dir:string},
+ *             warnings: string[], dryRun: boolean, agentsDir: string, skillsDir: string }}
+ */
+export function installPi(options = {}) {
+  const root = options.root ?? REPO_ROOT;
+  const output = options.output ?? DEFAULT_OUTPUT;
+  const dryRun = options.dryRun ?? false;
+  const warnings = [];
+  const warn = (msg) => {
+    warnings.push(msg);
+    (options.warn ?? DEFAULT_WARN)(msg);
+  };
+
+  const tokenMap = loadTokenMap(root);
+  if (typeof tokenMap.version === "number" && tokenMap.version > CONTRACT_VERSION) {
+    throw new Error(
+      `token-map.json version ${tokenMap.version} is newer than the contract version ${CONTRACT_VERSION} this installer implements — upgrade agent-cortex`,
+    );
+  }
+
+  const pluginRoot = options.pluginRoot ?? tokenMap.paths.plugin_root?.[PI];
+  const agentsDir = join(output, "agents");
+  const skillsDir = join(output, "skills");
+
+  const agents = installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
+  const skills = installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
+
+  return { agents, skills, warnings, dryRun, agentsDir, skillsDir };
+}
+
+// ─── Agents ──────────────────────────────────────────────────────────────────
+
+function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn }) {
+  const written = [];
+  const agentsSrc = join(root, "agents");
+  for (const entry of readdirSync(agentsSrc, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files
+    const dir = join(agentsSrc, entry.name);
+    if (!isFile(join(dir, "agent.md"))) continue; // not a composable agent dir
+    if (!isDirectory(join(dir, PI)) || !isFile(join(dir, PI, "frontmatter.json"))) {
+      throw new Error(`agent "${entry.name}": composable directory without pi/frontmatter.json — define the pi harness or exclude the agent`);
+    }
+
+    const fm = composeAgent(root, entry.name, PI, {
+      dropNullTools: true,
+      pluginRoot,
+      resolveRelativePaths: true,
+      warn,
+    });
+    const tools = translateToolList(fm.tools, tokenMap, PI, { warn });
+    const content = renderPiAgent(entry.name, fm, tools);
+    const filePath = join(agentsDir, `${entry.name}.agent.md`);
+    if (!dryRun) {
+      mkdirSync(agentsDir, { recursive: true });
+      writeFileSync(filePath, content);
+    }
+    written.push({ name: entry.name, filePath });
+  }
+  return written;
+}
+
+function renderPiAgent(name, fm, tools) {
+  const lines = [
+    "---",
+    `# GENERATED from agents/${name}/ by bin/installers/pi.mjs — DO NOT EDIT.`,
+    `name: ${JSON.stringify(fm.name)}`,
+    `description: ${JSON.stringify(fm.description)}`,
+    `tools: ${JSON.stringify(tools.join(" "))}`,
+  ];
+  if (fm.model) lines.push(`model: ${JSON.stringify(fm.model)}`);
+  if (fm.argumentHint) lines.push(`argument-hint: ${JSON.stringify(fm.argumentHint)}`);
+  lines.push("---");
+  return `${lines.join("\n")}\n\n${fm.body}\n`;
+}
+
+// ─── Skills ──────────────────────────────────────────────────────────────────
+
+function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn }) {
+  const skillsSrc = join(root, "skills");
+  if (!isDirectory(skillsSrc)) return { skills: 0, md: 0, files: 0, dir: skillsDir };
+
+  const transform = (content) =>
+    substituteTokens(content, PI, tokenMap, { dropNullTools: true, pluginRoot, resolveRelativePaths: true, warn });
+
+  if (!dryRun) mkdirSync(skillsDir, { recursive: true });
+  let skills = 0;
+  let md = 0;
+  let files = 0;
+  for (const group of readdirSync(skillsSrc).sort()) {
+    const groupDir = join(skillsSrc, group);
+    if (!isDirectory(groupDir)) continue;
+    for (const name of readdirSync(groupDir).sort()) {
+      if (!isFile(join(groupDir, name, "SKILL.md"))) continue;
+      skills += 1;
+      const stats = copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
+      md += stats.md;
+      files += stats.files;
+    }
+  }
+  return { skills, md, files, dir: skillsDir };
+}
+
+/** Recursively copy a tree; transform .md file contents, copy everything else verbatim. */
+function copyTree(src, dest, transform, dryRun) {
+  let md = 0;
+  let files = 0;
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = join(src, entry.name);
+    const to = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      const stats = copyTree(from, to, transform, dryRun);
+      md += stats.md;
+      files += stats.files;
+    } else if (entry.isFile()) {
+      files += 1;
+      if (entry.name.endsWith(".md")) md += 1;
+      if (dryRun) continue;
+      mkdirSync(dest, { recursive: true });
+      if (entry.name.endsWith(".md")) writeFileSync(to, transform(readFileSync(from, "utf-8")));
+      else copyFileSync(from, to);
+    }
+  }
+  return { md, files };
+}

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

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

package/claude/agents/plan.md

@@ -1,10 +1,12 @@
 ---
-# GENERATED from agents/plan.agent.md by scripts/build-claude-agents.mjs — DO NOT EDIT.
+# 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.

package/claude/agents/ralph-plan.md

@@ -1,10 +1,12 @@
 ---
-# GENERATED from agents/ralph-plan.agent.md by scripts/build-claude-agents.mjs — DO NOT EDIT.
+# 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
@@ -32,7 +34,7 @@ Invoke the **beads** skill (set workspace root, run `bd prime`). Hold the output
 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 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.
 
@@ -68,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`:
 
@@ -116,4 +118,4 @@ Every explore sub-agent prompt must include:
 - 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.).
+- Use Bash only for read-only commands (`git log`, `find`, `cat`, etc.).

package/claude/agents/strategy.md

@@ -1,10 +1,12 @@
 ---
-# GENERATED from agents/strategy.agent.md by scripts/build-claude-agents.mjs — DO NOT EDIT.
+# GENERATED from agents/strategy/ by bin/installers/claude.mjs — DO NOT EDIT.
 name: strategy
 description: "Creates top-level design documents across strategy, PRD, and technical direction so delivery planning starts with clear intent and justified decisions. Use when defining product direction before implementation planning, shaping a feature PRD, or selecting technical direction before ralph-plan."
 tools: Bash, Read, Grep, Glob, AskUserQuestion, WebFetch, Skill, Edit, Write
 ---
 
+# strategy — pre-delivery design agent
+
 You are a pre-delivery design agent. Your job is to produce high-quality design artifacts that set up `ralph-plan` for success.
 
 ## Scope

package/claude/hooks/scripts/notify.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Claude Code Notification hook — desktop notification on task completion/error.
+//
+// Reads the Notification hook JSON payload from stdin and prints a
+// `{ "terminalSequence": "..." }` response for Claude Code to emit. Hooks run
+// without a controlling terminal, so OSC sequences must go through Claude Code
+// itself (it handles tmux/screen re-wrapping); writing /dev/tty directly fails.
+//
+// Mapped from the pi `notify` extension (extensions/notify/): pi notifies on
+// agent_end for multi-turn or long tasks. Claude Code's Notification matcher is an
+// exact-string list over `notification_type` values (there are no `success`/
+// `error` types) — hooks.json selects `agent_completed|agent_needs_input|permission_prompt`
+// to mirror "task completed / failed / needs approval". The payload already carries
+// a message + title, so no summarization LLM call is needed here.
+//
+// Zero dependencies; runs on the Node that ships with Claude Code.
+
+let raw = "";
+for await (const chunk of process.stdin) {
+  raw += chunk;
+}
+
+let payload = {};
+try {
+  payload = raw.trim() ? JSON.parse(raw) : {};
+} catch {
+  process.exit(0); // never fail a session on an unparsable payload
+}
+
+const message = typeof payload.message === "string" ? payload.message.trim() : "";
+if (!message) process.exit(0); // nothing worth notifying (e.g. autocompact events)
+
+const title =
+  typeof payload.title === "string" && payload.title.trim() ? payload.title.trim() : "Claude Code";
+const type = typeof payload.notification_type === "string" ? payload.notification_type : "";
+
+process.stdout.write(JSON.stringify({ terminalSequence: pickSequence(title, message, type) }) + "\n");
+
+/** Pick an OSC notification escape sequence for the detected terminal. */
+function pickSequence(title, message, type) {
+  const body = message.replace(/\u001b/g, "").replace(/\n/g, " ").trim();
+  const label = type ? `${type}: ${title}` : title;
+
+  if (process.env.KITTY_WINDOW_ID) {
+    // Kitty: two-part persistent notification (title + body) — same form as the pi notify extension.
+    return `\u001b]99;i=1:d=1;${title}\u001b\\\u001b]99;i=1:p=body;${body}\u001b\\`;
+  }
+  if (process.env.TERM_PROGRAM === "iTerm.app" || process.env.ITERM_SESSION_ID) {
+    // iTerm2 / ConEmu / Windows Terminal / WezTerm: OSC 9.
+    return `\u001b]9;${label}: ${body}\u0007`;
+  }
+  // urxvt / Ghostty / Warp, and default fallback: OSC 777.
+  return `\u001b]777;notify;${label};${body}\u0007`;
+}

package/claude/hooks.json

@@ -12,12 +12,27 @@
             "type": "command",
             "command": "echo 'Style policy: this project ships style skills — prefer them over ad-hoc choices. Invoke style-code BEFORE writing or editing code (and when refactoring); style-tests BEFORE writing or changing tests; style-documentation BEFORE writing or updating docs; style-comms BEFORE composing commit messages, PR descriptions, tickets, or other written deliverables.'"
           },
+          {
+            "type": "command",
+            "command": "echo 'Skill policy: agent-cortex ships skills — prefer them over ad-hoc choices. using-agent-skills routes work to the right skill (check it first when unsure); bd-tool tracks beads tasks (run bd ready for available work); git-workflow enforces branch and PR discipline. Invoke skills via the Skill tool.'"
+          },
           {
             "type": "command",
             "command": "echo 'Be extremely concise. Sacrifice grammar for the sake of concision.'"
           }
         ]
       }
+    ],
+    "Notification": [
+      {
+        "matcher": "agent_completed|agent_needs_input|permission_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/notify.mjs\""
+          }
+        ]
+      }
     ]
   }
 }

package/docs/claude-hooks.md

@@ -0,0 +1,115 @@
+# Claude Code hooks — extension port audit
+
+The pi extensions in `extensions/` were audited for Claude Code equivalents.
+Implemented ports live in `hooks/claude/hooks.json` (copied verbatim into the
+generated plugin as `claude/hooks.json`); support scripts live in
+`hooks/claude/scripts/` and are bundled into `claude/hooks/scripts/` by
+`bin/installers/claude.mjs` (referenced from hooks.json via `$CLAUDE_PLUGIN_ROOT`).
+
+Claude Code's hook model differs from PI's: hooks are shell commands fed a JSON
+payload on stdin, with events like `SessionStart`, `SessionEnd`, `Stop`,
+`SubagentStop`, and `Notification` — there is no `before_agent_start` /
+`agent_end` / `tool_call` extension API, no runtime tool registration, and no
+UI surface. Each decision below is grounded in the Claude Code hooks reference.
+
+| pi extension | Claude port | Decision |
+|---|---|---|
+| `session-start.ts` | `SessionStart` hook commands | **Port** (extended) |
+| `auto-name.ts` | — | **Reject** — built-in |
+| `notify/` | `Notification` hook + `scripts/notify.mjs` | **Port** |
+| `skill-stats/` | — | **Reject** — no equivalent |
+| `subagent/` | — | **Reject** — native |
+| `agent-modes/` | — | **Reject** — no equivalent |
+
+## `session-start.ts` → SessionStart (port)
+
+pi injects skill-availability hints + project context files (AGENTS.md,
+`docs/user-preferences.md`) into every session. Claude Code already loads
+`AGENTS.md` natively and the existing SessionStart hook nudge ("Load AGENTS.md
+and active beads context…") plus the style-skill policy (PR #57) cover the
+context side. This bead closes the remaining gap: a skill-policy command listing
+the meta-skills (`using-agent-skills` for routing, `bd-tool` for beads context,
+`git-workflow` for branch/PR discipline). SessionStart command-hook stdout is
+added to Claude's context, so plain `echo` commands are the right shape —
+keep them fast and dependency-free. Skipped from the pi original: the dynamic
+file read of AGENTS.md/user-preferences.md, since Claude Code loads AGENTS.md
+itself and user-preferences.md is a pi-harness document.
+
+## `auto-name.ts` → Reject (built-in)
+
+pi names sessions via a tiny side-model call on the first prompt. Claude Code
+already auto-generates descriptive session titles (visible in `claude --resume`;
+a background model request in interactive and headless/SDK sessions) and supports
+explicit naming via `--name` / `/rename`. A hook-based title generator would
+duplicate platform behaviour with an extra LLM call — rejected. (SessionStart
+hooks can also set `sessionTitle` in JSON output for the rare case where a
+custom title is genuinely needed.)
+
+## `notify/` → Notification hook (port)
+
+pi notifies on `agent_end` for multi-turn/long tasks with a desktop notification
++ bell. Claude Code's native `Notification` event fires at the equivalent
+completion points and already carries `message`, `title`, and `notification_type`
+in the payload — and hooks emit desktop notifications by returning a
+`terminalSequence` JSON field (hooks have no controlling terminal; Claude Code
+emits the sequence itself, including inside tmux/screen).
+
+Implemented as a `Notification` hook with matcher
+`agent_completed|agent_needs_input|permission_prompt` invoking `scripts/notify.mjs`,
+which reads the payload from stdin and prints the OSC sequence for the detected
+terminal (Kitty OSC 99, iTerm2/Windows Terminal OSC 9, default urxvt/Ghostty/Warp
+OSC 777 — same detection as the pi `notify` extension). The Notification matcher
+is an **exact-string list** over the `notification_type` field; there are no
+`success`/`error` types (an earlier draft used that matcher, which silently never
+fired). The documented types are `permission_prompt`, `idle_prompt`, `auth_success`,
+`elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`,
+`elicitation_response`, `agent_needs_input`, `agent_completed`,
+`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`
+(the `agent_*` types require Claude Code v2.1.198+, the `quota_auto_resume_*`
+types v2.1.234+). The selection maps to pi's "task completed / failed / needs
+approval" semantics: `agent_completed` covers completion and failure ("finishes
+or fails"), `agent_needs_input` covers a background session waiting on input, and
+`permission_prompt` covers an awaited approval. Explicitly excluded as noise:
+`idle_prompt` (fires ~60s after every turn you don't answer within a minute — a
+desktop ping on every pause), `auth_success` and `quota_auto_resume_*` (not task
+events), and `elicitation_*` (dialog trivia). Skipped from the pi original: the LLM
+response summary (Claude's notification message is already the summary) and the tmux
+session:window.pane title (unavailable to hooks; the plugin title suffices).
+
+## `skill-stats/` → Reject (no equivalent)
+
+pi tracks skills loaded into the system prompt, `/skill:` invocations, SKILL.md
+reads, and turns, exposing a `/skill-stats` query. Claude Code exposes none of
+the required observability to hooks:
+
+- **No "loaded" event** — nothing fires when a skill enters context, and hooks
+  never see system-prompt contents, so the primary "loaded" metric has no source.
+- **Partial invocation/read observability only** — `PreToolUse` on the `Skill`
+  tool and `UserPromptExpansion` on slash commands would approximate
+  invocations, and `PostToolUse` on `Read` would approximate skill reads, but
+  the signals are fuzzy (Read covers any file; direct `/skill` typing bypasses
+  `PreToolUse`).
+- **No query surface** — Claude Code plugin commands are markdown files, not
+  scripts, so there is no equivalent of the pi `/skill-stats` command, and
+  persistent state would live outside the plugin model.
+
+A half-observable port would diverge from the pi semantics and add moving parts
+for little signal. Rejected; Claude Code ships its own usage analytics
+(`/usage`, sessions list, statsig) if insights are needed.
+
+## `subagent/` → Reject (native)
+
+pi's `subagent` tool spawns isolated `pi --mode json` processes. Claude Code has
+native subagents — the plugin already ships `claude/agents/*.md` (including
+`ralph`, `plan`, `strategy`, `ralph-plan`) executed via the built-in Agent/Task
+tools with per-session context isolation — so a hook-based workaround would be
+strictly worse.
+
+## `agent-modes/` → Reject (no equivalent)
+
+pi switches system prompts + tool restrictions at runtime with a TUI mode
+selector. Claude Code exposes no hook or settings surface for dynamic
+tool-restriction/prompt-switching of the main agent; the closest equivalents are
+native (permission modes like plan mode configured via settings, and subagents
+— already covered above). The `--agent <name>` start flag is covered by
+`claude --agent` in newer versions. Rejected.

package/docs/ideas/auto-model-selection.md

@@ -0,0 +1,75 @@
+# Idea: Auto-Model Selection Plugin
+
+## Status
+Backlog idea (not implementation-ready) — **direction: evaluate and adopt existing package**
+
+## Why it might be useful
+PI has no intelligent model selection. Users must manually choose models, which means they either over-provision (expensive models for simple tasks) or under-provision (weak models for complex work). Rate limits hit without warning, forcing manual model switching mid-session. An auto-selection plugin would optimize cost/performance by matching model capability to task complexity, and provide seamless fallbacks when rate limits are hit.
+
+## How we might do it
+**Evaluate and adopt an existing PI extension** rather than building from scratch. The ecosystem already has well-maintained packages that cover task-based routing and rate-limit fallbacks. The goal is to:
+
+1. **Evaluate the top candidates** (see "Packages to evaluate" below)
+2. **Pick the best fit** for agent-cortex's workflow (beads, pipeline stages, HITL/AFK classification)
+3. **Install and configure** it, possibly with light customisation if needed
+4. **Document** the chosen package and configuration in agent-cortex docs
+
+## Packages to evaluate (in priority order)
+**Top candidates — cover both task-based routing AND fallbacks:**
+1. **`@kylebrodeur/pi-model-router`** — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallback chains and rate-limit recovery. Well-documented fork of yeliu84's original.
+2. **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies, and quota-aware fallback.
+3. **`pi-tiered-router`** — routes different *phases* (planner/validator/executor/tool-parser) to different models. Quality-first, not cost-saving.
+
+**Fallback-only (simpler, if routing is overkill):**
+- **`pi-auto-models`** — Claude→Codex quota switching with 429/529 recovery
+- **`pi-provider-fallback`** — cross-provider fallback chain with TUI config
+
+**Evaluation criteria:**
+- Does it integrate cleanly with PI's existing provider/model system?
+- Does it respect user's explicit model choice, or override it?
+- How does it handle context window mismatches on fallback?
+- Is it configurable per-project?
+- Does it have fallback chains or just single fallback?
+- Rate-limit detection and retry logic
+- Documentation quality and maintenance status
+
+## When to think about it
+- After current feature stabilisation (refactor-to-template epic, npm publishing, system prompt improvements)
+- Not blocked, but benefits from stable extension infrastructure
+
+## Priority
+Medium / backlog — valuable for cost optimisation and reliability, but not urgent. Current manual model selection works, just isn't optimal.
+
+## Open questions
+- How to classify task complexity? Heuristics (file count, prompt length, keywords)? Or let user tag tasks?
+- What defines a "model class"? Cost tier, context window size, reasoning capability, speed?
+- Should the plugin override the user's explicit model choice, or only activate when no model is selected?
+- How to handle context window mismatches when falling back (e.g., 200k → 128k)?
+- Should this be configurable per-project (different policies for different repos)?
+
+## Existing packages in the ecosystem
+Several published packages already address parts of this problem:
+
+### Fallback / rate-limit recovery
+- **`pi-provider-fallback`** — cross-provider fallback with interactive TUI config
+- **`pi-auto-models`** — primary/fallback switching on quota (Claude→Codex default), 429/529 recovery
+
+### Task-based / tier routing
+- **`pi-model-router`** (yeliu84, forked by @kdejaeger and @kylebrodeur) — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallbacks
+- **`pi-model-auto`** — routes by Low/Medium/High/Ultra capability modes per turn
+- **`pi-tiered-router`** — routes different phases (planner/validator/executor/tool-parser) to different models
+
+### Full auto-router with failover
+- **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies
+- **`@ifi/pi-extension-adaptive-routing`** — adaptive routing with local telemetry persistence
+
+### Model selection (manual)
+- **`pi-model-switch`** — direct model switching tool
+- **`pi-model-select`** — `/select-model` with favourites and fuzzy search
+
+## Notes
+- **The ecosystem is active** — this space is already well-served. Before building, evaluate whether an existing package (especially `pi-model-router` or `pi-auto-router`) already meets the need.
+- **Gap analysis needed**: compare existing packages against the original requirements (task-based class selection + rate-limit fallbacks) to see if anything is genuinely missing.
+- **Partial solutions exist in PI core**: OpenRouter's routing config supports fallbacks and provider ordering, but only within OpenRouter. Cross-provider fallback requires an extension.
+- **Implementation approach** (if building): likely a PI extension that registers a "smart-router" provider, which internally delegates to real providers based on task classification and availability.
+- **Research done**: reviewed PI docs on providers, models, and extensions. Searched npm and pi.dev for existing packages.

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.