@jaybeeuu/agent-cortex 1.20.0 → 1.38.1

package/skills/workflow/ralph/REFERENCE.md

@@ -10,7 +10,7 @@ Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL
 2. **Read its `stage:*` label** from `bd show <id>`.
 3. **Load the universal stage runner prompt** from `skills/workflow/run-pipeline-stage/prompts/stage-runner.md`.
 4. **Read the parent task context**: follow the `parent-child` dependency to the parent task bead, run `bd show <parent-id>` to get the full task description.
-5. **Ensure branch + worktree exist for this parent task** (see _Feature branches and worktrees_ below), then note the worktree path — you'll pass it as `cwd` to `task`.
+5. **Ensure branch + worktree exist for this parent task** (see _Feature branches and worktrees_ below), then note the worktree path — you'll pass it as `cwd` to {{TOOL:task}}.
 6. **Fill in the prompt** — replace placeholders with:
    - Stage from bead label (`stage:<stage>`) for `<stage>`
    - `bd prime` output (held in memory from initialization)
@@ -18,7 +18,7 @@ Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL
    - For `fix` stage: `FILES_CHANGED` from the preceding stage's report (the required changes come from the fix bead's own description — read via `bd show <fix-id>`)
    - For `verify`, `review`, `document` stages: `SUMMARY` and `FILES_CHANGED` from the preceding stage's report
    - Bead ID and log file path (`.agent-cortex/ralph/ralph-<bead-id>.log`)
-7. **Call the `task` tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for log polling.
+7. **Call the {{TOOL:task}} tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for log polling.
 8. **Map** the agent ID to the bead ID in memory for lookup on completion.
 
 ---

package/skills/workflow/ralph/SKILL.md

@@ -35,7 +35,7 @@ Run once at startup:
    - **Task or other type without an `implementation-type:*` label**: unexpected here — classification is a planning-stage concern already applied by `create-task`. Do not invoke `classify-bead`; treat as needs-refinement and note for the shutdown summary.
    - **Task labelled `implementation-type:hitl`**: skip — record the bead ID for the **Pending Human Action** summary at shutdown.
 7. For each ready chore bead (up to 5), **dispatch** it (see _Dispatching a chore bead_ in REFERENCE.md). Chores for a parent bead must run from that parent's worktree.
