@sayansr26/agent-os 0.5.0

package/src/cli.mjs

@@ -0,0 +1,157 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { detect, summarise, TOOLS } from "./detect.mjs";
+import { load, write, readIfExists, matches, DIR } from "./source.mjs";
+import { compile, TARGETS } from "./targets.mjs";
+
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+const USAGE = `
+${bold("agent-os")} — one source of truth for AI coding agent config
+
+  agent-os init      detect your tools, create .agent-os/, compile
+  agent-os sync      recompile after editing .agent-os/
+  agent-os check     verify nothing drifted (exit 1 if it has) — for CI
+  agent-os detect    list which tools this project is set up for
+  agent-os audit     inspect the project's context layer and report findings
+  agent-os memory    inspect and health-check every memory store
+
+  Without a global install, prefix any of these with
+  ${dim("npx @sayansr26/agent-os")}
+
+Options
+  --root <dir>   project directory (default: cwd)
+  --dry-run      print what would change, write nothing
+`;
+
+function scaffold(root, found) {
+  const present = found.filter((t) => t.present).map((t) => t.id);
+  mkdirSync(join(root, DIR, "rules"), { recursive: true });
+  if (!existsSync(join(root, DIR, "config.json")))
+    write(root, `${DIR}/config.json`, JSON.stringify({ targets: present.length ? present : ["claude-code"] }, null, 2) + "\n");
+  if (!existsSync(join(root, DIR, "AGENTS.md")))
+    write(root, `${DIR}/AGENTS.md`, `# Project instructions
+
+Replace this with what is true in **every** session: how to build, how to run,
+how to verify, and the conventions that are not obvious from the code.
+
+Keep it short. Anything that only matters for part of the tree belongs in
+\`.agent-os/rules/\` instead, where it can be scoped to the files it applies to.
+`);
+  mkdirSync(join(root, DIR, "skills"), { recursive: true });
+  if (!existsSync(join(root, DIR, "rules", "example.md")))
+    write(root, `${DIR}/rules/example.md`, `---
+description: Conventions for the API layer
+paths:
+  - "src/api/**"
+---
+
+Delete this file once you have written a real one.
+
+A rule with \`paths:\` is loaded only when the agent touches a matching file, in
+every tool that supports conditional loading. Tools that do not support it get
+these as a referenced list instead of always-on text.
+`);
+  return present;
+}
+
+export async function main(argv) {
+  const cmd = argv.find((a) => !a.startsWith("-")) || "help";
+  const root = (() => { const i = argv.indexOf("--root"); return i === -1 ? process.cwd() : argv[i + 1]; })();
+  const dry = argv.includes("--dry-run");
+
+  if (cmd === "help" || argv.includes("-h") || argv.includes("--help")) { console.log(USAGE); return; }
+
+  const found = detect(root);
+
+  if (cmd === "detect") {
+    console.log(`\n${bold("Tools detected")}  ${root}\n`);
+    console.log(summarise(found));
+    console.log(`\n${dim("rules: native = same paths: schema · translate = converted · none = AGENTS.md + instructions list")}\n`);
+    return;
+  }
+
+  // Deterministic inspections. Both are plain scripts, so they run anywhere —
+  // unlike `map`, which dispatches an agent and therefore needs a model, not a
+  // CLI. That one stays a Claude Code skill.
+  const PKG = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+  const runScript = (rel, args) => {
+    const script = join(PKG, rel);
+    if (!existsSync(script)) throw new Error(`missing bundled script: ${rel}`);
+    const r = spawnSync(process.execPath, [script, ...args], { stdio: "inherit" });
+    if (r.error) throw r.error;
+    process.exitCode = r.status ?? 0;
+  };
+
+  if (cmd === "audit") {
+    console.log(`\n${bold("Tools detected")}\n`);
+    console.log(summarise(found));
+    runScript("plugins/agent-os/skills/init/scripts/audit.mjs", [root]);
+    console.log(dim("\nThe audit above is written around Claude Code's layout (CLAUDE.md,"));
+    console.log(dim(".claude/rules/, hooks, agent memory). For the other tools, `agent-os check`"));
+    console.log(dim("is the one that matters — it verifies their generated config matches source.\n"));
+    return;
+  }
+
+  if (cmd === "memory") {
+    runScript("plugins/agent-os/skills/memory/scripts/memory.mjs", argv.includes("--stale") ? [root, "--stale"] : [root]);
+    return;
+  }
+
+  if (cmd === "init") {
+    console.log(`\n${bold("agent-os init")}  ${root}\n`);
+    console.log(summarise(found));
+    const present = scaffold(root, found);
+    console.log(`\n  created ${DIR}/ ${dim("(config.json, AGENTS.md, rules/example.md)")}`);
+    if (!present.length) console.log(`  ${dim("no tools detected — defaulting to claude-code; edit .agent-os/config.json")}`);
+  }
+
+  if (cmd === "init" || cmd === "sync" || cmd === "check") {
+    const src = load(root);
+    if (!src) throw new Error(`no ${DIR}/ here. Run \`agent-os init\` first.`);
+    const targets = (src.config.targets || []).filter((t) => TARGETS[t]);
+    const unknown = (src.config.targets || []).filter((t) => !TARGETS[t]);
+    if (unknown.length) console.log(`  ${dim(`ignoring unknown target(s): ${unknown.join(", ")}`)}`);
+
+    const files = compile(src, targets, (rel) => readIfExists(root, rel));
+
+    if (cmd === "check") {
+      const state = files.map((f) => ({ f, m: matches(root, f.path, f.content) }));
+      const drifted = state.filter((s) => s.m !== true);
+      console.log(`\n${bold("agent-os check")}  ${root}\n`);
+      for (const { f, m } of state)
+        console.log(`  ${m === true ? "ok    " : m === null ? "MISSING" : "DRIFTED"} ${f.path}`);
+      if (drifted.length) {
+        console.log(`\n${drifted.length} file(s) out of date. Run \`agent-os sync\`.\n`);
+        process.exitCode = 1;
+      } else console.log(`\nAll ${files.length} generated file(s) match the source.\n`);
+      return;
+    }
+
+    console.log(`\n${bold(dry ? "would write" : "wrote")}  ${dim(`${src.rules.length} rule(s) -> ${targets.length} tool(s) + AGENTS.md`)}\n`);
+    const byTarget = {};
+    for (const f of files) (byTarget[f.target] ||= []).push(f);
+    const labelFor = (t) => {
+      if (t === "universal") return "AGENTS.md";
+      if (t.startsWith("skills:")) {
+        const ids = t.slice(7).split("+").map((i) => TARGETS[i]?.label || i);
+        return `skills → ${ids.join(", ")}`;
+      }
+      return TARGETS[t]?.label || t;
+    };
+    for (const [t, fs_] of Object.entries(byTarget)) {
+      console.log(`  ${labelFor(t).padEnd(38)} ${fs_.length} file(s)`);
+      for (const f of fs_) {
+        if (!dry) write(root, f.path, f.content);
+        console.log(`    ${f.path}`);
+      }
+    }
+    console.log(`\n${dim("Generated files carry a banner. Edit .agent-os/ and re-run sync; never edit them directly.")}\n`);
+    return;
+  }
+
+  console.log(USAGE);
+}

