@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/docs/technical-direction/migration-execution-labels.md

@@ -0,0 +1,132 @@
+# Technical Direction: Execution-Label Migration Tooling (two-axis model)
+
+## Problem and target outcome
+
+- Migrate all beads workspaces from `implementation-type:afk|hitl` to `execution:afk|hitl`
+  (strict rename, agent-agnostic) as part of the two-axis workflow model epic.
+- Provide a repo-agnostic tool + skill any workspace can run, and a single-package.json
+  script tooling story across the agent-cortex repo.
+
+## Current-state constraints
+
+- bd CLI is a global binary (`~/.local/bin/bd`); label ops: `bd label list-all [--json]`,
+  `bd list --label-pattern/regex [--json]`, `bd label add/remove` (batch multiple ids).
+- `bd list` supports `--label-pattern`/`--json`; `bd count` does NOT support `--label-pattern`.
+- `bd ready --label-pattern 'stage:*'` works; `bd ready -l execution:afk` verified.
+- 3 script packages exist with per-skill `package.json` + own `pnpm-workspace.yaml` +
+  own `pnpm-lock.yaml` (create-task, validate-agent-dir, run-pipeline-stage). They are NOT
+  members of the root workspace (root glob `skills/*/scripts` does not match the nested
+  `skills/<domain>/<name>/scripts`; root lockfile has zero refs to them).
+- All 3 scripts are stdlib-only (`node:child_process`, `node:fs`, `node:path`, `node:url`).
+- Extensions (`extensions/skill-stats`) have real peer deps on `@earendil-works/pi-coding-agent`
+  — they remain workspace members with their own package.json.
+- `node_modules` gitignored; per-skill modules are installed manually today — a fragility in
+  fresh clones and PI-installed contexts.
+
+## Decisions (locked in planning session)
+
+### D1: Script runtime — all skill scripts become zero-dep `.mjs` with `// @ts-check`
+
+- Every script in `skills/*/*/scripts/` runs with bare `node` (built-ins + shelling out to
+  `bd`). No tsx, no node_modules at runtime, no skill-scripts-dir resolution problem in any
+  installed context.
+- Build-in-publish (Option B) rejected: contradicts the repo's no-compilation PI package
+  model; 3 tiny stdlib-only scripts do not justify dist artifacts.
+- Root keeps `tsx`/`typescript`/`@types/node` for extensions and for `tsc --noEmit`
+  typechecking of `.mjs` via `checkJs`.
+
+### D2: Single package.json (root workspace consolidation)
+
+- Fold the 3 per-skill script packages into the root workspace: delete their `package.json`,
+  `pnpm-workspace.yaml`, `pnpm-lock.yaml`; convert scripts to `.mjs` (D1); root
+  `package.json` owns typecheck/test wiring.
+- Extensions stay as workspace members (`extensions/*` glob) — their package.jsons are
+  semantically meaningful (peer deps on the pi runtime).
+- Fresh-clone/installed-context verification: `pnpm install` at root then
+  `pnpm -r typecheck` + `pnpm -r test` (or root `node --test` wiring) cover all scripts.
+
+### D3: Migration tool shape
+
+- Script: `skills/productivity/migration/scripts/rename-execution-labels.mjs` — zero-dep,
+  `// @ts-check` + JSDoc.
+- Behavior:
+  1. Enumerate: `bd list --label-pattern 'implementation-type:*' --json`.
+  2. Group bead ids by label value (afk | hitl). A bead carrying both gets both execution labels.
+  3. Dry-run (default): print per-bead plan + summary counts; zero writes; exit 0.
+  4. Apply (`--apply`): batched `bd label add execution:<v> <ids...>` then
+     `bd label remove implementation-type:<v> <ids...>` per group.
+  5. Idempotent: re-run finds zero targets → no-op.
+  6. Fail loudly if `bd` unavailable or any subcommand errors.
+- Scope: rename ALL beads carrying `implementation-type:*` (including closed) — the F7
+  acceptance "zero implementation-type:* labels remain" requires it, and bd label history
+  tolerates it.
+
+### D4: Migration skill
+
+- Location: `skills/productivity/migration/SKILL.md` (productivity = workflow tooling).
+- Docs the full sequence for any workspace: preflight (count via `bd label list-all`),
+  dry-run, apply, post-checks (grep stale refs; `bd ready -l execution:afk` smoke), plus
+  pointers to idea-file migration (F2) and skill/doc updates (F3/F4/F5/F6).
+- Repo-agnostic: no agent-cortex-specific paths in the runnable steps.
+
+### D6: npm packaging hygiene (no build step — F9)
+
+- The npm tarball currently ships the whole repo, including `.beads/` (the live task DB),
+  `.github/`, `.changeset/`, `.junie/`, tests, and token-map.json. No `.npmignore`, no
+  `files` field.
+- Rejected: a compile build. Scripts are zero-dep `.mjs` (D1) — nothing to transpile;
+  extensions are TS by pi contract (`index.ts` entrypoint, loader transpiles; the pi runtime
+  import is type-only). Root build script is deliberately a no-op.
+- Chosen: (1) `files` whitelist in package.json — ship only runtime assets (skills/, agents/,
+  extensions/, bin/, lib/, AGENTS.md, plugin.json, README, LICENSE); (2) `prepublishOnly`
+  gate running `pnpm typecheck && pnpm test`; (3) wire `test/cli.test.mjs` into root `test`.
+- Revisit trigger: if an extension ever gains real runtime deps, bundle that extension with
+  esbuild at prepack — not a repo-wide build.
+
+### D5: Knocked-on invocation changes (F4/F5)
+
+- ralph init step 9: `pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx
+  generate-progress.ts` → `node <abs>/generate-progress.mjs`.
+- create-task chore creation: `<skill-scripts>/node_modules/.bin/tsx create-chores.ts` →
+  `node <abs>/create-chores.mjs`.
+
+## Options considered
+
+### Option A: all scripts zero-dep `.mjs` (chosen)
+- Pros: node-only everywhere; no install step; kills resolution problem; `node --test` native.
+- Cons: JSDoc typing instead of TS syntax; small convention shift (`.ts` → `.mjs`).
+
+### Option B: keep `.ts`, build in publish pipeline
+- Pros: full TS syntax.
+- Cons: compile step + dist artifacts contradict no-build PI package; installed contexts must
+  ship/install built output; over-engineered for 3 stdlib-only scripts.
+
+### Option C: per-skill tsx packages (status quo, rejected)
+- Pros: existing pattern.
+- Cons: 3 orphaned mini-workspaces, manual install fragility, resolution doc dance
+  (`<skill-scripts>/node_modules/.bin/tsx`), contradicts single-package.json preference.
+
+## Tradeoffs accepted
+
+- Scripts use JSDoc annotations where types matter; `tsc --noEmit` with `checkJs` keeps a
+  typecheck gate at root.
+- Closed beads get their history labels renamed — accepted for a clean label space.
+
+## Validation plan
+
+- F1-T3: scratch beads workspace (temp dir): create test beads with both labels + a dep pair,
+  dry-run (assert zero writes), apply, verify rename, re-run idempotence, `bd ready -l
+  execution:afk` smoke, then run the migration skill end-to-end once.
+- F8-T3: fresh clone (or temp copy) + `pnpm install` at root; `pnpm -r typecheck` and
+  `pnpm -r test` green; scripts execute via bare `node`.
+
+## Revisit triggers
+
+- A future script needs third-party deps at runtime → revisit D1 (either root dep or
+  per-package re-introduction).
+- New extension with conflicting devDeps → revisit D2 membership rules.
+
+## References
+
+- Code evidence: `skills/*/scripts/package.json` (3 orphaned), root `package.json` +
+  `pnpm-workspace.yaml`, bd CLI help (`bd list`, `bd label`), epic `agnt-ctx-s5xd` notes.

