@sayansr26/agent-os 0.6.2 → 0.6.3

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.6.3] — 2026-10-31
+
+agent-os plugin 0.5.1 (hooks gain a Cursor mode; Claude Code behaviour
+unchanged), auto-route unchanged (0.1.0), auto-handoff unchanged (0.8.6).
+
+### Added
+- **The agent-os layer for Cursor.** With `cursor` as a target, `init` and
+  `sync` compile the seven agents to `.cursor/agents/agent-os-<name>.md`, the
+  three skills to `/agent-os-init`, `/agent-os-map` and `/agent-os-memory`, the
+  session-start and pre-edit hooks plus git write protection to
+  `.cursor/hooks/agent-os/` (registered in `.cursor/hooks.json`, merged), and
+  the agent contract to an always-on `.cursor/rules/agent-os-agents.mdc`.
+  Subagent memory uses `.claude/agent-memory/agent-os-<name>/`, the directories
+  Claude Code's plugin agents use. `{ "cursor": { "agentOs": false } }` or
+  `{ "cursor": { "gitProtection": false } }` in `.agent-os/config.json` opt out.
+- `session-resume.mjs --cursor` and `pre-edit.mjs --cursor` answer in Cursor's
+  hook protocol (`additional_context`; `permission` with an explicit `allow`).
+
+### Fixed
+- **`init` in a project that does not target Claude Code** no longer prints
+  Claude Code's SETUP block or ends `fresh → repair` with a to-do list of
+  CLAUDE.md, `.claude/settings.json` and plugin items — including one telling
+  the user to run `init` again. It now ends with what it compiled for.
+
 ## [0.6.2] — 2026-10-22
 
 agent-os plugin unchanged (0.5.0), auto-route unchanged (0.1.0). New plugin

package/README.md

@@ -110,14 +110,38 @@ Generated files carry a banner. Edit `.agent-os/`, run `sync`, never edit the ou
 
 Being straight about this matters more than the feature list.
 
-**Hooks don't port.** Every tool differs in events *and* control protocol — Cursor returns JSON `permission`, Windsurf uses exit codes, Claude Code uses JSON. There is no honest common denominator, so `agent-os` doesn't invent one.
+**Hooks don't port generically.** Every tool differs in events *and* control protocol — Cursor returns JSON `permission`, Windsurf uses exit codes, Claude Code uses JSON. There is no honest common denominator, so `agent-os` doesn't invent one for your hooks. Its own hooks are written once per tool: Claude Code (the plugin) and Cursor (see below).
 
-**Memory doesn't port.** Only Claude Code (auto memory) and Windsurf have native per-session memory. Kilo deprecated its Memory Bank in favour of `AGENTS.md`; Cline's is a community methodology, not a feature. So the architecture map — the thing that makes *"change the login flow from email to OTP"* run off known structure — works in Claude Code and nowhere else yet.
+**Memory doesn't port generically.** Only Claude Code (auto memory) and Windsurf have native per-session memory. Kilo deprecated its Memory Bank in favour of `AGENTS.md`; Cline's is a community methodology, not a feature. So the architecture map — the thing that makes *"change the login flow from email to OTP"* run off known structure — works in Claude Code and Cursor, whose subagents are told where their memory lives, and nowhere else yet.
 
 **Antigravity's rules target is best effort.** Its docs state a rule is "simply a Markdown file" and never show frontmatter; glob activation is configured in the Customizations panel. So `agent-os` writes valid Markdown and states the intended scope in a comment, rather than inventing a `globs:` key that may silently do nothing.
 
 ---
 
+## Cursor
+
+When Cursor is a target, `init` and `sync` also compile the agent-os layer into the places Cursor reads it — the same agents, skills and hooks the Claude Code plugin ships:
+
+| Claude Code (plugin) | Cursor (generated) |
+|---|---|
+| agents `agent-os:<name>` | subagents `.cursor/agents/agent-os-<name>.md` |
+| `/agent-os:init`, `/agent-os:map`, `/agent-os:memory` | `/agent-os-init`, `/agent-os-map`, `/agent-os-memory` in `.cursor/skills/` |
+| SessionStart hook | `sessionStart` hook → `additional_context` |
+| PreToolUse guard on generated files + cartographer reminder | `preToolUse` hook on `Write` |
+| git write protection in `permissions.deny` | `beforeShellExecution` hook refusing the same git commands |
+| "Agents in this project" section of `CLAUDE.md` | `.cursor/rules/agent-os-agents.mdc`, always applied |
+| per-agent memory, `.claude/agent-memory/agent-os-<name>/` | the same directories — one map for both tools |
+
+Hook scripts live in `.cursor/hooks/agent-os/` and are registered in `.cursor/hooks.json`, merged so your own hooks stay. Everything carries the generated banner, so `check` catches drift and the pre-edit hook blocks hand edits; `sync` after upgrading the package is the Cursor equivalent of `claude plugin update`. Reload the Cursor window after `init`, then run `/agent-os-init` in Agent chat.
+
+```json
+{ "targets": ["cursor"], "cursor": { "agentOs": true, "gitProtection": true } }
+```
+
+`agentOs: false` stops generating the layer and removes its hooks from `hooks.json` (delete the `agent-os-*` files yourself); `gitProtection: false` drops only the git hook. What does not carry over: Claude Code's auto memory, task tools (Cursor has its own to-do list), and the auto-route and auto-handoff mods.
+
+---
+
 ## The Claude Code plugin
 
 The deeper context-engineering work — the architecture map, seven coordinated agents, per-agent memory, and the hooks that make Claude use them — ships as a Claude Code plugin in this repo:

