@jaybeeuu/agent-cortex 1.43.0 → 2.1.0

package/test/skill-frontmatter.test.mjs

@@ -0,0 +1,137 @@
+// Behaviour tests for scripts/lib/skill-frontmatter.mjs — the SKILL.md
+// frontmatter check that `pnpm lint` runs. Each case proves one failure mode
+// the check must catch: unparseable YAML, a missing name/description field, and
+// a description longer than the limit.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  MAX_DESCRIPTION_LENGTH,
+  checkSkills,
+  validateSkillFrontmatter,
+} from "../scripts/lib/skill-frontmatter.mjs";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Wrap frontmatter lines in a SKILL.md-shaped document. */
+function skillDocument(frontmatter) {
+  return `---\n${frontmatter}\n---\n\n# Skill body\n`;
+}
+
+/** Throwaway directory to lay out a fake skills tree in. */
+async function makeFixtureRoot() {
+  return await mkdtemp(join(tmpdir(), "agent-cortex-skill-frontmatter-"));
+}
+
+/** Write a SKILL.md at `<root>/<relativeSkillDir>/SKILL.md`. */
+async function writeSkill(root, relativeSkillDir, content) {
+  const dir = join(root, relativeSkillDir);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "SKILL.md"), content);
+}
+
+describe("validateSkillFrontmatter", () => {
+  it("accepts frontmatter with a name and a description", () => {
+    const errors = validateSkillFrontmatter(
+      skillDocument("name: example-skill\ndescription: Does a thing. Use when a thing needs doing."),
+    );
+
+    assert.deepEqual(errors, []);
+  });
+
+  it("reports unparseable YAML", () => {
+    const errors = validateSkillFrontmatter(
+      skillDocument("name: example-skill\ndescription: Use when the plan: breaks"),
+    );
+
+    assert.equal(errors.length, 1);
+    assert.match(errors[0], /not valid YAML/);
+  });
+
+  it("reports a missing name", () => {
+    const errors = validateSkillFrontmatter(skillDocument("description: Does a thing."));
+
+    assert.deepEqual(errors, ["frontmatter is missing a non-empty name"]);
+  });
+
+  it("reports a missing description", () => {
+    const errors = validateSkillFrontmatter(skillDocument("name: example-skill"));
+
+    assert.deepEqual(errors, ["frontmatter is missing a non-empty description"]);
+  });
+
+  it("reports a description over the length limit", () => {
+    const errors = validateSkillFrontmatter(
+      skillDocument(`name: example-skill\ndescription: ${"a".repeat(MAX_DESCRIPTION_LENGTH + 1)}`),
+    );
+
+    assert.equal(errors.length, 1);
+    assert.match(errors[0], /description exceeds 1024 characters \(1025\)/);
+  });
+
+  it("accepts a description exactly at the length limit", () => {
+    const errors = validateSkillFrontmatter(
+      skillDocument(`name: example-skill\ndescription: ${"a".repeat(MAX_DESCRIPTION_LENGTH)}`),
+    );
+
+    assert.deepEqual(errors, []);
+  });
+
+  it("reports a file with no frontmatter block", () => {
+    const errors = validateSkillFrontmatter("# Skill body\n\nNo frontmatter here.\n");
+
+    assert.deepEqual(errors, ["frontmatter block is missing (expected '---' delimiters)"]);
+  });
+});
+
+describe("checkSkills", () => {
+  it("reports each failing SKILL.md and counts every file it checked", async () => {
+    const root = await makeFixtureRoot();
+    try {
+      await writeSkill(
+        root,
+        "skills/good",
+        skillDocument("name: good-skill\ndescription: Does a thing. Use when testing the checker."),
+      );
+      await writeSkill(
+        root,
+        "skills/broken",
+        skillDocument("name: broken-skill\ndescription: Use when the plan: breaks"),
+      );
+
+      const result = await checkSkills({ root });
+
+      assert.equal(result.checked, 2);
+      assert.equal(result.failures.length, 1);
+      assert.equal(result.failures[0].file, join("skills", "broken", "SKILL.md"));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("ignores markdown files that are not SKILL.md", async () => {
+    const root = await makeFixtureRoot();
+    try {
+      await writeSkill(root, "skills/good", skillDocument("name: good-skill\ndescription: Does a thing."));
+      await writeFile(join(root, "skills", "good", "REFERENCE.md"), "---\nnot: a skill\n---\n");
+
+      const result = await checkSkills({ root });
+
+      assert.equal(result.checked, 1);
+      assert.deepEqual(result.failures, []);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("passes on this repository's own skills tree", async () => {
+    const result = await checkSkills({ root: REPO_ROOT });
+
+    assert.deepEqual(result.failures, []);
+    assert.ok(result.checked > 0, "expected the check to find SKILL.md files");
+  });
+});

package/token-map.README.md

@@ -1,7 +1,7 @@
 # token-map.json — multi-harness token substitution
 
 `token-map.json` is the central, single-source mapping of **tool names**, **paths**, and
-**agent naming conventions** across the three harnesses this repo ships to. It is the
+**agent naming conventions** across the two harnesses this repo ships to. It is the
 foundation for the install-time generation system: each harness installer (`agent-cortex
 install <harness>`) reads the map and substitutes `{{TOOL:...}}` / `{{PATH:...}}` tokens in
 the files it generates.
@@ -14,7 +14,6 @@ decisions behind the map.
 
 | id | Platform | Agent format | Plugin root |
 |---|---|---|---|
-| `copilot` | GitHub Copilot CLI | `agents/<name>/` composable dirs → generated `agents/*.agent.md` | `~/.copilot/installed-plugins/_direct/agent-cortex` |
 | `pi` | pi coding agent | `agents/<name>/` composable dirs (composed at runtime by agent-modes, or rendered install-time by `agent-cortex install pi`) | `~/.agent-cortex/pi` |
 | `claude` | Claude Code | `~/.agent-cortex/claude/agents/*.md` (materialised home install) | `${CLAUDE_PLUGIN_ROOT}` (env var) |
 
@@ -44,9 +43,9 @@ rather than inventing a dotted form:
 ### 2. What is mapped
 
 - **`tools`** — the twelve canonical tool names as authored in `agents/<name>/agent.md`
-  (copilot names are the authoring names). Each row gives the equivalent tool name per
-  harness. Source of truth for the copilot → claude half is `token-map.json`'s own claude
-  column, consumed by `bin/installers/claude.mjs` (the install-time generator — PR #91, #92); the pi column is grounded
+  (the canonical authoring names). Each row gives the equivalent tool name per harness.
+  The claude column is consumed by `bin/installers/claude.mjs` (the install-time
+  generator — PR #91, #92); the pi column is grounded
   in pi's documented built-in tool surface (`read`, `bash`, `edit`, `write`, `grep`, `find`,
   `ls`) plus `ask_questions` — added by the pi-questions package (mapped from
   `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools, the last three
@@ -101,7 +100,7 @@ so the warn-and-omit path applies only to future null entries. See
 
 The full contract is embedded in `token-map.json` under `contract`. In summary, installers:
 
-1. Bind a harness id (`copilot` | `claude` | `pi`).
+1. Bind a harness id (`claude` | `pi`).
 2. Substitute in order: `SECTION` (left for the composer), then `TOOL`, then `PATH`.
 3. For `TOOL`: look up the canonical key, replace with the harness name; null → drop/omit;
    unknown → throw.
@@ -111,7 +110,7 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
 
 ## Authoring guidance
 
-- Write tokens with the **canonical (copilot) names**: `Use {{TOOL:task}} to spawn
+- Write tokens with the **canonical authoring names**: `Use {{TOOL:task}} to spawn
   subagents`, `Read {{PATH:skills/workflow/plan/SKILL.md}}`.
 - Never embed a harness-specific name in the canonical sources (`agents/<name>/agent.md`,
   `skills/**/SKILL.md`) — that defeats the map. The materialised Claude plugin
@@ -125,11 +124,9 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
 
 - `agents/README.md` — composable agent directory format (ADR #63), defines the token
   grammar the map implements.
-- `scripts/build-copilot-agents.mjs` / `bin/installers/copilot.mjs` — the copilot
-  harness token composer (scripts/lib/compose-agent.mjs) resolves `{{TOOL:...}}` /
-  `{{PATH:...}}` against the map and `{{SECTION:...}}` from the per-harness section
-  files; `bin/installers/copilot.mjs` is the shared generator both `pnpm build:copilot`
-  and `agent-cortex install copilot` run.
+- `scripts/lib/compose-agent.mjs` — the shared token composer: resolves `{{TOOL:...}}` /
+  `{{PATH:...}}` against the map and `{{SECTION:...}}` from the per-harness section files
+  for `bin/installers/claude.mjs` and `bin/installers/pi.mjs`.
 - `bin/installers/claude.mjs` — the single Claude generator: plain
   `agent-cortex install claude` materialises the plugin into `~/.agent-cortex/claude`
   with token-substituted skills, merges the committed `claude/settings.json` into

package/token-map.json

@@ -1,8 +1,8 @@
 {
   "name": "agent-cortex token map",
-  "description": "Central mapping of tool names, paths, and agent naming conventions across the copilot, claude, and pi harnesses. Single source of truth for install-time token substitution. See token-map.README.md for the design rationale.",
+  "description": "Central mapping of tool names, paths, and agent naming conventions across the claude and pi harnesses. Single source of truth for install-time token substitution. See token-map.README.md for the design rationale.",
   "version": 1,
-  "harnesses": ["copilot", "claude", "pi"],
+  "harnesses": ["claude", "pi"],
   "token_format": {
     "convention": "{{TYPE:NAME}}",
     "decision": "Adopt the {{TOOL:name}} / {{PATH:name}} / {{SECTION:name}} grammar already standardised by ADR #63 (agents/README.md) rather than a dotted {{tool.name}} form. The uppercase type prefix disambiguates token kinds at a glance, keeps tool/path/section names in one namespace collision-free, and matches the token grammar skills are already written against.",
@@ -13,40 +13,36 @@
     }
   },
   "tools": {
-    "bash": { "copilot": "bash", "claude": "Bash", "pi": "bash" },
-    "view": { "copilot": "view", "claude": "Read", "pi": "read" },
-    "edit": { "copilot": "edit", "claude": "Edit", "pi": "edit" },
-    "create": { "copilot": "create", "claude": "Write", "pi": "write" },
-    "grep": { "copilot": "grep", "claude": "Grep", "pi": "grep" },
-    "rg": { "copilot": "rg", "claude": "Grep", "pi": "grep" },
-    "glob": { "copilot": "glob", "claude": "Glob", "pi": "find" },
-    "ask_user": { "copilot": "ask_user", "claude": "AskUserQuestion", "pi": "ask_questions" },
-    "web_fetch": { "copilot": "web_fetch", "claude": "WebFetch", "pi": "fetch_content" },
-    "skill": { "copilot": "skill", "claude": "Skill", "pi": "read" },
-    "task": { "copilot": "task", "claude": "Task", "pi": "task" },
-    "read_agent": { "copilot": "read_agent", "claude": null, "pi": "read_agent" },
-    "wait_for_agents": { "copilot": null, "claude": null, "pi": "wait_for_agents" }
+    "bash": { "claude": "Bash", "pi": "bash" },
+    "view": { "claude": "Read", "pi": "read" },
+    "edit": { "claude": "Edit", "pi": "edit" },
+    "create": { "claude": "Write", "pi": "write" },
+    "grep": { "claude": "Grep", "pi": "grep" },
+    "rg": { "claude": "Grep", "pi": "grep" },
+    "glob": { "claude": "Glob", "pi": "find" },
+    "ask_user": { "claude": "AskUserQuestion", "pi": "ask_questions" },
+    "web_fetch": { "claude": "WebFetch", "pi": "fetch_content" },
+    "skill": { "claude": "Skill", "pi": "read" },
+    "task": { "claude": "Task", "pi": "task" },
+    "read_agent": { "claude": null, "pi": "read_agent" },
+    "wait_for_agents": { "claude": null, "pi": "wait_for_agents" }
   },
   "paths": {
     "plugin_root": {
-      "copilot": "~/.copilot/installed-plugins/_direct/agent-cortex",
       "claude": "${CLAUDE_PLUGIN_ROOT}",
       "pi": "~/.agent-cortex/pi"
     },
     "agents_dir": {
-      "copilot": { "base": "plugin_root", "relative": "agents" },
       "claude": { "base": "plugin_root", "relative": "agents" },
       "pi": { "base": "plugin_root", "relative": "agents" }
     },
     "skills_dir": {
-      "copilot": { "base": "plugin_root", "relative": "skills" },
       "claude": { "base": "plugin_root", "relative": "skills" },
       "pi": { "base": "plugin_root", "relative": "skills" }
     }
   },
   "agents": {
     "prefix": {
-      "copilot": "agent-cortex:",
       "claude": "",
       "pi": "agent-cortex:"
     },
@@ -54,41 +50,40 @@
       "ralph": ["claude"]
     },
     "sources": {
-      "copilot": "agents/<name>/ composable dirs (canonical) — composed to agents/*.agent.md by scripts/build-copilot-agents.mjs",
       "pi": "agents/<name>/ composable dirs (canonical) — composed at runtime by the agent-modes extension",
       "claude": "agents/<name>/ composable dirs (canonical) — composed by bin/installers/claude.mjs (install-time generator, the only generator — the generated claude/ plugin subtree is not committed), plus agents-native/*.md for deferred agents"
     }
   },
   "notes": {
     "tools": {
-      "rg": "Copilot alias for grep. Claude and pi collapse it onto their single search tool (Grep / grep) — same collapse rule as the build script.",
+      "rg": "Canonical alias for grep. Claude and pi collapse it onto their single search tool (Grep / grep).",
       "glob": "Claude has a dedicated Glob tool. pi's built-in pattern-search tool is find (hypa_find when the pi-hypa extension is installed).",
-      "ask_user": "Copilot (ask_user) and Claude (AskUserQuestion) prompt the user mid-run. pi's equivalent is ask_questions, provided by the pi-questions package (an ordinary runtime dependency of this package that `agent-cortex install pi` bundles into the staged package's node_modules) — the genuine interactive-questioning tool, restoring grilling in plan/ralph-plan/strategy modes. Like fetch_content (pi-web-access), it is only present when its package is installed, so the mapping depends on that package (see the extension-manifests idea). pi still intentionally ships no permission popups; ask_questions is the interactive mid-run question tool, not a popup.",
+      "ask_user": "Claude (AskUserQuestion) prompts the user mid-run. pi's equivalent is ask_questions, provided by the pi-questions package (an ordinary runtime dependency of this package that `agent-cortex install pi` bundles into the staged package's node_modules) — the genuine interactive-questioning tool, restoring grilling in plan/ralph-plan/strategy modes. Like fetch_content (pi-web-access), it is only present when its package is installed, so the mapping depends on that package (see the extension-manifests idea). pi still intentionally ships no permission popups; ask_questions is the interactive mid-run question tool, not a popup.",
       "web_fetch": "pi's fetch_content comes from the pi-web-access package (an ordinary runtime dependency of this package that `agent-cortex install pi` bundles into the staged package's node_modules).",
-      "skill": "Copilot (skill) and Claude (Skill) expose skills as a tool. pi has no dedicated skill tool — skills are surfaced in the always-present 'Available skills' context block and loaded by reading the listed SKILL.md path ({{PATH:<skill>/SKILL.md}}). The pi mapping is read, the tool used to load a skill's file; a dedicated skill tool is a follow-on design candidate if prompting proves insufficient.",
-      "read_agent": "Claude's Task returns results inline — there is no separate read step, so read_agent drops on claude (null). Copilot uses the task + read_agent poll loop; pi exposes read_agent as a fallback to wait_for_agents.",
-      "task": "Copilot and Claude provide a subagent tool natively. On pi it is supplied by this repo's own extensions/subagent extension (which also registers read_agent and wait_for_agents), not by pi itself — a pi session started before that extension was installed has no dispatch tool at all. Skills must therefore stop and report a missing subagent tool rather than improvising a backgrounded CLI run, which has no completion signal.",
-      "wait_for_agents": "PI-only blocking wait over background subagent runs (the task tool): returns the results of completed agents and STILL RUNNING for the rest. Copilot has no equivalent tool (its task + read_agent poll loop stays) and Claude's Task delivers results inline with no wait step — both null."
+      "skill": "Claude (Skill) exposes skills as a tool. pi has no dedicated skill tool — skills are surfaced in the always-present 'Available skills' context block and loaded by reading the listed SKILL.md path ({{PATH:<skill>/SKILL.md}}). The pi mapping is read, the tool used to load a skill's file; a dedicated skill tool is a follow-on design candidate if prompting proves insufficient.",
+      "read_agent": "Claude's Task returns results inline — there is no separate read step, so read_agent drops on claude (null). pi exposes read_agent as a fallback to wait_for_agents.",
+      "task": "Claude provides a subagent tool natively. On pi it is supplied by this repo's own extensions/subagent extension (which also registers read_agent and wait_for_agents), not by pi itself — a pi session started before that extension was installed has no dispatch tool at all. Skills must therefore stop and report a missing subagent tool rather than improvising a backgrounded CLI run, which has no completion signal.",
+      "wait_for_agents": "PI-only blocking wait over background subagent runs (the task tool): returns the results of completed agents and STILL RUNNING for the rest. Claude's Task delivers results inline with no wait step — null on claude."
     },
     "paths": {
       "pi": "plugin_root is the staged package `agent-cortex install pi` materialises at ~/.agent-cortex/pi; pi loads that directory by path and the shipped extensions resolve their own resources relative to it (agent-modes computes plugin_root from its actual install location). A checkout or symlinked install differs — installers compute plugin_root from the actual resolution and can override it (--plugin-root).",
       "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim."
     },
     "agents": {
-      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): copilot/pi agents are agent-cortex:<slug>, claude agents are <slug>.",
-      "deferred": "ralph has no generated claude counterpart — it is authored natively as agents-native/ralph.md (its event-driven orchestration cannot be produced by section composition from the polling copilot source)."
+      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): pi agents are agent-cortex:<slug>, claude agents are <slug>.",
+      "deferred": "ralph has no generated claude counterpart — it is authored natively as agents-native/ralph.md (its event-driven orchestration cannot be produced by section composition from the polling pi source)."
     }
   },
   "contract": {
     "version": 1,
     "summary": "Installers substitute {{TOOL:...}}, {{PATH:...}}, and {{SECTION:...}} tokens in generated harness files using this map. This contract is the single reference installers must implement; token-map.json is the data those rules operate on.",
-    "harness_ids": ["copilot", "claude", "pi"],
+    "harness_ids": ["claude", "pi"],
     "binding": "The harness id is the same value the installer is invoked with (agent-cortex install <harness>). Each harness reads its own column from the tools, paths, and agents sections.",
     "substitution_order": ["SECTION", "TOOL", "PATH"],
     "rules": [
-      "TOOL: replace {{TOOL:<key>}} with tools.<key>.<harness>. Canonical keys are exact, case-sensitive strings (the copilot tool names, which are the authoring names in agents/<name>/agent.md).",
+      "TOOL: replace {{TOOL:<key>}} with tools.<key>.<harness>. Canonical keys are exact, case-sensitive strings (the names the canonical sources in agents/<name>/agent.md are authored with).",
       "TOOL null: a null value means the harness has no equivalent. In prose, remove the token (and emit a warning). In a tool-list context (frontmatter tools: [...]), omit the entry. Do not substitute an empty string.",
-      "TOOL unknown: a {{TOOL:<key>}} with no entry in tools is a hard error — the map must be extended. This mirrors the generators (scripts/build-copilot-agents.mjs, bin/installers/claude.mjs), which throw on unknown tools.",
+      "TOOL unknown: a {{TOOL:<key>}} with no entry in tools is a hard error — the map must be extended. This mirrors the generators (bin/installers/claude.mjs, bin/installers/pi.mjs), which throw on unknown tools.",
       "PATH named key: replace {{PATH:<key>}} with the resolved value of paths.<key>.<harness>.",
       "PATH relative: replace {{PATH:<relative>}} with plugin_root + '/' + <relative> (e.g. {{PATH:skills/workflow/plan/SKILL.md}}).",
       "PATH resolution: a value may be a literal string, an ${ENV_VAR} token, or a {base, relative} spec. Resolve {base, relative} by joining relative onto the resolved base. Leave ${ENV_VAR} values verbatim — the harness expands them at runtime (claude's ${CLAUDE_PLUGIN_ROOT}).",

package/agents/plan/copilot/frontmatter.json

@@ -1,6 +0,0 @@
-{
-  "name": "agent-cortex: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", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill"],
-  "argumentHint": "Plan <feature or change description>"
-}

package/agents/plan.agent.md

@@ -1,59 +0,0 @@
----
-# GENERATED from agents/plan/ by scripts/build-copilot-agents.mjs — DO NOT EDIT.
-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'."
-name: "agent-cortex:plan"
-tools: ["bash", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill"]
-argument-hint: "Plan <feature or change description>"
----
-
-# plan — end-to-end feature planning agent
-
-You are a planning agent. Your job is to guide a feature from first discussion through PRD and task breakdown to classified beads ready for ralph execution.
-
-You follow the **plan** skill workflow. The skill is defined in `skills/workflow/plan/SKILL.md`. Read it now to load the full instructions.
-
-## Workflow summary
-
-### Phase 1 — Understand and specify
-1. Ask the user to describe the problem, goal, or feature.
-2. Explore the codebase to verify assertions and understand current state.
-3. Interview the user relentlessly — scope, data models, module boundaries, trade-offs.
-4. Sketch major modules.
-5. Draft a PRD using the `write-a-prd` template.
-6. Present the PRD for user approval.
-7. Create an epic bead from the approved PRD.
-
-### Phase 2 — Break into tasks
-8. Review PRD stories and identify vertical-slice phases.
-9. Define each phase (title, stories, what to build, acceptance criteria).
-10. Create epics for multi-phase work.
-11. Present the breakdown for user approval.
-
-### Phase 3 — Create and classify beads
-13. Create task beads via `create-task` for each task.
-14. Tag parent epics with aggregate classification.
-15. Present the full bead tree.
-
-### Phase 4 — Prepare handoff to ralph
-16. Determine the handoff bead (epic or meta-epic).
-17. Tag it `workflow:ralph`.
-18. Push bead state with `bd dolt push`.
-19. Present the handoff summary.
-
-## Permitted writes
-
-| Location | Purpose |
-|---|---|
-| `.agent-cortex/working-docs/` | Research notes, decisions, exploration findings — gitignored |
-| Bead fields (`description`, `design`) | Plans and specifications |
-| `docs/prd/<topic>.md` | PRD documents |
-
-Do **not** modify source code or tracked documentation outside these locations.
-
-## Constraints
-
-- Never modify source code.
-- Always get user approval before moving between phases.
-- Each phase has a gate — do not skip it.
-- Work in `.agent-cortex/working-docs/` for scratchpad notes.
-- Use `bd` commands for all bead operations.

package/agents/ralph/copilot/frontmatter.json

@@ -1,6 +0,0 @@
-{
-  "name": "agent-cortex:ralph",
-  "description": "Use when running all pending beads end-to-end: finds the next available beads (dependencies met), runs the full implement → review → fix cycle for each feature in its own worktree, opens and reports PRs immediately, then waits for human merges before continuing.",
-  "tools": ["bash", "view", "rg", "glob", "task", "read_agent"],
-  "argumentHint": "Run all pending beads"
-}

package/agents/ralph/copilot/polling.md

@@ -1,62 +0,0 @@
-## Spawning subagents (Copilot)
-
-RALPH HAS ONLY ONE WAY TO SPAWN SUBAGENTS: call the **`task`** tool (not bash, not any other tool).
-
-**`task`** — Spawn a background sub-agent with the given prompt and return an agent ID immediately.
-- `prompt` (string, required): Full task prompt for the sub-agent.
-- `cwd` (string, optional): Working directory for the sub-agent (default: current project root). Always set this to the feature worktree path when running stage chores.
-
-Example:
-```
-Calling tool 'task' with arguments: { "prompt": "...", "cwd": ".agent-cortex/worktrees/abc-123" }
-```
-The response is a plain agent ID string (e.g. `agent-550e8400-e29b-41d4-a716-446655440000`). Store it in memory — you need it later to read the result.
-
-**`read_agent`** — When a sub-agent completes, read its full output.
-- `agentId` (string, required): The agent ID returned by `task`.
-
-Rules:
-- NEVER use `bash` to spawn subagents (no `pi`, no `tsx`, no `node` scripts).
-- NEVER try to run subagent work inline yourself — you only orchestrate.
-- ALWAYS use `task` + `read_agent` for every subagent interaction.
-- ALWAYS set `cwd` to the feature worktree path when running stage chores.
-- ALWAYS keep the `agentId` in memory to read the result later with `read_agent`.
-
-## Completion detection (Copilot)
-
-Copilot detects subagent completion with an active poll loop: a `sleep 120` background timer plus log tailing. When a background agent completes, flush its log with the _Log polling_ procedure below, then apply the shared completion handling in the **Event loop** section of agent.md (read the result with `read_agent`, re-read state.json, parse the REPORT, close the chore, advance the parent, check for newly ready beads, run the shutdown check).
-
-### Poll timer lifecycle
-
-- **Start** — during initialization, if any AFK beads were dispatched in the init step, start the **poll timer**: run `sleep 120` as a background bash process and record its shellId as `timerShellId` in `.agent-cortex/ralph/state.json`. **Otherwise**, if HITL gate beads are pending (open `lifecycle:feature-pr` beads or epics tagged `awaiting-epic-pr-merge`), proceed to **HITL Pause** (see below) immediately.
-- **Tick** — when the timer completes:
-  1. **Poll all in-flight bead logs** (see _Log polling_ below).
-  2. Regenerate `.agent-cortex/ralph/progress.md`.
-  3. **HITL pause check**: if no chore beads are in-flight AND `bd ready` has no `stage:*` chore beads AND HITL gate beads are pending (`bd list -l lifecycle:feature-pr -l implementation-type:hitl` or `bd list -l awaiting-epic-pr-merge` returns results), proceed to **HITL Pause** (see below) — do **not** restart the timer.
-  4. **Otherwise**: restart the timer: run `sleep 120` as a new background bash process, record its shellId as `timerShellId` in `.agent-cortex/ralph/state.json`.
-- **Stop** — when stopping completely (HITL Pause or Shutdown), kill the running timer: if `timerShellId` is non-null in `state.json`, run `kill <timerShellId>` (suppress errors), then set `timerShellId` to `null` in `state.json`. Never restart or schedule a new timer once the HITL pause condition has been met.
-
-## Log polling
-
-Run this procedure whenever polling is triggered (timer or agent completion):
-
-1. **Query in-flight beads**: read `inflight` from `state.json`. Each entry has a `parentId` and `logLine`.
-2. For each in-flight entry, read new lines from its log file:
-   ```bash
-   tail -n +<logLine> .agent-cortex/ralph/ralph-<parentId>.log 2>/dev/null
-   ```
-3. For each entry that has new lines:
-   - **Post a chat summary** of new key events (stage transitions and notable events — not every line verbatim). Format:
-     ```
-     📋 [parent-id] <title>
-        coding → verifying  (or whatever transition)
-        Tests: 12 passed, 0 failed
-     ```
-   - Update `logLine` in `state.json` for that entry.
-4. If no entry had new lines, post nothing — do not spam the chat with empty polls.
-
-## Polling constraints
-
-- **Always** restart the poll timer immediately after it fires **if** agent work is still in-flight or AFK task beads are available — never let running agent work stall without a timer.
-- **Never** restart or start a new timer once the HITL pause condition is met (no chores in-flight, no `stage:*` chores ready, HITL gate beads pending). Kill any running timer, proceed to **HITL Pause**, and stop completely.
-- **Never** post empty poll updates to chat — only surface new log content.

package/agents/ralph-plan/copilot/frontmatter.json

@@ -1,6 +0,0 @@
-{
-  "name": "agent-cortex: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", "view", "edit", "create", "grep", "glob", "ask_user"],
-  "argumentHint": "Plan <feature or change description>"
-}

package/agents/ralph-plan.agent.md

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