package/extensions/agent-modes/README.md

@@ -0,0 +1,54 @@
+# Agent Modes Extension
+
+Makes the agent-cortex agents (ralph, ralph-plan, plan, strategy) available as
+switchable PI modes. Each mode injects the agent's full system prompt into the
+running context, restricts tools to the agent's declared tool set, and shows a
+status indicator with the active agent name.
+
+## Usage
+
+| Command | Description |
+| --- | --- |
+| `/agent` | Show the agent mode selector |
+| `/agent <name>` | Switch to an agent mode directly (e.g. `/agent ralph`) |
+| `/agent default` | Return to default mode (full tool access) |
+| `Ctrl+Shift+A` | Cycle through agent modes |
+| `--agent <name>` | Start PI in a specific agent mode |
+
+## How agents are discovered
+
+Agents are read from the **composable source format** in the package's
+`agents/` directory:
+
+```
+agents/<name>/
+├── agent.md             # Shared body (harness-agnostic)
+└── pi/
+    ├── frontmatter.json # PI metadata: name, description, tools
+    └── <section>.md     # Optional sections referenced by {{SECTION:name}}
+```
+
+The PI system prompt is composed from `agent.md` per the token-map.json
+contract:
+
+1. `{{SECTION:name}}` tokens are replaced with the agent's `pi/<name>.md`.
+2. `{{TOOL:key}}` / `{{PATH:key}}` tokens are substituted against the pi column
+   of `token-map.json`, with the plugin root resolved from the actual extension
+   location. Tools without a PI equivalent (`ask_user`, `skill`) are omitted
+   from the tool set.
+
+Flat `agents/*.agent.md` files are parsed as a fallback when an agent has no
+composable directory — they are generated output (scripts/build-copilot-agents.mjs)
+but may exist for non-migrated agents. A composable directory always wins over its
+flat counterpart for the same agent id.
+
+## Development
+
+Discovery and prompt composition live in `discover.ts` (unit-tested against
+fixture directories in `discover.test.ts`); `index.ts` only wires discovery
+into the extension API.
+
+```bash
+pnpm test        # run discover.test.ts
+pnpm typecheck   # tsc --noEmit
+```

