delegation-layer 0.1.2 → 0.1.4

package/README.md

@@ -1,129 +1,119 @@
 # Delegation Layer
 
-Delegation Layer runs one bounded turn of a supported AI command line tool as a
-durable, supervised local task. It records the request before submission,
-checks the executable and its capabilities at runtime, and publishes a
-validated result that can be collected later.
-
-> **Preview release**
->
-> The project publishes checksum-verified CLI releases and an npm package with
-> installers for the CLI and integration skill. The provider CLI and Pueue
-> remain host prerequisites.
-
-## What it does
-
-The `delegate` command accepts a finite brief, a canonical workspace, a
-permission mode, and a wall clock budget. It prepares a provider-specific
-launch profile, submits exactly one provider turn through Pueue, and stores
-immutable task records and output descriptors under a private state root.
-
-The companion `delegate-run` executable is started by the supervisor. It
-reconstructs the recorded profile, verifies that admission and launch still
-refer to the same executable, policy, workspace, and request, then captures and
-seals the provider result. A later `collect` call can recover a committed
-outcome without launching the provider again.
-
-## Requirements
-
-- Go 1.27.1 is needed only for source builds and the Homebrew formula.
-- Pueue 4.0.4 and a running `pueued` daemon using a private configuration.
-- A signed-in installation of one or more supported provider CLIs: `agy`,
-  `codex`, `claude`, `pi`, or `opencode`.
-- A Darwin or Linux host on amd64 or arm64 for the supplied build targets.
-  Provider availability is profile-specific; see the provider guide for native
-  platform prerequisites.
-- Node.js 18 or newer is needed for the npm and pnpm installers; Bun is needed
-  for the Bun installer.
-
-The provider executable must be available to the process that dispatches the
-task. Delegation Layer runs the provider's version and help commands before
-admission and accepts any reported version that is valid and advertises every
-flag required by the adapter. It does not pin a provider release or predeclared
-binary hash. A valid version here means nonempty trimmed UTF-8 output without control
-characters; it is not required to match a semantic-version pattern. The
-observed version is diagnostic evidence, while capability flags, executable
-identity, and provider behavior decide compatibility. No web release lookup or
-semver allowlist is used.
+<p align="center">
+  <a href="#install"><img src="docs/assets/delegation-layer-hero.jpg" alt="A lead AI model coordinating several specialist coding agents through Delegation Layer" width="1400"></a>
+</p>
+
+Give your lead AI agent a reliable way to delegate bounded coding work to the
+provider that fits the task.
+
+Delegation Layer is a local CLI and Agent Skill for supervising one finite turn
+of a coding agent, checking its capabilities at runtime, and returning a
+validated result with durable evidence. It works with the provider CLIs you
+already use instead of replacing them.
+
+## Why use it?
+
+- **One simple control layer** — your agent can discover providers and dispatch
+  work through one provider-neutral interface.
+- **Bounded by design** — every task has an explicit workspace, permission mode,
+  and time budget.
+- **Recoverable results** — a later `collect` call can read a finished task
+  without launching the provider again.
+- **Runtime compatibility** — the selected provider's executable and advertised
+  capabilities are checked when the task is prepared.
+- **Native authentication** — provider login stays with the provider CLI; task
+  state does not contain copied credentials.
+
+## How it works
+
+1. Install the Agent Skill so your harness knows how to use Delegation Layer.
+2. The lead agent discovers the available provider capabilities.
+3. Delegation Layer admits one bounded provider turn through the supervisor.
+4. The lead agent collects the sealed result and evidence.
 
 ## Install
 
-### Install the CLI
+### Install the Agent Skill
 
-The shell installer downloads the latest published release, verifies its
-checksum, and installs both `delegate` and `delegate-run` in
-`$HOME/.local/bin`:
+The standard Agent Skills installer works across popular coding agents. From
+the project where you want the skill available, run:
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/hishamkaram/delegation-layer/main/install.sh | sh
+npx --yes skills add hishamkaram/delegation-layer --skill agent-integration
 ```
 
-Set `DELEGATION_LAYER_INSTALL_DIR` if you want to install somewhere other than
-`$HOME/.local/bin`.
+The `--skill agent-integration` selection matters because this repository also
+contains maintainer skills. The installer detects supported agents and lets you
+choose the project or global scope. Add `--global` to install for all projects,
+or `--agent codex` (and similar agent names) to choose a specific harness.
 
-Homebrew installs the same two executables:
+If you want the Delegation Layer guided installer instead, run:
 
 ```sh