package/src/detect.mjs

@@ -0,0 +1,54 @@
+/**
+ * Which agent tools is this project already set up for?
+ *
+ * Detection is by evidence on disk, never by asking. A tool counts as present
+ * if its config exists here — that is the only signal that survives a fresh
+ * clone, and the only one that matters for deciding what to compile.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+
+/**
+ * `rules` — can the tool scope instructions to file globs?
+ *   "native"    same `paths:` array as the canonical source; copy verbatim
+ *   "translate" supports scoping with a different schema; must be converted
+ *   "none"      no conditional loading; gets AGENTS.md and an instructions list
+ */
+export const TOOLS = [
+  { id: "claude-code", name: "Claude Code",  rules: "native",
+    marks: [".claude", "CLAUDE.md"],            home: [".claude"] },
+  { id: "cline",       name: "Cline",        rules: "native",
+    marks: [".clinerules", ".cline"],           home: [".cline"] },
+  { id: "cursor",      name: "Cursor",       rules: "translate",
+    marks: [".cursor"],                         home: [".cursor"] },
+  { id: "windsurf",    name: "Windsurf",     rules: "translate",
+    marks: [".windsurf", ".windsurfrules", ".devin"], home: [".codeium/windsurf"] },
+  { id: "antigravity", name: "Antigravity",  rules: "translate",
+    marks: [".agents/rules", ".agent/rules"],   home: [".gemini/config"] },
+  { id: "gemini-cli",  name: "Gemini CLI",   rules: "none",
+    marks: [".gemini", "GEMINI.md"],            home: [".gemini"] },
+  { id: "opencode",    name: "OpenCode",     rules: "none",
+    marks: [".opencode", "opencode.json", "opencode.jsonc"], home: [".config/opencode"] },
+  { id: "kilo",        name: "Kilo",         rules: "none",
+    marks: [".kilo", "kilo.json", "kilo.jsonc", ".kilocode"], home: [".config/kilo"] },
+];
+
+export function detect(root) {
+  return TOOLS.map((t) => {
+    const inProject = t.marks.some((m) => existsSync(join(root, m)));
+    const onMachine = (t.home || []).some((h) => existsSync(join(HOME, h)));
+    return { ...t, inProject, onMachine, present: inProject || onMachine };
+  });
+}
+
+export function summarise(found) {
+  const lines = [];
+  for (const t of found) {
+    const where = t.inProject ? "project" : t.onMachine ? "machine only" : "—";
+    lines.push(`  ${t.present ? "✓" : " "} ${t.name.padEnd(14)} ${where.padEnd(14)} rules: ${t.rules}`);
+  }
+  return lines.join("\n");
+}

