@sayansr26/agent-os 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] — 2026-09-15
+
+Found by running 0.5.0 against a real repository that already had six
+path-scoped rules and a hand-written `AGENTS.md`. It overwrote the
+`AGENTS.md`. 0.5.0 was never published.
+
+### Added
+- **`init` installs the Claude Code plugin.** When Claude Code is detected it
+  runs `claude plugin marketplace add` and `claude plugin install --yes` at
+  project scope, so the plugin travels with the repository rather than living
+  on one machine. If the `claude` CLI is not on PATH it prints the two slash
+  commands instead. `--no-plugin` skips it, and the rules are written either
+  way — the compiler never depends on the plugin step succeeding.
+
+### Fixed
+- **`init` scaffolded over projects that already had rules.** It wrote a
+  placeholder `AGENTS.md` and an `example.md` rule regardless of what was
+  there, and the next `sync` compiled the placeholder on top of the project's
+  real `AGENTS.md`. `init` now adopts what it finds — the existing `AGENTS.md`
+  and the first rules directory it recognises, `.cursor/rules/*.mdc` converted
+  back to `paths:` — and seeds `example.md` only when there was nothing to
+  adopt. A tool for stopping rule drift must not cause it.
+- **`sync` now refuses to overwrite a file it did not generate.** Generated
+  files carry a banner; anything else at a generated path is the user's own
+  work. `sync` names those files, leaves them alone and exits non-zero, with
+  `--force` as the explicit opt-out. `AGENTS.md` carries the banner too — it
+  previously did not, which is why nothing could tell it apart.
+
 ## [0.5.0] — 2026-09-15
 
 `agent-os` becomes a cross-tool CLI. The Claude Code plugin is now one target

package/README.md

@@ -76,6 +76,20 @@ Every command below is `npx @sayansr26/agent-os <command>`. Install it once —
 
 `--root <dir>` to target another directory, `--dry-run` to preview.
 
+**`init` sets up Claude Code completely.** When it detects Claude Code it also
+installs the plugin — the agents, skills, per-agent memory and session hook —
+with `claude plugin marketplace add` and `claude plugin install --yes` at
+project scope, so it travels with the repo. `--no-plugin` skips it. Every other
+detected tool gets its rules in its own schema; the plugin layer is Claude Code
+only because no other tool has anywhere to put it.
+
+**On an existing project, `init` adopts rather than scaffolds.** It takes your
+current `AGENTS.md` and the first rules directory it recognises as the source,
+so the first `sync` regenerates what you already had. **`sync` never overwrites
+a file it did not generate** — generated files carry a banner, anything else at
+that path is yours. It names those files, leaves them alone and exits 1; pass
+`--force` if you really mean to replace them.
+
 Generated files carry a banner. Edit `.agent-os/`, run `sync`, never edit the output.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayansr26/agent-os",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "One source of truth for AI coding agent config. Write your rules once; compile them to Claude Code, Cursor, Cline, Windsurf, Antigravity, Gemini CLI, OpenCode and Kilo.",
   "keywords": [
     "ai",
@@ -46,4 +46,4 @@
     "test": "node scripts/validate-plugin.mjs && node src/selftest.mjs",
     "prepublishOnly": "npm test"
   }
-}
+}

package/src/adopt.mjs

