@sayansr26/agent-os 0.5.1 → 0.5.3

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Context engineering and agent tooling for Claude Code.",
-    "version": "0.4.0"
+    "version": "0.4.1"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.3] — 2026-09-15
+
+### Added
+- **`init` finishes the Claude Code project setup.** Two things that are
+  neither rules nor plugin, both written at project scope only:
+  `.claude/settings.json` gets `env.CLAUDE_CODE_ENABLE_TODO_TOOLS = "1"`,
+  merged into the existing keys rather than replacing the file; and `CLAUDE.md`
+  gets the task-tracking rule, inserted under `## Operator preferences` when
+  the project keeps that heading. Both are idempotent, an existing truthy value
+  for the flag is left as the user set it, and `CLAUDE.md` is never created — a
+  project's always-loaded context should not be invented by a CLI. Nothing
+  writes to `~/.claude/`; a project setup tool has no business editing the
+  machine's global config.
+- **The validator checks release hygiene.** `package.json`'s version must have
+  a matching `## [x.y.z]` changelog section, and it must be the newest one.
+  0.5.2 shipped with no entry of its own; a deterministic check belongs in a
+  script rather than in a habit.
+
+### Changed
+- Plugin 0.4.1: the audit no longer misreports a generated rules directory as a
+  legacy store to fold into `CLAUDE.md` and delete.
+
+## [0.5.2] — 2026-09-15
+
+### 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.
+
+## [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`.
+
+### 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
@@ -40,18 +91,6 @@ among several rather than the whole product.
 - Documentation is generic throughout; examples are invented.
 
 ### 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.
 - `check` reported every skill file as drifted immediately after a `sync`. Skill
   files are read as buffers so a skill can ship a binary asset, rule files are
   generated as strings, and the two were compared with `!==`. Comparison is now

package/README.md

@@ -76,6 +76,16 @@ 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.** Beyond the rules it installs the
+plugin — agents, skills, per-agent memory, session hook — with
+`claude plugin marketplace add` and `claude plugin install --yes`, enables the
+task tools in `.claude/settings.json`, and adds the task-tracking rule to
+`CLAUDE.md` if it is not already there. All of it at **project scope**, so the
+setup travels with the repo and nothing writes to `~/.claude/`. `--no-plugin`
+skips the plugin step. 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayansr26/agent-os",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",

