agenticloops 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# agenticloops
+
+Install and run **agentic loops** — recurring AI agents defined in a single
+[`LOOP.md`](https://github.com/5dive-ai/loops/blob/main/SPEC.md) file: a trigger,
+a set of skills, and a prompt. One file defines it; any harness can run it.
+
+The directory lives at **[agenticloops.dev](https://agenticloops.dev)**. This is
+the install CLI — the loop-level analogue of `npx skills add`.
+
+```bash
+# install a loop onto the harness in the current project (auto-detected)
+npx agenticloops install <owner/repo>
+
+# target a specific harness
+npx agenticloops install <owner/repo> --harness=5dive
+
+# search the directory
+npx agenticloops find research
+
+# what's installed here + global install counts
+npx agenticloops list
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `install <owner/loop>` | Fetch + validate the `LOOP.md`, install its skills, pre-flight its `requires`, and register the recurring job on your harness. |
+| `find <query>` | Search the public directory. |
+| `list` | Loops installed on this machine + their global install counts. |
+| `update [<slug>]` | Re-fetch + re-install (all, or one). |
+
+You can also point `install` / `validate` at a **local path** (`./my-loop` or a
+`LOOP.md`) while you're authoring.
+
+## How install works
+
+Per the [spec](https://github.com/5dive-ai/loops/blob/main/SPEC.md):
+
+1. **Fetch + validate** the `LOOP.md` against spec v0.1 (required: `name`,
+   `description`, a `schedule`/`event` trigger).
+2. **Install skills** (`skills:`). `owner/repo/skill` paths are fetched directly;
+   bare names resolve against the skills registry; anything the harness already
+   provides is used as-is. An unresolvable skill is skipped with a warning — a
+   loop degrades rather than refusing to install.
+3. **Pre-flight `requires`** (`cli` / `secrets` / `mcp` / `network`). This is
+   **declare-and-check**: missing binaries, secrets, and servers are reported and
+   you're prompted or the install refuses. Nothing is **ever auto-installed** —
+   binaries, secrets, and MCP servers run code or carry trust, so that consent is
+   yours.
+4. **Register the trigger** on the harness (a recurring 5dive task, a GitHub
+   Actions workflow, a cron scaffold, …).
+
+### Harnesses
+
+`5dive` · `github-actions` · `claude-code` · `cursor` · `cron`
+
+Auto-detected from the current directory/env. A loop needs **scheduling**, so a
+run-only harness (an IDE) can run the agent but can't honor a recurring trigger —
+the installer warns you and suggests a scheduling harness.
+
+## Telemetry — anonymous, opt-out, and exactly this
+
+On a **successful install**, the CLI sends one fire-and-forget ping to
+`agenticloops.dev/api/install` so the directory can show real install counts
+(like npm download counts):
+
+```json
+{ "slug": "ci-analyst", "ts": "2026-06-30T12:00:00.000Z" }
+```
+
+That is the **entire** payload. The loop slug is a public id. We do **not** send
+or store your IP, username, machine id, repo, prompt, or any other field. Updates
+don't re-count. Failure is silent and never blocks an install.
+
+**Opt out** any of these ways:
+
+```bash
+npx agenticloops install <owner/repo> --no-telemetry
+AGENTICLOOPS_NO_TELEMETRY=1 npx agenticloops install <owner/repo>
+DO_NOT_TRACK=1 npx agenticloops install <owner/repo>   # cross-tool standard
+```
+
+## License
+
+MIT. Spec + directory: [github.com/5dive-ai/loops](https://github.com/5dive-ai/loops).

package/bin/cli.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// agenticloops — install and run agentic loops (recurring AI agents in one
+// LOOP.md). One file defines it; any harness can run it. https://agenticloops.dev
+import { install } from "../src/install.mjs";
+import { loadRegistry, search } from "../src/registry.mjs";
+import { listRecords, parseSchedule } from "../src/schedule.mjs";
+import { fetchInstalls } from "../src/telemetry.mjs";
+import { c, sym, fail, info, CliError } from "../src/util.mjs";
+
+const VERSION = "0.1.0";
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (const a of argv) {
+    if (a.startsWith("--")) {
+      const [k, v] = a.slice(2).split("=");
+      flags[k] = v === undefined ? true : v;
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+const HELP = `${c.bold("agenticloops")} — install and run agentic loops ${c.dim("v" + VERSION)}
+
+${c.bold("Usage")}
+  npx agenticloops install <owner/loop> [--harness=<id>] [--no-telemetry] [--yes] [--dry-run]
+  npx agenticloops find <query>
+  npx agenticloops list
+  npx agenticloops update [<slug>]
+
+${c.bold("Commands")}
+  install   Fetch + validate a LOOP.md, install its skills, pre-flight its
+            requirements, and register the recurring job on your harness.
+  find      Search the public directory (agenticloops.dev) for loops.
+  list      Show loops installed on this machine + their install counts.
+  update    Re-fetch + re-install a loop (all, or one slug).
+
+${c.bold("Harnesses")}  5dive · github-actions · claude-code · cursor · cron
+  Auto-detected from the current directory/env. A loop needs SCHEDULING, so a
+  run-only harness (an IDE) is warned about; target a scheduler to run on time.
+
+${c.bold("Flags")}
+  --harness=<id>    Target a specific harness instead of auto-detecting.
+  --no-telemetry    Don't send the anonymous install ping (slug + ts only).
+                    Also honored: AGENTICLOOPS_NO_TELEMETRY=1, DO_NOT_TRACK=1.
+  --yes             Assume yes to prompts (non-interactive installs).
+  --dry-run         Show what would happen; change nothing, send nothing.
+
+Spec: https://github.com/5dive-ai/loops/blob/main/SPEC.md  ·  MIT`;
+
+async function cmdInstall(positional, flags) {
+  const ref = positional[0];
+  if (!ref) throw new CliError("usage: agenticloops install <owner/loop>", 2);
+  await install(ref, {
+    harness: typeof flags.harness === "string" ? flags.harness : undefined,
+    noTelemetry: !!flags["no-telemetry"],
+    yes: !!flags.yes,
+    dryRun: !!flags["dry-run"],
+  });
+}
+
+async function cmdFind(positional) {
+  const query = positional.join(" ");
+  const { loops, url } = await loadRegistry();
+  if (!loops.length) throw new CliError("could not load the loop directory", 1);
+  const hits = search(loops, query);
+  if (!hits.length) {
+    info(`no loops match "${query}" ${c.dim("(" + loops.length + " in the directory)")}`);
+    return;
+  }
+  const installs = await fetchInstalls().catch(() => ({}));
+  process.stderr.write(`\n${c.dim(`${hits.length} of ${loops.length} loops · ${url}`)}\n\n`);
+  for (const l of hits.slice(0, 25)) {
+    const n = installs[l.slug];
+    const badge = l.imported ? c.dim(" [community]") : "";
+    const count = typeof n === "number" ? c.dim(`  ${n}↓`) : "";
+    process.stdout.write(
+      `${c.bold(l.slug)}${badge}${count}\n  ${c.cyan(l.jobTitle || "")} — ${l.tagline || ""}\n` +
+        (l.source?.repo ? `  ${c.dim("install: agenticloops install " + l.source.repo)}\n` : "") +
+        "\n",
+    );
+  }
+}
+
+async function cmdList() {
+  const recs = listRecords();
+  if (!recs.length) {
+    info("no loops installed on this machine yet. Try: agenticloops find <query>");
+    return;
+  }
+  const installs = await fetchInstalls().catch(() => ({}));
+  process.stderr.write(`\n${c.dim(recs.length + " installed")}\n\n`);
+  for (const r of recs) {
+    const n = installs[r.slug];
+    const sched = r.cron ? r.cron : r.trigger?.value || "?";
+    process.stdout.write(
+      `${c.bold(r.slug)}  ${c.dim("on " + r.harness)}${typeof n === "number" ? c.dim("  " + n + "↓ globally") : ""}\n` +
+        `  ${c.cyan(sched)} — ${(r.description || "").split("\n")[0]}\n` +
+        `  ${c.dim(r.source || r.ref)}\n\n`,
+    );
+  }
+}
+
+async function cmdUpdate(positional, flags) {
+  const recs = listRecords();
+  const targets = positional[0] ? recs.filter((r) => r.slug === positional[0]) : recs;
+  if (!targets.length) {
+    info(positional[0] ? `"${positional[0]}" is not installed` : "nothing installed to update");
+    return;
+  }
+  for (const r of targets) {
+    info(`updating ${c.bold(r.slug)} ${c.dim("(" + r.ref + ")")}`);
+    await install(r.ref, {
+      harness: r.harness,
+      yes: true,
+      noTelemetry: true, // an update isn't a new install — don't double-count
+      dryRun: !!flags["dry-run"],
+    });
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { positional, flags } = parseArgs(argv);
+  const cmd = positional.shift(); // first non-flag token is the command
+
+  if (flags.version || flags.v || cmd === "version") {
+    process.stdout.write(VERSION + "\n");
+    return;
+  }
+  if (!cmd || flags.help || flags.h || cmd === "help") {
+    process.stdout.write(HELP + "\n");
+    return;
+  }
+
+  switch (cmd) {
+    case "install":
+    case "add":
+      return cmdInstall(positional, flags);
+    case "find":
+    case "search":
+      return cmdFind(positional, flags);
+    case "list":
+    case "ls":
+      return cmdList(positional, flags);
+    case "update":
+    case "upgrade":
+      return cmdUpdate(positional, flags);
+    default:
+      throw new CliError(`unknown command "${cmd}". Run: agenticloops --help`, 2);
+  }
+}
+
+main().catch((e) => {
+  if (e instanceof CliError) {
+    fail(e.message);
+    process.exit(e.code || 1);
+  }
+  fail(e?.stack || String(e));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agenticloops",
+  "version": "0.1.0",
+  "description": "Install and run agentic loops — recurring AI agents defined in a single LOOP.md file. One file defines it; any harness can run it.",
+  "type": "module",
+  "bin": {
+    "agenticloops": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "agentic-loop",
+    "agentic-loops",
+    "ai-agent",
+    "scheduler",
+    "loop",
+    "skills",
+    "claude",
+    "cron",
+    "automation"
+  ],
+  "homepage": "https://agenticloops.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/5dive-ai/agenticloops.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.4.5"
+  }
+}

package/src/config.mjs

@@ -0,0 +1,18 @@
+// Central constants. The telemetry + registry endpoints live on agenticloops.dev.
+export const SITE = "https://agenticloops.dev";
+
+// Anonymous install counter (POST {slug, ts}) + tallies (GET). See src/telemetry.mjs.
+export const TELEMETRY_URL = process.env.AGENTICLOOPS_TELEMETRY_URL || `${SITE}/api/install`;
+
+// The bundled directory the site builds from + the canonical spec registry.
+export const SITE_REGISTRY_URL = `${SITE}/loops.json`;
+export const SPEC_REGISTRY_URL =
+  "https://raw.githubusercontent.com/5dive-ai/loops/main/index.json";
+
+// skills.sh-style index used to resolve BARE skill names (§3.1 tier 3).
+export const SKILLS_REGISTRY_URL = "https://skills.sh/index.json";
+
+export const SPEC_VERSION = "0.1";
+
+// User-Agent so server logs can attribute pings to the CLI (still anonymous).
+export const UA = `agenticloops-cli/0.1.0 (+${SITE})`;

package/src/harness.mjs

@@ -0,0 +1,68 @@
+// Harness detection + capabilities. A harness is anything that can resolve the
+// loop's skills, honor its trigger, and run the prompt. Crucially, a loop needs
+// SCHEDULING — a harness that can only run interactively (an IDE) can run the
+// agent but cannot honor a recurring trigger; we warn when targeting one.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+function has(bin) {
+  try {
+    execSync(`command -v ${bin}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Each harness: id, label, canSchedule, and a detect() that inspects cwd/env.
+export const HARNESSES = [
+  {
+    id: "5dive",
+    label: "5dive runtime",
+    canSchedule: true,
+    detect: () => has("5dive") || existsSync("/var/lib/5dive"),
+  },
+  {
+    id: "github-actions",
+    label: "GitHub Actions",
+    canSchedule: true,
+    detect: (cwd) => existsSync(join(cwd, ".github", "workflows")) || !!process.env.GITHUB_ACTIONS,
+  },
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    canSchedule: false,
+    detect: (cwd) => existsSync(join(cwd, ".claude")) || has("claude"),
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    canSchedule: false,
+    detect: (cwd) => existsSync(join(cwd, ".cursor")),
+  },
+  {
+    id: "cron",
+    label: "system cron",
+    canSchedule: true,
+    detect: () => has("crontab"),
+  },
+];
+
+export function getHarness(id) {
+  return HARNESSES.find((h) => h.id === id);
+}
+
+// Auto-detect: prefer a schedulable harness when several are present, since a
+// loop's whole point is the recurring trigger. Returns { harness, all }.
+export function detectHarness(cwd = process.cwd()) {
+  const all = HARNESSES.filter((h) => {
+    try {
+      return h.detect(cwd);
+    } catch {
+      return false;
+    }
+  });
+  const scheduler = all.find((h) => h.canSchedule);
+  return { harness: scheduler || all[0] || null, all };
+}

package/src/install.mjs

@@ -0,0 +1,165 @@
+// The install flow (SPEC §3): fetch+validate LOOP.md -> install skills ->
+// pre-flight `requires` (prompt-or-refuse, never auto-install) -> register the
+// scheduled job -> (on success) anonymous telemetry ping.
+import { fetchLoopMd, parseLoopMd, validateManifest, triggerOf } from "./loop.mjs";
+import { detectHarness, getHarness } from "./harness.mjs";
+import { planSkills, installSkill } from "./skills.mjs";
+import { preflight } from "./preflight.mjs";
+import { parseSchedule, registerTrigger, saveRecord } from "./schedule.mjs";
+import { pingInstall, telemetryDisabled } from "./telemetry.mjs";
+import { loadRegistry, resolveSlug } from "./registry.mjs";
+import { c, sym, info, ok, warn, fail, step, confirm, ask, CliError } from "./util.mjs";
+
+export async function install(ref, opts = {}) {
+  const assumeYes = !!opts.yes;
+  const dryRun = !!opts.dryRun;
+
+  // 0. Resolve a bare slug to owner/repo via the registry, if needed.
+  let loopRef = ref;
+  if (!ref.includes("/")) {
+    const { loops } = await loadRegistry();
+    const resolved = resolveSlug(loops, ref);
+    if (!resolved)
+      throw new CliError(
+        `"${ref}" is a bare slug I can't resolve to a repo. Use owner/repo, or find it: agenticloops find ${ref}`,
+        4,
+      );
+    info(`resolved ${c.bold(ref)} -> ${c.bold(resolved)}`);
+    loopRef = resolved;
+  }
+
+  // 1. Fetch + validate the LOOP.md.
+  step("Fetching loop");
+  const fetched = await fetchLoopMd(loopRef);
+  const { manifest, prompt } = parseLoopMd(fetched.raw);
+  const errs = validateManifest(manifest);
+  if (errs.length) {
+    errs.forEach((e) => fail(e));
+    throw new CliError("LOOP.md failed validation against spec v0.1", 3);
+  }
+  const slug = manifest.name;
+  const trig = triggerOf(manifest);
+  ok(`${c.bold(manifest.name)} — ${manifest.description?.split("\n")[0] ?? ""}`);
+  info(`trigger: ${trig.kind === "event" ? `on ${trig.value}` : trig.value}`);
+
+  // 2. Pick the harness (auto-detect unless --harness given) + warn if it can't schedule.
+  step("Target harness");
+  let harness;
+  if (opts.harness) {
+    harness = getHarness(opts.harness);
+    if (!harness) throw new CliError(`unknown harness "${opts.harness}"`, 2);
+    info(`harness: ${c.bold(harness.label)}`);
+  } else {
+    const det = detectHarness();
+    harness = det.harness;
+    if (!harness)
+      throw new CliError(
+        "no harness detected here. Pass --harness=<5dive|github-actions|claude-code|cron|cursor>",
+        4,
+      );
+    info(`auto-detected: ${c.bold(harness.label)}${det.all.length > 1 ? c.dim(` (of ${det.all.map((h) => h.id).join(", ")})`) : ""}`);
+  }
+  if (trig.needsScheduler && !harness.canSchedule) {
+    warn(
+      `${harness.label} can run the agent but cannot honor a recurring schedule. ` +
+        `The loop will be installed but won't fire on its own — target a scheduling harness ` +
+        `(--harness=5dive | github-actions | cron) to schedule it.`,
+    );
+    if (!(await confirm("Install anyway (unscheduled)?", { fallback: false, assumeYes }))) {
+      throw new CliError("aborted — no scheduling harness", 1);
+    }
+  }
+
+  // 3. Install skills (§3.1) — host-satisfied skipped, paths fetched, bare resolved.
+  const skillPlan = await planSkills(manifest.skills || [], opts.hostSkills || []);
+  if (skillPlan.length) {
+    step("Skills");
+    for (const s of skillPlan) {
+      if (s.action === "host") info(`${s.id} ${c.dim("(provided by harness — skipped)")}`);
+      else if (s.action === "unresolved") warn(`${s.id} — unresolvable, skipped (loop will degrade)`);
+      else {
+        const r = installSkill(s, { dryRun });
+        if (r.ok) ok(`${s.id} ${c.dim("<- " + s.owner + "/" + s.repo)}`);
+        else warn(`${s.id} — install failed (exit ${r.status}); skipped`);
+      }
+    }
+  }
+
+  // 4. Pre-flight `requires` — declare-and-check, prompt-or-refuse, never auto-install.
+  const pf = preflight(manifest.requires, { harness });
+  const needsCheck =
+    (manifest.requires &&
+      (manifest.requires.cli || manifest.requires.secrets || manifest.requires.mcp || manifest.requires.network)) ||
+    false;
+  if (needsCheck) {
+    step("Pre-flight (requires)");
+    pf.cli.forEach((x) => (x.present ? ok(`cli ${x.bin}`) : fail(`cli ${x.bin} — not on PATH`)));
+    pf.secrets.forEach((x) =>
+      x.present ? ok(`secret ${x.name}`) : fail(`secret ${x.name} — not set`),
+    );
+    pf.mcp.forEach((x) => info(`mcp ${x.name} ${c.dim("(must be configured + consented — not auto-launched)")}`));
+    pf.network.forEach((x) => info(`network ${x.host} ${c.dim("(egress the loop will use)")}`));
+
+    if (pf.hasBlockers) {
+      if (pf.missing.cli.length)
+        warn(`missing binaries: ${pf.missing.cli.join(", ")} — install them yourself (never auto-installed)`);
+      if (pf.missing.secrets.length) {
+        warn(`missing secrets: ${pf.missing.secrets.join(", ")}`);
+        // Offer to capture values interactively; they are stored host-side only,
+        // never written into LOOP.md or sent anywhere.
+        for (const name of pf.missing.secrets) {
+          if (process.stdin.isTTY && !assumeYes) {
+            const v = await ask(`  set ${name} now? (leave blank to skip)`);
+            if (v) process.env[name] = v;
+          }
+        }
+      }
+      const stillMissing =
+        pf.missing.cli.length > 0 ||
+        pf.missing.secrets.some((n) => !process.env[n]);
+      if (stillMissing && !(await confirm("Some requirements are unmet. Install anyway?", { fallback: false, assumeYes }))) {
+        throw new CliError("aborted — unmet requirements (nothing was auto-installed)", 1);
+      }
+    }
+  }
+
+  // 5. Register the trigger on the harness + persist the local record.
+  step("Register");
+  const sched = trig.needsScheduler ? parseSchedule(manifest.schedule) : { cron: null };
+  if (trig.needsScheduler && !sched.cron) {
+    warn(`could not parse schedule "${manifest.schedule}" to cron — registering as-is`);
+  }
+  const record = {
+    slug,
+    ref: loopRef,
+    source: fetched.url,
+    harness: harness.id,
+    trigger: trig,
+    cron: sched.cron || null,
+    description: manifest.description,
+    installedAt: new Date().toISOString(),
+  };
+  if (!dryRun) saveRecord(slug, record, fetched.raw);
+  const reg = registerTrigger(harness.id, {
+    slug,
+    name: manifest.name,
+    prompt,
+    cron: sched.cron || manifest.schedule || "",
+    dryRun,
+  });
+  if (reg.ok) ok(reg.detail || `registered on ${harness.label}`);
+  else warn(`trigger registration reported a problem: ${reg.detail || reg.status}`);
+
+  // 6. Anonymous telemetry (opt-out) — only on a successful install.
+  const optedOut = telemetryDisabled({ flag: opts.noTelemetry });
+  if (!dryRun) {
+    const t = await pingInstall(slug, { disabled: optedOut });
+    if (optedOut) info(c.dim("telemetry: opted out"));
+    else if (t.sent) info(c.dim("telemetry: counted (anonymous: slug + ts only)"));
+  }
+
+  step(`${sym.ok} Installed ${c.bold(slug)} on ${harness.label}${dryRun ? c.dim(" (dry-run)") : ""}`);
+  if (reg.scheduled === false && trig.needsScheduler)
+    info(`it won't fire until you wire a scheduler — see ${c.cyan("agenticloops list")}`);
+  return record;
+}

package/src/loop.mjs

@@ -0,0 +1,113 @@
+// Fetch, parse, and validate a LOOP.md against the spec (v0.1).
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { fetchText, CliError } from "./util.mjs";
+
+const BRANCHES = ["main", "master", "HEAD"];
+
+// A ref points at the local filesystem if it's a path to a LOOP.md or a dir
+// containing one. Lets you install/validate a loop you're authoring locally.
+function localLoopPath(ref) {
+  if (!(ref.startsWith(".") || isAbsolute(ref) || ref.endsWith("LOOP.md"))) return null;
+  const p = isAbsolute(ref) ? ref : join(process.cwd(), ref);
+  if (!existsSync(p)) return null;
+  const file = statSync(p).isDirectory() ? join(p, "LOOP.md") : p;
+  return existsSync(file) ? file : null;
+}
+
+// A loop ref is a GitHub shorthand:
+//   owner/repo                -> LOOP.md at repo root
+//   owner/repo/sub/dir        -> LOOP.md inside that subdirectory
+// (A bare registry slug is resolved upstream in install.mjs before we get here.)
+export function parseRef(ref) {
+  const parts = String(ref).trim().replace(/^\/+|\/+$/g, "").split("/");
+  if (parts.length < 2) {
+    throw new CliError(
+      `"${ref}" is not a valid loop reference — expected owner/repo or owner/repo/path`,
+      2,
+    );
+  }
+  const [owner, repo, ...rest] = parts;
+  const subpath = rest.join("/");
+  return { owner, repo, subpath, slug: rest.length ? rest[rest.length - 1] : repo };
+}
+
+function rawUrl(owner, repo, branch, subpath) {
+  const dir = subpath ? `${subpath}/` : "";
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${dir}LOOP.md`;
+}
+
+// Try each branch in turn; return the first LOOP.md found.
+export async function fetchLoopMd(ref) {
+  const local = localLoopPath(ref);
+  if (local) {
+    const slug = ref.replace(/\/?LOOP\.md$/, "").split("/").filter(Boolean).pop() || "local-loop";
+    return { raw: readFileSync(local, "utf8"), url: local, owner: null, repo: null, subpath: null, slug, branch: null, local: true };
+  }
+  const { owner, repo, subpath, slug } = parseRef(ref);
+  for (const branch of BRANCHES) {
+    const url = rawUrl(owner, repo, branch, subpath);
+    const r = await fetchText(url);
+    if (r.ok) return { raw: r.text, url, owner, repo, subpath, slug, branch };
+  }
+  throw new CliError(
+    `No LOOP.md found for ${owner}/${repo}${subpath ? "/" + subpath : ""} ` +
+      `(tried ${BRANCHES.join(", ")}). Is the repo public and does it contain a LOOP.md?`,
+    4,
+  );
+}
+
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
+
+// Split a LOOP.md into { manifest, prompt }. Manifest is YAML frontmatter; the
+// body is the starter prompt (markdown).
+export function parseLoopMd(raw) {
+  const m = raw.match(FRONTMATTER_RE);
+  if (!m) {
+    throw new CliError("LOOP.md has no YAML frontmatter (expected a leading --- block)", 3);
+  }
+  let manifest;
+  try {
+    manifest = parseYaml(m[1]) || {};
+  } catch (e) {
+    throw new CliError(`LOOP.md frontmatter is not valid YAML: ${e.message}`, 3);
+  }
+  return { manifest, prompt: (m[2] || "").trim() };
+}
+
+// Validate the manifest against the required-field rules in §2. Returns a list
+// of human-readable error strings (empty = valid). Unknown fields are ignored
+// per §5 (forward-compatible).
+export function validateManifest(manifest) {
+  const errs = [];
+  const m = manifest || {};
+  if (!m.name || typeof m.name !== "string") errs.push("missing required `name`");
+  else if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(m.name))
+    errs.push("`name` must be kebab-case, ≤ 64 chars");
+  if (!m.description || typeof m.description !== "string")
+    errs.push("missing required `description`");
+  if (!m.schedule && !m.event)
+    errs.push("missing a trigger — set `schedule` (or `event`)");
+
+  if (m.tier && !["frontier", "standard", "fast"].includes(m.tier))
+    errs.push("`tier` must be one of frontier | standard | fast (never a vendor model)");
+  if (m.effort && !["low", "medium", "high"].includes(m.effort))
+    errs.push("`effort` must be low | medium | high");
+  if (m.concurrency && !["skip", "queue", "replace", "allow"].includes(m.concurrency))
+    errs.push("`concurrency` must be skip | queue | replace | allow");
+  if (m.skills && !Array.isArray(m.skills)) errs.push("`skills` must be a list");
+  if (m.requires && typeof m.requires !== "object") errs.push("`requires` must be a mapping");
+
+  return errs;
+}
+
+// A trigger that a harness must be able to honor. `schedule` accepts human
+// grammar or raw cron; we don't expand it here — adapters do — but we surface a
+// label and whether scheduling (vs event) is needed.
+export function triggerOf(manifest) {
+  if (manifest.event) {
+    return { kind: "event", value: String(manifest.event), needsScheduler: false };
+  }
+  return { kind: "schedule", value: String(manifest.schedule), needsScheduler: true };
+}

package/src/preflight.mjs

@@ -0,0 +1,35 @@
+// Pre-flight the loop's `requires` (§3.2). This is DECLARE-AND-CHECK: we verify
+// the environment and prompt-or-refuse for what's missing. We NEVER auto-install
+// a binary, mint a secret, or launch an MCP server — that consent is the user's.
+import { execSync } from "node:child_process";
+
+function onPath(bin) {
+  try {
+    execSync(`command -v ${bin}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Returns a structured report. `missing` lists what blocks a clean install.
+export function preflight(requires = {}, { harness } = {}) {
+  const r = requires || {};
+  const cli = (r.cli || []).map((bin) => ({ bin, present: onPath(bin) }));
+  const secrets = (r.secrets || []).map((name) => ({
+    name,
+    present: typeof process.env[name] === "string" && process.env[name] !== "",
+  }));
+  // MCP + network are environment expectations we can't fully verify from here:
+  // we surface them for consent rather than asserting pass/fail.
+  const mcp = (r.mcp || []).map((name) => ({ name }));
+  const network = (r.network || []).map((host) => ({ host }));
+
+  const missing = {
+    cli: cli.filter((x) => !x.present).map((x) => x.bin),
+    secrets: secrets.filter((x) => !x.present).map((x) => x.name),
+  };
+  const hasBlockers = missing.cli.length > 0 || missing.secrets.length > 0;
+
+  return { cli, secrets, mcp, network, missing, hasBlockers, harness };
+}

package/src/registry.mjs

@@ -0,0 +1,47 @@
+// The public directory — used by `find` and to resolve a bare slug to an
+// installable owner/repo. We read the site's bundled loops.json (richest: core
+// + imported with source attribution) and fall back to the spec index.json.
+import { fetchJson } from "./util.mjs";
+import { SITE_REGISTRY_URL, SPEC_REGISTRY_URL } from "./config.mjs";
+
+export async function loadRegistry() {
+  for (const url of [SITE_REGISTRY_URL, SPEC_REGISTRY_URL]) {
+    const r = await fetchJson(url);
+    if (r.ok && r.json) {
+      const loops = Array.isArray(r.json) ? r.json : r.json.loops || [];
+      if (loops.length) return { loops, url };
+    }
+  }
+  return { loops: [], url: null };
+}
+
+const hay = (l) =>
+  [l.slug, l.jobTitle, l.tagline, l.description, ...(l.tags || [])]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+
+export function search(loops, query) {
+  if (!query) return loops;
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return loops
+    .map((l) => {
+      const h = hay(l);
+      const score = terms.reduce((s, t) => s + (h.includes(t) ? 1 : 0), 0);
+      return { l, score };
+    })
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map((x) => x.l);
+}
+
+// Resolve a registry slug to an installable owner/repo[/path], when the entry
+// records its source. Core 5dive loops live under the canonical loops repo.
+export function resolveSlug(loops, slug) {
+  const l = loops.find((x) => x.slug === slug);
+  if (!l) return null;
+  if (l.source && l.source.repo) return l.source.repo; // "owner/repo" or "owner/repo/path"
+  if (l.repo) return l.repo;
+  if (l.imported) return null; // imported but no resolvable source
+  return `5dive-ai/loops/${slug}`; // core loop convention
+}

package/src/schedule.mjs

@@ -0,0 +1,156 @@
+// Trigger registration. Two halves:
+//   1. parseSchedule() — the human grammar in §2 -> 5-field cron (or passthrough)
+//   2. harness adapters — actually register the recurring job on the target
+// Every install also persists a local record under the state dir, so `list`
+// and `update` work regardless of how the harness schedules.
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+export const STATE_DIR = join(homedir(), ".agenticloops", "loops");
+
+const DOW = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+
+// Human schedule grammar -> cron. Throws nothing; returns { cron } or { cron:null, raw }.
+export function parseSchedule(input) {
+  if (!input) return { cron: null, raw: input };
+  const s = String(input).trim().toLowerCase();
+
+  // Already a 5-field cron expression.
+  if (/^[\d*/,\-?]+(\s+[\d*/,\-?a-z]+){4}$/.test(s)) return { cron: s };
+
+  const at = s.match(/@\s*(\d{1,2}):(\d{2})/);
+  const hh = at ? Number(at[1]) : 0;
+  const mm = at ? Number(at[2]) : 0;
+
+  let m;
+  if ((m = s.match(/^every\s+(\d+)\s*h(ours?)?$/))) return { cron: `0 */${m[1]} * * *` };
+  if ((m = s.match(/^every\s+(\d+)\s*m(in(utes?)?)?$/))) return { cron: `*/${m[1]} * * * *` };
+  if (/^hourly$/.test(s)) return { cron: "0 * * * *" };
+  if (/^daily/.test(s)) return { cron: `${mm} ${hh} * * *` };
+  if (/^weekdays?/.test(s)) return { cron: `${mm} ${hh} * * 1-5` };
+  if (/^weekly/.test(s)) return { cron: `${mm} ${hh} * * 0` };
+  if ((m = s.match(/^(?:every\s+)?(sun|mon|tue|wed|thu|fri|sat)/))) {
+    return { cron: `${mm} ${hh} * * ${DOW[m[1]]}` };
+  }
+  return { cron: null, raw: input };
+}
+
+export function recordPath(slug) {
+  return join(STATE_DIR, slug);
+}
+
+// Persist the installed loop locally (the source of truth for list/update).
+export function saveRecord(slug, data, raw) {
+  const dir = recordPath(slug);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "LOOP.md"), raw, "utf8");
+  writeFileSync(join(dir, "meta.json"), JSON.stringify(data, null, 2), "utf8");
+}
+
+export function listRecords() {
+  if (!existsSync(STATE_DIR)) return [];
+  return readdirSync(STATE_DIR)
+    .map((slug) => {
+      try {
+        return JSON.parse(readFileSync(join(STATE_DIR, slug, "meta.json"), "utf8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function removeRecord(slug) {
+  const dir = recordPath(slug);
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+// --- harness adapters: register the recurring trigger -----------------------
+
+function registerOn5dive({ name, prompt, cron, dryRun }) {
+  const args = ["task", "add", name, "--body", prompt, "--recurring", cron];
+  if (dryRun) return { ok: true, detail: `5dive ${args.join(" ")}`, skipped: "dry-run" };
+  const res = spawnSync("5dive", args, { stdio: "inherit" });
+  return { ok: res.status === 0, detail: `5dive ${args.join(" ")}`, status: res.status };
+}
+
+function registerGithubActions({ slug, name, cron, prompt, dryRun }) {
+  const wf = join(process.cwd(), ".github", "workflows", `loop-${slug}.yml`);
+  const yml = `# Generated by agenticloops — agentic loop "${name}"
+name: loop-${slug}
+on:
+  schedule:
+    - cron: "${cron}"
+  workflow_dispatch: {}
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # TODO: invoke your agent harness with the starter prompt below.
+      # The prompt is committed at .agenticloops/${slug}.prompt.md
+      - run: echo "run loop ${slug}"
+`;
+  if (dryRun) return { ok: true, detail: `write ${wf}`, skipped: "dry-run" };
+  mkdirSync(join(process.cwd(), ".github", "workflows"), { recursive: true });
+  writeFileSync(wf, yml, "utf8");
+  mkdirSync(join(process.cwd(), ".agenticloops"), { recursive: true });
+  writeFileSync(join(process.cwd(), ".agenticloops", `${slug}.prompt.md`), prompt, "utf8");
+  return { ok: true, detail: `wrote ${wf}` };
+}
+
+// Generic cron: write a runner stub + the exact crontab line, but DON'T edit
+// the user's crontab silently (invasive). The runner holds the starter prompt;
+// the user drops in their harness's run command and installs the line.
+function registerCron({ slug, name, prompt, cron, dryRun }) {
+  const dir = recordPath(slug);
+  const runner = join(dir, "run.sh");
+  const line = `${cron} ${runner}  # agenticloops loop "${name}"`;
+  if (dryRun) return { ok: true, scheduled: false, detail: `would scaffold ${runner} + crontab line` };
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    runner,
+    `#!/usr/bin/env bash
+# agenticloops runner for "${name}". Schedule: ${cron}
+# The starter prompt is below. Replace the TODO with your harness's run command
+# (e.g. \`claude -p\`, \`codex exec\`, or \`5dive agent send <agent>\`).
+set -euo pipefail
+PROMPT="$(cat "$(dirname "$0")/prompt.md")"
+# TODO: pipe "$PROMPT" into your agent harness here.
+echo "$PROMPT"
+`,
+    { mode: 0o755 },
+  );
+  writeFileSync(join(dir, "prompt.md"), prompt, "utf8");
+  return {
+    ok: true,
+    scheduled: false,
+    detail: `scaffolded ${runner} — add to crontab:  ${line}`,
+  };
+}
+
+// For an interactive-only harness we record the loop but cannot honor the
+// trigger; the caller has already warned. We still write the local record so
+// the user can wire their own scheduler.
+function registerLocalOnly({ slug }) {
+  return {
+    ok: true,
+    detail: `recorded under ${recordPath(slug)} (no scheduler — wire cron or a scheduling harness)`,
+    scheduled: false,
+  };
+}
+
+export function registerTrigger(harnessId, ctx) {
+  switch (harnessId) {
+    case "5dive":
+      return { scheduled: true, ...registerOn5dive(ctx) };
+    case "github-actions":
+      return { scheduled: true, ...registerGithubActions(ctx) };
+    case "cron":
+      return registerCron(ctx);
+    default:
+      return registerLocalOnly(ctx);
+  }
+}

package/src/skills.mjs

@@ -0,0 +1,66 @@
+// Skill resolution + install (§3.1). Three tiers, in order:
+//   1. host-satisfied  — harness already provides it -> use as-is, fetch nothing
+//   2. path-resolved    — owner/repo/skill -> fetch from that public repo
+//   3. registry-resolved — a bare name -> the skills.sh index's canonical entry
+// An unresolvable skill is skipped with a warning, never a hard failure (§3.1).
+import { spawnSync } from "node:child_process";
+import { fetchJson } from "./util.mjs";
+import { SKILLS_REGISTRY_URL } from "./config.mjs";
+
+// Normalise one `skills:` entry into { id, owner, repo } or { id, bare:true }.
+export function parseSkillEntry(entry) {
+  if (entry && typeof entry === "object") {
+    // { id, source: "owner/repo" }
+    const src = entry.source ? String(entry.source).split("/") : [];
+    return { id: entry.id, owner: src[0], repo: src[1] };
+  }
+  const parts = String(entry).split("/");
+  if (parts.length >= 3) return { id: parts[2], owner: parts[0], repo: parts[1] };
+  if (parts.length === 2) return { id: parts[1], owner: parts[0], repo: parts[1] };
+  return { id: parts[0], bare: true };
+}
+
+async function resolveBare(id) {
+  const r = await fetchJson(SKILLS_REGISTRY_URL);
+  if (!r.ok || !r.json) return null;
+  // The skills.sh index is a name -> owner/repo map (shape-tolerant lookup).
+  const idx = r.json;
+  const hit =
+    idx[id] ||
+    (Array.isArray(idx.skills) && idx.skills.find((s) => s.name === id || s.id === id)) ||
+    (Array.isArray(idx) && idx.find((s) => s.name === id || s.id === id));
+  if (!hit) return null;
+  const src = (hit.source || hit.repo || hit || "").toString().split("/");
+  if (src.length >= 2) return { id, owner: src[0], repo: src[1] };
+  return null;
+}
+
+// Build an install plan without side effects. `hostSkills` = names the harness
+// already provides (skipped). Returns [{ id, action, owner?, repo? }].
+export async function planSkills(skills = [], hostSkills = []) {
+  const host = new Set(hostSkills);
+  const plan = [];
+  for (const raw of skills) {
+    const s = parseSkillEntry(raw);
+    if (host.has(s.id)) {
+      plan.push({ id: s.id, action: "host" });
+      continue;
+    }
+    if (s.owner && s.repo) {
+      plan.push({ id: s.id, action: "fetch", owner: s.owner, repo: s.repo });
+      continue;
+    }
+    const resolved = await resolveBare(s.id);
+    if (resolved) plan.push({ id: resolved.id, action: "fetch", owner: resolved.owner, repo: resolved.repo });
+    else plan.push({ id: s.id, action: "unresolved" });
+  }
+  return plan;
+}
+
+// Execute one fetch via the skills.sh CLI: `npx skills add <owner/repo> --skill <id>`.
+export function installSkill({ owner, repo, id }, { dryRun = false } = {}) {
+  const args = ["--yes", "skills", "add", `${owner}/${repo}`, "--skill", id];
+  if (dryRun) return { ok: true, cmd: `npx ${args.join(" ")}`, skipped: "dry-run" };
+  const res = spawnSync("npx", args, { stdio: "inherit" });
+  return { ok: res.status === 0, cmd: `npx ${args.join(" ")}`, status: res.status };
+}

package/src/telemetry.mjs

@@ -0,0 +1,51 @@
+// Anonymous install telemetry. On a SUCCESSFUL install the CLI fires a single
+// fire-and-forget ping: { slug, ts } and nothing else. No PII, no IP logging
+// intent, no machine id. Opt out with --no-telemetry, AGENTICLOOPS_NO_TELEMETRY=1,
+// or the cross-tool DO_NOT_TRACK=1 standard. Failure is silent — telemetry must
+// never block or break an install.
+import { TELEMETRY_URL, UA } from "./config.mjs";
+
+export function telemetryDisabled({ flag = false } = {}) {
+  return (
+    flag ||
+    process.env.AGENTICLOOPS_NO_TELEMETRY === "1" ||
+    process.env.DO_NOT_TRACK === "1"
+  );
+}
+
+export async function pingInstall(slug, { disabled = false, timeout = 4000 } = {}) {
+  if (disabled || telemetryDisabled()) return { sent: false, reason: "opted-out" };
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeout);
+  try {
+    const r = await fetch(TELEMETRY_URL, {
+      method: "POST",
+      signal: ctrl.signal,
+      headers: { "content-type": "application/json", "user-agent": UA },
+      // ts is the client's send time; the server stamps its own authoritative
+      // time. slug is the only identifying field, and it's a public loop id.
+      body: JSON.stringify({ slug, ts: new Date().toISOString() }),
+    });
+    return { sent: r.ok, status: r.status };
+  } catch (e) {
+    return { sent: false, reason: e.name === "AbortError" ? "timeout" : e.message };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// GET the per-slug tallies (used by `list` to annotate, and by the site UI).
+export async function fetchInstalls({ timeout = 6000 } = {}) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeout);
+  try {
+    const r = await fetch(TELEMETRY_URL, { signal: ctrl.signal, headers: { "user-agent": UA } });
+    if (!r.ok) return {};
+    const j = await r.json();
+    return j.installs || j.counts || j || {};
+  } catch {
+    return {};
+  } finally {
+    clearTimeout(t);
+  }
+}

package/src/util.mjs

@@ -0,0 +1,98 @@
+// Small shared helpers — TTY-aware colour, prompts, fetch-with-timeout.
+import { createInterface } from "node:readline";
+
+const useColor =
+  process.stdout.isTTY && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
+
+const wrap = (open, close) => (s) => (useColor ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+export const c = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  cyan: wrap(36, 39),
+};
+
+export const sym = {
+  ok: c.green("✓"),
+  warn: c.yellow("⚠"),
+  err: c.red("✗"),
+  info: c.cyan("›"),
+  bullet: c.dim("•"),
+};
+
+export function info(msg) {
+  process.stderr.write(`${sym.info} ${msg}\n`);
+}
+export function ok(msg) {
+  process.stderr.write(`${sym.ok} ${msg}\n`);
+}
+export function warn(msg) {
+  process.stderr.write(`${sym.warn} ${c.yellow(msg)}\n`);
+}
+export function fail(msg) {
+  process.stderr.write(`${sym.err} ${c.red(msg)}\n`);
+}
+export function step(msg) {
+  process.stderr.write(`\n${c.bold(msg)}\n`);
+}
+
+export class CliError extends Error {
+  constructor(message, code = 1) {
+    super(message);
+    this.code = code;
+  }
+}
+
+// Yes/no prompt. Non-interactive (no TTY) returns `fallback` so CI doesn't hang.
+export async function confirm(question, { fallback = false, assumeYes = false } = {}) {
+  if (assumeYes) return true;
+  if (!process.stdin.isTTY) return fallback;
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const ans = (await new Promise((res) => rl.question(`${question} ${c.dim("[y/N]")} `, res)))
+      .trim()
+      .toLowerCase();
+    return ans === "y" || ans === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+// Free-text prompt (used for missing secrets). Returns "" non-interactively.
+export async function ask(question) {
+  if (!process.stdin.isTTY) return "";
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return (await new Promise((res) => rl.question(`${question} `, res))).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function fetchText(url, { timeout = 15000 } = {}) {
+  const { UA } = await import("./config.mjs");
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeout);
+  try {
+    const r = await fetch(url, { signal: ctrl.signal, headers: { "user-agent": UA } });
+    if (!r.ok) return { ok: false, status: r.status };
+    return { ok: true, status: r.status, text: await r.text() };
+  } catch (e) {
+    return { ok: false, status: 0, error: e.message };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export async function fetchJson(url, opts) {
+  const r = await fetchText(url, opts);
+  if (!r.ok) return r;
+  try {
+    return { ok: true, status: r.status, json: JSON.parse(r.text) };
+  } catch (e) {
+    return { ok: false, status: r.status, error: `bad JSON: ${e.message}` };
+  }
+}