@@ -0,0 +1,80 @@
+/**
+ * Adopt what a project already has, instead of scaffolding over it.
+ *
+ * `init` used to write a placeholder `AGENTS.md` and an `example.md` rule into
+ * every project, including projects that already had a real AGENTS.md and a
+ * directory of real rules. The next `sync` then compiled the placeholder over
+ * the real file. A tool whose whole purpose is to stop rule files drifting must
+ * not destroy the rules it finds, so `init` now imports them as the source.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { BANNER } from "./source.mjs";
+
+const isGenerated = (text) => text.includes(BANNER);
+
+const readDirMd = (dir, ext) => {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(ext))
+    .map((f) => ({ name: basename(f, ext), text: readFileSync(join(dir, f), "utf8") }))
+    .filter((r) => !isGenerated(r.text));
+};
+
+/** `.cursor/rules/*.mdc` back into the canonical `paths:` / `always:` shape. */
+function fromCursor({ name, text }) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return { name, text };
+  const fields = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    if (kv) fields[kv[1]] = kv[2].trim();
+  }
+  const globs = (fields.globs || "").split(",").map((g) => g.trim()).filter(Boolean);
+  const always = String(fields.alwaysApply) === "true";
+  const fm = ["---"];
+  if (fields.description) fm.push(`description: ${fields.description}`);
+  if (always || globs.length === 0) fm.push("always: true");
+  else { fm.push("paths:"); for (const g of globs) fm.push(`  - "${g}"`); }
+  fm.push("---", "");
+  return { name, text: `${fm.join("\n")}\n${m[2].trim()}\n` };
+}
+
+/**
+ * What this project already has that should become the source.
+ * Returns `{ agents, rules, from, paths }`; `from` is what to tell the user,
+ * `paths` the files it consumed — safe for `init` to regenerate in place.
+ */
+export function adopt(root) {
+  const from = [];
+  const paths = new Set();
+  let agents = null;
+
+  const agentsPath = join(root, "AGENTS.md");
+  if (existsSync(agentsPath)) {
+    const text = readFileSync(agentsPath, "utf8");
+    if (!isGenerated(text)) { agents = text; from.push("AGENTS.md"); paths.add("AGENTS.md"); }
+  }
+
+  // In precedence order — the first store that has anything wins, because these
+  // are copies of each other in a project that was keeping them in sync by hand.
+  const sources = [
+    [".claude/rules", ".md", (r) => r],
+    [".clinerules", ".md", (r) => r],
+    [".agents/rules", ".md", (r) => r],
+    [".cursor/rules", ".mdc", fromCursor],
+    [".windsurf/rules", ".md", (r) => r],
+  ];
+
+  let rules = [];
+  for (const [dir, ext, convert] of sources) {
+    const found = readDirMd(join(root, dir), ext);
+    if (!found.length) continue;
+    rules = found.map(convert);
+    from.push(`${dir}/ (${rules.length} rule${rules.length === 1 ? "" : "s"})`);
+    for (const r of found) paths.add(`${dir}/${r.name}${ext}`);
+    break;
+  }
+
+  return { agents, rules, from, paths };
+}

package/src/cli.mjs

@@ -1,9 +1,11 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync } 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 { load, write, readIfExists, matches, BANNER, DIR } from "./source.mjs";
+import { adopt } from "./adopt.mjs";
+import { installPlugin, MARKETPLACE, MARKETPLACE_NAME, PLUGIN } from "./plugin.mjs";
 import { compile, TARGETS } from "./targets.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -25,6 +27,8 @@ ${bold("agent-os")} — one source of truth for AI coding agent config
 Options
   --root <dir>   project directory (default: cwd)
   --dry-run      print what would change, write nothing
+  --force        overwrite files agent-os did not generate (it refuses by default)
+  --no-plugin    skip installing the Claude Code plugin during init
 `;
 
 function scaffold(root, found) {
@@ -32,6 +36,17 @@ function scaffold(root, found) {
   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");
+
+  // Take what the project already has as the source. Writing a placeholder over
+  // a real AGENTS.md, then compiling the placeholder back on top of it, is the
+  // exact drift this tool exists to prevent.
+  const taken = adopt(root);
+  if (taken.agents && !existsSync(join(root, DIR, "AGENTS.md")))
+    write(root, `${DIR}/AGENTS.md`, taken.agents);
+  for (const r of taken.rules)
+    if (!existsSync(join(root, DIR, "rules", `${r.name}.md`)))
+      write(root, `${DIR}/rules/${r.name}.md`, r.text);
+
   if (!existsSync(join(root, DIR, "AGENTS.md")))
     write(root, `${DIR}/AGENTS.md`, `# Project instructions
 
