@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/skills/workflow/run-pipeline-stage/scripts/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/skills/workflow/run-pipeline-stage/scripts/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/skills/workflow/run-pipeline-stage/scripts/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

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

@@ -0,0 +1,122 @@
+---
+name: using-agent-skills
+description: Routes incoming work to the right skill and enforces core agent behaviors. Use when starting a session, deciding which skill applies, or when you need to check "which skill should I use?".
+---
+
+# Using Agent Skills
+
+## When to use
+
+- Starting a new session and need to orient on available workflows.
+- A task arrives and you need to decide which skill applies.
+- The user asks "which skill should I use for this?"
+- You want to verify that core operating behaviors are being followed.
+
+## Workflow
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Don't know what to build yet? ──────→ grill-me
+    ├── Have a rough idea? ─────────────────→ record-idea
+    ├── New feature / PRD needed? ──────────→ write-a-prd
+    ├── PRD approved, need tasks? ──────────→ prd-to-tasks
+    ├── Need a single task tracked? ────────→ create-task
+    ├── Need to plan a feature end-to-end? ─→ plan
+    ├── Running beads / task execution? ────→ ralph
+    │   └── Single stage? ─────────────────→ run-pipeline-stage
+    ├── Implementing code? ────────────────→ tdd
+    │   ├── Designing an interface? ───────→ design-an-interface
+    │   └── Need style conventions? ───────→ style-code
+    ├── Reviewing code? ───────────────────→ style-code
+    │   ├── Security concerns? ────────────→ review-security
+    │   └── Reviewing tests? ──────────────→ style-tests
+    ├── Writing tests? ────────────────────→ style-tests
+    ├── Writing docs? ─────────────────────→ style-documentation
+    ├── Writing external comms? ───────────→ style-comms
+    ├── Stress-testing a plan? ────────────→ grill-with-docs
+    ├── Planning a refactor? ──────────────→ request-refactor-plan
+    ├── Evaluating architecture? ──────────→ technical-direction
+    ├── Finding refactor opportunities? ───→ improve-codebase-architecture
+    ├── Need task tracking? ───────────────→ bd-tool
+    ├── Need human review / HITL? ─────────→ hitl-collab
+    ├── Need a handoff doc? ───────────────→ handoff
+    ├── Writing a ticket for Jira? ────────→ write-a-ticket
+    ├── Creating a new skill? ─────────────→ write-a-skill
+    ├── Refactoring a skill? ──────────────→ refactor-skill
+    ├── Updating agent docs? ──────────────→ maintain-agent-docs
+    └── Setting up beads in a new project? → init-beads
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions. Don't silently fill in ambiguous requirements — surface uncertainty early, it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications: **STOP**. Name the specific confusion, present the tradeoff or ask the clarifying question, and wait for resolution before continuing.
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems, point out the issue directly, explain the concrete downside, propose an alternative, and accept the human's decision if they override with full information.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Before finishing any implementation, ask: Can this be done in fewer lines? Are these abstractions earning their complexity? Prefer the boring, obvious solution.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch. Do not clean up orthogonal code, refactor adjacent systems, or add features not in the spec. Surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+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:
+
+1. `grill-me` → Extract what the user actually wants
+2. `record-idea` → Refine vague ideas
+3. `write-a-prd` → Define what we're building
+4. `prd-to-tasks` → Break into verifiable chunks
+5. `plan` → Orchestrate the full flow end-to-end
+6. `ralph` → Execute all pending beads
+7. `tdd` → Prove each slice works
+8. `style-code` → Review before merge
+9. `review-security` → Check for secrets
+10. `git-workflow` → Clean commit history
+
+Not every task needs every skill. A bug fix might only need: `tdd` → `style-code` → `review-security`.
+
+## Red Flags
+
+- Starting work without checking which skill applies.
+- Skipping verification because "it looks right."
+- 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
+
+- [ ] Correct skill identified before starting work.
+- [ ] Core operating behaviors followed throughout.
+- [ ] Verification completed with evidence (tests, build, runtime).
+- [ ] Scope limited to the task at hand.

package/test/claude-installer.test.mjs