-8. **If** any chore beads were dispatched in step 7, start the **poll timer**: run `sleep 120` as a background bash process and hold its shellId in memory. **Otherwise**, if HITL gate beads are pending (check `bd list -l lifecycle:feature-pr -l implementation-type:hitl` and `bd list -l awaiting-epic-pr-merge`), proceed to **HITL Pause** (see REFERENCE.md) immediately.
+8. **If** any chore beads were dispatched in step 7, start the **poll timer** (Copilot only): run `sleep 120` as a background bash process and hold its shellId in memory. PI has no timer — keep a `wait_for_agents` call outstanding over every in-flight agent ID instead (see the Event Loop note). **Otherwise**, if HITL gate beads are pending (check `bd list -l lifecycle:feature-pr -l implementation-type:hitl` and `bd list -l awaiting-epic-pr-merge`), proceed to **HITL Pause** (see REFERENCE.md) immediately.
 9. Regenerate `.agent-cortex/ralph/progress.md`:
    ```bash
    # workspace must be the absolute path you cd'd into — never . or $(pwd)
@@ -47,7 +47,7 @@ Run once at startup:
 
 ## Event Loop
 
-After initialization, wait for background agents or the poll timer to complete. On each completion notification:
+After initialization, wait for background agents or the poll timer to complete. Completion detection is harness-specific: the `sleep 120` poll timer described below is the **Copilot** mechanism. **PI** replaces it with the blocking `wait_for_agents` tool — it returns as soon as any in-flight agent finishes, so each return plays the role of a poll-timer tick with its completed-agent result attached; there is no timer to start or kill on PI. On each completion notification:
 
 ### Poll timer completed
 
@@ -59,7 +59,7 @@ After initialization, wait for background agents or the poll timer to complete.
 ### Background agent completed
 
 1. **Poll that bead's log** to flush any final lines.
-2. **Read** the completed agent's full output with `read_agent`.
+2. **Read** the completed agent's full output with {{TOOL:read_agent}} (on PI the completed result arrives in the `wait_for_agents` response; read_agent remains a fallback for a specific result).
 3. **Identify the bead**: parse the `---REPORT---` block for `BEAD_ID` and `STAGE_COMPLETED`.
 4. **Close** the chore bead: `bd close <bead-id>`.
 5. **Handle stage outcome**:
@@ -90,10 +90,10 @@ After initialization, wait for background agents or the poll timer to complete.
 - **Always** run in **foreground** (interactive) mode. If you find yourself executing as a background task, immediately surface a warning to the user and ask them to re-run you in foreground mode.
 - **Never** write, edit, or create source code or documentation yourself.
 - **Never** edit bead task files directly — only use `bd` commands.
-- **ALWAYS call the `task` tool to spawn subagents** — never use bash, never run stages inline, never use any other tool. This is your only spawning mechanism.
+- **ALWAYS call the {{TOOL:task}} tool to spawn subagents** — never use {{TOOL:bash}}, never run stages inline, never use any other tool. This is your only spawning mechanism.
 - **Always** derive orchestration state from beads — do not maintain a separate state file.
-- **Always** include the full `bd prime` output verbatim in every `task` tool prompt.
-- **Always** keep the poll timer running — restart it immediately after it fires — **unless** the HITL pause condition is met (no chores in-flight, no `stage:*` chores ready, HITL gate beads pending), in which case proceed to **HITL Pause** (see REFERENCE.md) and stop instead.
+- **Always** include the full `bd prime` output verbatim in every {{TOOL:task}} tool prompt.
+- **Always** keep the poll timer running (Copilot) — restart it immediately after it fires — **unless** the HITL pause condition is met (no chores in-flight, no `stage:*` chores ready, HITL gate beads pending), in which case proceed to **HITL Pause** (see REFERENCE.md) and stop instead. On PI there is no timer to keep alive — always keep one `wait_for_agents` call outstanding while agents are in-flight.
 - **Never** post empty poll updates to chat — only surface new log content.
 - **Max 5** tasks in-flight at once.
 - **Max fix rounds** per task as defined by `maxFixRounds` in `skills/planning/create-task/pipeline.json`.

package/skills/workflow/run-pipeline-stage/scripts/generate-progress.ts

@@ -50,8 +50,10 @@ const STATUS_CHAR_MAP: Record<string, BeadStatus> = {
 export function parseListLine(
   line: string,
 ): { id: string; status: BeadStatus; title: string } | null {
-  // Format: {STATUS_CHAR} {ID} ● P{N} {TITLE}
-  const match = line.trim().match(/^([○◐●✓❄])\s+(\S+)\s+●\s+P\d+\s+(.+)$/);
+  // Formats accepted:
+  //   {STATUS_CHAR} {ID} P{N} {TITLE}        — current bd list output
+  //   {STATUS_CHAR} {ID} ● P{N} {TITLE}      — older bd (● before P{N} is optional)
+  const match = line.trim().match(/^([○◐●✓❄])\s+(\S+)\s+(?:●\s+)?P\d+\s+(.+)$/);
   if (!match) return null;
   const [, statusChar, id, title] = match;
   const status = STATUS_CHAR_MAP[statusChar];

package/skills/workflow/using-agent-skills/SKILL.md

@@ -28,9 +28,11 @@ Task arrives
     ├── Running beads / task execution? ────→ ralph
     │   └── Single stage? ─────────────────→ run-pipeline-stage
     ├── Implementing code? ────────────────→ tdd
-    │   └── Designing an interface? ───────→ design-an-interface
+    │   ├── Designing an interface? ───────→ design-an-interface
+    │   └── Need style conventions? ───────→ style-code
     ├── Reviewing code? ───────────────────→ style-code
-    │   └── Security concerns? ────────────→ review-security
+    │   ├── Security concerns? ────────────→ review-security
+    │   └── Reviewing tests? ──────────────→ style-tests
     ├── Writing tests? ────────────────────→ style-tests
     ├── Writing docs? ─────────────────────→ style-documentation
     ├── Writing external comms? ───────────→ style-comms
@@ -76,6 +78,14 @@ Touch only what you're asked to touch. Do not clean up orthogonal code, refactor
 
 A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence: passing tests, build output, or runtime data.
 
+### 7. Flag Persistent Failures
+
+When a tool or command fails repeatedly, stop and flag it to the user for investigation. Don't paper over failures with workarounds — workarounds waste tokens and hide real problems. Describe what failed, how many times, and any obvious patterns. Let the user decide whether to investigate in a dedicated session. Inefficiencies and failures should be squashed, not hidden.
+
+### 8. Stay On Target
+
+Stick to the task at hand. If you discover work that's outside the current scope — a tangential bug, an adjacent improvement, a missing doc — flag it to the user but don't pursue it. If the side quest blocks or slows your progress, stop and report it. Otherwise, note it and get back on track. Scope creep mid-task burns tokens and dilutes focus.
+
 ## Lifecycle Sequence
 
 For a complete feature, the typical skill sequence is:
@@ -100,6 +110,9 @@ Not every task needs every skill. A bug fix might only need: `tdd` → `style-co
 - Making wrong assumptions without stating them.
 - Overcomplicating code when a simple solution exists.
 - Modifying code orthogonal to the task scope.
