@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

package/bin/installers/copilot.mjs

@@ -30,7 +30,7 @@
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { writeFile, mkdir, readdir, stat } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
@@ -38,9 +38,17 @@ import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = join(MODULE_DIR, "..", "..");
 
-function isDirectory(p) {
+async function isDirectory(p) {
   try {
-    return statSync(p).isDirectory();
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function isFile(p) {
+  try {
+    return (await stat(p)).isFile();
   } catch {
     return false;
   }
@@ -71,19 +79,21 @@ function frontmatterYaml(name, fm) {
 }
 
 /** Compose agents from agents/<name>/; every composable dir must ship a copilot harness. */
-function buildAgents(root) {
+async function buildAgents(root) {
   const files = [];
-  const entries = readdirSync(join(root, "agents"), { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+  const entries = (await readdir(join(root, "agents"), { withFileTypes: true })).sort((a, b) =>
+    byName(a.name, b.name),
+  );
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files and README
     const dir = join(root, "agents", entry.name);
-    if (!existsSync(join(dir, "agent.md"))) continue; // not a composable agent dir
-    if (!isDirectory(join(dir, "copilot")) || !existsSync(join(dir, "copilot", "frontmatter.json"))) {
+    if (!(await isFile(join(dir, "agent.md")))) continue; // not a composable agent dir
+    if (!(await isDirectory(join(dir, "copilot"))) || !(await isFile(join(dir, "copilot", "frontmatter.json")))) {
       throw new Error(`agent "${entry.name}": composable directory without copilot/frontmatter.json — define the copilot harness or exclude the agent`);
     }
 
-    const fm = composeAgent(root, entry.name, "copilot");
+    const fm = await composeAgent(root, entry.name, "copilot");
     files.push({
       name: entry.name,
       file: `${entry.name}.agent.md`,
@@ -105,9 +115,9 @@ function buildAgents(root) {
  * @param {boolean} [options.dryRun] Plan and report without writing anything.
  * @returns {{ output: string, agents: string[], dryRun: boolean }}
  */
-export function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
+export async function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
   const out = output ?? join(root, "agents");
-  const files = buildAgents(root);
+  const files = await buildAgents(root);
   const summary = {
     output: out,
     agents: files.map((f) => f.name),
@@ -120,9 +130,9 @@ export function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } =
     return summary;
   }
 
-  mkdirSync(out, { recursive: true });
+  await mkdir(out, { recursive: true });
   for (const { file, content } of files) {
-    writeFileSync(join(out, file), content);
+    await writeFile(join(out, file), content);
   }
   console.log(`Generated ${files.length} Copilot agent file(s): ${summary.agents.join(", ")}`);
   return summary;

package/bin/installers/pi.mjs

@@ -8,8 +8,9 @@
 // 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).
+//   2. {{TOOL:key}} is substituted with the pi column (pi maps ask_user →
+//      ask_questions and skill → read); any (future) null pi mapping drops the
+//      token from prose with a warning.
 //   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).
@@ -24,7 +25,7 @@
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "node:fs";
+import { readFile, writeFile, mkdir, copyFile, readdir, stat } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -37,22 +38,22 @@ const PI = "pi";
 // extended before this installer can trust it.
 const CONTRACT_VERSION = 1;
 
-const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PACKAGE_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) {
+async function isDirectory(p) {
   try {
-    return statSync(p).isDirectory();
+    return (await stat(p)).isDirectory();
   } catch {
     return false;
   }
 }
 
-function isFile(p) {
+async function isFile(p) {
   try {
-    return statSync(p).isFile();
+    return (await stat(p)).isFile();
   } catch {
     return false;
   }
@@ -73,8 +74,8 @@ function isFile(p) {
  * @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;
+export async function installPi(options = {}) {
+  const root = options.root ?? PACKAGE_ROOT;
   const output = options.output ?? DEFAULT_OUTPUT;
   const dryRun = options.dryRun ?? false;
   const warnings = [];
@@ -83,7 +84,7 @@ export function installPi(options = {}) {
     (options.warn ?? DEFAULT_WARN)(msg);
   };
 
-  const tokenMap = loadTokenMap(root);
+  const tokenMap = await 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`,
@@ -94,26 +95,28 @@ export function installPi(options = {}) {
   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 });
+  const agents = await installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
+  const skills = await installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
 
   return { agents, skills, warnings, dryRun, agentsDir, skillsDir };
 }
 
 // ─── Agents ──────────────────────────────────────────────────────────────────
 
-function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn }) {
+async 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))) {
+  for (const entry of (await readdir(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"))) {
+    if (!(await isFile(join(dir, "agent.md")))) continue; // not a composable agent dir
+    if (!(await isDirectory(join(dir, PI))) || !(await 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, {
+    const fm = await composeAgent(root, entry.name, PI, {
       dropNullTools: true,
       pluginRoot,
       resolveRelativePaths: true,
@@ -123,8 +126,8 @@ function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, 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);
+      await mkdir(agentsDir, { recursive: true });
+      await writeFile(filePath, content);
     }
     written.push({ name: entry.name, filePath });
   }
@@ -147,24 +150,24 @@ function renderPiAgent(name, fm, tools) {
 
 // ─── Skills ──────────────────────────────────────────────────────────────────
 
-function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn }) {
+async 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 };
+  if (!(await 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 });
+  if (!dryRun) await mkdir(skillsDir, { recursive: true });
   let skills = 0;
   let md = 0;
   let files = 0;
-  for (const group of readdirSync(skillsSrc).sort()) {
+  for (const group of (await readdir(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;
+    if (!(await isDirectory(groupDir))) continue;
+    for (const name of (await readdir(groupDir)).sort()) {
+      if (!(await isFile(join(groupDir, name, "SKILL.md")))) continue;
       skills += 1;
-      const stats = copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
+      const stats = await copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
       md += stats.md;
       files += stats.files;
     }
@@ -173,24 +176,24 @@ function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn })
 }
 
 /** Recursively copy a tree; transform .md file contents, copy everything else verbatim. */
-function copyTree(src, dest, transform, dryRun) {
+async function copyTree(src, dest, transform, dryRun) {
   let md = 0;
   let files = 0;
-  const entries = readdirSync(src, { withFileTypes: true });
+  const entries = await readdir(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);
+      const stats = await 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);
+      await mkdir(dest, { recursive: true });
+      if (entry.name.endsWith(".md")) await writeFile(to, transform(await readFile(from, "utf-8")));
+      else await copyFile(from, to);
     }
   }
   return { md, files };

package/docs/claude-hooks.md

@@ -2,8 +2,8 @@
 
 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
+materialised plugin as its `hooks.json`); support scripts live in
+`hooks/claude/scripts/` and are bundled into the plugin's `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
@@ -100,7 +100,7 @@ for little signal. Rejected; Claude Code ships its own usage analytics
 ## `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
+native subagents — the plugin already ships `~/.agent-cortex/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.

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).

package/docs/ideas/subagent-visibility.md

@@ -0,0 +1,72 @@
+# Idea: subagent-visibility
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-08-25
+
+## Problem
+The bundled `subagent` extension delegates work to separate `pi` processes with isolated
+context windows. It streams output live, shows per-agent usage stats (turns, tokens, cost), and
+supports abort — but after a run there's no retained record of what each subagent actually did
+(files touched, decisions, blockers), and while a run is in flight there's no richer
+dashboard-level view of what each agent is up to. There's also no way to influence a running
+subagent: you can only watch or Ctrl+C the whole thing. For the ralph-style parallel dispatches
+(up to 5 concurrent chores) this is a real blind spot.
+
+## Who benefits
+The author, whenever running parallel subagent work (ralph pipeline chores, parallel research).
+A live dashboard helps during runs; persisted per-run reports turn subagent work into a
+reviewable after-action record (which also complements the HITL/summary flow). Mid-run steering
+reduces wasted tokens from subagents heading the wrong way and having to restart.
+
+## Proposed outcome
+Expand (or adopt, if a store extension fits) subagent tooling to give:
+
+1. **Live dashboard** — richer TUI during runs: per-agent status (phase, current tool call,
+   files touched), so you can see what each parallel subagent is doing without digging into
+   streamed output.
+2. **Persisted reports** — a per-run record per subagent (what it did, files changed,
+   decisions, blockers), stored for after-action review. Persistence should follow the repo
+   convention: write to `~/.pi/agent-cortex/`, tagged with project path for per-project slicing.
+3. **Mid-run steering** — send a message to a running subagent to change its direction
+   ("skip that, focus on X") rather than killing and restarting.
+
+Decision from the interview: **evaluate the pi extension store first** — if a maintained
+extension already covers dashboard + reports (and ideally steering), adopt it; otherwise expand
+the bundled `subagent` extension. Building is a fallback, not the default.
+
+## Validity check
+- Evidence we already have: the bundled `subagent` extension is a working base — it already
+  spawns `pi` subprocesses, streams, and collects usage data, so the hooks for a dashboard and
+  reports exist in some form. The repo has a data convention (`~/.pi/agent-cortex/`, per-project
+  tagging) that reports would slot into.
+- Riskiest assumption: that mid-run steering is technically feasible — subagents run as separate
+  `pi` processes, so steering likely needs a message channel (e.g. a FIFO / IPC pipe into the
+  running process, or a PI-native way to inject input). If the process model doesn't allow input
+  mid-run, the interaction half collapses to "abort and re-dispatch with corrected instruction".
+- What would invalidate this idea: if store extensions are all visibility-only (no steering) and
+  the process model rules out mid-run input, the remaining value is dashboard + reports only.
+  Also, if subagents use private pipes that block reading live state cheaply, the dashboard may
+  be constrained to what the streamer already shows.
+
+## Constraints
+- Keep it lightweight and consistent with the repo's extension conventions (no internal LLM
+  calls in the extension itself).
+- Should compose with ralph's parallel dispatch (up to 5 concurrent chores) without making the
+  TUI unusable.
+- Steering must be safe: a message is advisory input to the subagent, not a force-kill;
+  abort stays available.
+
+## Next validation step
+Two-part check before building: (1) search the pi extension store for subagent/dashboard/steering
+extensions and evaluate against this wishlist; (2) verify whether a running `pi` subagent
+process accepts input mid-run (checked against how the subagent extension spawns processes and
+whether PI exposes any IPC/input channel) — this decides whether steering is scoped in.
+
+## Notes
+Recorded 2026-08-25. Interview decisions: visibility = both live dashboard AND persisted
+per-run reports; interaction = mid-run steering (not approve-gates, not pause/resume); path =
+evaluate store first, fall back to expanding the bundled `subagent` extension. Complements
+`unified-ci-pipeline` (pipeline visibility) and the ralph parallelism work in this repo.

package/docs/ideas/task-session-context.md

@@ -0,0 +1,89 @@
+# Idea: task-session-context
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-08-25
+
+## Problem
+Coding sessions accumulate context turn by turn: every question, every tool call, every
+tangent stays in the window until it's manually compacted or the session is restarted. Keeping
+the context small and relevant is an active management burden — the author has to notice the
+bloat, decide what matters, and intervene. Long conversations either burn tokens or require
+frequent manual resets that drop useful memory.
+
+## Who benefits
+The author, daily. Removing context management from the loop means sessions stay small and
+focused no matter how long the overall thread runs. It also produces a durable, reviewable log
+of work: each task's bead + summary memory is an audit trail of what was done and why.
+
+## Proposed outcome
+A workflow organised around **tasks** instead of sessions. Whenever the user does something
+discrete — asks a new question, records an idea, fleshes out a piece of work — it **begins a
+task**:
+
+1. **Task = blank session with memory context.** The task starts a fresh, self-contained
+   session. It does NOT get every turn and tool call of the parent conversation — only access
+   to the accumulated **memories** of what came before (a summary/compressed view, not the raw
+   transcript).
+2. **Self-contained execution.** The task works on its own: it takes action, and **records
+   memories along the way** as it produces outcomes.
+3. **Single summary memory on completion.** The last thing a task does is write one summary
+   memory capturing its outcome. These memories are additive — the running memory store grows as
+   tasks complete.
+4. **Fresh session continues the thread.** Once the task completes, a new session starts with
+   access to the memories — including the new summary — so to the user it feels like one
+   continuous thread, but each underlying session stays small.
+
+**Ties into beads (bd):** "the completion of a bead is the completion of a task". A bead becomes
+the log of work completed: the task's outcome is recorded on/with the bead, the fresh session
+starts, and the bead is accompanied by **referential memory** (a pointer/memory entry that links
+the outcome to the bead). So the bead doubles as the durable record AND the context-boundary
+marker: starting a bead is the trigger for task-session separation.
+
+**The bead is the artifact — the session is disposable.** Once a task is complete, the whole
+conversation context is no longer needed; the bead is the artifact. The current conversation is
+the live example: recording this idea is a task, and when it's done the transcript of every turn
+and tool call can be discarded — what remains is the record plus its summary/referential memory.
+This is the load-bearing philosophical point of the idea: sessions exist to serve tasks, not the
+other way around. Context is an implementation detail of a single task; the bead is the durable
+unit of history.
+
+The mechanism likely needs: a memory store (per-project, e.g. under `~/.pi/agent-cortex/` or a
+records convention), a session-scoping rule (what memories a fresh task session is seeded with),
+the summary-writing step, and the bead ↔ memory linkage.
+
+## Validity check
+- Evidence we already have: the repo already runs on beads as the unit of work (bd), and the
+  ralph pipeline already treats beads as self-contained executable units — so task-per-bead
+  separation is a natural extension of an existing pattern. Existing ideas
+  (`record-ideas-as-beads`, `pi-task-memory`, `extension-manifests`) all push in the direction of
+  making agent-cortex the declared, memory-rich source of truth.
+- Riskiest assumption: that a fresh session seeded with *memories only* (no raw transcript) is
+  sufficient context for a task — the compression of a conversation into memories must not lose
+  the specifics a task needs. Also: whether the harness (pi/Claude) even supports programmatic
+  session spawning with a seed context cleanly enough for this to feel seamless.
+- What would invalidate this idea: if memory-as-context proves lossy in a way that keeps tasks
+  mis-executing (then the blank-session model needs the raw transcript after all, defeating the
+  point); or if the session boundary machinery (start/stop/spawn with seed) fights the harness.
+
+## Constraints
+- Sessions must stay small — this is the whole point; memory is the interface, not the transcript.
+- Memories are additive and durable; the summary memory is the handoff contract between tasks.
+- The bead is the work log AND the context boundary: no task completion without its summary
+  memory and bead record.
+- Must not break the existing task loops (ralph pipeline stages, HITL handoffs) — it should
+  compose with them, not fork them.
+
+## Next validation step
+Flesh-out session (proposed by the author): nail down the trigger rules (what counts as "begin a
+task"), the memory store schema and what a "memory" is vs a summary, how a fresh session gets
+seeded, and how the bead carries the summary + referential memory. Then a spike: one task
+completing with summary → fresh session seeded → verify the thread feels continuous.
+
+## Notes
+Recorded 2026-08-25. The author explicitly wants to flesh this out later — this record captures
+the working concept. It connects several existing ideas: `record-ideas-as-beads` (beads as the
+unit of everything), `pi-task-memory` (memory as a first-class mechanism), and
+`subagent-visibility` (visibility into what task sessions do).