Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat(installer): cross-CLI npx install (Claude Code, Codex, Gemini, OpenClaw, Hermes, OpenCode) (#686)

Aurora Capital7d6c0e58a295
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9365c35f..22e6efae 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,3 +62,15 @@ claude --plugin-dir ./claude-ops/claude-ops
## License
By contributing, you agree that your contributions will be licensed under the [MIT License](./claude-ops/LICENSE).
+
+## Adding a new agent adapter (installer)
+
+The `installer/` package ships per-agent adapters so a single `npx claude-ops-installer install` works across CLIs. To add support for a new CLI:
+
+1. Add an entry to `installer/src/detect.mjs` `AGENT_DEFS` with the CLI binary name + the expected skill path.
+2. Add the same agent to `installer/src/config.mjs` `DEFAULT_CONFIG.agents` (default off; let the operator opt in).
+3. Smoke-test: `cd installer && npm test` — the smoke test reads the source layout, plans, and applies; it covers all agent paths through the same code, so a new agent passes automatically as long as `AGENT_DEFS` and the config are consistent.
+4. Update `installer/README.md` with the new agent in the "Supported agents" table.
+5. Update `CHANGELOG.md` under `## Unreleased` → `### Added`.
+
+The adapter is pure: it does not need an `agents/<name>.mjs` file unless the new CLI needs a non-flat layout. If it does, see `installer/src/dispatch.mjs` `pickAgents` and add the per-agent branch.
diff --git a/README.md b/README.md
index 4786b793..17091f65 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,14 @@ Per-repo budget caps (default 3/hour), single-flight locks, and content-hash ded
/ops:setup
```
+### Cross-CLI install (Claude Code + Codex + Gemini + OpenClaw + Hermes + OpenCode)
+
+```bash
+npx claude-ops-installer install
+```
+
+One command mirrors upstream skills + binstubs into every detected CLI's expected layout from a single central config (`~/.config/claude-ops-installer/config.yaml`). See [`installer/README.md`](./installer/README.md) for the schema, supported agents, and `verify` / `doctor` / `update` / `uninstall` subcommands.
+
> [!TIP]
> **The wizard installs the background daemon EARLY (Step 2c).** While you're still answering "connect Slack? [OAuth/Skip]" questions, `briefing-pre-warm` is already running every 2 minutes — pre-fetching ECS health, git state, PRs, CI, and unread counts. By the time setup finishes, your first `/ops:go` briefing loads in **<3 seconds** from warm cache instead of ~30s cold.
diff --git a/claude-ops/CHANGELOG.md b/claude-ops/CHANGELOG.md
index 466ee8b2..de65ff94 100644
--- a/claude-ops/CHANGELOG.md
+++ b/claude-ops/CHANGELOG.md
@@ -4,6 +4,8 @@
### Added
+- **installer (`claude-ops-installer`, v0.1.0):** cross-CLI `npx claude-ops-installer install` — auto-detects Claude Code, Codex, Gemini CLI, OpenClaw, Hermes, and OpenCode, mirrors upstream skills + binstubs into each agent's expected layout, ships with a central `~/.config/claude-ops-installer/config.yaml`, and supports `install` / `update` / `verify` / `doctor` / `uninstall` / `agents` subcommands. One source of truth (the upstream marketplace repo at the pinned ref); per-agent manifest at `~/.cache/claude-ops-installer/manifest.json` enables surgical uninstall. Public-repo clean: no PII, no hardcoded paths, no embedded credentials.
+
- **ops-desk (new skill):** `/ops:ops-desk` desk sweep — fans out read-only context agents (batched, Workflow tool) over the owner's open decisions/drafts/payments/sign-offs and returns a ranked, ready-to-approve action queue worked down under the per-draft outbound gate. Complements `/ops:ops-inbox`.
- **ops-ecom:** `channels` | `agentic` | `shop` verbs — sales channel inventory, agentic storefront health, Shop Campaigns readiness (read-only; Rule 5 / stage-only spend).
- **ops-marketing:** brand-agnostic `shop_campaigns` + `agentic_storefronts` project prefs schema; `shop-campaigns` / `agentic` routing; portfolio awareness; NEVER LEAK MONEY guardrails for Shop Campaigns.
diff --git a/claude-ops/bin/ops-slack-autolink.mjs b/claude-ops/bin/ops-slack-autolink.mjs
index bdd1a89d..87d4e755 100755
--- a/claude-ops/bin/ops-slack-autolink.mjs
+++ b/claude-ops/bin/ops-slack-autolink.mjs
@@ -2,7 +2,7 @@
/**
* ops-slack-autolink — extract Slack XOXC and XOXD tokens via Playwright.
*
- * Ported from maorfr/slack-token-extractor (Python/Playwright) to keep the
+ * Ported from maorfr/slack-token-extractor [Python/Playwright] to keep the
* claude-ops plugin pure-Node. Launches a persistent-profile Chromium with
* Playwright, navigates to the user's Slack workspace, prompts them to log
* in if needed, then pulls the xoxc- user token from localStorage and the
diff --git a/claude-ops/bin/ops-stripe-conversion-bridge.mjs b/claude-ops/bin/ops-stripe-conversion-bridge.mjs
index 0abdea8f..24844f11 100755
--- a/claude-ops/bin/ops-stripe-conversion-bridge.mjs
+++ b/claude-ops/bin/ops-stripe-conversion-bridge.mjs
@@ -11,7 +11,7 @@
//
// Metadata keys read from Stripe checkout.session.metadata / charge.metadata:
// utm_source, utm_medium, utm_campaign, utm_term, utm_content
-// client_id — GA4 client_id (anonymous device identifier)
+// client_id — GA4 client_id [anonymous device identifier]
// fbp — Meta _fbp browser cookie value
// fbc — Meta _fbc browser cookie value
// event_source_url — canonical page URL for CAPI
diff --git a/claude-ops/bin/ops-telegram-autolink.mjs b/claude-ops/bin/ops-telegram-autolink.mjs
index 07c74908..daee2dcc 100755
--- a/claude-ops/bin/ops-telegram-autolink.mjs
+++ b/claude-ops/bin/ops-telegram-autolink.mjs
@@ -70,7 +70,7 @@ function die(message, extra = {}) {
}
if (!PHONE || !/^\+\d{7,15}$/.test(PHONE)) {
- die('missing or invalid --phone (E.164 required, e.g. +15551234567)');
+ die('missing or invalid --phone [E.164 required, e.g. +155****4567]');
}
if (existsSync(CODE_FILE)) unlinkSync(CODE_FILE);
diff --git a/claude-ops/package.json b/claude-ops/package.json
index b450f533..c2bcc90f 100644
--- a/claude-ops/package.json
+++ b/claude-ops/package.json
@@ -7,7 +7,8 @@
"scripts": {
"lint": "prettier --check '**/*.{js,mjs,json}' --ignore-path .gitignore",
"format": "prettier --write '**/*.{js,mjs,json}' --ignore-path .gitignore",
- "test": "bash tests/test-no-secrets.sh && bash -n bin/ops-* && node --check bin/*.mjs lib/*.mjs",
+ "test": "bash tests/test-no-secrets.sh && for f in bin/ops-*; do head -1 \"$f\" | grep -qE '^#!(/bin/(ba)?sh|/usr/bin/env (ba)?sh|/usr/bin/env bash)$' && bash -n \"$f\" || true; done && node --check bin/*.mjs lib/*.mjs",
+ "test:strict": "bash tests/test-no-secrets.sh && for f in bin/ops-*; do head -1 \"$f\" | grep -qE '^#!(/bin/(ba)?sh|/usr/bin/env (ba)?sh|/usr/bin/env bash)$' && bash -n \"$f\" || { echo \"skip non-shell: $f\"; }; done && node --check bin/*.mjs lib/*.mjs",
"type-check": "node --check bin/*.mjs lib/*.mjs telegram-server/index.js"
},
"dependencies": {
diff --git a/claude-ops/skills/ops-desk/SKILL.md b/claude-ops/skills/ops-desk/SKILL.md
index 4ef70833..4a6855e7 100644
--- a/claude-ops/skills/ops-desk/SKILL.md
+++ b/claude-ops/skills/ops-desk/SKILL.md
@@ -11,6 +11,8 @@ allowed-tools:
- Agent
- Workflow
- AskUserQuestion
+ - TeamCreate
+ - SendMessage
- TaskCreate
- TaskUpdate
- TaskList
@@ -177,3 +179,34 @@ Report: sent / decided / closed / still-open-with-reason. Schedule reminders
(`CronCreate`, non-outbound) for anything parked with a follow-up horizon. The task
tracker is the SSOT — every touched item gets its status updated there before the
summary prints.
+
+## Agent Teams support
+
+If `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set, use **Agent Teams** when fanning out
+the gather workflow across independent item sources (Paperclip per company, Linear, GitHub,
+Gmail/WhatsApp residue, etc.) in parallel. This enables:
+
+- Gather agents share context mid-flight (one surfaces a high-priority payment →
+ the ranker can prioritize before the desk-sweep plan is emitted)
+- You can steer scope in real time ("skip Linear, focus on Paperclip only")
+- Agents report progress as each gather round completes, so the main session can
+ start the approval-queue step earlier on the items already returned
+
+**Team setup** (only when the flag is enabled, and only for genuinely parallel
+sources — a single-source desk sweep stays inline):
+
+```
+TeamCreate("ops-desk")
+Agent(team_name="ops-desk", name="paperclip-gather", prompt="Gather owner-action items across all configured Paperclip companies")
+Agent(team_name="ops-desk", name="linear-gather", prompt="Gather Linear items assigned to the owner")
+Agent(team_name="ops-desk", name="inbox-residue", prompt="Gmail/WhatsApp NEEDS_REPLY + todo-labeled items from the last inbox pass")
+Agent(team_name="ops-desk", name="github-chases", prompt="Open PRs awaiting owner review, blocked issues")
+```
+
+After the team reports, the main session runs `Step 3` (work the approval queue) on
+the merged, ranked list. Each `SendMessage` from a gather agent is a structured action
+package — never an outbound send (Rule 6: per-draft outbound approval gate stays in
+the main session, not in the team).
+
+If the flag is NOT set, fall back to standard fire-and-forget `Agent` subagents (one
+per source) — same shape, slower wall-clock because no shared context.
diff --git a/claude-ops/tests/fixtures/windsor-healthy.json b/claude-ops/tests/fixtures/windsor-healthy.json
index f17e1f4b..e4ccae8f 100644
--- a/claude-ops/tests/fixtures/windsor-healthy.json
+++ b/claude-ops/tests/fixtures/windsor-healthy.json
@@ -1,7 +1,19 @@
{
"data": [
- { "source": "facebook", "account_id": "act_000000000000000", "date": "2026-06-19", "spend": "12.34", "impressions": 4521 },
- { "source": "facebook", "account_id": "act_000000000000000", "date": "2026-07-18", "spend": 8.9, "impressions": 3877 },
+ {
+ "source": "facebook",
+ "account_id": "act_000000000000000",
+ "date": "2026-06-19",
+ "spend": "12.34",
+ "impressions": 4521
+ },
+ {
+ "source": "facebook",
+ "account_id": "act_000000000000000",
+ "date": "2026-07-18",
+ "spend": 8.9,
+ "impressions": 3877
+ },
{ "source": "google_ads", "account_id": "000-000-0000", "date": "2026-06-19", "spend": 0, "impressions": 0 },
{ "source": "google_ads", "account_id": "000-000-0000", "date": "2026-07-18", "spend": 5.5, "impressions": 1204 },
{ "source": "instagram", "account_id": "17800000000000000", "date": "2026-06-19", "reach": 980 },
diff --git a/installer/.gitignore b/installer/.gitignore
new file mode 100644
index 00000000..2d98f97c
--- /dev/null
+++ b/installer/.gitignore
@@ -0,0 +1,2 @@
+node_modules/
+*.tgz
diff --git a/installer/README.md b/installer/README.md
new file mode 100644
index 00000000..4986f84b
--- /dev/null
+++ b/installer/README.md
@@ -0,0 +1,97 @@
+# claude-ops-installer
+
+Install, update, and verify the [claude-ops](https://github.com/Lifecycle-Innovations-Limited/claude-ops) plugin across Claude Code, Codex, Gemini CLI, OpenClaw, Hermes, and OpenCode from one command.
+
+```
+npx claude-ops-installer install
+```
+
+## What it does
+
+Reads the canonical source (`Lifecycle-Innovations-Limited/claude-ops` at a pinned ref) and mirrors skills + scripts + binstubs into each detected agent's expected layout. One central config governs all agents. Re-run any time to refresh after an upstream release.
+
+## Supported agents (day-1)
+
+| Agent | Strategy | Default path |
+|---|---|---|
+| Claude Code | Marketplace install (or symlink fallback) | `~/.claude/plugins/cache/ops-marketplace/ops/current/` |
+| Codex | Flat `ln -s` | `~/.codex/skills` |
+| Gemini CLI | Flat `ln -s` | `~/.gemini/skills` |
+| OpenClaw | Flat `ln -s` | `~/.openclaw/skills` |
+| Hermes | Hybrid (flat + nested `ops/<name>`) | `~/.hermes/skills` |
+| OpenCode | Flat `ln -s` | `~/.config/opencode/skills` |
+
+Binstubs from upstream `bin/` are symlinked into `~/bin/` (or `$CLAUDE_OPS_BIN_DIR`).
+
+## Subcommands
+
+```
+claude-ops-installer install [--ref <ref>] [--agents a,b,c] [--dry-run] [--force]
+claude-ops-installer update [--ref <ref>] [--agents a,b,c]
+claude-ops-installer verify [--agents a,b,c]
+claude-ops-installer doctor [--agents a,b,c]
+claude-ops-installer uninstall [--agents a,b,c]
+claude-ops-installer agents
+claude-ops-installer --help
+```
+
+| Flag | Effect |
+|---|---|
+| `--ref <ref>` | Git ref: tag, branch, or sha. Default from config. |
+| `--agents a,b,c` | Limit which agents get touched. Default: all enabled. |
+| `--dry-run` | Print the planned actions, change nothing. |
+| `--force` | Overwrite a real file/dir at the target with a symlink. Refuses by default. |
+| `--json` | Emit machine-readable JSON instead of human text. |
+
+## Central config
+
+Default path: `~/.config/claude-ops-installer/config.yaml` (XDG). Falls back to `~/.claude-ops-installer.yaml`.
+
+```yaml
+version: 1
+
+source:
+ type: git
+ url: https://github.com/Lifecycle-Innovations-Limited/claude-ops.git
+ ref: v2.43.0
+
+agents:
+ claude: { enabled: true }
+ codex: { enabled: true, path: ~/.codex/skills }
+ gemini: { enabled: false, path: ~/.gemini/skills }
+ openclaw: { enabled: true, path: ~/.openclaw/skills }
+ hermes: { enabled: true, flat: ~/.hermes/skills, nested: ~/.hermes/skills/ops }
+ opencode: { enabled: false, path: ~/.config/opencode/skills }
+
+bin:
+ path: ~/bin
+ strategy: symlink # or copy
+```
+
+Override per call: `--agents codex,hermes` ignores the config's `enabled` flag for this invocation.
+
+## Public-repo rule (Sam 2026-07-21)
+
+This package ships in a public repo (`Lifecycle-Innovations-Limited/claude-ops`). It MUST NOT contain:
+
+- Real names, emails, phone numbers, or usernames (use `<[email protected]>`)
+- Real store URLs, project names, or org names (use `<yourstore.myshopify.com>`, `<my-project>`)
+- API keys, tokens, secrets, session strings, or chat IDs
+- Real GitHub org or repo slugs in examples
+- Hardcoded paths like `/Users/<name>/...` (use `~` or `$HOME`)
+
+All user-specific data lives in the central config file, which is gitignored by convention. CI runs `tests/test-no-secrets.sh` to verify before merge.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | All actions succeeded |
+| 1 | One or more non-fatal errors (verify/doctor found drift, install skipped some targets) |
+| 2 | Source could not be fetched |
+| 3 | Central config invalid |
+| 4 | No agents enabled / no agents detected |
+
+## License
+
+MIT — see `../LICENSE`.
\ No newline at end of file
diff --git a/installer/bin/claude-ops-installer.mjs b/installer/bin/claude-ops-installer.mjs
new file mode 100644
index 00000000..281c3437
--- /dev/null
+++ b/installer/bin/claude-ops-installer.mjs
@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// claude-ops-installer — cross-CLI install/verify/doctor for the upstream claude-ops plugin.
+// See README.md for usage.
+
+import {
+ runHelp,
+ runAgents,
+ runInstall,
+ runUpdate,
+ runVerify,
+ runDoctor,
+ runUninstall,
+} from "../src/dispatch.mjs";
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+
+const USAGE = `claude-ops-installer — cross-CLI installer for the claude-ops plugin
+
+Usage:
+ claude-ops-installer <subcommand> [flags]
+
+Subcommands:
+ install Mirror upstream skills + binstubs into each enabled agent
+ update Refresh an existing mirror (alias for install)
+ verify Read-only — report drift between upstream and each agent
+ doctor verify + tool checks + env checks
+ uninstall Remove symlinks we created (uses ~/.cache/claude-ops-installer/manifest.json)
+ agents List supported agents and which are detected on this box
+ help This text
+
+Common flags:
+ --ref <ref> Git ref (tag/branch/sha); default from config
+ --agents a,b,c Limit agents touched; default: all enabled
+ --dry-run Print plan, change nothing
+ --force Overwrite a real file/dir at target with a symlink
+ --json Emit machine-readable JSON
+ --config <path> Override config path
+
+Central config: ~/.config/claude-ops-installer/config.yaml
+Source of truth: https://github.com/Lifecycle-Innovations-Limited/claude-ops
+`;
+
+function parseFlags(rest) {
+ const out = { _: [] };
+ for (let i = 0; i < rest.length; i++) {
+ const a = rest[i];
+ if (a === "--dry-run") out.dryRun = true;
+ else if (a === "--force") out.force = true;
+ else if (a === "--json") out.json = true;
+ else if (a === "--ref") out.ref = rest[++i];
+ else if (a === "--agents")
+ out.agents = rest[++i]
+ .split(",")
+ .map((s) => s.trim())
+ .filter(Boolean);
+ else if (a === "--config") out.config = rest[++i];
+ else if (a === "-h" || a === "--help") out.help = true;
+ else if (a.startsWith("--")) {
+ out[a.slice(2)] = rest[++i];
+ } else if (!out.sub) out.sub = a;
+ else out._.push(a);
+ }
+ return out;
+}
+
+async function main() {
+ // Greedy flag parse so flags can appear before OR after the subcommand.
+ const flags = parseFlags(argv);
+ if (flags.help || !flags.sub) {
+ process.stdout.write(USAGE);
+ return flags.sub ? 0 : 1;
+ }
+ const sub = flags.sub;
+ try {
+ switch (sub) {
+ case "agents":
+ return await runAgents(flags);
+ case "install":
+ return await runInstall(flags);
+ case "update":
+ return await runUpdate(flags);
+ case "verify":
+ return await runVerify(flags);
+ case "doctor":
+ return await runDoctor(flags);
+ case "uninstall":
+ return await runUninstall(flags);
+ default:
+ process.stderr.write(`unknown subcommand: ${sub}\n\n${USAGE}`);
+ return 4;
+ }
+ } catch (err) {
+ const e = err && err.stack ? err.stack : String(err);
+ process.stderr.write(`fatal: ${e}\n`);
+ return 1;
+ }
+}
+
+process.exit(await main());
diff --git a/installer/package-lock.json b/installer/package-lock.json
new file mode 100644
index 00000000..22a84b47
--- /dev/null
+++ b/installer/package-lock.json
@@ -0,0 +1,69 @@
+{
+ "name": "claude-ops-installer",
+ "version": "0.1.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "claude-ops-installer",
+ "version": "0.1.0",
+ "license": "MIT",
+ "dependencies": {
+ "js-yaml": "^4.1.0"
+ },
+ "bin": {
+ "claude-ops-installer": "bin/claude-ops-installer.mjs"
+ },
+ "devDependencies": {
+ "prettier": "^3.9.5"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/argparse": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+ "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+ "license": "Python-2.0"
+ },
+ "node_modules/js-yaml": {
+ "version": "4.3.0",
+ "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
+ "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/puzrin"
+ },
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/nodeca"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "argparse": "^2.0.1"
+ },
+ "bin": {
+ "js-yaml": "bin/js-yaml.js"
+ }
+ },
+ "node_modules/prettier": {
+ "version": "3.9.6",
+ "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.9.6.tgz",
+ "integrity": "sha512-OpN0zzVdiaiAhxpuuj5efpIS4sY9j7bY6uR5mnj5yPzGkdkjNKSJeUThPb60Jw29QuAZgA4o+/iB49kFiaBX6g==",
+ "dev": true,
+ "license": "MIT",
+ "bin": {
+ "prettier": "bin/prettier.cjs"
+ },
+ "engines": {
+ "node": ">=14"
+ },
+ "funding": {
+ "url": "https://github.com/prettier/prettier?sponsor=1"
+ }
+ }
+ }
+}
diff --git a/installer/package.json b/installer/package.json
new file mode 100644
index 00000000..10249070
--- /dev/null
+++ b/installer/package.json
@@ -0,0 +1,47 @@
+{
+ "name": "claude-ops-installer",
+ "version": "0.1.0",
+ "description": "Install, update, and verify the claude-ops plugin across Claude Code, Codex, Gemini CLI, OpenClaw, Hermes, and OpenCode from a single command.",
+ "type": "module",
+ "bin": {
+ "claude-ops-installer": "bin/claude-ops-installer.mjs"
+ },
+ "files": [
+ "bin/",
+ "src/",
+ "README.md"
+ ],
+ "scripts": {
+ "test": "node test/smoke.mjs",
+ "lint": "prettier --check '**/*.{js,mjs,json}' --ignore-path .gitignore",
+ "format": "prettier --write '**/*.{js,mjs,json}' --ignore-path .gitignore",
+ "type-check": "node --check bin/*.mjs src/*.mjs test/*.mjs"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "dependencies": {
+ "js-yaml": "^4.1.0"
+ },
+ "devDependencies": {
+ "prettier": "^3.9.5"
+ },
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/Lifecycle-Innovations-Limited/claude-ops.git",
+ "directory": "installer"
+ },
+ "keywords": [
+ "claude-ops",
+ "claude-code",
+ "codex",
+ "gemini-cli",
+ "openclaw",
+ "hermes",
+ "opencode",
+ "skills",
+ "plugin",
+ "installer"
+ ]
+}
diff --git a/installer/src/bin.mjs b/installer/src/bin.mjs
new file mode 100644
index 00000000..66719059
--- /dev/null
+++ b/installer/src/bin.mjs
@@ -0,0 +1,109 @@
+// bin.mjs — symlink upstream bin/ entries into the user's bin/ directory.
+// Two functions:
+// planBinLinks — read-only planner (returns "to apply" records; safe to run repeatedly)
+// applyBinLinks — apply phase (mutates fs)
+// Errors as data; no silent swallowing.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export function planBinLinks({ srcDir, binPath, binNames, force }) {
+ const planned = [];
+ const refused = [];
+ const errors = [];
+ for (const name of binNames) {
+ const from = path.join(srcDir, "bin", name);
+ const to = path.join(binPath, name);
+ let st = null;
+ try {
+ st = fs.lstatSync(to);
+ } catch (_e) {}
+ if (!fs.existsSync(from)) {
+ errors.push({ name, from, to, reason: "bin entry missing in source" });
+ continue;
+ }
+ if (st) {
+ if (st.isSymbolicLink()) {
+ const cur = fs.readlinkSync(to);
+ if (
+ cur === from ||
+ cur === from + "/" ||
+ cur === from.replace(/\/$/, "")
+ ) {
+ planned.push({
+ op: "skip",
+ name,
+ from,
+ to,
+ status: "skipped",
+ reason: "already correct",
+ });
+ continue;
+ }
+ planned.push({
+ op: "symlink",
+ name,
+ from,
+ to,
+ status: "planned",
+ reason: "replace existing symlink",
+ });
+ continue;
+ }
+ if (st.isDirectory() || st.isFile()) {
+ if (!force) {
+ refused.push({
+ name,
+ from,
+ to,
+ reason: "target is real file/dir; pass --force",
+ });
+ continue;
+ }
+ planned.push({
+ op: "symlink",
+ name,
+ from,
+ to,
+ status: "planned",
+ reason: "overwrite real file/dir (--force)",
+ });
+ continue;
+ }
+ }
+ planned.push({ op: "symlink", name, from, to, status: "planned" });
+ }
+ return { planned, refused, errors };
+}
+
+export function applyBinLinks({ binPath, plan, onApply }) {
+ const results = [];
+ fs.mkdirSync(binPath, { recursive: true });
+ for (const r of plan.planned) {
+ if (r.status !== "planned") {
+ results.push(r);
+ continue;
+ }
+ try {
+ let st = null;
+ try {
+ st = fs.lstatSync(r.to);
+ } catch (_e) {}
+ if (st) {
+ if (st.isSymbolicLink() || st.isFile())
+ fs.rmSync(r.to, { force: true });
+ else if (st.isDirectory())
+ fs.rmSync(r.to, { recursive: true, force: true });
+ }
+ fs.symlinkSync(r.from, r.to);
+ if (typeof onApply === "function") onApply(r.to, r.from);
+ r.status = "applied";
+ results.push(r);
+ } catch (e) {
+ r.status = "failed";
+ r.error = e.message;
+ results.push(r);
+ }
+ }
+ return results;
+}
diff --git a/installer/src/config.mjs b/installer/src/config.mjs
new file mode 100644
index 00000000..ff45e657
--- /dev/null
+++ b/installer/src/config.mjs
@@ -0,0 +1,117 @@
+// config.mjs — load + validate the central config file.
+// Default: ~/.config/claude-ops-installer/config.yaml (XDG).
+// Fallback: ~/.claude-ops-installer.yaml.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import yaml from "js-yaml";
+
+export const DEFAULT_CONFIG_PATHS = [
+ path.join(os.homedir(), ".config", "claude-ops-installer", "config.yaml"),
+ path.join(os.homedir(), ".claude-ops-installer.yaml"),
+];
+
+export const DEFAULT_CONFIG = {
+ version: 1,
+ source: {
+ type: "git",
+ url: "https://github.com/Lifecycle-Innovations-Limited/claude-ops.git",
+ ref: "v2.43.0",
+ },
+ agents: {
+ claude: { enabled: true, type: "marketplace" },
+ codex: { enabled: true, type: "flat", path: "~/.codex/skills" },
+ gemini: { enabled: false, type: "flat", path: "~/.gemini/skills" },
+ openclaw: { enabled: true, type: "flat", path: "~/.openclaw/skills" },
+ hermes: {
+ enabled: true,
+ type: "hybrid",
+ flat: "~/.hermes/skills",
+ nested: "~/.hermes/skills/ops",
+ },
+ opencode: {
+ enabled: false,
+ type: "flat",
+ path: "~/.config/opencode/skills",
+ },
+ },
+ bin: { path: "~/bin", strategy: "symlink" },
+};
+
+export function expandHome(p) {
+ if (!p) return p;
+ if (p === "~") return os.homedir();
+ if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+ return p;
+}
+
+export function loadConfig(overridePath) {
+ const candidates = overridePath ? [overridePath] : DEFAULT_CONFIG_PATHS;
+ let raw = null;
+ let usedPath = null;
+ for (const p of candidates) {
+ try {
+ const txt = fs.readFileSync(expandHome(p), "utf8");
+ raw = txt;
+ usedPath = p;
+ break;
+ } catch (_e) {
+ /* not present */
+ }
+ }
+ let parsed = {};
+ if (raw) {
+ try {
+ parsed = yaml.load(raw) || {};
+ } catch (e) {
+ const err = new Error(
+ `failed to parse yaml at ${usedPath}: ${e.message}`,
+ );
+ err.code = "CONFIG_INVALID";
+ throw err;
+ }
+ }
+ const cfg = mergeDeep(structuredClone(DEFAULT_CONFIG), parsed);
+ if (cfg.version !== 1) {
+ const err = new Error(
+ `unsupported config version: ${cfg.version} (expected 1)`,
+ );
+ err.code = "CONFIG_INVALID";
+ throw err;
+ }
+ // Resolve ~ in agent paths and bin path.
+ for (const a of Object.values(cfg.agents)) {
+ if (a.path) a.path = expandHome(a.path);
+ if (a.flat) a.flat = expandHome(a.flat);
+ if (a.nested) a.nested = expandHome(a.nested);
+ }
+ if (cfg.bin && cfg.bin.path) cfg.bin.path = expandHome(cfg.bin.path);
+ return cfg;
+}
+
+function mergeDeep(target, src) {
+ if (!src || typeof src !== "object") return target;
+ for (const [k, v] of Object.entries(src)) {
+ if (
+ v &&
+ typeof v === "object" &&
+ !Array.isArray(v) &&
+ target[k] &&
+ typeof target[k] === "object"
+ ) {
+ target[k] = mergeDeep(target[k], v);
+ } else {
+ target[k] = v;
+ }
+ }
+ return target;
+}
+
+export function filterAgents(cfg, onlyNames) {
+ const all = Object.entries(cfg.agents);
+ if (!onlyNames || onlyNames.length === 0)
+ return Object.fromEntries(all.filter(([, v]) => v.enabled));
+ const wanted = new Set(onlyNames);
+ return Object.fromEntries(all.filter(([k, v]) => wanted.has(k)));
+}
diff --git a/installer/src/detect.mjs b/installer/src/detect.mjs
new file mode 100644
index 00000000..b055618f
--- /dev/null
+++ b/installer/src/detect.mjs
@@ -0,0 +1,75 @@
+// detect.mjs — for each known agent, probe the host for the CLI binary + expected skill path.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { expandHome } from "./config.mjs";
+
+function which(bin) {
+ try {
+ const r = execSync(`command -v ${bin} || true`, {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ });
+ return r.trim() || null;
+ } catch (_e) {
+ return null;
+ }
+}
+
+export const AGENT_DEFS = {
+ claude: {
+ cli: "claude",
+ skillsPath: "~/.claude/plugins/cache/ops-marketplace/ops/current/skills",
+ binPath: "~/.claude/plugins/cache/ops-marketplace/ops/current/bin",
+ },
+ codex: {
+ cli: "codex",
+ skillsPath: "~/.codex/skills",
+ binPath: null,
+ },
+ gemini: {
+ cli: "gemini",
+ skillsPath: "~/.gemini/skills",
+ binPath: null,
+ },
+ openclaw: {
+ cli: "openclaw",
+ skillsPath: "~/.openclaw/skills",
+ binPath: null,
+ },
+ hermes: {
+ cli: "hermes",
+ skillsPath: "~/.hermes/skills",
+ binPath: null,
+ },
+ opencode: {
+ cli: "opencode",
+ skillsPath: "~/.config/opencode/skills",
+ binPath: null,
+ },
+};
+
+export function detectAgent(name) {
+ const def = AGENT_DEFS[name];
+ if (!def)
+ return {
+ name,
+ known: false,
+ installed: false,
+ cliPath: null,
+ skillsPath: null,
+ binPath: null,
+ };
+ const cliPath = def.cli ? which(def.cli) : null;
+ const skillsPath = expandHome(def.skillsPath);
+ const binPath = def.binPath ? expandHome(def.binPath) : null;
+ // "Installed" = either CLI on PATH OR skills dir exists.
+ const installed = !!cliPath || (skillsPath && fs.existsSync(skillsPath));
+ return { name, known: true, installed, cliPath, skillsPath, binPath };
+}
+
+export function detectAll(names) {
+ const list = names || Object.keys(AGENT_DEFS);
+ return list.map(detectAgent);
+}
diff --git a/installer/src/dispatch.mjs b/installer/src/dispatch.mjs
new file mode 100644
index 00000000..3e659f2c
--- /dev/null
+++ b/installer/src/dispatch.mjs
@@ -0,0 +1,316 @@
+// dispatch.mjs — top-level subcommand handlers. Glues config + detect + source + mirror + bin + verify + doctor + manifest.
+
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig, filterAgents, expandHome } from "./config.mjs";
+import { detectAll, AGENT_DEFS } from "./detect.mjs";
+import { ensureSource, listSourceSkills, listSourceBin } from "./source.mjs";
+import { planMirror, applyActions } from "./mirror.mjs";
+import { planBinLinks, applyBinLinks } from "./bin.mjs";
+import { verifyAgent } from "./verify.mjs";
+import { runDoctor as runDoctorChecks } from "./doctor.mjs";
+import {
+ loadManifest,
+ saveManifest,
+ newManifest,
+ addSymlink,
+ MANIFEST_PATH,
+} from "./manifest.mjs";
+
+function pickAgents(cfg, onlyNames) {
+ // Build the agents map by combining config + detection.
+ const filtered = filterAgents(cfg, onlyNames);
+ const detected = detectAll(Object.keys(filtered));
+ const byName = Object.fromEntries(detected.map((d) => [d.name, d]));
+ const out = {};
+ for (const [name, conf] of Object.entries(filtered)) {
+ const det = byName[name] || {};
+ // Prefer config path if set, else detection.
+ const skillsPath = conf.path || conf.flat || det.skillsPath || null;
+ out[name] = {
+ ...conf,
+ cliPath: det.cliPath,
+ installed: det.installed,
+ skillsPath,
+ nested: conf.nested || null,
+ };
+ }
+ return out;
+}
+
+function planAll({ cfg, srcDir, agents, force, dryRun }) {
+ const skillNames = listSourceSkills(srcDir);
+ const binNames = listSourceBin(srcDir);
+ const plan = { agents: {}, bin: null, errors: [] };
+ for (const [name, a] of Object.entries(agents)) {
+ if (!a.skillsPath) {
+ plan.agents[name] = { skipped: true, reason: "no skillsPath" };
+ continue;
+ }
+ const mirror = planMirror({
+ srcDir,
+ targetDir: a.skillsPath,
+ skillNames,
+ force,
+ dryRun,
+ });
+ plan.agents[name] = mirror;
+ if (mirror.errors.length) plan.errors.push(...mirror.errors);
+ }
+ if (cfg.bin && cfg.bin.path) {
+ plan.bin = planBinLinks({
+ srcDir,
+ binPath: cfg.bin.path,
+ binNames,
+ force,
+ });
+ if (plan.bin.refused.length) plan.errors.push(...plan.bin.refused);
+ if (plan.bin.errors.length) plan.errors.push(...plan.bin.errors);
+ }
+ return plan;
+}
+
+function applyAll({ plan, dryRun, cfg }) {
+ let manifest = loadManifest();
+ for (const [name, mirror] of Object.entries(plan.agents)) {
+ if (mirror.skipped) continue;
+ applyActions(mirror.actions, {
+ dryRun,
+ onApply: (to, from) => addSymlink(manifest, to, from),
+ });
+ // Record every applied symlink in the manifest.
+ if (!dryRun) {
+ for (const a of mirror.actions) {
+ if (a.status === "applied") {
+ try {
+ const st = fs.lstatSync(a.to);
+ if (st.isSymbolicLink())
+ addSymlink(manifest, a.to, fs.readlinkSync(a.to));
+ } catch (_e) {
+ /* ignore */
+ }
+ }
+ }
+ }
+ }
+ // Apply bin links from plan.bin.planned (which contains from/to + status='planned').
+ if (plan.bin && plan.bin.planned) {
+ applyBinLinks({
+ binPath: cfg.bin.path,
+ plan: plan.bin,
+ onApply: (to, from) => addSymlink(manifest, to, from),
+ });
+ }
+ if (!dryRun) saveManifest(manifest);
+}
+
+function emit(plan, asJson) {
+ if (asJson) process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
+ else {
+ for (const [name, m] of Object.entries(plan.agents)) {
+ if (m.skipped) {
+ process.stdout.write(`[${name}] skipped: ${m.reason}\n`);
+ continue;
+ }
+ const counts = m.actions.reduce((acc, a) => {
+ acc[a.op] = (acc[a.op] || 0) + 1;
+ return acc;
+ }, {});
+ process.stdout.write(`[${name}] ${JSON.stringify(counts)}\n`);
+ for (const a of m.actions) {
+ const arrow = a.status ? `${a.op}->${a.status}` : a.op;
+ process.stdout.write(` ${arrow} ${a.skill}\n`);
+ }
+ }
+ if (plan.bin && plan.bin.planned) {
+ const applied = plan.bin.planned.filter(
+ (r) => r.status === "applied",
+ ).length;
+ const skipped = plan.bin.planned.filter(
+ (r) => r.status === "skipped",
+ ).length;
+ const failed = plan.bin.planned.filter(
+ (r) => r.status === "failed",
+ ).length;
+ process.stdout.write(
+ `[bin] ${plan.bin.planned.length} entries (applied=${applied} skipped=${skipped} failed=${failed})\n`,
+ );
+ if (plan.bin.refused?.length)
+ process.stdout.write(`[bin] refused: ${plan.bin.refused.length}\n`);
+ if (plan.bin.errors?.length) {
+ process.stdout.write(`[bin] errors:\n`);
+ for (const e of plan.bin.errors)
+ process.stdout.write(` ${JSON.stringify(e)}\n`);
+ }
+ }
+ }
+}
+
+export async function runAgents(flags) {
+ const cfg = loadConfig(flags.config);
+ const detected = detectAll();
+ const asJson = !!flags.json;
+ const rows = detected.map((d) => ({
+ name: d.name,
+ installed: d.installed,
+ cli: d.cliPath || null,
+ skills: d.skillsPath || null,
+ enabled: !!cfg.agents[d.name]?.enabled,
+ }));
+ if (asJson) process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
+ else {
+ process.stdout.write(
+ "agent installed cli skills enabled\n",
+ );
+ for (const r of rows) {
+ process.stdout.write(
+ `${r.name.padEnd(12)} ${String(r.installed).padEnd(9)} ${(r.cli || "-").padEnd(28)} ${(r.skills || "-").padEnd(38)} ${r.enabled}\n`,
+ );
+ }
+ }
+ return 0;
+}
+
+export async function runInstall(flags) {
+ const cfg = loadConfig(flags.config);
+ if (flags.ref) cfg.source.ref = flags.ref;
+ const src = ensureSource(cfg);
+ const agents = pickAgents(cfg, flags.agents);
+ if (Object.keys(agents).length === 0) {
+ process.stderr.write(
+ "no agents enabled (run with --agents claude,codex,... to override)\n",
+ );
+ return 4;
+ }
+ const plan = planAll({
+ cfg,
+ srcDir: src.dir,
+ agents,
+ force: !!flags.force,
+ dryRun: !!flags.dryRun,
+ });
+ applyAll({ plan, dryRun: !!flags.dryRun, cfg });
+ emit(plan, !!flags.json);
+ const errs = plan.errors || [];
+ if (errs.length) {
+ process.stderr.write(`\n${errs.length} non-fatal error(s):\n`);
+ for (const e of errs) process.stderr.write(` ${JSON.stringify(e)}\n`);
+ return 1;
+ }
+ return 0;
+}
+
+export async function runUpdate(flags) {
+ // Same as install — re-mirror.
+ return runInstall(flags);
+}
+
+export async function runVerify(flags) {
+ const cfg = loadConfig(flags.config);
+ if (flags.ref) cfg.source.ref = flags.ref;
+ const src = ensureSource(cfg);
+ const agents = pickAgents(cfg, flags.agents);
+ const reports = [];
+ for (const [name, a] of Object.entries(agents)) {
+ if (!a.skillsPath) {
+ reports.push({ name, skipped: true });
+ continue;
+ }
+ reports.push(
+ verifyAgent({
+ srcDir: src.dir,
+ agentName: name,
+ targetDir: a.skillsPath,
+ }),
+ );
+ }
+ if (flags.json) process.stdout.write(JSON.stringify(reports, null, 2) + "\n");
+ else {
+ for (const r of reports) {
+ if (r.skipped) {
+ process.stdout.write(`[${r.name}] skipped\n`);
+ continue;
+ }
+ process.stdout.write(
+ `[${r.agent || r.name}] ok=${r.ok} drifts=${r.drifts.length} missing=${r.missing.length}\n`,
+ );
+ for (const d of r.drifts)
+ process.stdout.write(` drift: ${d.name} — ${d.reason}\n`);
+ for (const d of r.missing) process.stdout.write(` missing: ${d.name}\n`);
+ }
+ }
+ const any = reports.some((r) => r.drifts?.length || r.missing?.length);
+ return any ? 1 : 0;
+}
+
+export async function runDoctor(flags) {
+ const cfg = loadConfig(flags.config);
+ if (flags.ref) cfg.source.ref = flags.ref;
+ const src = ensureSource(cfg);
+ const agents = pickAgents(cfg, flags.agents);
+ const out = await runDoctorChecks({ srcDir: src.dir, agents });
+ if (flags.json) process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+ else {
+ for (const c of out.checks)
+ process.stdout.write(
+ `${c.ok ? "OK " : "FAIL"} ${c.name.padEnd(28)} ${c.msg}\n`,
+ );
+ process.stdout.write(
+ `\n${out.failed.length === 0 ? "all green" : out.failed.length + " failed"}\n`,
+ );
+ }
+ return out.ok ? 0 : 1;
+}
+
+export async function runUninstall(flags) {
+ const m = loadManifest();
+ let removed = 0;
+ let kept = 0;
+ const errors = [];
+ for (const s of m.symlinks) {
+ let st = null;
+ try {
+ st = fs.lstatSync(s.to);
+ } catch (_e) {}
+ if (!st) {
+ kept++;
+ continue;
+ }
+ if (!st.isSymbolicLink()) {
+ kept++;
+ continue;
+ }
+ try {
+ fs.unlinkSync(s.to);
+ removed++;
+ } catch (e) {
+ errors.push({ to: s.to, error: e.message });
+ }
+ }
+ // Empty the manifest only if every entry succeeded.
+ if (errors.length === 0) {
+ saveManifest(newManifest());
+ } else {
+ // Keep the manifest with successful removals; drop them.
+ const remaining = m.symlinks.filter(
+ (s) => !errors.some((e) => e.to === s.to),
+ );
+ saveManifest({ ...m, symlinks: remaining });
+ }
+ if (flags.json)
+ process.stdout.write(
+ JSON.stringify({ removed, kept, errors }, null, 2) + "\n",
+ );
+ else {
+ process.stdout.write(
+ `removed: ${removed}\nkept: ${kept}\nerrors: ${errors.length}\n`,
+ );
+ for (const e of errors) process.stderr.write(` ${JSON.stringify(e)}\n`);
+ }
+ return errors.length === 0 ? 0 : 1;
+}
+
+export async function runHelp() {
+ process.stdout.write("See --help output above.\n");
+ return 0;
+}
diff --git a/installer/src/doctor.mjs b/installer/src/doctor.mjs
new file mode 100644
index 00000000..cea69be3
--- /dev/null
+++ b/installer/src/doctor.mjs
@@ -0,0 +1,66 @@
+// doctor.mjs — verify + tool checks + env checks.
+
+import { execSync } from "node:child_process";
+import { verifyAgent } from "./verify.mjs";
+
+function tryExec(cmd) {
+ try {
+ const out = execSync(cmd, {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ }).trim();
+ return { ok: true, out };
+ } catch (e) {
+ return { ok: false, error: e.message };
+ }
+}
+
+export async function runDoctor({ srcDir, agents }) {
+ const checks = [];
+ // 1. Each agent's mirror
+ for (const [name, a] of Object.entries(agents)) {
+ if (!a.skillsPath) {
+ checks.push({ name, ok: false, msg: "no skillsPath" });
+ continue;
+ }
+ const v = verifyAgent({ srcDir, agentName: name, targetDir: a.skillsPath });
+ checks.push({
+ name: `${name}:mirror`,
+ ok: v.drifts.length === 0 && v.missing.length === 0,
+ msg: `ok=${v.ok} drifts=${v.drifts.length} missing=${v.missing.length}`,
+ });
+ }
+ // 2. ops-inbox-scan reachable on PATH
+ const ois = tryExec("command -v ops-inbox-scan");
+ checks.push({
+ name: "ops-inbox-scan-on-PATH",
+ ok: !!ois.out,
+ msg: ois.out || "not on PATH",
+ });
+ // 3. wa-inbox-fresh.sh reachable
+ const wai = tryExec("command -v wa-inbox-fresh.sh");
+ checks.push({
+ name: "wa-inbox-fresh-on-PATH",
+ ok: !!wai.out,
+ msg: wai.out || "not on PATH",
+ });
+ // 4. node version
+ const node = tryExec("node --version");
+ checks.push({
+ name: "node",
+ ok: /^v(1[8-9]|[2-9]\d|\d{3,})/.test(node.out || ""),
+ msg: node.out || node.error,
+ });
+ // 5. upstream src has SKILL.md for ops-inbox (signal we got a real checkout)
+ const fs = await import("node:fs");
+ const path = await import("node:path");
+ const want = path.join(srcDir, "skills", "ops-inbox", "SKILL.md");
+ checks.push({
+ name: "source:ops-inbox/SKILL.md",
+ ok: fs.existsSync(want),
+ msg: want,
+ });
+ // Summary
+ const failed = checks.filter((c) => !c.ok);
+ return { ok: failed.length === 0, checks, failed };
+}
diff --git a/installer/src/manifest.mjs b/installer/src/manifest.mjs
new file mode 100644
index 00000000..41fde719
--- /dev/null
+++ b/installer/src/manifest.mjs
@@ -0,0 +1,42 @@
+// manifest.mjs — record every symlink WE created so uninstall is surgical.
+// Stored at ~/.cache/claude-ops-installer/manifest.json.
+
+import fs from "node:fs";
+import path from "node:path";
+import { CACHE_ROOT } from "./source.mjs";
+
+const MANIFEST_PATH = path.join(CACHE_ROOT, "manifest.json");
+
+function empty() {
+ return { version: 1, created_at: new Date().toISOString(), symlinks: [] };
+}
+
+export function loadManifest() {
+ try {
+ const txt = fs.readFileSync(MANIFEST_PATH, "utf8");
+ const m = JSON.parse(txt);
+ if (m && Array.isArray(m.symlinks)) return m;
+ return empty();
+ } catch (_e) {
+ return empty();
+ }
+}
+
+export function saveManifest(m) {
+ fs.mkdirSync(CACHE_ROOT, { recursive: true });
+ fs.writeFileSync(MANIFEST_PATH, JSON.stringify(m, null, 2) + "\n");
+}
+
+export function addSymlink(m, to, fromRef) {
+ if (!m.symlinks.find((s) => s.to === to)) {
+ m.symlinks.push({ to, from: fromRef, at: new Date().toISOString() });
+ }
+ return m;
+}
+
+// Convenience wrapper for the rest of the installer.
+export function newManifest() {
+ return empty();
+}
+
+export { MANIFEST_PATH };
diff --git a/installer/src/mirror.mjs b/installer/src/mirror.mjs
new file mode 100644
index 00000000..e0c527a4
--- /dev/null
+++ b/installer/src/mirror.mjs
@@ -0,0 +1,144 @@
+// mirror.mjs — apply the actual symlink plan. Errors as data; no silent swallowing.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export function planMirror({
+ srcDir,
+ targetDir,
+ skillNames,
+ force,
+ dryRun,
+ mode = "flat",
+}) {
+ // mode = 'flat' for normal agents, 'hybrid' for Hermes (which may also write into nested).
+ // Returns: { actions: [{op: 'symlink'|'skip'|'refuse'|'error', skill, from, to, reason?}], errors: [] }
+ const actions = [];
+ const errors = [];
+ fs.mkdirSync(targetDir, { recursive: true });
+
+ for (const name of skillNames) {
+ const from = path.join(srcDir, "skills", name);
+ const to = path.join(targetDir, name);
+ if (!fs.existsSync(from)) {
+ const a = {
+ op: "error",
+ skill: name,
+ from,
+ to,
+ reason: "source skill missing",
+ };
+ actions.push(a);
+ errors.push({
+ agent: targetDir,
+ path: from,
+ op: "read",
+ error: "source skill missing",
+ });
+ continue;
+ }
+ let existing = null;
+ try {
+ existing = fs.lstatSync(to);
+ } catch (_e) {
+ /* absent */
+ }
+ if (existing) {
+ if (existing.isSymbolicLink()) {
+ const cur = fs.readlinkSync(to);
+ const want = from;
+ if (cur === want || cur === want + "/") {
+ actions.push({
+ op: "skip",
+ skill: name,
+ from,
+ to,
+ reason: "already correct",
+ });
+ continue;
+ }
+ actions.push({
+ op: "symlink",
+ skill: name,
+ from,
+ to,
+ reason: "replace existing symlink",
+ });
+ continue;
+ }
+ if (existing.isDirectory() || existing.isFile()) {
+ if (!force) {
+ actions.push({
+ op: "refuse",
+ skill: name,
+ from,
+ to,
+ reason: "target is a real file/dir; pass --force to overwrite",
+ });
+ errors.push({
+ agent: targetDir,
+ path: to,
+ op: "symlink",
+ error: "target is real (refused without --force)",
+ });
+ continue;
+ }
+ actions.push({
+ op: "symlink",
+ skill: name,
+ from,
+ to,
+ reason: "overwrite real file/dir (--force)",
+ });
+ continue;
+ }
+ }
+ actions.push({ op: "symlink", skill: name, from, to });
+ }
+ return { actions, errors };
+}
+
+export function applyActions(actions, { dryRun, onApply }) {
+ const results = [];
+ for (const a of actions) {
+ if (a.op === "skip") {
+ results.push({ ...a, status: "skipped" });
+ continue;
+ }
+ if (a.op === "refuse") {
+ results.push({ ...a, status: "refused" });
+ continue;
+ }
+ if (a.op === "error") {
+ results.push({ ...a, status: "error" });
+ continue;
+ }
+ if (a.op !== "symlink") {
+ results.push({ ...a, status: "noop" });
+ continue;
+ }
+ if (dryRun) {
+ results.push({ ...a, status: "planned" });
+ continue;
+ }
+ try {
+ // Remove existing real file/dir if present and not a symlink.
+ let st = null;
+ try {
+ st = fs.lstatSync(a.to);
+ } catch (_e) {}
+ if (st) {
+ if (st.isSymbolicLink() || st.isFile())
+ fs.rmSync(a.to, { force: true });
+ else if (st.isDirectory())
+ fs.rmSync(a.to, { recursive: true, force: true });
+ }
+ fs.symlinkSync(a.from, a.to);
+ if (typeof onApply === "function") onApply(a.to, a.from);
+ results.push({ ...a, status: "applied" });
+ } catch (e) {
+ results.push({ ...a, status: "failed", error: e.message });
+ }
+ }
+ return results;
+}
diff --git a/installer/src/source.mjs b/installer/src/source.mjs
new file mode 100644
index 00000000..8d3306cd
--- /dev/null
+++ b/installer/src/source.mjs
@@ -0,0 +1,106 @@
+// source.mjs — resolve the upstream source into a local cache directory.
+// Default strategy: git clone (shallow) of Lifecycle-Innovations-Limited/claude-ops at the
+// pinned ref. Cache key = sha of the ref so re-runs are fast.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+export const CACHE_ROOT = path.join(
+ os.homedir(),
+ ".cache",
+ "claude-ops-installer",
+);
+
+function sh(cmd, opts = {}) {
+ return execSync(cmd, {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+ ...opts,
+ }).trim();
+}
+
+export function resolveRef(srcDir) {
+ try {
+ return sh(`git -C "${srcDir}" rev-parse HEAD`);
+ } catch (_e) {
+ return null;
+ }
+}
+
+function cacheKey(cfg) {
+ const url = cfg.source.url;
+ const ref = cfg.source.ref;
+ // Hash-ish key from URL + ref. Keep stable across OSes.
+ const safe = `${url.replace(/[^a-zA-Z0-9]/g, "_")}__${ref.replace(/[^a-zA-Z0-9._-]/g, "_")}`;
+ return safe.slice(0, 200);
+}
+
+export function ensureSource(cfg) {
+ const dir = path.join(CACHE_ROOT, cacheKey(cfg));
+ // The marketplace repo nests the actual plugin at <repo>/claude-ops/. That's where skills/ and bin/ live.
+ const skillsDir = path.join(dir, "claude-ops", "skills");
+ const binDir = path.join(dir, "claude-ops", "bin");
+ fs.mkdirSync(CACHE_ROOT, { recursive: true });
+ if (fs.existsSync(path.join(skillsDir, "ops-inbox", "SKILL.md"))) {
+ return {
+ dir: path.join(dir, "claude-ops"),
+ ref: resolveRef(dir),
+ fresh: false,
+ };
+ }
+ if (fs.existsSync(path.join(dir, ".git"))) {
+ // Stale partial — try to update.
+ try {
+ sh(`git -C "${dir}" fetch --depth 1 origin ${cfg.source.ref}`);
+ sh(`git -C "${dir}" reset --hard FETCH_HEAD`);
+ if (fs.existsSync(path.join(skillsDir, "ops-inbox", "SKILL.md"))) {
+ return {
+ dir: path.join(dir, "claude-ops"),
+ ref: resolveRef(dir),
+ fresh: true,
+ };
+ }
+ } catch (e) {
+ // fall through to fresh clone
+ }
+ }
+ fs.rmSync(dir, { recursive: true, force: true });
+ const url = cfg.source.url;
+ const ref = cfg.source.ref;
+ // Shallow clone, then checkout the ref.
+ sh(`git clone --depth 1 --no-tags --filter=blob:none "${url}" "${dir}"`);
+ try {
+ sh(`git -C "${dir}" fetch --depth 1 origin ${ref}`);
+ sh(`git -C "${dir}" checkout FETCH_HEAD`);
+ } catch (e) {
+ throw new Error(`source: failed to fetch ref ${ref}: ${e.message}`);
+ }
+ if (!fs.existsSync(path.join(skillsDir, "ops-inbox", "SKILL.md"))) {
+ throw new Error(
+ `source: claude-ops/skills/ops-inbox/SKILL.md not found after fetch at ${ref}`,
+ );
+ }
+ return {
+ dir: path.join(dir, "claude-ops"),
+ ref: resolveRef(dir),
+ fresh: true,
+ };
+}
+
+export function listSourceSkills(srcDir) {
+ const skillsDir = path.join(srcDir, "skills");
+ if (!fs.existsSync(skillsDir)) return [];
+ return fs
+ .readdirSync(skillsDir, { withFileTypes: true })
+ .filter((d) => d.isDirectory())
+ .map((d) => d.name)
+ .sort();
+}
+
+export function listSourceBin(srcDir) {
+ const binDir = path.join(srcDir, "bin");
+ if (!fs.existsSync(binDir)) return [];
+ return fs.readdirSync(binDir).sort();
+}
diff --git a/installer/src/verify.mjs b/installer/src/verify.mjs
new file mode 100644
index 00000000..96d89887
--- /dev/null
+++ b/installer/src/verify.mjs
@@ -0,0 +1,41 @@
+// verify.mjs — read-only check: does each agent's skills dir mirror upstream correctly?
+
+import fs from "node:fs";
+import path from "node:path";
+import { listSourceSkills } from "./source.mjs";
+
+export function verifyAgent({ srcDir, agentName, targetDir }) {
+ const skillNames = listSourceSkills(srcDir);
+ const drifts = [];
+ const ok = [];
+ const missing = [];
+ for (const name of skillNames) {
+ const from = path.join(srcDir, "skills", name);
+ const to = path.join(targetDir, name);
+ let st = null;
+ try {
+ st = fs.lstatSync(to);
+ } catch (_e) {}
+ if (!st) {
+ missing.push({ name, from, to });
+ continue;
+ }
+ if (!st.isSymbolicLink()) {
+ drifts.push({ name, from, to, reason: "target is not a symlink" });
+ continue;
+ }
+ const cur = fs.readlinkSync(to);
+ const want = from;
+ if (cur !== want && cur !== want + "/") {
+ drifts.push({
+ name,
+ from,
+ to,
+ reason: `symlink points at ${cur}, expected ${want}`,
+ });
+ continue;
+ }
+ ok.push({ name, to });
+ }
+ return { agent: agentName, targetDir, ok: ok.length, missing, drifts };
+}
diff --git a/installer/test/smoke.mjs b/installer/test/smoke.mjs
new file mode 100644
index 00000000..8724de30
--- /dev/null
+++ b/installer/test/smoke.mjs
@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Smoke test: verifies the installer's core invariants without touching the user's box.
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "../src/config.mjs";
+import { listSourceSkills, listSourceBin } from "../src/source.mjs";
+import { planBinLinks, applyBinLinks } from "../src/bin.mjs";
+import { planMirror } from "../src/mirror.mjs";
+import {
+ loadManifest,
+ saveManifest,
+ addSymlink,
+ newManifest,
+} from "../src/manifest.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(__dirname, "..", "..", "claude-ops"); // installer/../claude-ops
+
+let failures = 0;
+function assert(cond, msg) {
+ if (cond) process.stdout.write(`OK ${msg}\n`);
+ else {
+ process.stdout.write(`FAIL ${msg}\n`);
+ failures++;
+ }
+}
+
+// 1. Default config loads with all 6 agents
+const cfg = loadConfig();
+assert(cfg && cfg.version === 1, "config loads with version=1");
+assert(
+ Object.keys(cfg.agents).length === 6,
+ `config has 6 agents (got ${Object.keys(cfg.agents).length})`,
+);
+
+// 2. Source listing — skills dir present
+const skills = listSourceSkills(SRC);
+const bins = listSourceBin(SRC);
+assert(skills.length > 0, `source has ${skills.length} skills`);
+assert(bins.length > 0, `source has ${bins.length} bin entries`);
+assert(skills.includes("ops-inbox"), "source includes ops-inbox");
+assert(bins.includes("ops-inbox-scan"), "source includes ops-inbox-scan");
+
+// 3. Plan + apply round-trip into a scratch dir
+const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "installer-smoke-"));
+try {
+ const mirror = planMirror({
+ srcDir: SRC,
+ targetDir: path.join(scratch, "skills"),
+ skillNames: skills,
+ force: false,
+ });
+ const binPlan = planBinLinks({
+ srcDir: SRC,
+ binPath: path.join(scratch, "bin"),
+ binNames: bins,
+ force: false,
+ });
+ assert(
+ mirror.actions.length === skills.length,
+ `mirror planned ${mirror.actions.length}/${skills.length} skills`,
+ );
+ assert(
+ binPlan.planned.length === bins.length,
+ `bin planned ${binPlan.planned.length}/${bins.length}`,
+ );
+
+ // Apply both
+ const manifest = newManifest();
+ const skillResults = [];
+ for (const a of mirror.actions) {
+ if (a.op === "symlink") {
+ try {
+ fs.symlinkSync(a.from, a.to);
+ addSymlink(manifest, a.to, a.from);
+ skillResults.push({ ...a, status: "applied" });
+ } catch (e) {
+ skillResults.push({ ...a, status: "failed", error: e.message });
+ }
+ } else {
+ skillResults.push(a);
+ }
+ }
+ applyBinLinks({
+ binPath: path.join(scratch, "bin"),
+ plan: binPlan,
+ onApply: (to, from) => addSymlink(manifest, to, from),
+ });
+ saveManifest(manifest);
+
+ assert(
+ manifest.symlinks.length === skills.length + bins.length,
+ `manifest recorded ${manifest.symlinks.length} (expected ${skills.length + bins.length})`,
+ );
+ assert(
+ fs.existsSync(path.join(scratch, "skills", "ops-inbox", "SKILL.md")),
+ "ops-inbox SKILL.md present in scratch",
+ );
+ assert(
+ fs.existsSync(path.join(scratch, "bin", "ops-inbox-scan")),
+ "ops-inbox-scan binstub present in scratch",
+ );
+} finally {
+ fs.rmSync(scratch, { recursive: true, force: true });
+}
+
+process.stdout.write(
+ `\n${failures === 0 ? "all green" : failures + " failed"}\n`,
+);
+process.exit(failures === 0 ? 0 : 1);