package/extensions/agent-modes/discover.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import {
+  type AgentDef,
+  type TokenMap,
+  discoverAgents,
+  loadTokenMap,
+} from "./discover.ts";
+
+// Real token-map.json at the package root — the canonical tool/path map the
+// extension ships with. Used to verify translation against the source of truth.
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const REAL_TOKEN_MAP = loadTokenMap(join(REPO_ROOT, "agents"));
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+interface Fixture {
+  dir: string;
+  agentsDir: string;
+  cleanup: () => void;
+}
+
+function makeFixture(): Fixture {
+  const dir = mkdtempSync(join(tmpdir(), "agent-modes-"));
+  return {
+    dir,
+    agentsDir: join(dir, "agents"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+function writeFixture(fx: Fixture, relPath: string, content: string): void {
+  const p = join(fx.dir, relPath);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+
+function writeComposableAgent(
+  fx: Fixture,
+  name: string,
+  opts: {
+    body?: string;
+    frontmatter?: Record<string, unknown>;
+    sections?: Record<string, string>;
+  } = {},
+): void {
+  const base = `agents/${name}`;
+  writeFixture(fx, `${base}/agent.md`, opts.body ?? `# ${name}\nBody of ${name}.`);
+  writeFixture(
+    fx,
+    `${base}/pi/frontmatter.json`,
+    JSON.stringify(
+      opts.frontmatter ?? {
+        name: `agent-cortex:${name}`,
+        description: `Description of ${name}`,
+        tools: ["bash", "view", "task"],
+      },
+    ),
+  );
+  for (const [section, body] of Object.entries(opts.sections ?? {})) {
+    writeFixture(fx, `${base}/pi/${section}.md`, body);
+  }
+}
+
+function writeFlatAgent(fx: Fixture, name: string, body: string): void {
+  writeFixture(fx, `agents/${name}.agent.md`, body);
+}
+
+const fixtures: Fixture[] = [];
+function track(fx: Fixture): Fixture {
+  fixtures.push(fx);
+  return fx;
+}
+
+after(() => {
+  for (const fx of fixtures) fx.cleanup();
+});
+
+const FLAT_FRONTMATTER = (name: string, tools: string) =>
+  `---\ndescription: "Flat description of ${name}"\nname: "agent-cortex:${name}"\ntools: ${tools}\n---\n\nFlat body of ${name}.`;
+
+// ─── Tokens ───────────────────────────────────────────────────────────────────
+
+const TOKEN_PROSE =
+  "Run with {{TOOL:bash}}.\n" +
+  "Ask the user with {{TOOL:ask_user}}.\n" +
+  "Read the plan skill at {{PATH:skills/workflow/plan/SKILL.md}}.\n" +
+  "Agents live in {{PATH:agents_dir}}.";
+
+// ─── Composable discovery ────────────────────────────────────────────────────
+
+describe("discoverAgents (composable source format)", () => {
+  it("discovers agents from <name>/agent.md + <name>/pi/frontmatter.json", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "ralph", {
+      body: "# ralph\nUse {{TOOL:task}} to spawn subagents.\n\n{{SECTION:polling}}",
+      frontmatter: {
+        name: "agent-cortex:ralph",
+        description: "Runs beads end-to-end",
+        tools: ["bash", "view", "rg", "glob", "task", "read_agent"],
+      },
+      sections: {
+        polling: "## PI polling\nPoll with task + read_agent.",
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    const ralph = agents[0];
+    assert.equal(ralph.id, "ralph");
+    assert.equal(ralph.name, "agent-cortex:ralph");
+    assert.equal(ralph.description, "Runs beads end-to-end");
+    // Canonical tool names translated to PI names via token-map (glob→find, rg→grep, view→read).
+    assert.deepEqual(ralph.tools, ["bash", "find", "grep", "read", "read_agent", "task"]);
+    // SECTION token resolved from pi/<section>.md; TOOL token substituted.
+    assert.match(ralph.prompt, /Use task to spawn subagents\./);
+    assert.match(ralph.prompt, /Poll with task \+ read_agent\./);
+    assert.doesNotMatch(ralph.prompt, /\{\{/);
+  });
+
+  it("substitutes TOOL / PATH tokens against token-map.json using the real plugin root", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "plan", {
+      body: TOKEN_PROSE,
+      frontmatter: { name: "agent-cortex:plan", description: "Planner", tools: [] },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+    assert.equal(agents.length, 1);
+    const plan = agents[0];
+
+    // {{TOOL:bash}} → bash.
+    assert.match(plan.prompt, /Run with bash\./);
+    // {{TOOL:ask_user}} → null for pi — token dropped (dangling prose is the author's
+    // responsibility per token-map.README), not left as literal token syntax.
+    assert.doesNotMatch(plan.prompt, /\{\{TOOL:ask_user\}\}/);
+    // Relative {{PATH:...}} resolves against the actual package root (dir of agents/).
+    assert.match(plan.prompt, new RegExp(`Read the plan skill at ${escapeRegExp(fx.dir)}/skills/workflow/plan/SKILL\\.md\\.`));
+    // Named {{PATH:agents_dir}} resolves to <root>/agents.
+    assert.match(plan.prompt, new RegExp(`Agents live in ${escapeRegExp(fx.agentsDir)}\\.`));
+    assert.doesNotMatch(plan.prompt, /\{\{/);
+  });
+
+  it("drops null-mapped tools (ask_user, skill) from the PI tool set", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "plan", {
+      frontmatter: {
+        name: "agent-cortex:plan",
+        description: "Planner",
+        tools: ["bash", "ask_user", "skill", "web_fetch"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+    assert.equal(agents.length, 1);
+    // ask_user → null (omitted), skill → null (omitted), web_fetch → fetch_content.
+    assert.deepEqual(agents[0].tools, ["bash", "fetch_content"]);
+  });
+
+  it("uses the built-in fallback map when token-map.json is unavailable", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "legacy", {
+      frontmatter: {
+        name: "agent-cortex:legacy",
+        description: "No token map",
+        tools: ["view", "glob", "ask_user"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir);
+    assert.equal(agents.length, 1);
+    // Copilot→PI fallback: view→read, glob→find+ls; unmapped ask_user passes through.
+    assert.deepEqual(agents[0].tools, ["ask_user", "find", "ls", "read"]);
+  });
+
+  it("returns an empty list for a missing agents directory", () => {
+    const fx = track(makeFixture());
+    assert.deepEqual(discoverAgents(join(fx.dir, "does-not-exist"), REAL_TOKEN_MAP), []);
+  });
+
+  it("returns an empty list when no agents are present", () => {
+    const fx = track(makeFixture());
+    mkdirSync(fx.agentsDir, { recursive: true });
+    assert.deepEqual(discoverAgents(fx.agentsDir, REAL_TOKEN_MAP), []);
+  });
+});
+
+// ─── Flat fallback ────────────────────────────────────────────────────────────
+
+describe("discoverAgents (flat fallback)", () => {
+  it("prefers a composable directory over its flat file for the same agent", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "ralph", { body: "Composable body." });
+    writeFlatAgent(fx, "ralph", FLAT_FRONTMATTER("ralph", '["bash", "view"]'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    assert.equal(agents[0].id, "ralph");
+    assert.match(agents[0].prompt, /Composable body\./);
+    assert.doesNotMatch(agents[0].prompt, /Flat body/);
+  });
+
+  it("falls back to flat *.agent.md for agents without a composable directory", () => {
+    const fx = track(makeFixture());
+    writeFlatAgent(fx, "strategy", FLAT_FRONTMATTER("strategy", '["bash", "view", "web_fetch"]'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    const strategy = agents[0];
+    assert.equal(strategy.id, "strategy");
+    assert.equal(strategy.name, "agent-cortex:strategy");
+    assert.equal(strategy.description, "Flat description of strategy");
+    // view→read, web_fetch→fetch_content via token-map.
+    assert.deepEqual(strategy.tools, ["bash", "fetch_content", "read"]);
+    assert.match(strategy.prompt, /Flat body of strategy\./);
+  });
+});
+
+// ─── loadTokenMap ────────────────────────────────────────────────────────────
+
+describe("loadTokenMap", () => {
+  it("reads the real token-map.json at the package root", () => {
+    assert.ok(REAL_TOKEN_MAP);
+    assert.equal(typeof REAL_TOKEN_MAP?.tools?.bash?.pi, "string");
+    // ask_user has no PI equivalent per the contract — must stay null.
+    assert.equal(REAL_TOKEN_MAP?.tools?.ask_user?.pi, null);
+    assert.ok(REAL_TOKEN_MAP?.paths?.agents_dir);
+  });
+});
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}