-brew install hishamkaram/tap/delegation-layer
+npx --yes delegation-layer install
 ```
 
-The npm package also provides a checksum-verified CLI installer through npm,
-pnpm, and Bun:
+It provides an interactive scope and harness picker, with global installation
+selected by default. For scripts or a choice without prompts:
 
 ```sh
-npx --yes delegation-layer install-cli
-pnpm dlx delegation-layer install-cli
-bunx --bun delegation-layer install-cli
+npx --yes delegation-layer install \
+  --scope project \
+  --harness universal \
+  --yes
 ```
 
-For a source build, install both Go commands from the latest version:
+The skill installer only installs guidance for your agent. It does not install
+the CLI, change provider logins, or configure a supervisor.
+
+### Install the CLI
+
+Use the prebuilt installer that fits your machine:
 
 ```sh
-go install github.com/hishamkaram/delegation-layer/cmd/delegate@latest
-go install github.com/hishamkaram/delegation-layer/cmd/delegate-run@latest
+curl -fsSL https://raw.githubusercontent.com/hishamkaram/delegation-layer/main/install.sh | sh
 ```
 
-Ensure the directory used by the installer or Go is on `PATH`.
-
-Confirm the installation:
+```sh
+brew install hishamkaram/tap/delegation-layer
+```
 
 ```sh
-delegate --help
-delegate providers --json
+npx --yes delegation-layer install-cli
+pnpm dlx delegation-layer install-cli
+bunx --bun delegation-layer install-cli
 ```
 
-### Install the agent integration skill
+The release installer verifies checksums and installs `delegate` and
+`delegate-run` into `$HOME/.local/bin` by default. Set
+`DELEGATION_LAYER_INSTALL_DIR` to use another directory.
 
-The provider-agnostic skill is separate from the CLI installation. Hermes can
-install the current skill directly:
+Check the installation:
 
 ```sh
-hermes skills install \
-  https://raw.githubusercontent.com/hishamkaram/delegation-layer/main/skills/agent-integration/SKILL.md
+delegate --help
+delegate providers --json
 ```
 
-Any harness with a writable skill directory can use the dependency-free npm,
-pnpm, or Bun installer:
+## What you need to run a task
 
-```sh
-npx --yes delegation-layer \
-  --target "$HOME/.hermes/skills/agent-integration"
-pnpm dlx delegation-layer \
-  --target "$HOME/.hermes/skills/agent-integration"
-bunx --bun delegation-layer \
-  --target "$HOME/.hermes/skills/agent-integration"
-```
+Normal users do not need Go or Node after choosing an installation method.
+Dispatching a task requires:
+
+- a released Delegation Layer CLI;
+- Pueue 4.0.4 with a private, running `pueued` daemon;
+- a signed-in supported provider CLI such as `agy`, `codex`, `claude`, `pi`,
+  or `opencode`;
+- Darwin or Linux on amd64 or arm64 for the supplied release builds.
 
-The default package command copies only `SKILL.md` into the target directory.
-The package's explicit `install-cli` command installs the CLI separately; it
-does not change the skill or configure Pueue or a provider CLI. Release tags
-and `DELEGATION_LAYER_VERSION` remain available when a deployment needs a
-reproducible version.
+Go is only needed for source builds and contributor work. Node.js 18 or newer
+is needed for the npm-based installers; it is not a runtime requirement for the
+released Go CLI. Provider authentication remains native to each provider.
 
-## Quick start
+## Try one bounded task
 
-Create a brief and a workspace outside the state root. Use an absolute path to
-the Pueue configuration that controls the private daemon:
+Create a brief and a workspace outside the private state root:
 
 ```sh
 mkdir -p "$HOME/delegation-workspace"