package/src/selftest.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/** End-to-end: scaffold a throwaway project, compile all 8 targets, assert the
+ *  output matches each tool's real schema, and prove drift is detected. */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const PKG = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const cli = (args, cwd) => spawnSync(process.execPath, [join(PKG, "bin/agent-os.mjs"), ...args, "--root", cwd], { encoding: "utf8" });
+let fail = 0;
+const ok = (c, m) => { console.log(`  ${c ? "ok  " : "FAIL"} ${m}`); if (!c) fail++; };
+
+const root = mkdtempSync(join(tmpdir(), "agent-os-"));
+try {
+  mkdirSync(join(root, ".agent-os/rules"), { recursive: true });
+  mkdirSync(join(root, ".agent-os/skills/demo"), { recursive: true });
+  writeFileSync(join(root, ".agent-os/config.json"), JSON.stringify({
+    targets: ["claude-code","cline","cursor","windsurf","antigravity","gemini-cli","opencode","kilo"] }));
+  writeFileSync(join(root, ".agent-os/AGENTS.md"), "# Test project\n\nBuild with `make`.\n");
+  writeFileSync(join(root, ".agent-os/rules/api.md"),
+    '---\ndescription: API conventions\npaths:\n  - "src/api/**"\n---\n\nValidate at the boundary.\n');
+  writeFileSync(join(root, ".agent-os/rules/global.md"),
+    "---\ndescription: Applies everywhere\nalways: true\n---\n\nNever commit secrets.\n");
+  writeFileSync(join(root, ".agent-os/skills/demo/SKILL.md"),
+    "---\nname: demo\ndescription: A demo skill.\n---\n\nDo the thing.\n");
+
+  const r = cli(["sync"], root);
+  ok(r.status === 0, `sync exits 0 ${r.status === 0 ? "" : "\n" + r.stderr}`);
+  const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
+
+  console.log("\n  each target gets its own schema");
+  ok(read(".claude/rules/api.md")?.includes('paths:\n  - "src/api/**"'), "Claude Code: paths: verbatim");
+  ok(read(".clinerules/api.md")?.includes('paths:\n  - "src/api/**"'), "Cline: paths: verbatim");
+  const cur = read(".cursor/rules/api.mdc");
+  ok(cur?.includes("globs: src/api/**") && cur.includes("alwaysApply: false"), "Cursor: globs + alwaysApply");
+  ok(read(".cursor/rules/global.mdc")?.includes("alwaysApply: true"), "Cursor: always rule -> alwaysApply: true");
+  ok(read(".windsurf/rules/api.md")?.includes("trigger: glob"), "Windsurf: trigger: glob");
+  ok(read(".windsurf/rules/global.md")?.includes("trigger: always_on"), "Windsurf: always rule -> always_on");
+  ok(read(".agents/rules/api.md")?.includes("Intended activation: Glob"), "Antigravity: scope stated, no invented syntax");
+  ok(JSON.parse(read(".gemini/settings.json")).context.fileName.includes("AGENTS.md"), "Gemini CLI: context.fileName");
+  ok(JSON.parse(read("opencode.json")).instructions.some((i) => i.includes("api.md")), "OpenCode: instructions array");
+  ok(JSON.parse(read("kilo.json")).instructions.some((i) => i.includes("api.md")), "Kilo: instructions array");
+
+  console.log("\n  universal + skills");
+  const am = read("AGENTS.md");
+  ok(am?.includes("Never commit secrets"), "AGENTS.md inlines always-on rules");
+  ok(am?.includes("src/api/**"), "AGENTS.md lists scoped rules rather than inlining");
+  ok(read(".agents/skills/demo/SKILL.md")?.includes("name: demo"), "skills -> .agents/skills (4 vendors)");
+  ok(read(".claude/skills/demo/SKILL.md") !== null, "skills -> .claude/skills");
+  ok(read(".cline/skills/demo/SKILL.md") !== null, "skills -> .cline/skills");
+
+  console.log("\n  drift");
+  ok(cli(["check"], root).status === 0, "check passes when in sync");
+  writeFileSync(join(root, ".cursor/rules/api.mdc"), "hand edited\n");
+  const d = cli(["check"], root);
+  ok(d.status === 1, "check exits 1 on drift");
+  ok(d.stdout.includes("DRIFTED"), "check names the drifted file");
+  ok(cli(["sync"], root).status === 0 && cli(["check"], root).status === 0, "sync repairs drift");
+
+  console.log("\n  merge, not overwrite");
+  writeFileSync(join(root, "opencode.json"), JSON.stringify({ model: "anthropic/x", instructions: ["KEEP.md"] }, null, 2));
+  cli(["sync"], root);
+  const oc = JSON.parse(read("opencode.json"));
+  ok(oc.model === "anthropic/x", "existing keys preserved");
+  ok(oc.instructions.includes("KEEP.md"), "existing instructions preserved");
+} finally { rmSync(root, { recursive: true, force: true }); }
+
+console.log(`\n${fail ? `FAILED (${fail})` : "PASSED"}\n`);
+process.exit(fail ? 1 : 0);