@@ -42,7 +57,11 @@ 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")))
+
+  // Only seed the placeholder when there was nothing to adopt. A project with
+  // real rules does not need an `example.md` compiled into every tool it uses.
+  const anyRule = readdirSync(join(root, DIR, "rules")).some((f) => f.endsWith(".md"));
+  if (!anyRule)
     write(root, `${DIR}/rules/example.md`, `---
 description: Conventions for the API layer
 paths:
@@ -55,7 +74,7 @@ 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;
+  return { present, taken };
 }
 
 export async function main(argv) {
@@ -101,11 +120,19 @@ export async function main(argv) {
     return;
   }
 
+  let adopted = new Set();
+
   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)")}`);
+    const { present, taken } = scaffold(root, found);
+    adopted = taken.paths;
+    if (taken.from.length) {
+      console.log(`\n  adopted into ${DIR}/ ${dim("— your existing files are now the source")}`);
+      for (const f of taken.from) console.log(`    ${f}`);
+    } else {
+      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")}`);
   }
 
@@ -142,14 +169,61 @@ export async function main(argv) {
       }
       return TARGETS[t]?.label || t;
     };
+    // Never overwrite a file this tool did not write. A generated file carries
+    // the banner; anything else at that path is the user's own work, and
+    // silently compiling over it is worse than doing nothing.
+    const force = argv.includes("--force");
+    const isOurs = (f) => {
+      const cur = readIfExists(root, f.path);
+      if (cur === null) return true;                       // nothing there yet
+      if (cur.includes(BANNER)) return true;               // we wrote it
+      if (TARGETS[f.target]?.merge) return true;           // merged in place, nothing lost
+      if (adopted.has(f.path)) return true;                // init just took this as the source
+      if (matches(root, f.path, f.content) === true) return true; // already identical
+      return false;
+    };
+
+    const blocked = [];
     for (const [t, fs_] of Object.entries(byTarget)) {
       console.log(`  ${labelFor(t).padEnd(38)} ${fs_.length} file(s)`);
       for (const f of fs_) {
+        if (!force && !isOurs(f)) { blocked.push(f.path); console.log(`    ${f.path}  ${dim("SKIPPED — not generated by agent-os")}`); continue; }
         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`);
+
+    if (blocked.length) {
+      console.log(`\n${bold(`${blocked.length} file(s) left alone`)} because agent-os did not write them:\n`);
+      for (const b of blocked) console.log(`  ${b}`);
+      console.log(`
+Pick one:
+  · move the content into ${DIR}/ so it becomes the source, then re-run
+  · ${dim("--force")} to overwrite (the current content is lost — commit first)
+`);
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(`\n${dim("Generated files carry a banner. Edit .agent-os/ and re-run sync; never edit them directly.")}`);
+
+    // The rules are done and safe at this point. The Claude Code plugin is the
+    // other half — agents, skills, per-agent memory, the session hook — and it
+    // installs from the same repo. Only on `init`, never on `sync`.
+    if (cmd === "init" && targets.includes("claude-code") && !argv.includes("--no-plugin")) {
+      console.log(`\n${bold("Claude Code plugin")} ${dim(`${PLUGIN}@${MARKETPLACE_NAME}`)}\n`);
+      const r = installPlugin({ dry });
+      for (const line of r.done) console.log(`  ${dim(line)}`);
+      if (r.ok && r.reason === "installed") {
+        console.log(`\n  installed at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`);
+        console.log(`  ${dim("restart Claude Code, or /reload-plugins, then run /agent-os:init")}`);
+      } else if (!r.ok) {
+        console.log("");
+        for (const line of r.hint) console.log(`  ${line}`);
+      }
+      console.log(`\n  ${dim("--no-plugin skips this")}`);
+    }
+    console.log("");
     return;
   }
 

package/src/plugin.mjs

@@ -0,0 +1,74 @@
+/**
+ * Install the Claude Code half of agent-os during `init`.
+ *
+ * The CLI compiles rules for every tool. Claude Code additionally gets the
+ * agents, skills, per-agent memory and session hook, which ship as a plugin —
+ * so `init` should install it rather than printing two slash commands and
+ * hoping. `claude plugin ...` with `--yes` is the documented automation path.
+ *
+ * Everything here is best effort and reversible: if the `claude` CLI is not on
+ * PATH, or a command fails, `init` reports it and carries on. The rules are the
+ * part that must not depend on this.
+ */
+import { spawnSync } from "node:child_process";
+
+export const MARKETPLACE = "sayansr26/agent-os";
+export const MARKETPLACE_NAME = "sayan-plugins";
+export const PLUGIN = "agent-os";
+
+const run = (args) =>
+  spawnSync("claude", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+/** Is the Claude Code CLI usable from here? */
+export function claudeAvailable() {
+  const r = spawnSync("claude", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return !r.error && r.status === 0;
+}
+
+/**
+ * Add the marketplace and install the plugin at project scope, so the setup
+ * travels with the repository instead of living on one machine.
+ */
+export function installPlugin({ dry = false, scope = "project" } = {}) {
+  const steps = [
+    ["marketplace", ["plugin", "marketplace", "add", MARKETPLACE, "--scope", scope]],
+    ["plugin", ["plugin", "install", `${PLUGIN}@${MARKETPLACE_NAME}`, "--scope", scope, "--yes"]],
+  ];
+
+  if (!claudeAvailable())
+    return {
+      ok: false,
+      reason: "no-cli",
+      done: [],
+      hint: [
+        "The `claude` CLI is not on PATH, so the plugin was not installed.",
+        "Inside Claude Code, run:",
+        `  /plugin marketplace add ${MARKETPLACE}`,
+        `  /plugin install ${PLUGIN}@${MARKETPLACE_NAME}`,
+      ],
+    };
+
+  if (dry)
+    return { ok: true, reason: "dry-run", done: steps.map(([, a]) => `claude ${a.join(" ")}`), hint: [] };
+
+  const done = [];
+  for (const [what, args] of steps) {
+    const r = run(args);
+    if (r.status !== 0) {
+      const err = (r.stderr || r.stdout || "").trim().split("\n").slice(-3).join("\n");
+      return {
+        ok: false,
+        reason: what,
+        done,
+        hint: [
+          `\`claude ${args.join(" ")}\` failed:`,
+          ...err.split("\n").map((l) => `  ${l}`),
+          "The rules above were still written. Install the plugin by hand inside",
+          `Claude Code: /plugin install ${PLUGIN}@${MARKETPLACE_NAME}`,
+        ],
+      };
+    }
+    done.push(`claude ${args.join(" ")}`);
+  }
+  return { ok: true, reason: "installed", done, hint: [] };
+}