@@ -139,80 +129,35 @@ delegate --pueue-config /absolute/path/to/pueue.yml dispatch \
 ```
 
 The response contains a task ID and separate admission, liveness, and
-publication fields. Observe it with `status`, wait for a terminal publication,
-then read the validated result with `collect`:
+publication fields. Observe and collect it with:
 
 ```sh
 delegate status TASK_ID --json
 delegate collect TASK_ID --watch 5s --json
 ```
 
-Use the exact task ID printed by `dispatch`. A continuation is a new task that
-names its predecessor with `--resume-task`; it never silently reuses the most
-recent conversation.
-
-## Providers
-
-| Profile | Modes | Options |
-| --- | --- | --- |
-| `antigravity:print` | `workspace-write` | `continuation`, `native-timeout` |
-| `codex:exec` | `read-only`, `workspace-write` | `continuation` |
-| `claude:print` | `read-only`, `workspace-write` | `continuation` |
-| `pi:json` | `read-only` | `continuation`, `model`, `effort` |
-| `opencode:run` | `read-only`, `workspace-write` | `continuation`, `model`, `effort` |
-
-Run `delegate providers --json` for the compiled capability catalog. See
-[providers](docs/providers.md) for launch behavior, policy boundaries, and
-runtime compatibility checks.
-Use `delegate capabilities --provider PROFILE --json` for one provider's
-provider-neutral contract. Its catalog response is descriptive; dispatch is
-where the supervised runtime probe establishes host compatibility.
-
-When native logins are available, `make acceptance-native` runs the Pi and
-OpenCode live gates through a private supervisor. A pass exits `0`; an
-unavailable executable, supervisor, or login emits a sanitized `BLOCKED`
-receipt and exits `2`, which the aggregate target treats as neutral. Real
-behavior and evidence failures still fail the target.
-
-The catalog uses public request option names. The public `effort` option maps
-to Pi's native `--thinking` flag and OpenCode's native `--variant` flag.
-
-## Safety model
-
-- Every task has one immutable request and one provider turn.
-- State, workspace, provider runtime, and temporary directories are canonical
-  and kept disjoint where the selected policy requires it.
-- The supervisor owns process lifetime; the runner owns capture and sealing.
-- Admission and launch re-check executable identity, effective policy, and
-  session identity.
-- Briefs and control responses are bounded. Sealed payloads and raw streams are
-  described by validated paths, sizes, and SHA-256 digests.
-- Provider authentication remains native to the provider CLI. Delegation Layer
-  does not copy credentials into task state or rewrite account settings.
-
-Read [security](docs/security.md) for the full boundary and its operational
-limitations.
+Use `delegate providers --json` for the compiled provider catalog and
+`delegate capabilities --provider PROFILE --json` for a provider-neutral
+capability response. Dispatch still performs the host-specific runtime probe;
+catalog discovery alone does not prove authentication or supervisor readiness.
 
 ## Documentation
 
-- [Getting started](docs/getting-started.md) — install, configure, and run a
-  first task.
+- [Getting started](docs/getting-started.md) — install and run a first task.
 - [CLI reference](docs/cli-reference.md) — commands, flags, responses, and
   exit codes.
-- [Integration API](docs/api.md) — JSON responses, state semantics, and
-  idempotent client behavior.
-- [Provider guide](docs/providers.md) — supported profiles and compatibility
+- [Integration API](docs/api.md) — JSON responses and idempotent client
   behavior.
-- [Architecture](docs/architecture.md) — task lifecycle and ownership.
-- [System components](diagrams/components.html) — current Archify component map.
-- [Task lifecycle](diagrams/lead-interface.html) — current Archify sequence view.
+- [Provider guide](docs/providers.md) — profiles and runtime compatibility.
+- [Architecture](docs/architecture.md) — lifecycle and ownership boundaries.
+- [System components](diagrams/components.html) — interactive Archify view.
+- [Task lifecycle](diagrams/lead-interface.html) — interactive lifecycle view.
 - [Security](docs/security.md) — isolation, policy, and result integrity.
 - [Troubleshooting](docs/troubleshooting.md) — common setup and runtime
   failures.
-- [Contributing](docs/contributing.md) — development setup and adapter
-  extension guidance.
-- [Agent integration skill](skills/agent-integration/SKILL.md) — provider-neutral
-  JSON and evidence handling guidance for agents.
+- [Agent integration skill](skills/agent-integration/SKILL.md) — the
+  provider-neutral instructions installed into an agent harness.
+- [Contributing](CONTRIBUTING.md) — development and review guidance.
 
 ## License
 

package/package.json

@@ -1,13 +1,28 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.2",
-  "description": "Delegation Layer CLI and provider-agnostic agent skill installers.",
+  "version": "0.1.4",
+  "description": "Multi-provider AI agent delegation CLI and Agent Skill for running bounded coding tasks across provider CLIs.",
+  "keywords": [
+    "ai-agents",
+    "agent-skills",
+    "ai-orchestration",
+    "coding-agents",
+    "multi-agent",
+    "llm-orchestration",
+    "model-routing",
+    "delegation",
+    "developer-tools",
+    "cli",
+    "automation",
+    "golang"
+  ],
   "type": "module",
   "bin": {
     "delegation-layer": "scripts/install-agent-integration.mjs"
   },
   "files": [
     "LICENSE",
+    "docs/assets/delegation-layer-hero.jpg",
     "install.sh",
     "skills/agent-integration/SKILL.md",
     "scripts/install-agent-integration.mjs",

package/scripts/install-agent-integration.mjs

@@ -1,23 +1,116 @@
 #!/usr/bin/env node
 
+import { accessSync, constants } from "node:fs";
 import { copyFile, lstat, mkdir, readFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { emitKeypressEvents } from "node:readline";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const sourcePath = join(packageRoot, "skills", "agent-integration", "SKILL.md");
+const harnesses = [
+  {
+    name: "universal",
+    label: "Universal Agent Skills",
+    projectPath: join(".agents", "skills"),
+    globalPath: join(".agents", "skills"),
+    projectMarkers: [".agents"],
+    globalMarkers: [".agents"],
+    commands: [],
+  },
+  {
+    name: "codex",
+    label: "Codex",
+    projectPath: join(".agents", "skills"),
+    globalPath: join(".agents", "skills"),
+    projectMarkers: [".agents", ".codex"],
+    globalMarkers: [".agents", ".codex"],
+    commands: ["codex"],
+  },
+  {
+    name: "claude",
+    label: "Claude Code",
+    projectPath: join(".claude", "skills"),
+    globalPath: join(".claude", "skills"),
+    projectMarkers: [".claude"],
+    globalMarkers: [".claude"],
+    commands: ["claude"],
+  },
+  {
+    name: "cursor",
+    label: "Cursor",
+    projectPath: join(".cursor", "skills"),
+    globalPath: join(".cursor", "skills"),
+    projectMarkers: [".cursor"],
+    globalMarkers: [".cursor"],
+    commands: ["cursor"],
+  },
+  {
+    name: "gemini",
+    label: "Gemini CLI",
+    projectPath: join(".gemini", "skills"),
+    globalPath: join(".gemini", "skills"),
+    projectMarkers: [".gemini"],
+    globalMarkers: [".gemini"],
+    commands: ["gemini"],
+  },
+  {
+    name: "opencode",
+    label: "OpenCode",
+    projectPath: join(".opencode", "skills"),
+    globalPath: join(".config", "opencode", "skills"),
+    projectMarkers: [".opencode"],
+    globalMarkers: [join(".config", "opencode")],
+    commands: ["opencode"],
+  },
+  {
+    name: "pi",
+    label: "Pi",
+    projectPath: join(".pi", "skills"),
+    globalPath: join(".pi", "agent", "skills"),
+    projectMarkers: [".pi"],
+    globalMarkers: [join(".pi", "agent")],
+    commands: ["pi"],
+  },
+  {
+    name: "hermes",
+    label: "Hermes",
+    projectPath: join(".hermes", "skills"),
+    globalPath: join(".hermes", "skills"),
+    projectMarkers: [".hermes"],
+    globalMarkers: [".hermes"],
+    commands: ["hermes"],
+  },
+];
+const harnessByName = new Map(harnesses.map((harness) => [harness.name, harness]));
 
-function usage(message) {
+function usage(message, exitCode = 2) {
   if (message) {
     console.error(`Error: ${message}`);
   }
   console.error(
-    "Usage:\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
+    "Usage:\n  delegation-layer install [--scope project|global] [--harness NAME[,NAME...]] [--yes] [--force]\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
   );
-  process.exitCode = 2;
+  process.exitCode = exitCode;
 }
 
-function parseArguments(argumentsList) {
+function help() {
+  console.log(
+    "Usage:\n  delegation-layer install [--scope project|global] [--harness NAME[,NAME...]] [--yes] [--force]\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]\n\nThe install command detects supported agent harnesses and installs the skill for a project or user.\nGlobal scope is the default; use --scope project for a project-local install.\nUse --harness universal when no specific harness is detected.",
+  );
+}
+
+function requiredValue(argumentsList, index, option) {
+  const value = argumentsList[index + 1];
+  if (!value || value.startsWith("--")) {
+    usage(`${option} requires a value`);
+    return null;
+  }
+  return value;
+}
+
+function parseLegacyArguments(argumentsList) {
   let target;
   let force = false;
 
@@ -28,14 +121,15 @@ function parseArguments(argumentsList) {
       continue;
     }
     if (argument === "--target") {
-      target = argumentsList[index + 1];
+      target = requiredValue(argumentsList, index, "--target");
+      if (!target) {
+        return null;
+      }
       index += 1;
       continue;
     }
     if (argument === "--help" || argument === "-h") {
-      console.log(
-        "Usage:\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
-      );
+      help();
       process.exit(0);
     }
     usage(`unknown argument ${argument}`);
@@ -53,6 +147,63 @@ function parseArguments(argumentsList) {
   return { force, target: resolve(target) };
 }
 
+function parseInstallArguments(argumentsList) {
+  let force = false;
+  let harnessNames;
+  let scope;
+  let yes = false;
+
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === "--force") {
+      force = true;
+      continue;
+    }
+    if (argument === "--yes" || argument === "-y") {
+      yes = true;
+      continue;
+    }
+    if (argument === "--scope") {
+      scope = requiredValue(argumentsList, index, "--scope");
+      if (!scope) {
+        return null;
+      }
+      index += 1;
+      continue;
+    }
+    if (argument === "--harness") {
+      const value = requiredValue(argumentsList, index, "--harness");
+      if (!value) {
+        return null;
+      }
+      harnessNames = value.split(",").map((name) => name.trim().toLowerCase());
+      index += 1;
+      continue;
+    }
+    if (argument === "--help" || argument === "-h") {
+      help();
+      process.exit(0);
+    }
+    usage(`unknown argument ${argument}`);
+    return null;
+  }
+
+  if (scope && scope !== "project" && scope !== "global") {
+    usage("--scope must be project or global");
+    return null;
+  }
+  if (harnessNames?.length === 0 || harnessNames?.some((name) => !name)) {
+    usage("--harness requires at least one harness name");
+    return null;
+  }
+  if (harnessNames?.some((name) => !harnessByName.has(name))) {
+    const unknown = harnessNames.find((name) => !harnessByName.has(name));
+    usage(`unknown harness ${unknown}; choose from ${harnesses.map((harness) => harness.name).join(", ")}`);
+    return null;
+  }
+  return { force, harnessNames, scope, yes };
+}
+
 async function existingPath(path) {
   try {
     return await lstat(path);
@@ -64,6 +215,255 @@ async function existingPath(path) {
   }
 }
 
+function executableOnPath(command) {
+  const pathEntries = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const candidates = process.platform === "win32" ? [command, `${command}.exe`, `${command}.cmd`] : [command];
+  return pathEntries.some((pathEntry) =>
+    candidates.some((candidate) => {
+      try {
+        accessSync(join(pathEntry, candidate), constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    }),
+  );
+}
+
+async function detectHarnesses({ cwd, home }) {
+  return Promise.all(
+    harnesses.map(async (harness) => {
+      const reasons = [];
+      for (const marker of harness.projectMarkers) {
+        const markerPath = resolve(cwd, marker);
+        if ((await existingPath(markerPath))?.isDirectory()) {
+          reasons.push(`project ${marker}`);
+          break;
+        }
+      }
+      for (const marker of harness.globalMarkers) {
+        const markerPath = resolve(home, marker);
+        if ((await existingPath(markerPath))?.isDirectory()) {
+          reasons.push(`global ${marker}`);
+          break;
+        }
+      }
+      for (const command of harness.commands) {
+        if (executableOnPath(command)) {
+          reasons.push(`${command} on PATH`);
+          break;
+        }
+      }
+      return { harness, reasons };
+    }),
+  );
+}
+
+function defaultHarnessNames(detections) {
+  const detected = detections
+    .filter(({ harness, reasons }) => harness.name !== "universal" && reasons.length > 0)
+    .map(({ harness }) => harness.name);
+  if (detected.length > 0) {
+    return detected;
+  }
+  return ["universal"];
+}
+
+function formatDetected(reasons) {
+  return reasons.length > 0 ? ` (detected: ${reasons.join(", ")})` : "";
+}
+
+function printDetections(detections) {
+  console.log("Detected harnesses:");
+  detections.forEach(({ harness, reasons }, index) => {
+    console.log(`  ${index + 1}. ${harness.label}${formatDetected(reasons)}`);
+  });
+}
+
+function renderPicker({ error, index, multiple, options, selected, title }) {
+  const lines = [title, ""];
+  options.forEach((option, optionIndex) => {
+    const current = optionIndex === index;
+    const marker = multiple ? (selected.has(option.value) ? "[x]" : "[ ]") : "";
+    const cursor = current ? "❯" : " ";
+    const color = current ? "\u001b[36m" : "";
+    const reset = current ? "\u001b[0m" : "";
+    lines.push(`${color}${cursor} ${marker ? `${marker} ` : ""}${option.label}${reset}`);
+    if (option.description) {
+      lines.push(`      ${option.description}`);
+    }
+  });
+  lines.push("");
+  lines.push(multiple ? "↑↓ move  Space select  Enter continue  a all  n none  q cancel" : "↑↓ move  Enter select  q cancel");
+  if (error) {
+    lines.push(`\u001b[31m${error}\u001b[0m`);
+  }
+  process.stdout.write(`\u001b[2J\u001b[H${lines.join("\n")}\n`);
+}
+
+function pickOptions({ initialValues = [], multiple = false, options, title }) {
+  const input = process.stdin;
+  const output = process.stdout;
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") {
+    return null;
+  }
+
+  let index = 0;
+  const selected = new Set(initialValues);
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let error;
+
+    const cleanup = () => {
+      input.off("keypress", onKeypress);
+      try {
+        input.setRawMode(false);
+      } catch {
+        // The terminal may already be closed while handling cancellation.
+      }
+      input.pause();
+      output.write("\u001b[?25h\u001b[0m");
+    };
+
+    const finish = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+
+    const onKeypress = (character, key = {}) => {
+      if ((key.ctrl && key.name === "c") || key.name === "escape" || key.name === "q") {
+        finish(null);
+        return;
+      }
+      if (key.name === "up" || key.name === "k") {
+        index = (index + options.length - 1) % options.length;
+        error = undefined;
+        renderPicker({ error, index, multiple, options, selected, title });
+        return;
+      }
+      if (key.name === "down" || key.name === "j") {
+        index = (index + 1) % options.length;
+        error = undefined;
+        renderPicker({ error, index, multiple, options, selected, title });
+        return;
+      }
+      if (multiple && (key.name === "space" || character === " ")) {
+        const value = options[index].value;
+        if (selected.has(value)) {
+          selected.delete(value);
+        } else {
+          selected.add(value);
+        }
+        error = undefined;
+        renderPicker({ error, index, multiple, options, selected, title });
+        return;
+      }
+      if (multiple && key.name === "a") {
+        options.forEach((option) => selected.add(option.value));
+        error = undefined;
+        renderPicker({ error, index, multiple, options, selected, title });
+        return;
+      }
+      if (multiple && key.name === "n") {
+        selected.clear();
+        error = undefined;
+        renderPicker({ error, index, multiple, options, selected, title });
+        return;
+      }
+      if (key.name === "return" || key.name === "enter") {
+        if (multiple && selected.size === 0) {
+          error = "Select at least one harness, or press q to cancel.";
+          renderPicker({ error, index, multiple, options, selected, title });
+          return;
+        }
+        finish(multiple ? options.filter((option) => selected.has(option.value)).map((option) => option.value) : options[index].value);
+      }
+    };
+
+    try {
+      emitKeypressEvents(input);
+      input.setRawMode(true);
+      input.resume();
+      input.on("keypress", onKeypress);
+      output.write("\u001b[?25l");
+      renderPicker({ error, index, multiple, options, selected, title });
+    } catch (pickerError) {
+      cleanup();
+      reject(pickerError);
+    }
+  });
+}
+
+async function chooseInstallOptions({ force, harnessNames, scope, yes }) {
+  const cwd = process.cwd();
+  const home = resolve(process.env.DELEGATION_LAYER_HOME ?? homedir());
+  const detections = await detectHarnesses({ cwd, home });
+  const defaults = defaultHarnessNames(detections);
+  const canPrompt = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const needsPrompt = !yes && !harnessNames && !scope && canPrompt;
+
+  if (!harnessNames && !needsPrompt) {
+    printDetections(detections);
+  }
+  if (!canPrompt && !yes && !harnessNames && !scope) {
+    console.log("No interactive terminal detected; using global scope and detected harnesses.");
+  }
+
+  if (needsPrompt) {
+    scope = await pickOptions({
+      initialValues: ["global"],
+      options: [
+        {
+          value: "global",
+          label: "Global",
+          description: `available to your agents from ${home}`,
+        },
+        {
+          value: "project",
+          label: "Project",
+          description: `available to this project from ${cwd}`,
+        },
+      ],
+      title: "Where should the agent skill be installed?",
+    });
+    if (!scope) {
+      return null;
+    }
+    harnessNames = await pickOptions({
+      initialValues: defaults,
+      multiple: true,
+      options: detections.map(({ harness, reasons }) => ({
+        value: harness.name,
+        label: `${harness.label}${formatDetected(reasons)}`,
+        description: targetFor(harness, scope, cwd, home),
+      })),
+      title: "Which harnesses should use the skill?",
+    });
+    if (!harnessNames) {
+      return null;
+    }
+  }
+
+  return {
+    cwd,
+    force,
+    harnessNames: harnessNames ?? defaults,
+    home,
+    scope: scope ?? "global",
+  };
+}
+
+function targetFor(harness, scope, cwd, home) {
+  const root = scope === "global" ? home : cwd;
+  const relativePath = scope === "global" ? harness.globalPath : harness.projectPath;
+  return join(resolve(root, relativePath), "agent-integration");
+}
+
 async function install({ force, target }) {
   const targetStat = await existingPath(target);
   if (targetStat?.isSymbolicLink()) {
@@ -109,8 +509,28 @@ if (argumentsList[0] === "install-cli") {
     console.error(`Error: ${error.message}`);
     process.exitCode = 1;
   }
+} else if (argumentsList[0] === "install") {
+  const options = parseInstallArguments(argumentsList.slice(1));
+  if (options) {
+    try {
+      const selected = await chooseInstallOptions(options);
+      if (!selected) {
+        console.log("Installation cancelled.");
+      } else {
+        const targets = selected.harnessNames.map((name) => targetFor(harnessByName.get(name), selected.scope, selected.cwd, selected.home));
+        const uniqueTargets = [...new Set(targets)];
+        console.log(`Installing for ${selected.scope}: ${uniqueTargets.join(", ")}`);
+        for (const target of uniqueTargets) {
+          await install({ force: selected.force, target });
+        }
+      }
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
 } else {
-  const options = parseArguments(argumentsList);
+  const options = parseLegacyArguments(argumentsList);
   if (options) {
     try {
       await install(options);