package/src/source.mjs

@@ -0,0 +1,102 @@
+/**
+ * The canonical source. One place you edit; everything else is generated.
+ *
+ *   .agent-os/
+ *     config.json      { targets: [...] }
+ *     AGENTS.md        instructions that apply everywhere
+ *     rules/<name>.md  --- paths: [globs] | always: true | description: ... ---
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, statSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+
+export const DIR = ".agent-os";
+export const BANNER = "agent-os: generated from .agent-os/ — edit the source, then run `npx @sayansr26/agent-os sync`";
+
+export function parseFrontmatter(text) {
+  if (!text.startsWith("---\n")) return { fields: {}, body: text };
+  const end = text.indexOf("\n---\n", 3);
+  if (end === -1) return { fields: {}, body: text };
+  const block = text.slice(4, end + 1);
+  const body = text.slice(end + 5).replace(/^\n+/, "");
+  const fields = {};
+  let key = null;
+  for (const line of block.split("\n")) {
+    const kv = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    const item = line.match(/^\s*-\s+(.*)$/);
+    if (kv) { key = kv[1]; const v = kv[2].trim(); fields[key] = v === "" ? [] : v; }
+    else if (item && key) {
+      if (!Array.isArray(fields[key])) fields[key] = [];
+      fields[key].push(item[1].trim().replace(/^["']|["']$/g, ""));
+    }
+  }
+  return { fields, body };
+}
+
+export function load(root) {
+  const dir = join(root, DIR);
+  if (!existsSync(dir)) return null;
+  const cfgPath = join(dir, "config.json");
+  const config = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, "utf8")) : { targets: [] };
+  const agents = existsSync(join(dir, "AGENTS.md")) ? readFileSync(join(dir, "AGENTS.md"), "utf8") : "";
+  const rulesDir = join(dir, "rules");
+  const rules = (existsSync(rulesDir) ? readdirSync(rulesDir) : [])
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => {
+      const { fields, body } = parseFrontmatter(readFileSync(join(rulesDir, f), "utf8"));
+      const paths = Array.isArray(fields.paths) ? fields.paths : fields.paths ? [fields.paths] : [];
+      return {
+        name: basename(f, ".md"),
+        description: typeof fields.description === "string" ? fields.description : "",
+        paths,
+        always: String(fields.always) === "true" || paths.length === 0,
+        body: body.trim(),
+      };
+    });
+  // Skills: a directory per skill, SKILL.md plus any supporting files.
+  const skillsDir = join(dir, "skills");
+  const skills = (existsSync(skillsDir) ? readdirSync(skillsDir) : [])
+    .filter((d) => existsSync(join(skillsDir, d, "SKILL.md")))
+    .map((d) => ({ name: d, files: walkRel(join(skillsDir, d)) }));
+
+  return { root, config, agents: agents.trim(), rules, skills };
+}
+
+export function write(root, rel, content) {
+  const p = join(root, rel);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+  return rel;
+}
+
+export function readIfExists(root, rel) {
+  const p = join(root, rel);
+  return existsSync(p) ? readFileSync(p, "utf8") : null;
+}
+
+/**
+ * Compare a generated file against what is on disk.
+ *
+ * Skill files are read as Buffers by `walkRel` so that a skill can ship a PNG
+ * or a zip without being mangled, while rule files are generated as strings.
+ * Comparing the two kinds with `!==` reports every skill file as drifted even
+ * immediately after a sync, so the comparison is done per kind here.
+ *
+ * Returns `null` when the file does not exist, otherwise a boolean.
+ */
+export function matches(root, rel, content) {
+  const p = join(root, rel);
+  if (!existsSync(p)) return null;
+  const cur = readFileSync(p);
+  return Buffer.isBuffer(content) ? cur.equals(content) : cur.toString("utf8") === content;
+}
+
+/** Every file under `dir`, as paths relative to it. */
+export function walkRel(dir, prefix = "") {
+  const out = [];
+  for (const e of readdirSync(dir)) {
+    const abs = join(dir, e);
+    if (statSync(abs).isDirectory()) out.push(...walkRel(abs, prefix ? `${prefix}/${e}` : e));
+    else out.push({ rel: prefix ? `${prefix}/${e}` : e, content: readFileSync(abs) });
+  }
+  return out;
+}