package/src/selftest.mjs

@@ -53,11 +53,66 @@ try {
 
   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");
+  // Realistic drift: someone edits the body of a generated file and leaves the
+  // banner in place. sync owns that file and must put it back.
+  writeFileSync(join(root, ".cursor/rules/api.mdc"),
+    read(".cursor/rules/api.mdc").replace("Validate at the boundary.", "hand edited"));
   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");
+  // Banner stripped: now indistinguishable from a hand-written file, so sync
+  // refuses rather than guessing.
+  writeFileSync(join(root, ".cursor/rules/api.mdc"), "mine now\n");
+  ok(cli(["sync"], root).status === 1, "sync refuses once the banner is gone");
+  ok(read(".cursor/rules/api.mdc") === "mine now\n", "and leaves that file untouched");
+  cli(["sync", "--force"], root);
+
+  console.log("\n  never clobbers what it did not write");
+  {
+    const r2 = mkdtempSync(join(tmpdir(), "agent-os-adopt-"));
+    mkdirSync(join(r2, ".claude/rules"), { recursive: true });
+    const realAgents = "# Real AGENTS.md\n\nCLAUDE.md is the source of truth.\n";
+    writeFileSync(join(r2, "AGENTS.md"), realAgents);
+    writeFileSync(join(r2, ".claude/rules/theming.md"),
+      '---\ndescription: Theming\npaths:\n  - "src/**/*.tsx"\n---\n\nUse the token set.\n');
+
+    const i = cli(["init", "--no-plugin"], r2);
+    ok(i.status === 0, "init exits 0 on a project that already has rules");
+    ok(readFileSync(join(r2, "AGENTS.md"), "utf8") === realAgents ||
+       readFileSync(join(r2, ".agent-os/AGENTS.md"), "utf8") === realAgents,
+       "existing AGENTS.md becomes the source rather than being replaced");
+    ok(existsSync(join(r2, ".agent-os/rules/theming.md")), "existing .claude/rules/ are adopted");
+    ok(!existsSync(join(r2, ".agent-os/rules/example.md")), "no example.md when real rules were adopted");
+    ok(!existsSync(join(r2, ".claude/rules/example.md")), "no example.md compiled into the project");
+    ok(!i.stdout.includes("Claude Code plugin"), "--no-plugin skips the plugin install");
+
+    // init offers the plugin when not told otherwise; --dry-run proves the
+    // commands without running them against the machine's real config.
+    const r4 = mkdtempSync(join(tmpdir(), "agent-os-plug-"));
+    const pi = cli(["init", "--dry-run"], r4);
+    ok(pi.stdout.includes("Claude Code plugin"), "init sets up the Claude Code plugin by default");
+    ok(/marketplace add sayansr26\/agent-os|plugin marketplace add|not on PATH/.test(pi.stdout),
+       "init names the marketplace step or says why it could not run it");
+    rmSync(r4, { recursive: true, force: true });
+
+    // A hand-written file at a generated path must survive a sync.
+    const r3 = mkdtempSync(join(tmpdir(), "agent-os-guard-"));
+    mkdirSync(join(r3, ".agent-os/rules"), { recursive: true });
+    writeFileSync(join(r3, ".agent-os/config.json"), JSON.stringify({ targets: ["claude-code"] }));
+    writeFileSync(join(r3, ".agent-os/AGENTS.md"), "# Compiled\n");
+    writeFileSync(join(r3, ".agent-os/rules/x.md"), '---\npaths:\n  - "a/**"\n---\n\nBody.\n');
+    const mine = "# Mine, by hand\n";
+    writeFileSync(join(r3, "AGENTS.md"), mine);
+    const g = cli(["sync"], r3);
+    ok(g.status === 1, "sync exits 1 rather than clobbering");
+    ok(readFileSync(join(r3, "AGENTS.md"), "utf8") === mine, "hand-written AGENTS.md survives sync");
+    ok(g.stdout.includes("SKIPPED"), "sync says which file it left alone");
+    const fg = cli(["sync", "--force"], r3);
+    ok(fg.status === 0 && readFileSync(join(r3, "AGENTS.md"), "utf8") !== mine, "--force overwrites when asked");
+    rmSync(r2, { recursive: true, force: true });
+    rmSync(r3, { recursive: true, force: true });
+  }
 
   console.log("\n  merge, not overwrite");
   writeFileSync(join(root, "opencode.json"), JSON.stringify({ model: "anthropic/x", instructions: ["KEEP.md"] }, null, 2));

package/src/targets.mjs

@@ -28,7 +28,9 @@ function agentsMd(src) {
       s.map((r) => `- \`${r.paths.join("`, `")}\` — ${r.description || r.name}`).join("\n")
     );
   }
-  return parts.filter(Boolean).join("\n\n") + "\n";
+  // The banner is what lets `sync` tell its own output from the user's file.
+  // Without it AGENTS.md is indistinguishable from hand-written work.
+  return mdHeader + parts.filter(Boolean).join("\n\n") + "\n";
 }
 
 export const TARGETS = {