package/cursor/hooks/git-guard.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * Cursor beforeShellExecution hook — git write protection.
+ *
+ * Claude Code gets this as `permissions.deny` rules in .claude/settings.json.
+ * Cursor has no deny list, so the same rules (GIT_DENY, generated next to this
+ * file from settings.mjs) are enforced here: any git command that changes the
+ * repository is denied, read-only inspection is allowed.
+ *
+ * The hook is registered with a `git` matcher, so it only sees commands that
+ * mention git. Cursor reads a missing or invalid response as a block, so every
+ * exit answers explicitly.
+ */
+import { readFileSync } from "node:fs";
+import { GIT_DENY } from "../lib/git-deny.mjs";
+
+const answer = (o) => { process.stdout.write(JSON.stringify(o)); process.exit(0); };
+
+// "Bash(git push *)" -> "git push" plus anything after a space;
+// "Bash(git -C*)" -> anything starting "git -C".
+const RULES = GIT_DENY.map((r) => r.replace(/^Bash\(/, "").replace(/\)$/, "")).map((r) =>
+  r.endsWith(" *") ? { prefix: r.slice(0, -2), spaced: true } : { prefix: r.replace(/\*$/, ""), spaced: false });
+
+const denied = (segment) => {
+  const cmd = segment.trim().replace(/\s+/g, " ").replace(/^(?:\w+=\S*\s+)+/, "");
+  return RULES.find((r) => r.spaced ? cmd === r.prefix || cmd.startsWith(`${r.prefix} `) : cmd.startsWith(r.prefix));
+};
+
+let command = "";
+try { command = String(JSON.parse(readFileSync(0, "utf8") || "{}").command ?? ""); } catch { answer({ permission: "allow" }); }
+
+// Check every command in a chain: `cd x && git push` is still a push.
+for (const segment of command.split(/&&|\|\||[;|\n]|\$\(|`/)) {
+  const hit = denied(segment);
+  if (!hit) continue;
+  const text = `agent-os blocks git commands that change the repository (${hit.prefix}${hit.spaced ? " …" : "…"}). ` +
+    "Read-only git (status, log, diff, show, blame) is allowed. Ask the user to run this one themselves.";
+  answer({ permission: "deny", user_message: text, agent_message: text });
+}
+answer({ permission: "allow" });

package/cursor/skills/agent-os-init/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: agent-os-init
+description: Set up or repair this project's agent-os context layer in Cursor. Checks the generated rules, subagents and hooks against .agent-os/, inspects agent memory, then establishes, maps, migrates or maintains the layer. Use for "set up agent-os", "agent-os init", "initialise this project", "bootstrap my context setup", "migrate off memory-bank or .cursorrules", "my AGENTS.md is too big", or when starting work in a repo with no setup.
+---
+
+# agent-os for Cursor — set up or repair
+
+The Cursor counterpart of Claude Code's `/agent-os:init`. Same layout, same
+agents, same memory — only the file names differ.
+
+| Tier | Lives in | Startup cost | Holds |
+|---|---|---|---|
+| Always-loaded | `AGENTS.md` (from `.agent-os/AGENTS.md`), ≤200 lines | small, fixed | Only what is true in *every* session |
+| On-demand | `.cursor/rules/*.mdc` with `globs:` (from `.agent-os/rules/*.md` with `paths:`) | **zero** | Durable facts scoped to some files |
+| Explored | `.claude/agent-memory/agent-os-feature-cartographer/` | **zero** (subagent context) | How each feature is actually built |
+| Task state | the project's own vault / handoff file | zero (read selectively) | What is in flight right now |
+
+Agent memory stays under `.claude/agent-memory/` on purpose: Claude Code's
+agent-os agents use the same directories, so a team on both tools shares one map.
+
+**Storing a fact and loading a fact are different acts.** Anything that makes
+them the same act — a handbook `AGENTS.md`, a memory bank read at every startup,
+an always-apply rule that only matters for one directory — is the bug.
+
+## Arguments
+
+| Argument | Do |
+|---|---|
+| *(none)* | The full pass below |
+| `audit` | Steps 1 and 3 only. Change nothing. |
+
+`/agent-os-map` builds the architecture map; `/agent-os-memory` inspects and
+repairs what the project remembers.
+
+## Step 1 — Read the state
+
+Three commands. Do not rediscover this with a dozen file reads — they are
+deterministic:
+
+```bash
+npx -y @sayansr26/agent-os detect
+npx -y @sayansr26/agent-os check
+npx -y @sayansr26/agent-os memory
+```
+
+`check` lists every generated file — rules, `AGENTS.md`, the `agent-os-*`
+subagents and skills, the hook scripts and `.cursor/hooks.json` — as `ok`,
+`MISSING` or `DRIFTED`. `memory` lists every agent's memory, which features are
+mapped, and a health list.
+
+**Show the output to the user before you change anything.**
+
+## Step 2 — Fresh setup or repair?
+
+| State | Do |
+|---|---|
+| no `.agent-os/` | `npx -y @sayansr26/agent-os init`, then carry on with Step 3 |
+| `check` reports `MISSING` or `DRIFTED` | `npx -y @sayansr26/agent-os sync` — it rewrites only what it generated |
+| `sync` names files it did not generate | stop and ask: move their content into `.agent-os/` (preferred), or `--force` after a commit |
+| everything `ok` | nothing to repair |
+
+Never edit a generated file by hand. They carry a banner, the pre-edit hook
+blocks the edit, and the next `sync` would revert it. Edit `.agent-os/` and sync.
+
+## Step 3 — Decide what this run is for
+
+Judge from what Step 1 printed and a look at the source tree:
+
+| Mode | Evidence | Do |
+|---|---|---|
+| `TOO-EARLY` | Barely any source (under ~5 files) | **Build nothing.** A layer over an empty project is invented conventions. |
+| `ESTABLISH` | `.agent-os/AGENTS.md` is still the placeholder, or the only rule is `example.md` | `references/establishing.md` — build the layer *from the code* |
+| `MAP` | Layer real, but `memory` shows no `_architecture.md` | `references/establishing.md`, "Map the architecture" — or `/agent-os-map` |
+| `MIGRATE` | `.cursorrules`, `memory-bank/`, `.serena/memories/`, or an always-apply rule that only concerns part of the tree | fix it; `references/migrating.md` for legacy stores |
+| `MAINTAIN` | Real layer, architecture mapped | report and stop |
+
+`references/changing-a-feature.md` is the workflow that pays all this back —
+point the user at it once the layer exists.
+
+The references were written for Claude Code. Read them through this table:
+
+| They say | In Cursor |
+|---|---|
+| `CLAUDE.md` | `.agent-os/AGENTS.md` (compiled to `AGENTS.md`). Draft it yourself from the code — there is no `/init` to run first. |
+| `.claude/rules/*.md` | `.agent-os/rules/*.md`, then `sync` (compiled to `.cursor/rules/*.mdc`) |
+| `agent-os:<name>` | the `agent-os-<name>` subagent |
+| `/agent-os:init`, `/agent-os:map`, `/agent-os:memory` | `/agent-os-init`, `/agent-os-map`, `/agent-os-memory` |
+| `node "${CLAUDE_PLUGIN_ROOT}/…/<script>.mjs"` | `npx -y @sayansr26/agent-os <script>` |
+| "Wire the agents into CLAUDE.md" (Step 4b) | already done: `.cursor/rules/agent-os-agents.mdc` is always applied — skip it |
+| the settings pass, `permissions.deny`, task tools | see "Git write protection" below; Cursor has its own to-do list |
+
+## Step 4 — Verify by re-running
+
+Run `check` and `memory` again and show before and after: generated files all
+`ok`, features mapped, health findings. Do not declare success on vibes — the
+commands produce the numbers, so quote them.
+
+## Git write protection
+
+Claude Code gets git write protection as `permissions.deny` rules. Cursor has no
+deny list, so `sync` registers a `beforeShellExecution` hook in
+`.cursor/hooks.json` (`.cursor/hooks/agent-os/hooks/git-guard.mjs`) that refuses
+the same commands: every git command that changes the repository. Read-only git
+stays available. `references/git-permissions.md` explains each rule.
+
+If the user wants it off: `{ "cursor": { "gitProtection": false } }` in
+`.agent-os/config.json`, then `sync`. Say what that gives up.
+
+## What this skill will not do
+
+- It will not write facts it has not verified in the repo. An invented rule is
+  worse than a missing one, because it will be trusted.
+- It will not delete a legacy store before its content has landed in `.agent-os/`.
+- It will not hand-edit generated files, or another agent's memory.
+- It will not add a memory MCP server. The common failure is that nothing was
+  *written*, which a graph does not fix and the cartographer's memory does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayansr26/agent-os",
-  "version": "0.6.2",
+  "version": "0.6.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",
@@ -34,6 +34,7 @@
     "bin",
     "src",
     "plugins",
+    "cursor",
     ".claude-plugin",
     "README.md",
     "LICENSE",
@@ -43,7 +44,6 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node scripts/validate-plugin.mjs && node src/selftest.mjs",
-    "prepublishOnly": "npm test"
+    "test": "node scripts/validate-plugin.mjs && node src/selftest.mjs"
   }
-}
+}

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

@@ -1,15 +1,15 @@
 {
   "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.5.0",
+  "version": "0.5.1",
   "author": {
     "name": "Sayan Choudhury",
     "email": "sayan.choudhury.in@gmail.com"
   },
   "homepage": "https://github.com/sayansr26/agent-os",
   "repository": "https://github.com/sayansr26/agent-os",
-  "privacyPolicyUrl": "https://s3techpulse.com/privacy-policy",
-  "supportUrl": "https://s3techpulse.com/support",
+  "privacyPolicyUrl": "https://github.com/sayansr26/agent-os/blob/master/PRIVACY.md",
+  "supportUrl": "https://github.com/sayansr26/agent-os/issues",
   "license": "MIT",
   "keywords": [
     "context-engineering",

package/plugins/agent-os/hooks/pre-edit.mjs

@@ -10,11 +10,16 @@
  *      Deny, and name the source to edit instead.
  *   2. Cartographer reminder (advisory, never blocks). The first edit to an
  *      existing feature with no cartographer map adds a note telling Claude to
- *      ask agent-os:feature-cartographer first. Once per feature per session.
+ *      ask agent-os:feature-cartographer first (agent-os-feature-cartographer
+ *      in Cursor). Once per feature per session.
  *
  * Stays silent for new (untracked) features, paths outside a feature
  * directory, and anything it cannot work out. Turn the reminder off with
  * `{ "claude": { "cartographerReminder": false } }` in `.agent-os/config.json`.
+ *
+ * `--cursor` is the same hook as Cursor's preToolUse on Write. Cursor reads a
+ * missing or empty response as a block, so in that mode every exit answers
+ * explicitly: `allow` (with the reminder as `agent_message`) or `deny`.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -24,17 +29,33 @@ import { claudeConfig, featureOf, findMap, mapFiles, tracked } from "../lib/feat
 // Must stay a substring of BANNER in src/source.mjs.
 const BANNER = "agent-os: generated from .agent-os/";
 
-const quiet = () => process.exit(0);
+const CURSOR = process.argv.includes("--cursor");
+const agent = (name) => `agent-os${CURSOR ? "-" : ":"}${name}`;
+
+const quiet = () => {
+  if (CURSOR) process.stdout.write(JSON.stringify({ permission: "allow" }));
+  process.exit(0);
+};
 const emit = (hookSpecificOutput) => {
-  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", ...hookSpecificOutput } }));
+  if (CURSOR) {
+    const deny = hookSpecificOutput.permissionDecision === "deny";
+    const text = deny ? hookSpecificOutput.permissionDecisionReason : hookSpecificOutput.additionalContext;
+    process.stdout.write(JSON.stringify(deny
+      ? { permission: "deny", user_message: text, agent_message: text }
+      : { permission: "allow", agent_message: text }));
+  } else
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", ...hookSpecificOutput } }));
   process.exit(0);
 };
 
 let payload;
 try { payload = JSON.parse(readFileSync(0, "utf8") || "{}"); } catch { quiet(); }
 
-const root = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
-const raw = String(payload?.tool_input?.file_path ?? "");
+// Claude Code may run inside Cursor's terminal, so CURSOR_PROJECT_DIR counts only in --cursor mode.
+const root = (CURSOR && process.env.CURSOR_PROJECT_DIR) || process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
+// Cursor does not document its Write tool's input, so take the usual names.
+const input = payload?.tool_input || {};
+const raw = String(input.file_path ?? input.path ?? input.target_file ?? input.filePath ?? "");
 if (!raw) quiet();
 const abs = isAbsolute(raw) ? raw : join(root, raw);
 const rel = relative(root, abs).replace(/\\/g, "/");
@@ -44,6 +65,14 @@ if (rel.startsWith("..")) quiet();
 try {
   if (existsSync(join(root, ".agent-os")) && existsSync(abs) && readFileSync(abs, "utf8").includes(BANNER)) {
     let source = ".agent-os/";
+    // Cursor's agent-os layer is compiled from the package, not from .agent-os/.
+    if (/^\.cursor\/(?:agents\/agent-os-|skills\/agent-os-|hooks\/agent-os\/|rules\/agent-os-agents\.mdc$)/.test(rel))
+      emit({
+        permissionDecision: "deny",
+        permissionDecisionReason:
+          `${rel} is part of the agent-os layer for Cursor and the next sync would revert this edit. ` +
+          `To customise it, set \`{ "cursor": { "agentOs": false } }\` in .agent-os/config.json and keep your own copy.`,
+      });
     const rule = rel.match(/^\.(?:claude|clinerules|cursor|windsurf|kilocode|gemini|agents?)\/(?:rules\/)?(.+?)\.(?:md|mdc)$/);
     if (rel === "AGENTS.md") source = ".agent-os/AGENTS.md";
     else if (rule && existsSync(join(root, ".agent-os/rules", `${basename(rule[1])}.md`)))
@@ -67,7 +96,7 @@ try {
 
   const dir = join(tmpdir(), "agent-os-reminders");
   mkdirSync(dir, { recursive: true });
-  const session = String(payload?.session_id ?? "nosession").replace(/[^\w-]/g, "");
+  const session = String(payload?.session_id ?? payload?.conversation_id ?? "nosession").replace(/[^\w-]/g, "");
   const marker = join(dir, `${session}--${feature.dir.replace(/[^\w-]/g, "_")}`);
   if (existsSync(marker)) quiet();
   writeFileSync(marker, "");
@@ -75,7 +104,7 @@ try {
   emit({
     additionalContext:
       `agent-os (advisory): ${feature.dir}/ is an existing feature with no cartographer map. ` +
-      `Before changing it further, ask agent-os:feature-cartographer how "${feature.name}" is built — ` +
+      `Before changing it further, ask ${agent("feature-cartographer")} how "${feature.name}" is built — ` +
       `it answers and files the map for every later session. This applies in plan mode too ` +
       `(ask it read-only; it writes the map after plan mode ends). Shown once per feature per session.`,
   });

package/plugins/agent-os/hooks/session-resume.mjs

@@ -16,6 +16,9 @@
  *   - The snapshot is hard-capped (MAX_LINES); the contract is fixed-size.
  *   - Fails silent: any error exits 0, so a broken hook never blocks a session.
  *   - Read-only. Runs git for reading only; never writes, never mutates.
+ *
+ * `--cursor` is the same hook as Cursor's sessionStart: agent names in Cursor's
+ * `agent-os-<name>` form, and the text wrapped as `{ additional_context }`.
  */
 
 import { execSync } from "node:child_process";
@@ -24,7 +27,13 @@ import { join } from "node:path";
 import { coverage } from "../lib/features.mjs";
 
 const MAX_LINES = 40;
-const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const CURSOR = process.argv.includes("--cursor");
+// Claude Code may run inside Cursor's terminal, so CURSOR_PROJECT_DIR counts only in --cursor mode.
+const cwd = (CURSOR && process.env.CURSOR_PROJECT_DIR) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+// Claude Code namespaces plugin agents and skills with `:`; Cursor names allow
+// only letters and hyphens, so its generated copies use `-`.
+const agent = (name) => `agent-os${CURSOR ? "-" : ":"}${name}`;
+const skill = (name) => `/agent-os${CURSOR ? "-" : ":"}${name}`;
 const out = [];
 
 const sh = (cmd) => {
@@ -135,13 +144,13 @@ function snapshot() {
 
 // The agents and what triggers each. `subagent_type` is the namespaced name.
 const AGENTS = [
-  ["agent-os:feature-cartographer", "BEFORE changing any existing feature — ask how it is built (files, state, API, blast radius). It answers from its map, or maps the feature and files the map."],
-  ["agent-os:architect", "before a new subsystem, a cross-module change, or a data model others will depend on."],
-  ["agent-os:builder", "to write the code once the shape is settled; it enforces the project's rules while writing."],
-  ["agent-os:tester", "after building, to verify the change actually works."],
-  ["agent-os:reviewer", "before calling any change done or opening a PR."],
-  ["agent-os:documenter", "once work is verified, to update the changelog, task state and docs the change invalidated."],
-  ["agent-os:orchestrator", "for work spanning several of the above, or that cannot be stated in one sentence."],
+  ["feature-cartographer", "BEFORE changing any existing feature — ask how it is built (files, state, API, blast radius). It answers from its map, or maps the feature and files the map."],
+  ["architect", "before a new subsystem, a cross-module change, or a data model others will depend on."],
+  ["builder", "to write the code once the shape is settled; it enforces the project's rules while writing."],
+  ["tester", "after building, to verify the change actually works."],
+  ["reviewer", "before calling any change done or opening a PR."],
+  ["documenter", "once work is verified, to update the changelog, task state and docs the change invalidated."],
+  ["orchestrator", "for work spanning several of the above, or that cannot be stated in one sentence."],
 ];
 
 function contract() {
@@ -153,15 +162,17 @@ function contract() {
     return [
       "## agent-os",
       "",
-      "The agent-os plugin is installed but this project is not set up. If the user starts feature work, suggest `/agent-os:init` once.",
+      `agent-os is installed but this project is not set up. If the user starts feature work, suggest \`${skill("init")}\` once.`,
     ];
 
   const lines = [
     "## agent-os is active in this project",
     "",
-    "These agents are how work is done here — use them without being asked (Agent tool, `subagent_type` as shown):",
+    CURSOR
+      ? "These subagents are how work is done here — delegate to them without being asked, by the names shown:"
+      : "These agents are how work is done here — use them without being asked (Agent tool, `subagent_type` as shown):",
   ];
-  for (const [name, when] of AGENTS) lines.push(`- \`${name}\` — ${when}`);
+  for (const [name, when] of AGENTS) lines.push(`- \`${agent(name)}\` — ${when}`);
 
   const cov = coverage(cwd);
   lines.push("");
@@ -173,12 +184,14 @@ function contract() {
   } else if (cov.dir) {
     lines.push(`Cartographer maps are indexed in \`${cov.dir.slice(cwd.length + 1)}/MEMORY.md\`.`);
   }
-  if (!cov.architecture) lines.push("No architecture map yet — `/agent-os:map` builds it.");
+  if (!cov.architecture) lines.push(`No architecture map yet — \`${skill("map")}\` builds it.`);
 
   lines.push("");
-  lines.push("Plan mode: its \"Explore agents only\" phase does not replace the cartographer. Ask the cartographer read-only during planning (it will not write), and let it file its map once plan mode ends.");
+  lines.push(CURSOR
+    ? "Plan mode: ask the cartographer read-only during planning (it will not write), and let it file its map once plan mode ends."
+    : "Plan mode: its \"Explore agents only\" phase does not replace the cartographer. Ask the cartographer read-only during planning (it will not write), and let it file its map once plan mode ends.");
   if (existsSync(join(cwd, ".agent-os/rules")))
-    lines.push("Rules: `.claude/rules/*` and other tool copies are generated. Edit `.agent-os/rules/`, then run `npx @sayansr26/agent-os sync`.");
+    lines.push(`Rules: \`${CURSOR ? ".cursor/rules/*" : ".claude/rules/*"}\` and other tool copies are generated. Edit \`.agent-os/rules/\`, then run \`npx @sayansr26/agent-os sync\`.`);
   return lines;
 }
 
@@ -186,7 +199,8 @@ try {
   const blocks = [];
   try { const s = snapshot(); if (s.length) blocks.push(s.join("\n")); } catch {}
   try { blocks.push(contract().join("\n")); } catch {}
-  if (blocks.length) process.stdout.write(blocks.join("\n\n") + "\n");
+  if (CURSOR) process.stdout.write(JSON.stringify(blocks.length ? { additional_context: blocks.join("\n\n") } : {}));
+  else if (blocks.length) process.stdout.write(blocks.join("\n\n") + "\n");
 } catch {
   // Never let a resume hook break a session.
 }

package/src/cli.mjs

@@ -10,6 +10,7 @@ import { setupState, describeState } from "../plugins/agent-os/skills/init/scrip
 import { applyScope, describe } from "./claude-setup.mjs";
 import { createInterface } from "node:readline/promises";
 import { compile, TARGETS } from "./targets.mjs";
+import { enabled as cursorEnabled } from "./cursor.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
@@ -42,6 +43,16 @@ Options
   --no-global    init: leave ~/.claude alone
 `;
 
+/** Will this init/sync compile for Claude Code? Mirrors how scaffold picks targets. */
+function claudeTargeted(root, found) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, DIR, "config.json"), "utf8"));
+    return (cfg.targets || []).includes("claude-code");
+  } catch {}
+  const present = found.filter((t) => t.present).map((t) => t.id);
+  return present.includes("claude-code") || !present.length;
+}
+
 function scaffold(root, found) {
   const present = found.filter((t) => t.present).map((t) => t.id);
   mkdirSync(join(root, DIR, "rules"), { recursive: true });
@@ -95,6 +106,17 @@ export async function main(argv) {
 
   if (cmd === "help" || argv.includes("-h") || argv.includes("--help")) { console.log(USAGE); return; }
 
+  // A repository Rulegate owns: init would adopt Rulegate's generated CLAUDE.md and
+  // AGENTS.md as this tool's source, and every write after that fights `rulegate check`.
+  // That happened to Rulegate's own repository (its T112), so both writers stop here.
+  if ((cmd === "init" || cmd === "sync") && existsSync(join(root, ".rulegate"))) {
+    console.error(`\n  This repository uses Rulegate (.rulegate/ exists), which replaces agent-os.`);
+    console.error(`  agent-os ${cmd} would treat Rulegate's generated files as its source. Nothing was written.`);
+    console.error(`\n  Use ${bold("npx rulegate sync")} here instead.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
   const found = detect(root);
 
   if (cmd === "detect") {
@@ -141,18 +163,24 @@ export async function main(argv) {
   let adopted = new Set();
 
   let before = null;
+  // The SETUP state is Claude Code's: CLAUDE.md, .claude/settings.json, the
+  // plugin. In a project that does not target Claude Code every item reads
+  // MISSING and the verdict never leaves REPAIR, so it is not shown there.
+  const forClaude = claudeTargeted(root, found);
   if (cmd === "init") {
     console.log(`\n${bold("agent-os init")}  ${root}\n`);
     // Decide fresh vs repair before touching anything, and say which, so a
     // second run on a set-up project reads as a repair rather than a re-init.
     before = setupState(root);
-    for (const l of describeState(before)) console.log(`  ${l}`);
-    console.log({
-      fresh: `\n  ${dim("Fresh setup: creating everything.")}`,
-      repair: `\n  ${dim("Existing setup: fixing the items marked MISSING, leaving the rest as it is.")}`,
-      healthy: `\n  ${dim("Setup is complete: re-syncing and checking the plugin for updates.")}`,
-    }[before.status]);
-    console.log("");
+    if (forClaude) {
+      for (const l of describeState(before)) console.log(`  ${l}`);
+      console.log({
+        fresh: `\n  ${dim("Fresh setup: creating everything.")}`,
+        repair: `\n  ${dim("Existing setup: fixing the items marked MISSING, leaving the rest as it is.")}`,
+        healthy: `\n  ${dim("Setup is complete: re-syncing and checking the plugin for updates.")}`,
+      }[before.status]);
+      console.log("");
+    }
     console.log(summarise(found));
     const hadSource = existsSync(join(root, DIR));
     const { present, taken } = scaffold(root, found);
@@ -209,7 +237,7 @@ export async function main(argv) {
       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 (f.merged) 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;
@@ -290,7 +318,22 @@ Pick one:
       console.log(`\n  ${dim("--no-plugin skips this; --no-auto-route / --no-auto-handoff skip one mod")}`);
     }
 
-    if (cmd === "init" && !dry) {
+    if (cmd !== "check" && targets.includes("cursor") && cursorEnabled(src.config)) {
+      const n = (re) => files.filter((f) => re.test(f.path)).length;
+      console.log(`\n${bold("Cursor")}  ${dim("agent-os layer, compiled from this package")}\n`);
+      console.log(`  ${n(/^\.cursor\/agents\/agent-os-/)} subagents     agent-os-feature-cartographer, -architect, -builder, -tester, -reviewer, …`);
+      console.log(`  ${n(/^\.cursor\/skills\/agent-os-[^/]+\/SKILL\.md$/)} skills        /agent-os-init, /agent-os-map, /agent-os-memory`);
+      console.log(`  hooks           session start, generated-file guard${src.config.cursor?.gitProtection === false ? "" : ", git write protection"}  ${dim("(.cursor/hooks.json)")}`);
+      console.log(`  agent memory    .claude/agent-memory/agent-os-<agent>/  ${dim("— shared with Claude Code")}`);
+      if (cmd === "init") console.log(`\n  ${dim("Reload the Cursor window, then run /agent-os-init in Agent chat.")}`);
+    }
+
+    if (cmd === "init" && !dry && !forClaude) {
+      const labels = targets.map((t) => TARGETS[t]?.label || t);
+      console.log(`\n${bold("Result")}  ${labels.length ? `compiled for ${labels.join(", ")}` : "AGENTS.md only"}`);
+    }
+
+    if (cmd === "init" && !dry && forClaude) {
       const after = setupState(root);
       console.log(`\n${bold("Result")}  ${before.status} → ${after.status}`);
       if (after.missing.length) {

package/src/cursor.mjs

@@ -0,0 +1,167 @@
+/**
+ * The agent-os layer for Cursor: the same agents, skills and hooks the Claude
+ * Code plugin ships, compiled into the places Cursor reads them.
+ *
+ *   .cursor/agents/agent-os-<name>.md        the seven agents, as subagents
+ *   .cursor/skills/agent-os-{init,map,memory}/  the three skills
+ *   .cursor/hooks/agent-os/                  the session and pre-edit hooks, plus
+ *                                            git write protection
+ *   .cursor/hooks.json                       merged: user hooks are kept
+ *   .cursor/rules/agent-os-agents.mdc        when to use which agent, always on
+ *
+ * Everything is generated from this package, never from `.agent-os/`, so `sync`
+ * keeps it current the way `claude plugin update` does for Claude Code.
+ *
+ * Agent memory stays in `.claude/agent-memory/agent-os-<name>/`: the directory
+ * Claude Code's plugin agents use, so a project on both tools has one map.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BANNER, parseFrontmatter } from "./source.mjs";
+import { GIT_DENY } from "../plugins/agent-os/skills/init/scripts/settings.mjs";
+
+const PKG = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const PLUGIN = join(PKG, "plugins/agent-os");
+const OWN = join(PKG, "cursor");
+const HOOKS = ".cursor/hooks/agent-os";
+
+const read = (p) => readFileSync(p, "utf8");
+const md = (fields, body) => `---\n${fields}---\n\n<!-- ${BANNER} -->\n\n${body.trim()}\n`;
+const js = (text) => text.startsWith("#!")
+  ? text.replace(/^(#!.*\n)/, `$1// ${BANNER}\n`)
+  : `// ${BANNER}\n${text}`;
+
+/** `{ "cursor": { "agentOs": false } }` turns the whole layer off. */
+export const enabled = (config) => config?.cursor?.agentOs !== false;
+const gitGuard = (config) => config?.cursor?.gitProtection !== false;
+
+/** Claude Code names and commands, rewritten to what this layer installs. */
+export function translate(text) {
+  return text
+    .replace(/agent-os:([a-z][a-z-]*)/g, "agent-os-$1")
+    .replace(/node "\$\{CLAUDE_PLUGIN_ROOT\}\/skills\/\w+\/scripts\/(\w+)\.mjs"/g, "npx -y @sayansr26/agent-os $1");
+}
+
+/** A description is what the parent reads to pick a subagent, so it names Cursor's files. */
+const describe = (d) => JSON.stringify(translate(String(d || ""))
+  .replace(/CLAUDE\.md/g, "AGENTS.md").replace(/\.claude\/rules\//g, ".cursor/rules/"));
+
+const READ_AS = `> **Running in Cursor.** This text was written for Claude Code. Read it as:
+> \`CLAUDE.md\` → \`AGENTS.md\` (edit \`.agent-os/AGENTS.md\`, then \`npx @sayansr26/agent-os sync\`);
+> \`.claude/rules/\` → \`.cursor/rules/\` (edit \`.agent-os/rules/\`, then sync);
+> an agent \`<name>\` → the \`agent-os-<name>\` subagent; \`/agent-os:<skill>\` → \`/agent-os-<skill>\`;
+> "the Agent tool" or "dispatch" → delegate to that subagent.`;
+
+function agents() {
+  const dir = join(PLUGIN, "agents");
+  return readdirSync(dir).filter((f) => f.endsWith(".md")).sort().map((f) => {
+    const { fields, body } = parseFrontmatter(read(join(dir, f)));
+    const name = `agent-os-${fields.name}`;
+    // Claude Code creates the memory directory and preloads MEMORY.md for an
+    // agent with `memory: project`. Cursor does neither, so the agent is told.
+    const memory = `> **Your memory directory** is \`.claude/agent-memory/${name}/\` at the project root
+> (shared with Claude Code's agent-os agents). Create it if it does not exist. Cursor does
+> not load \`MEMORY.md\` for you — read it yourself before anything else.
+>
+${READ_AS}`;
+    return {
+      path: `.cursor/agents/${name}.md`,
+      content: md(
+        `name: ${name}\ndescription: ${describe(fields.description)}\nmodel: inherit\n`,
+        `${memory}\n\n${translate(body)}`),
+    };
+  });
+}
+
+function skills() {
+  const out = [];
+  const refs = join(PLUGIN, "skills/init/references");
+  // init is rewritten for Cursor; its references are shared, read through the table.
+  {
+    const { fields, body } = parseFrontmatter(read(join(OWN, "skills/agent-os-init/SKILL.md")));
+    out.push({ path: ".cursor/skills/agent-os-init/SKILL.md",
+      content: md(`name: ${fields.name}\ndescription: ${JSON.stringify(fields.description)}\n`, body) });
+    for (const f of readdirSync(refs).filter((f) => f.endsWith(".md")).sort())
+      out.push({ path: `.cursor/skills/agent-os-init/references/${f}`,
+        content: `<!-- ${BANNER} -->\n\n${READ_AS}\n\n${translate(read(join(refs, f))).trim()}\n` });
+  }
+  // map and memory carry over as they are, renamed. Their scripts run through
+  // the CLI, which bundles the same files, so no script is copied.
+  for (const s of ["map", "memory"]) {
+    const { fields, body } = parseFrontmatter(read(join(PLUGIN, "skills", s, "SKILL.md")));
+    out.push({ path: `.cursor/skills/agent-os-${s}/SKILL.md`,
+      content: md(`name: agent-os-${s}\ndescription: ${describe(fields.description)}\n`, `${READ_AS}\n\n${translate(body)}`) });
+  }
+  return out;
+}
+
+function hookScripts(config) {
+  const out = [
+    { path: `${HOOKS}/hooks/session-resume.mjs`, content: js(read(join(PLUGIN, "hooks/session-resume.mjs"))) },
+    { path: `${HOOKS}/hooks/pre-edit.mjs`, content: js(read(join(PLUGIN, "hooks/pre-edit.mjs"))) },
+    { path: `${HOOKS}/lib/features.mjs`, content: js(read(join(PLUGIN, "lib/features.mjs"))) },
+  ];
+  if (gitGuard(config)) out.push(
+    { path: `${HOOKS}/hooks/git-guard.mjs`, content: js(read(join(OWN, "hooks/git-guard.mjs"))) },
+    { path: `${HOOKS}/lib/git-deny.mjs`,
+      content: js(`/** The same rules Claude Code gets as permissions.deny (settings.mjs). */\nexport const GIT_DENY = ${JSON.stringify(GIT_DENY, null, 2)};\n`) },
+  );
+  return out;
+}
+
+/** The agent contract, always on — the Cursor half of CLAUDE.md's Step 4b section. */
+const contract = () => ({
+  path: ".cursor/rules/agent-os-agents.mdc",
+  content: md("description: When to use each agent-os subagent\nalwaysApply: true\n", `## Agents in this project (agent-os)
+
+Delegate to these subagents without being asked:
+
+- Before changing an existing feature: ask \`agent-os-feature-cartographer\` how
+  it is built. In plan mode ask it read-only, and have it file the map as the
+  first step after plan mode ends.
+- New subsystem, cross-module change, shared data model: \`agent-os-architect\` first.
+- Writing the change: \`agent-os-builder\`, given the map and the files to change.
+- Done means: \`agent-os-tester\` verified it and \`agent-os-reviewer\` found no
+  rule violations.
+- Once verified: \`agent-os-documenter\` records it.
+- Work spanning several of these, or that cannot be stated in one sentence:
+  \`agent-os-orchestrator\`.
+
+\`/agent-os-map\` builds the architecture map, \`/agent-os-memory\` inspects agent
+memory, \`/agent-os-init\` sets up or repairs all of this.
+
+Generated files carry a banner. Edit \`.agent-os/\`, then run
+\`npx @sayansr26/agent-os sync\`; never edit the output.`),
+});
+
+/** Every file of the layer except hooks.json. */
+export function cursorFiles(src) {
+  if (!enabled(src.config)) return [];
+  return [...agents(), ...skills(), ...hookScripts(src.config), contract()];
+}
+
+const OURS = (h) => String(h?.command || "").includes(`${HOOKS}/`);
+
+/**
+ * Merge the agent-os hooks into `.cursor/hooks.json`. Hooks the user wrote are
+ * kept; earlier agent-os entries are replaced, so a removed hook goes away.
+ */
+export function mergeHooks(src, existing) {
+  if (!existing && !enabled(src.config)) return [];
+  const cfg = existing ? JSON.parse(existing) : { version: 1, hooks: {} };
+  cfg.version ||= 1;
+  cfg.hooks ||= {};
+  for (const ev of Object.keys(cfg.hooks)) {
+    cfg.hooks[ev] = (cfg.hooks[ev] || []).filter((h) => !OURS(h));
+    if (!cfg.hooks[ev].length) delete cfg.hooks[ev];
+  }
+  if (enabled(src.config)) {
+    const add = (ev, h) => (cfg.hooks[ev] ||= []).push(h);
+    add("sessionStart", { command: `node ${HOOKS}/hooks/session-resume.mjs --cursor` });
+    add("preToolUse", { command: `node ${HOOKS}/hooks/pre-edit.mjs --cursor`, matcher: "Write" });
+    if (gitGuard(src.config))
+      add("beforeShellExecution", { command: `node ${HOOKS}/hooks/git-guard.mjs`, matcher: "\\bgit\\b" });
+  }
+  return [{ path: ".cursor/hooks.json", content: JSON.stringify(cfg, null, 2) + "\n" }];
+}

package/src/selftest.mjs

@@ -57,6 +57,39 @@ try {
   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  Cursor gets the agent-os layer");
+  {
+    const agents = ["architect", "builder", "documenter", "feature-cartographer", "orchestrator", "reviewer", "tester"];
+    ok(agents.every((a) => read(`.cursor/agents/agent-os-${a}.md`)?.startsWith(`---\nname: agent-os-${a}\n`)), "7 subagents in .cursor/agents/, Cursor-legal names");
+    const carto = read(".cursor/agents/agent-os-feature-cartographer.md");
+    ok(carto.includes(".claude/agent-memory/agent-os-feature-cartographer/"), "subagent memory shared with Claude Code's directory");
+    ok(!/agent-os:[a-z]/.test(carto) && !/^memory:|^tools:/m.test(carto), "no Claude-only names or frontmatter left");
+    ok(["init", "map", "memory"].every((s) => read(`.cursor/skills/agent-os-${s}/SKILL.md`)?.includes(`name: agent-os-${s}\n`)), "skills /agent-os-init, -map, -memory");
+    ok(!read(".cursor/skills/agent-os-memory/SKILL.md").includes("CLAUDE_PLUGIN_ROOT"), "skill scripts run through the CLI");
+    ok(read(".cursor/rules/agent-os-agents.mdc")?.includes("alwaysApply: true"), "agent contract is an always-on rule");
+    const hooks = JSON.parse(read(".cursor/hooks.json"));
+    ok(hooks.version === 1 && hooks.hooks.sessionStart && hooks.hooks.preToolUse && hooks.hooks.beforeShellExecution, "hooks.json: sessionStart, preToolUse, beforeShellExecution");
+
+    const hook = (script, args, input) => spawnSync(process.execPath, [join(root, ".cursor/hooks/agent-os/hooks", script), ...args],
+      { cwd: root, encoding: "utf8", input, env: { ...process.env, CURSOR_PROJECT_DIR: root } }).stdout;
+    const start = JSON.parse(hook("session-resume.mjs", ["--cursor"], ""));
+    ok(start.additional_context?.includes("`agent-os-feature-cartographer`"), "session start returns additional_context with Cursor names");
+    const pre = (file) => JSON.parse(hook("pre-edit.mjs", ["--cursor"], JSON.stringify({ tool_input: { file_path: join(root, file) } })));
+    ok(pre(".cursor/rules/api.mdc").permission === "deny", "pre-edit denies an edit to a generated rule");
+    ok(pre(".cursor/agents/agent-os-builder.md").permission === "deny", "pre-edit denies an edit to a generated subagent");
+    ok(pre("src/new.ts").permission === "allow", "pre-edit answers allow, never empty, for everything else");
+    const git = (command) => JSON.parse(hook("git-guard.mjs", [], JSON.stringify({ command }))).permission;
+    ok(git("git status") === "allow" && git("git log --oneline") === "allow", "read-only git allowed");
+    ok(["git push", "git commit -m x", "cd a && git reset --hard", "git -C x add .", "A=1 git rebase main"].every((c) => git(c) === "deny"), "git writes denied, chained and flag forms too");
+
+    writeFileSync(join(root, ".cursor/hooks.json"), JSON.stringify({ version: 1, hooks: { afterFileEdit: [{ command: "./fmt.sh" }] } }));
+    cli(["sync"], root);
+    const merged = JSON.parse(read(".cursor/hooks.json")).hooks;
+    ok(merged.afterFileEdit?.[0]?.command === "./fmt.sh" && merged.sessionStart?.length === 1, "hooks.json merged: user hook kept, ours added once");
+    cli(["sync"], root);
+    ok(JSON.parse(read(".cursor/hooks.json")).hooks.preToolUse.length === 1, "re-sync does not duplicate hooks");
+  }
+
   console.log("\n  drift");
   ok(cli(["check"], root).status === 0, "check passes when in sync");
   // Realistic drift: someone edits the body of a generated file and leaves the
@@ -229,7 +262,34 @@ try {
   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 }); rmSync(HOME, { recursive: true, force: true }); }
+} finally { rmSync(root, { recursive: true, force: true }); }
+
+console.log("\n  a Cursor-only init does not report Claude Code items");
+const cu = mkdtempSync(join(tmpdir(), "agent-os-cursor-"));
+try {
+  mkdirSync(join(cu, ".agent-os"), { recursive: true });
+  writeFileSync(join(cu, ".agent-os/config.json"), JSON.stringify({ targets: ["cursor"] }));
+  const r = cli(["init", "--no-global"], cu);
+  ok(r.status === 0, "init exits 0");
+  ok(!r.stdout.includes("SETUP") && !r.stdout.includes("still to do") && !r.stdout.includes("CLAUDE.md"), "no Claude Code SETUP or to-do list");
+  ok(/Result.*compiled for Cursor/.test(r.stdout) && r.stdout.includes("/agent-os-init"), "result names Cursor and the next step");
+  ok(!existsSync(join(cu, ".claude/settings.json")), "nothing written for Claude Code");
+  writeFileSync(join(cu, ".agent-os/config.json"), JSON.stringify({ targets: ["cursor"], cursor: { gitProtection: false } }));
+  cli(["sync"], cu);
+  ok(!JSON.parse(readFileSync(join(cu, ".cursor/hooks.json"), "utf8")).hooks.beforeShellExecution, "gitProtection: false removes the git hook");
+} finally { rmSync(cu, { recursive: true, force: true }); }
+
+console.log("\n  a Rulegate repository is left alone");
+const rg = mkdtempSync(join(tmpdir(), "agent-os-rulegate-"));
+try {
+  mkdirSync(join(rg, ".rulegate/rules"), { recursive: true });
+  writeFileSync(join(rg, "CLAUDE.md"), "<!-- Generated by Rulegate -->\n# Project\n");
+  for (const cmd of ["init", "sync"]) {
+    const r = cli([cmd, "--no-plugin", "--no-global"], rg);
+    ok(r.status === 1 && /uses Rulegate/.test(r.stderr), `${cmd} refuses with .rulegate/ present`);
+  }
+  ok(!existsSync(join(rg, ".agent-os")) && !existsSync(join(rg, "AGENTS.md")), "nothing written");
+} finally { rmSync(rg, { recursive: true, force: true }); rmSync(HOME, { recursive: true, force: true }); }
 
 console.log(`\n${fail ? `FAILED (${fail})` : "PASSED"}\n`);
 process.exit(fail ? 1 : 0);

package/src/targets.mjs

@@ -7,6 +7,7 @@
  * existing JSON config receive the current contents and return the merged file.
  */
 import { BANNER } from "./source.mjs";
+import { cursorFiles, mergeHooks } from "./cursor.mjs";
 
 const hdr = (comment) => `${comment} ${BANNER}\n`;
 const mdHeader = `<!-- ${BANNER} -->\n\n`;
@@ -54,13 +55,19 @@ export const TARGETS = {
   // ---- 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`,
-    })),
+    // .mdc, and a rule without frontmatter is ignored entirely. Then the
+    // agent-os layer — subagents, skills, hooks — which src/cursor.mjs builds.
+    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`,
+      })),
+      ...cursorFiles(src),
+    ],
+    merge: mergeHooks,
+    mergeFrom: ".cursor/hooks.json",
   },
 
   windsurf: {
@@ -179,10 +186,10 @@ export function compile(src, targetIds, readExisting) {
   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 })));
+    // A target writes files, merges into one existing config, or both. Merged
+    // files are marked: they are rewritten in place with nothing of the user's lost.
+    if (t.files) out.push(...t.files(src).map((f) => ({ ...f, target: id })));
+    if (t.merge) out.push(...t.merge(src, readExisting(t.mergeFrom)).map((f) => ({ ...f, target: id, merged: true })));
   }
   return out;
 }