package/src/targets.mjs

@@ -0,0 +1,186 @@
+/**
+ * One adapter per tool. Each turns the canonical source into that tool's own
+ * format. The schemas genuinely differ — this file is where that cost is paid
+ * once instead of by every user.
+ *
+ * Every adapter returns [{ path, content }]. Adapters that must merge into an
+ * existing JSON config receive the current contents and return the merged file.
+ */
+import { BANNER } from "./source.mjs";
+
+const hdr = (comment) => `${comment} ${BANNER}\n`;
+const mdHeader = `<!-- ${BANNER} -->\n\n`;
+
+/** Rules whose `paths` are empty apply everywhere. */
+const scoped = (rules) => rules.filter((r) => !r.always);
+const universal = (rules) => rules.filter((r) => r.always);
+
+/** AGENTS.md — the one format 35+ tools read natively. */
+function agentsMd(src) {
+  const parts = [src.agents];
+  for (const r of universal(src.rules)) parts.push(`## ${r.name}\n\n${r.body}`);
+  const s = scoped(src.rules);
+  if (s.length) {
+    parts.push(
+      "## Path-scoped rules\n\n" +
+      "These apply only to matching files. Tools with conditional rule loading\n" +
+      "receive them as real scoped rules; read the relevant one before editing.\n\n" +
+      s.map((r) => `- \`${r.paths.join("`, `")}\` — ${r.description || r.name}`).join("\n")
+    );
+  }
+  return parts.filter(Boolean).join("\n\n") + "\n";
+}
+
+export const TARGETS = {
+  // ---- native `paths:` — copy verbatim -------------------------------------
+  "claude-code": {
+    label: "Claude Code",
+    files: (src) => scoped(src.rules).map((r) => ({
+      path: `.claude/rules/${r.name}.md`,
+      content: `---\npaths:\n${r.paths.map((p) => `  - "${p}"`).join("\n")}\n---\n\n${mdHeader}${r.body}\n`,
+    })),
+  },
+
+  cline: {
+    label: "Cline",
+    files: (src) => scoped(src.rules).map((r) => ({
+      path: `.clinerules/${r.name}.md`,
+      content: `---\npaths:\n${r.paths.map((p) => `  - "${p}"`).join("\n")}\n---\n\n${mdHeader}${r.body}\n`,
+    })),
+  },
+
+  // ---- translate ----------------------------------------------------------
+  cursor: {
+    label: "Cursor",
+    // .mdc, and a rule without frontmatter is ignored entirely.
+    files: (src) => src.rules.map((r) => ({
+      path: `.cursor/rules/${r.name}.mdc`,
+      content: `---\ndescription: ${r.description || r.name}\n` +
+        (r.always ? "alwaysApply: true\n" : `globs: ${r.paths.join(",")}\nalwaysApply: false\n`) +
+        `---\n\n${mdHeader}${r.body}\n`,
+    })),
+  },
+
+  windsurf: {
+    label: "Windsurf",
+    // `trigger:` rather than `alwaysApply:`. 12,000 char cap per file.
+    files: (src) => src.rules.map((r) => {
+      const body = r.body.length > 11500 ? r.body.slice(0, 11500) + "\n\n<!-- truncated: Windsurf caps rule files at 12,000 characters -->" : r.body;
+      return {
+        path: `.windsurf/rules/${r.name}.md`,
+        content: `---\ntrigger: ${r.always ? "always_on" : "glob"}\n` +
+          (r.always ? "" : `globs: ${r.paths.join(",")}\n`) +
+          `description: ${r.description || r.name}\n---\n\n${mdHeader}${body}\n`,
+      };
+    }),
+  },
+
+  antigravity: {
+    label: "Antigravity",
+    // Glob activation exists but is set in the Customizations UI — the on-disk
+    // syntax is undocumented. We write plain Markdown (which is what the docs
+    // specify a rule is) and state the intended scope in the file so it can be
+    // set by hand. 12,000 char cap.
+    files: (src) => src.rules.map((r) => {
+      const body = r.body.length > 11000 ? r.body.slice(0, 11000) + "\n\n<!-- truncated: Antigravity caps rule files at 12,000 characters -->" : r.body;
+      const scope = r.always
+        ? "Intended activation: Always On."
+        : `Intended activation: Glob — ${r.paths.join(", ")}\nSet this in Customizations → Rules; Antigravity has no documented file syntax for it.`;
+      return {
+        path: `.agents/rules/${r.name}.md`,
+        content: `${mdHeader}<!-- ${scope.replace(/\n/g, " ")} -->\n\n# ${r.description || r.name}\n\n${body}\n`,
+      };
+    }),
+  },
+
+  // ---- no conditional loading: AGENTS.md plus an instructions list ---------
+  "gemini-cli": {
+    label: "Gemini CLI",
+    // Reads GEMINI.md by default; AGENTS.md only if context.fileName says so.
+    merge: (src, existing) => {
+      const cfg = existing ? JSON.parse(existing) : {};
+      const names = new Set([].concat(cfg.context?.fileName || ["GEMINI.md"]));
+      names.add("AGENTS.md");
+      cfg.context = { ...(cfg.context || {}), fileName: [...names] };
+      return [{ path: ".gemini/settings.json", content: JSON.stringify(cfg, null, 2) + "\n" }];
+    },
+    mergeFrom: ".gemini/settings.json",
+  },
+
+  opencode: {
+    label: "OpenCode",
+    merge: (src, existing) => {
+      const cfg = existing ? JSON.parse(existing) : { $schema: "https://opencode.ai/config.json" };
+      const want = scoped(src.rules).map((r) => `.agent-os/rules/${r.name}.md`);
+      cfg.instructions = [...new Set([...(cfg.instructions || []), ...want])];
+      return [{ path: "opencode.json", content: JSON.stringify(cfg, null, 2) + "\n" }];
+    },
+    mergeFrom: "opencode.json",
+  },
+
+  kilo: {
+    label: "Kilo",
+    merge: (src, existing) => {
+      const cfg = existing ? JSON.parse(existing) : { $schema: "https://app.kilo.ai/config.json" };
+      const want = scoped(src.rules).map((r) => `.agent-os/rules/${r.name}.md`);
+      cfg.instructions = [...new Set([...(cfg.instructions || []), ...want])];
+      return [{ path: "kilo.json", content: JSON.stringify(cfg, null, 2) + "\n" }];
+    },
+    mergeFrom: "kilo.json",
+  },
+};
+
+/**
+ * Where each tool looks for skills.
+ *
+ * `.agents/skills/` is the one genuinely shared path in this whole landscape —
+ * Antigravity treats it as primary, Gemini CLI as its highest-precedence alias,
+ * and Cursor and Windsurf both read it. Four vendors, one directory, identical
+ * `name`/`description` frontmatter. So it gets written once, not four times.
+ *
+ * OpenCode and Kilo have commands rather than skills — a different concept with
+ * different invocation semantics — so they are deliberately absent.
+ */
+export const SKILL_DIRS = {
+  antigravity: ".agents/skills",
+  "gemini-cli": ".agents/skills",
+  cursor: ".agents/skills",
+  windsurf: ".agents/skills",
+  "claude-code": ".claude/skills",
+  cline: ".cline/skills",
+};
+
+/** Always written, for every project, regardless of which tools are present. */
+export const UNIVERSAL = {
+  label: "AGENTS.md",
+  files: (src) => [{ path: "AGENTS.md", content: agentsMd(src) }],
+};
+
+export function compile(src, targetIds, readExisting) {
+  const out = [];
+  out.push(...UNIVERSAL.files(src).map((f) => ({ ...f, target: "universal" })));
+
+  // Skills — deduped by destination, so `.agents/skills/` is emitted once even
+  // when four tools that read it are all enabled.
+  const dests = new Map();
+  for (const id of targetIds) {
+    const d = SKILL_DIRS[id];
+    if (!d) continue;
+    if (!dests.has(d)) dests.set(d, []);
+    dests.get(d).push(id);
+  }
+  for (const [dest, ids] of dests)
+    for (const skill of src.skills || [])
+      for (const f of skill.files)
+        out.push({ path: `${dest}/${skill.name}/${f.rel}`, content: f.content, target: `skills:${ids.join("+")}` });
+
+  for (const id of targetIds) {
+    const t = TARGETS[id];
+    if (!t) continue;
+    const files = t.merge
+      ? t.merge(src, readExisting(t.mergeFrom))
+      : t.files(src);
+    out.push(...files.map((f) => ({ ...f, target: id })));
+  }
+  return out;
+}