package/plugins/agent-os/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-os",
   "description": "A context-engineered agent system for Claude Code. Ships a durable per-project memory layer, a cartographer that maps your codebase once and remembers it, and a coordinated agent set that reads your project's rules rather than hardcoding them.",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "author": {
     "name": "Sayan Choudhury",
     "email": "sayan.choudhury.in@gmail.com"

package/src/claude-setup.mjs

@@ -0,0 +1,81 @@
+/**
+ * The two Claude Code settings that are not rules and not a plugin.
+ *
+ * Both are written at PROJECT scope only — `.claude/settings.json` and the
+ * project's `CLAUDE.md`. Nothing here touches `~/.claude/`: a project setup
+ * tool that edits the machine's global config is overreach, and the point is
+ * that the setup travels with the repository.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { write } from "./source.mjs";
+
+export const TODO_ENV = "CLAUDE_CODE_ENABLE_TODO_TOOLS";
+
+export const TASK_RULE = `- **Always track work with the task tool (TaskCreate / TaskUpdate).** Any request
+  with more than one step gets a task list before work starts: one task per
+  deliverable, marked \`in_progress\` when started and \`completed\` only when
+  verified. Keep it current as scope changes, including work delegated to
+  subagents, so I can see what is done, running and left at any moment.`;
+
+/**
+ * Turn on the todo tools in project settings, preserving every other key.
+ * Returns "added" | "present" | "conflict" | "invalid".
+ */
+export function ensureTodoEnv(root, { dry = false } = {}) {
+  const rel = ".claude/settings.json";
+  const p = join(root, rel);
+  let settings = {};
+  if (existsSync(p)) {
+    try { settings = JSON.parse(readFileSync(p, "utf8")); }
+    catch { return { status: "invalid", rel }; }
+  }
+  const env = settings.env || {};
+  const current = env[TODO_ENV];
+
+  // "true" and "1" are both truthy to Claude Code; an existing truthy value is
+  // the user's choice and is left alone rather than normalised.
+  if (current !== undefined) {
+    const on = current === "1" || current === "true" || current === true;
+    return { status: on ? "present" : "conflict", rel, current };
+  }
+
+  settings.env = { ...env, [TODO_ENV]: "1" };
+  if (!dry) write(root, rel, JSON.stringify(settings, null, 2) + "\n");
+  return { status: "added", rel };
+}
+
+/**
+ * Put the task-tracking rule in CLAUDE.md if it is not already there.
+ * Never creates CLAUDE.md — that file is the project's own always-loaded
+ * context, and inventing one from a CLI is how a project ends up with a stub
+ * nobody owns. Returns "added" | "present" | "no-file".
+ */
+export function ensureTaskRule(root, { dry = false } = {}) {
+  const rel = "CLAUDE.md";
+  const p = join(root, rel);
+  if (!existsSync(p)) return { status: "no-file", rel };
+
+  const text = readFileSync(p, "utf8");
+  if (/TaskCreate/.test(text)) return { status: "present", rel };
+
+  // Prefer the operator-preferences section if the project keeps one, so the
+  // rule lands with the other instructions about how to work rather than
+  // orphaned at the bottom of the file.
+  const heading = text.match(/^##\s+Operator preferences\s*$/m);
+  let next;
+  if (heading) {
+    const start = heading.index + heading[0].length;
+    const rest = text.slice(start);
+    const nextHeading = rest.search(/^##\s+/m);
+    const end = nextHeading === -1 ? text.length : start + nextHeading;
+    const before = text.slice(0, end).replace(/\s*$/, "");
+    next = `${before}\n\n${TASK_RULE}\n\n${text.slice(end)}`;
+  } else {
+    next = `${text.replace(/\s*$/, "")}\n\n## Working agreement\n\n${TASK_RULE}\n`;
+  }
+  next = next.replace(/\n{4,}/g, "\n\n\n");
+
+  if (!dry) write(root, rel, next);
+  return { status: "added", rel, section: heading ? "Operator preferences" : "Working agreement" };
+}

package/src/cli.mjs

@@ -5,6 +5,8 @@ import { join } from "node:path";
 import { detect, summarise, TOOLS } from "./detect.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 { ensureTodoEnv, ensureTaskRule, TODO_ENV } from "./claude-setup.mjs";
 import { compile, TARGETS } from "./targets.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -27,6 +29,7 @@ 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) {
@@ -203,7 +206,46 @@ Pick one:
       return;
     }
 
-    console.log(`\n${dim("Generated files carry a banner. Edit .agent-os/ and re-run sync; never edit them directly.")}\n`);
+    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")) {
+      console.log(`\n${bold("Claude Code setup")}\n`);
+
+      const e = ensureTodoEnv(root, { dry });
+      const eMsg = {
+        added: `  ${e.rel}  ${dim(`env.${TODO_ENV} = "1"`)}`,
+        present: `  ${e.rel}  ${dim(`env.${TODO_ENV} already set`)}`,
+        conflict: `  ${e.rel}  ${dim(`env.${TODO_ENV} is "${e.current}" — left as you set it`)}`,
+        invalid: `  ${e.rel}  ${dim("is not valid JSON — left alone, fix it and re-run")}`,
+      }[e.status];
+      console.log(eMsg);
+
+      const t = ensureTaskRule(root, { dry });
+      const tMsg = {
+        added: `  ${t.rel}  ${dim(`task-tracking rule added under ${t.section}`)}`,
+        present: `  ${t.rel}  ${dim("task-tracking rule already there")}`,
+        "no-file": `  ${t.rel}  ${dim("absent — run /agent-os:init inside Claude Code to build it")}`,
+      }[t.status];
+      console.log(tMsg);
+    }
+
+    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

@@ -77,7 +77,7 @@ try {
     writeFileSync(join(r2, ".claude/rules/theming.md"),
       '---\ndescription: Theming\npaths:\n  - "src/**/*.tsx"\n---\n\nUse the token set.\n');
 
-    const i = cli(["init"], r2);
+    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,
@@ -85,6 +85,16 @@ try {
     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-"));
@@ -104,6 +114,47 @@ try {
     rmSync(r3, { recursive: true, force: true });
   }
 
+  console.log("\n  Claude Code project setup");
+  {
+    const r5 = mkdtempSync(join(tmpdir(), "agent-os-cc-"));
+    mkdirSync(join(r5, ".claude"), { recursive: true });
+    // An existing settings.json with unrelated keys must survive untouched.
+    writeFileSync(join(r5, ".claude/settings.json"),
+      JSON.stringify({ permissions: { deny: ["Bash(git push *)"] }, env: { FOO: "bar" } }, null, 2));
+    writeFileSync(join(r5, "CLAUDE.md"),
+      "# CLAUDE.md\n\nStack notes.\n\n## Operator preferences\n\n- Never run git unasked.\n\n## Verification\n\nRun make test.\n");
+
+    cli(["init", "--no-plugin"], r5);
+    const st = JSON.parse(readFileSync(join(r5, ".claude/settings.json"), "utf8"));
+    ok(st.env.CLAUDE_CODE_ENABLE_TODO_TOOLS === "1", "todo tools enabled in project settings");
+    ok(st.env.FOO === "bar", "existing env keys preserved");
+    ok(st.permissions?.deny?.[0] === "Bash(git push *)", "existing permissions preserved");
+
+    const cm = readFileSync(join(r5, "CLAUDE.md"), "utf8");
+    ok(cm.includes("TaskCreate / TaskUpdate"), "task-tracking rule added to CLAUDE.md");
+    ok(cm.indexOf("TaskCreate") > cm.indexOf("## Operator preferences") &&
+       cm.indexOf("TaskCreate") < cm.indexOf("## Verification"),
+       "rule lands inside Operator preferences, not at the end");
+    ok(cm.includes("Never run git unasked."), "existing CLAUDE.md content preserved");
+
+    // Idempotent: a second init must not duplicate either.
+    cli(["init", "--no-plugin"], r5);
+    const cm2 = readFileSync(join(r5, "CLAUDE.md"), "utf8");
+    ok(cm2.split("TaskCreate").length - 1 === 1, "second init does not duplicate the rule");
+
+    // A user who set the flag their own way keeps their value.
+    const r6 = mkdtempSync(join(tmpdir(), "agent-os-cc2-"));
+    mkdirSync(join(r6, ".claude"), { recursive: true });
+    writeFileSync(join(r6, ".claude/settings.json"),
+      JSON.stringify({ env: { CLAUDE_CODE_ENABLE_TODO_TOOLS: "true" } }, null, 2));
+    cli(["init", "--no-plugin"], r6);
+    ok(JSON.parse(readFileSync(join(r6, ".claude/settings.json"), "utf8"))
+       .env.CLAUDE_CODE_ENABLE_TODO_TOOLS === "true", "an existing truthy value is left as the user set it");
+
+    rmSync(r5, { recursive: true, force: true });
+    rmSync(r6, { 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));
   cli(["sync"], root);