@@ -0,0 +1,248 @@
+// Tests for `agent-cortex install claude` runtime registration: after
+// regenerating the claude/ subtree, the plain install registers the plugin
+// with Claude Code by driving the `claude plugin` CLI (marketplace add →
+// install → marketplace update → plugin update). The real CLI is a genuine
+// external system, so these tests drive a fake `claudeBin` script that records
+// every invocation; the real repo's marketplace.json supplies the manifest.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  readFileSync,
+  chmodSync,
+  existsSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { registerClaude } from "../bin/installers/claude.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 });
+    });
+  });
+}
+
+// ─── Fake claude CLI ─────────────────────────────────────────────────────────
+
+/**
+ * A fake `claude` binary recording every argv line to `log` (one line per
+ * invocation, space-joined). Set `failWhen` to a substring: any invocation
+ * whose argv contains it exits 1. Exits 0 otherwise.
+ */
+function makeFakeClaude(dir, { failWhen = null } = {}) {
+  const bin = join(dir, "claude");
+  const log = join(dir, "calls.log");
+  const script = [
+    "#!/bin/sh",
+    `echo "$*" >> "${log}"`,
+    ...(failWhen
+      ? [`if printf '%s' "$*" | grep -q -- "${failWhen}"; then exit 1; fi`]
+      : []),
+    "exit 0",
+  ].join("\n");
+  writeFileSync(bin, `${script}\n`);
+  chmodSync(bin, 0o755);
+  return { bin, log };
+}
+
+function makeTmp() {
+  return mkdtempSync(join(tmpdir(), "agent-cortex-claude-installer-"));
+}
+
+/** A minimal marketplace tree (as seen in the real repo) at a scratch path. */
+function makeMarketplaceRoot({ name = "jaybeeuu", plugin = "agent-cortex" } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "agent-cortex-marketplace-"));
+  mkdirSync(join(root, ".claude-plugin"), { recursive: true });
+  writeFileSync(
+    join(root, ".claude-plugin", "marketplace.json"),
+    JSON.stringify({
+      name,
+      owner: { name: "tester" },
+      plugins: [{ name: plugin, source: "./claude", description: "test plugin" }],
+    }),
+  );
+  return root;
+}
+
+// ─── registerClaude ──────────────────────────────────────────────────────────
+
+describe("registerClaude", () => {
+  it("drives claude plugin marketplace add → install → marketplace update → plugin update", () => {
+    const tmp = makeTmp();
+    const root = makeMarketplaceRoot();
+    const fake = makeFakeClaude(tmp);
+    try {
+      const result = registerClaude({ root, claudeBin: fake.bin });
+      assert.equal(result.marketplace, "jaybeeuu");
+      assert.equal(result.plugin, "agent-cortex");
+      assert.equal(result.dryRun, false);
+
+      const calls = readFileSync(fake.log, "utf-8").trim().split("\n");
+      // The availability probe (`plugin --help`) is a spawn, but the registration
+      // surface is the four commands below — assert those, in order.
+      const registration = calls.filter((c) => !c.startsWith("plugin --help"));
+      assert.deepEqual(registration, [
+        `plugin marketplace add ${root}`,
+        "plugin install agent-cortex@jaybeeuu -y",
+        "plugin marketplace update jaybeeuu",
+        "plugin update agent-cortex -y",
+      ]);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("derives marketplace and plugin names from the manifest", () => {
+    const tmp = makeTmp();
+    const root = makeMarketplaceRoot({ name: "scratchmkt", plugin: "scratchplug" });
+    const fake = makeFakeClaude(tmp);
+    try {
+      const result = registerClaude({ root, claudeBin: fake.bin });
+      assert.equal(result.marketplace, "scratchmkt");
+      assert.equal(result.plugin, "scratchplug");
+      const calls = readFileSync(fake.log, "utf-8").trim().split("\n");
+      const registration = calls.filter((c) => !c.startsWith("plugin --help"));
+      assert.ok(registration.some((c) => c === "plugin install scratchplug@scratchmkt -y"));
+      assert.ok(registration.some((c) => c === "plugin update scratchplug -y"));
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("--dry-run plans the commands without spawning claude at all", () => {
+    const tmp = makeTmp();
+    const root = makeMarketplaceRoot();
+    const fake = makeFakeClaude(tmp);
+    try {
+      const result = registerClaude({ root, claudeBin: fake.bin, dryRun: true });
+      assert.equal(result.dryRun, true);
+      assert.deepEqual(
+        result.commands,
+        [
+          ["plugin", "marketplace", "add", root],
+          ["plugin", "install", "agent-cortex@jaybeeuu", "-y"],
+          ["plugin", "marketplace", "update", "jaybeeuu"],
+          ["plugin", "update", "agent-cortex", "-y"],
+        ],
+      );
+      // No registration spawns happened at all in dry-run mode.
+      assert.equal(existsSync(fake.log), false);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("defaults the claude binary to `claude` from PATH (dry-run only — no spawn)", () => {
+    const root = makeMarketplaceRoot();
+    try {
+      const result = registerClaude({ root, dryRun: true });
+      assert.equal(result.commands.length, 4);
+      assert.ok(result.commands[0][0] === "plugin");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("fails with upgrade guidance when the claude binary lacks the plugin subcommand", () => {
+    const tmp = makeTmp();
+    const root = makeMarketplaceRoot();
+    const fake = makeFakeClaude(tmp, { failWhen: "plugin --help" });
+    try {
+      assert.throws(
+        () => registerClaude({ root, claudeBin: fake.bin }),
+        /plugin.*subcommand.*update/i,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("fails, naming the failing command, when a claude plugin command errors", () => {
+    const tmp = makeTmp();
+    const root = makeMarketplaceRoot();
+    const fake = makeFakeClaude(tmp, { failWhen: "plugin install" });
+    try {
+      assert.throws(
+        () => registerClaude({ root, claudeBin: fake.bin }),
+        /claude plugin install agent-cortex@jaybeeuu -y/,
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("fails when the checkout has no marketplace manifest", () => {
+    const tmp = makeTmp();
+    const root = mkdtempSync(join(tmpdir(), "agent-cortex-no-market-"));
+    const fake = makeFakeClaude(tmp);
+    try {
+      assert.throws(
+        () => registerClaude({ root, claudeBin: fake.bin }),
+        /marketplace\.json/,
+      );
+      // The failed manifest read happens before any claude invocation.
+      assert.equal(existsSync(fake.log), false);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("works against the real repo checkout and its marketplace manifest", () => {
+    const tmp = makeTmp();
+    const fake = makeFakeClaude(tmp);
+    try {
+      const result = registerClaude({ root: ROOT, claudeBin: fake.bin });
+      assert.equal(result.marketplace, "jaybeeuu");
+      assert.equal(result.plugin, "agent-cortex");
+      const calls = readFileSync(fake.log, "utf-8").trim().split("\n");
+      const registration = calls.filter((c) => !c.startsWith("plugin --help"));
+      assert.equal(registration.length, 4);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── CLI wiring ───────────────────────────────────────────────────────────────
+
+describe("install claude CLI: registration", () => {
+  it("--dry-run without --output prints the registration plan and writes nothing", async () => {
+    const { exitCode, stdout } = await runCli(["install", "claude", "--dry-run"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("would run: claude plugin marketplace add"));
+    assert.ok(stdout.includes("claude plugin install agent-cortex@jaybeeuu"));
+    assert.ok(stdout.includes("claude plugin marketplace update jaybeeuu"));
+    assert.ok(stdout.includes("claude plugin update agent-cortex"));
+    assert.ok(/dry-run/i.test(stdout));
+  });
+
+  it("--output <dir> generates only — no registration plan is printed", async () => {
+    const out = mkdtempSync(join(tmpdir(), "agent-cortex-cli-out-"));
+    try {
+      const { exitCode, stdout } = await runCli(["install", "claude", "--output", out]);
+      assert.equal(exitCode, 0);
+      assert.doesNotMatch(stdout, /claude plugin/);
+      assert.ok(stdout.includes("Generated"));
+    } finally {
+      rmSync(out, { recursive: true, force: true });
+    }
+  });
+});

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