+- Going on side-quests instead of staying on target.
+- Going on side-quests instead of staying on target.
+- Going on side-quests instead of staying on target.
 
 ## Verification checklist
 

package/test/cli.test.mjs

@@ -1,6 +1,8 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
@@ -56,6 +58,84 @@ describe("parseArgs", () => {
     assert.deepStrictEqual(result, { command: "install", harness: null });
   });
 
+  it("returns output for install claude --output <dir>", () => {
+    const result = parseArgs(["install", "claude", "--output", "/tmp/x"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "claude", output: "/tmp/x" });
+  });
+
+  it("returns output for install claude --output=<dir>", () => {
+    const result = parseArgs(["install", "claude", "--output=/tmp/x"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "claude", output: "/tmp/x" });
+  });
+
+  it("returns dryRun for install claude --dry-run", () => {
+    const result = parseArgs(["install", "claude", "--dry-run"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "claude", dryRun: true });
+  });
+
+  it("combines --dry-run with --output", () => {
+    const result = parseArgs(["install", "claude", "--output", "/tmp/x", "--dry-run"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "claude", output: "/tmp/x", dryRun: true });
+  });
+
+  it("reports an unknown option for claude", () => {
+    const result = parseArgs(["install", "claude", "--bogus"]);
+    assert.equal(result.command, "install");
+    assert.equal(result.harness, "claude");
+    assert.ok(result.optionError.includes("--bogus"));
+  });
+
+  it("reports a missing value for --output for claude", () => {
+    const result = parseArgs(["install", "claude", "--output"]);
+    assert.equal(result.command, "install");
+    assert.equal(result.harness, "claude");
+    assert.ok(result.optionError.includes("--output"));
+  });
+
+  it("parses --dry-run for install", () => {
+    const result = parseArgs(["install", "pi", "--dry-run"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "pi", dryRun: true });
+  });
+
+  it("parses --output <dir> for install", () => {
+    const result = parseArgs(["install", "pi", "--output", "/tmp/out"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "pi", output: "/tmp/out" });
+  });
+
+  it("parses --plugin-root <dir> for install", () => {
+    const result = parseArgs(["install", "pi", "--plugin-root", "/tmp/plugin"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "pi", pluginRoot: "/tmp/plugin" });
+  });
+
+  it("combines multiple install options", () => {
+    const result = parseArgs(["install", "pi", "--dry-run", "--output", "/tmp/out", "--plugin-root", "/tmp/plugin"]);
+    assert.deepStrictEqual(result, {
+      command: "install",
+      harness: "pi",
+      dryRun: true,
+      output: "/tmp/out",
+      pluginRoot: "/tmp/plugin",
+    });
+  });
+
+  it("reports a missing value for --output", () => {
+    const result = parseArgs(["install", "pi", "--output"]);
+    assert.equal(result.command, "install");
+    assert.equal(result.harness, "pi");
+    assert.ok(result.optionError.includes("--output"));
+  });
+
+  it("reports an unknown option", () => {
+    const result = parseArgs(["install", "pi", "--bogus"]);
+    assert.equal(result.command, "install");
+    assert.equal(result.harness, "pi");
+    assert.ok(result.optionError.includes("--bogus"));
+  });
+
+  it("keeps the old shape when no options are given", () => {
+    assert.deepStrictEqual(parseArgs(["install", "pi"]), { command: "install", harness: "pi" });
+  });
+
   it("returns { command: 'unknown', name: 'foo' } for unknown command", () => {
     const result = parseArgs(["foo"]);
     assert.deepStrictEqual(result, { command: "unknown", name: "foo" });
@@ -117,8 +197,9 @@ describe("CLI integration", () => {
     assert.ok(stdout.includes("copilot"));
   });
 
-  it("exits 0 for install claude", async () => {
-    const { exitCode, stdout } = await runCli(["install", "claude"]);
+  it("exits 0 for install claude (into a temp output dir)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "agent-cortex-cli-"));
+    const { exitCode, stdout } = await runCli(["install", "claude", "--output", dir]);
     assert.equal(exitCode, 0);
     assert.ok(stdout.includes("claude"));
   });
@@ -135,6 +216,38 @@ describe("CLI integration", () => {
     assert.ok(stderr.includes("Missing harness"));
   });
 
+  it("exits 1 and prints error for install with an unknown option", async () => {
+    const { exitCode, stderr } = await runCli(["install", "pi", "--bogus"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("--bogus"));
+  });
+
+  it("exits 1 and prints error for install with a missing option value", async () => {
+    const { exitCode, stderr } = await runCli(["install", "pi", "--output"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("--output"));
+  });
+
+  it("exits 0 for install pi --dry-run and writes nothing", async () => {
+    const { exitCode, stdout } = await runCli(["install", "pi", "--dry-run"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("ralph.agent.md"));
+    assert.ok(stdout.includes("dry-run"));
+  });
+
+  it("exits 0 for install pi --output <tmp> and writes agent files", async () => {
+    const outDir = mkdtempSync(join(tmpdir(), "cli-pi-install-"));
+    try {
+      const { exitCode, stdout } = await runCli(["install", "pi", "--output", outDir]);
+      assert.equal(exitCode, 0);
+      assert.ok(stdout.includes("ralph.agent.md"));
+      const ralph = readFileSync(join(outDir, "agents", "ralph.agent.md"), "utf-8");
+      assert.ok(ralph.includes("agent-cortex:ralph"));
+    } finally {
+      rmSync(outDir, { recursive: true, force: true });
+    }
+  });
+
   it("exits 1 and prints error for install with unknown harness", async () => {
     const { exitCode, stderr } = await runCli(["install", "docker"]);
     assert.equal(exitCode, 1);

package/test/copilot-installer.test.mjs

@@ -0,0 +1,298 @@
+// Integration tests for `agent-cortex install copilot`: the install-time
+// generator for the Copilot CLI flat agent files (agents/*.agent.md). All tests
+// install into mkdtemp dirs so the real repo agents/ is never touched.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+import { installCopilot } from "../bin/installers/copilot.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+const CLI_PATH = join(ROOT, "bin", "agent-cortex.mjs");
+
+function runCli(args) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
+      resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
+    });
+  });
+}
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+function tokenMap() {
+  return {
+    name: "fixture token map",
+    version: 1,
+    harnesses: ["copilot"],
+    tools: {
+      bash: { copilot: "bash" },
+      view: { copilot: "view" },
+      task: { copilot: "task" },
+      ask_user: { copilot: "ask_user" },
+    },
+    paths: {
+      plugin_root: { copilot: "~/.copilot/installed-plugins/_direct/agent-cortex" },
+      agents_dir: { copilot: { base: "plugin_root", relative: "agents" } },
+    },
+  };
+}
+
+function makeFixture() {
+  const root = mkdtempSync(join(tmpdir(), "copilot-installer-"));
+  return {
+    root,
+    output: join(root, "generated"),
+    cleanup: () => rmSync(root, { recursive: true, force: true }),
+  };
+}
+
+function writeFixture(fx, relPath, content) {
+  const p = join(fx.root, relPath);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+
+/** Seed a minimal but realistic package tree (agents + token-map). */
+function seedCopilotPackage(fx, opts = {}) {
+  const { agents = {} } = opts;
+  writeFixture(fx, "token-map.json", JSON.stringify(tokenMap()));
+  for (const [name, def] of Object.entries(agents)) {
+    writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
+    writeFixture(
+      fx,
+      `agents/${name}/copilot/frontmatter.json`,
+      JSON.stringify(
+        def.frontmatter ?? {
+          name: `agent-cortex:${name}`,
+          description: `Description of ${name}`,
+          tools: ["bash", "view"],
+          argumentHint: `Hint for ${name}`,
+        },
+      ),
+    );
+    for (const [section, content] of Object.entries(def.sections ?? {})) {
+      writeFixture(fx, `agents/${name}/copilot/${section}.md`, content);
+    }
+  }
+}
+
+/** Deterministic snapshot of a directory: relative paths + byte content. */
+function snapshot(dir) {
+  const entries = [];
+  const walk = (p) => {
+    for (const e of readdirSync(p, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join(p, e.name);
+      if (e.isDirectory()) {
+        entries.push([e.name, "dir"]);
+        walk(full);
+      } else entries.push([e.name, "file", readFileSync(full, "utf-8")]);
+    }
+  };
+  walk(dir);
+  return entries;
+}
+
+// ─── Agent composition ───────────────────────────────────────────────────────
+
+describe("installCopilot — agent composition", () => {
+  it("writes one flat <name>.agent.md per composable agent dir with copilot frontmatter and no leftover tokens", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, {
+        agents: {
+          alpha: {
+            body: "# alpha\nUse {{TOOL:view}} to read.\n{{SECTION:polling}}\nRead {{PATH:agents_dir}}.",
+            sections: { polling: "Spawn with {{TOOL:task}}." },
+            frontmatter: {
+              name: "agent-cortex:alpha",
+              description: "Reads things.",
+              tools: ["bash", "view"],
+              argumentHint: "Read something",
+            },
+          },
+        },
+      });
+
+      const result = installCopilot({ root: fx.root, output: fx.output });
+
+      const file = join(fx.output, "alpha.agent.md");
+      assert.ok(existsSync(file), "flat agent file written");
+      const content = readFileSync(file, "utf-8");
+      assert.ok(content.startsWith("---\n"), "yaml frontmatter");
+      assert.ok(content.includes("# GENERATED from agents/alpha/ by scripts/build-copilot-agents.mjs — DO NOT EDIT."));
+      // Committed flat-file field order: description, name, tools (YAML array), argument-hint.
+      const order = ["description:", "name: \"agent-cortex:alpha\"", "tools: [", "argument-hint:"].map((s) => content.indexOf(s));
+      assert.ok(order.every((i) => i !== -1), "all frontmatter fields present");
+      assert.deepEqual([...order].sort((a, b) => a - b), order, "frontmatter fields in committed order");
+      assert.match(content, /tools: \["bash", "view"\]/, "copilot tools kept as a YAML array (no translation)");
+      assert.ok(content.includes("Use view to read."), "{{TOOL:view}} substituted");
+      assert.ok(content.includes("Spawn with task."), "{{SECTION:polling}} composed from copilot/polling.md");
+      assert.ok(!/{{/.test(content), "no literal tokens remain");
+      assert.equal(result.agents.length, 1);
+      assert.deepEqual(result.agents, ["alpha"]);
+      assert.equal(result.output, fx.output);
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("skips non-composable entries in agents/ and never clobbers composable sources", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      writeFixture(fx, "agents/README.md", "# agents dir docs\n");
+
+      const result = installCopilot({ root: fx.root, output: fx.output });
+
+      assert.deepEqual(readdirSync(fx.output).sort(), ["alpha.agent.md"], "no README, no subdirectories written");
+      assert.deepEqual(result.agents, ["alpha"]);
+      // The composable source dir next to the generated file stays untouched.
+      assert.ok(existsSync(join(fx.root, "agents", "alpha", "agent.md")), "composable source preserved");
+      assert.ok(existsSync(join(fx.root, "agents", "alpha", "copilot", "frontmatter.json")), "harness dir preserved");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("throws when a composable dir lacks copilot/frontmatter.json", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      rmSync(join(fx.root, "agents", "alpha", "copilot"), { recursive: true, force: true });
+      assert.throws(
+        () => installCopilot({ root: fx.root, output: fx.output }),
+        /without copilot\/frontmatter\.json/,
+      );
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("defaults to the plugin-scanned agents/ dir of the package root (plugin.json \"agents\": \"agents/\")", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+
+      const result = installCopilot({ root: fx.root });
+
+      assert.equal(result.output, join(fx.root, "agents"), "default output is the dir plugin.json scans");
+      assert.ok(existsSync(join(fx.root, "agents", "alpha.agent.md")), "flat file lands next to the composable dir");
+      assert.ok(existsSync(join(fx.root, "agents", "alpha", "agent.md")), "composable source untouched");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("throws on an unknown tool token", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha\nUse {{TOOL:nope}} now." } } });
+      assert.throws(() => installCopilot({ root: fx.root, output: fx.output }), /unknown tool token {{TOOL:nope}}/);
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── Output / dry-run ────────────────────────────────────────────────────────
+
+describe("installCopilot — output & dry-run", () => {
+  it("dry-run reports the plan without writing anything", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+
+      const result = installCopilot({ root: fx.root, output: fx.output, dryRun: true });
+
+      assert.equal(result.dryRun, true);
+      assert.equal(existsSync(fx.output), false, "no output dir created in dry-run");
+      assert.deepEqual(result.agents, ["alpha"], "planned files still reported");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("is deterministic across repeated installs into the same output", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, {
+        agents: {
+          alpha: { body: "# alpha\n{{SECTION:polling}}", sections: { polling: "Poll with {{TOOL:task}}." } },
+          beta: { body: "# beta" },
+        },
+      });
+
+      installCopilot({ root: fx.root, output: fx.output });
+      const first = snapshot(fx.output);
+      installCopilot({ root: fx.root, output: fx.output });
+      assert.deepEqual(snapshot(fx.output), first);
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── Integration against the real repo ───────────────────────────────────────
+
+describe("installCopilot — real repo integration", () => {
+  it("regenerates byte-identical copies of the committed agents/*.agent.md files", () => {
+    const fx = makeFixture();
+    try {
+      const result = installCopilot({ root: ROOT, output: fx.output });
+
+      assert.deepEqual(result.agents.sort(), ["plan", "ralph", "ralph-plan", "strategy"]);
+      for (const name of result.agents) {
+        const generated = readFileSync(join(fx.output, `${name}.agent.md`), "utf-8");
+        const committed = readFileSync(join(ROOT, "agents", `${name}.agent.md`), "utf-8");
+        assert.equal(generated, committed, `${name}.agent.md must match the committed flat file (CI drift check)`);
+      }
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── CLI wiring ──────────────────────────────────────────────────────────────
+
+describe("CLI integration", () => {
+  it("exits 0 for install copilot --output <tmp> and writes the flat files", async () => {
+    const fx = makeFixture();
+    try {
+      const { exitCode, stdout } = await runCli(["install", "copilot", "--output", fx.output]);
+      assert.equal(exitCode, 0);
+      assert.ok(stdout.includes("copilot"), "prints the harness name");
+      assert.ok(stdout.includes("Generated"), "prints the generation summary");
+      assert.ok(existsSync(join(fx.output, "ralph.agent.md")), "agent files written");
+      assert.ok(existsSync(join(fx.output, "plan.agent.md")));
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("exits 0 for install copilot --dry-run and writes nothing", async () => {
+    const fx = makeFixture();
+    try {
+      const { exitCode, stdout } = await runCli(["install", "copilot", "--output", fx.output, "--dry-run"]);
+      assert.equal(exitCode, 0);
+      assert.ok(/dry-run/i.test(stdout));
+      assert.equal(existsSync(fx.output), false, "no files written in dry-run");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("exits 0 for install copilot (default output) without touching committed files", async () => {
+    const before = readFileSync(join(ROOT, "agents", "ralph.agent.md"), "utf-8");
+    const { exitCode } = await runCli(["install", "copilot"]);
+    assert.equal(exitCode, 0);
+    // Default output regenerates the shared agents/ dir in place — output must
+    // stay byte-identical to what is committed.
+    assert.equal(readFileSync(join(ROOT, "agents", "ralph.agent.md"), "utf-8"), before);
+  });
+});