@sayansr26/agent-os 0.5.3 → 0.6.0

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.0] — 2026-09-25
+
+Plugin 0.5.0. Found by running 0.4.1 in a real project: the plugin passed its
+own audit while Claude ignored it — a whole feature was built without the
+cartographer, and the audit still said `MAINTAIN`.
+
+### Added
+- **Claude uses agent-os without being told to.** The SessionStart hook now
+  prints, after the git snapshot, which agent to use for what, which features
+  the cartographer has mapped, the plan-mode rule and where rules are edited.
+  It also fires on `compact`, so the contract survives a long session. The
+  "snapshot, not instructions" footer now covers only the snapshot; it used to
+  read as an instruction to ignore everything the hook said.
+- **PreToolUse hook on Edit/MultiEdit/Write.** Blocks edits to files generated
+  from `.agent-os/` — the next sync reverted them silently — and names the
+  source to edit. The first edit to an existing feature with no map adds a
+  one-time note to ask the cartographer first. Advisory, never blocks; off with
+  `claude.cartographerReminder: false`.
+- **Settings are written, not handed over.** `scripts/settings.mjs` (and
+  `agent-os settings`) merges the git write-protection deny rules and
+  `CLAUDE_CODE_ENABLE_TODO_TOOLS` into project and user settings, and the
+  task-tracking rule into each `CLAUDE.md`. `/agent-os:init` previews, asks
+  once, applies. `agent-os init` writes project scope and asks before
+  `~/.claude` (`--global` / `--no-global`). Changed `~/.claude` files are backed
+  up to `*.agent-os.bak`. This reverses 0.5.3's "nothing writes to
+  `~/.claude/`": in practice that meant the protection was never applied.
+- **`init` knows a fresh setup from a repair.** `scripts/state.mjs` checks the
+  source, CLAUDE.md, git protection and task tools at both scopes, the
+  task-tracking rule, the agent triggers and the plugin (installed, enabled,
+  version) and says `FRESH`, `REPAIR` or `HEALTHY`. `agent-os init` prints it
+  first, keeps an existing `.agent-os/` instead of re-scaffolding, and ends
+  with before → after and anything still to do. The audit prints the same
+  block, and `/agent-os:init` fixes only the `MISSING` items on a repair.
+- **`agent-os init` updates the plugin.** It used to install only; a project
+  installed once stayed on that version. Now it refreshes the marketplace and
+  runs `claude plugin update` (or `enable`, or `install`) for this project's
+  install, reports `from → to`, and runs every `claude` command in the project
+  directory so `--root` installs into the right project.
+- `claude.features` in `.agent-os/config.json` names the feature directories
+  (`["src/features/*"]` style). Defaults to the first of `src/features`,
+  `src/modules`, `app/features`, `features`, `modules`.
+
+### Fixed
+- **The audit's "mapped" check was a folder-exists test.** It now requires the
+  architecture map and reports feature coverage (mapped of total) and maps
+  older than their feature's last commit.
+- The audit now flags generated `.claude/rules/*` that drifted from
+  `.agent-os/rules/`, folders nested inside agent memory, missing git
+  protection or task tools, a CLAUDE.md with no agent triggers, and a
+  project-level cartographer reminder hook the plugin now duplicates.
+- **Nested `.claude/agent-memory/` inside agent memory.** Every agent is told
+  to write flat, by absolute path, inside its own memory directory.
+- **Plan mode skipped the cartographer.** The cartographer answers read-only in
+  plan mode and files its map when called again after; the change workflow
+  and session contract say so.
+- Builder, cartographer and documenter name `.agent-os/rules/` as the rule
+  source when the project has one. `establishing.md` adds an "Agents in this
+  project" section to CLAUDE.md so each agent has a trigger.
+
 ## [0.5.3] — 2026-09-15
 
 ### Added

package/README.md

@@ -73,16 +73,25 @@ Every command below is `npx @sayansr26/agent-os <command>`. Install it once —
 | `detect` | Show which tools this project is set up for |
 | `audit` | Inspect the context layer and report findings |
 | `memory` | Inspect and health-check every memory store |
+| `settings` | Git write protection + task tools for Claude Code (`--scope project\|user\|both`, `--apply`) |
 
 `--root <dir>` to target another directory, `--dry-run` to preview.
 
+**`init` is safe to re-run.** It first reports the setup as `FRESH`,
+`REPAIR` (with each missing item) or `HEALTHY`, fixes only what is missing, and
+brings the Claude Code plugin to the latest version — installing it, enabling
+it, or refreshing the marketplace and running `claude plugin update`.
+`/agent-os:init` inside Claude Code reads the same state.
+
 **`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
+plugin — agents, skills, per-agent memory, hooks — with
+`claude plugin marketplace add` and `claude plugin install --yes`, and writes
+the settings: git write-protection deny rules and the task tools in
+`.claude/settings.json`, plus the task-tracking rule in `CLAUDE.md`. It then
+asks once whether to apply the same to `~/.claude/` so every project on the
+machine is protected (`--global` / `--no-global` answer in advance). Every
+write merges into what is there; changed `~/.claude` files are backed up to
+`*.agent-os.bak`. `--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.
 
@@ -111,7 +120,7 @@ Being straight about this matters more than the feature list.
 
 ## The Claude Code plugin
 
-The deeper context-engineering work — the architecture map, seven coordinated agents, per-agent memory, the session-resume hook — ships as a Claude Code plugin in this repo:
+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:
 
 ```
 /plugin marketplace add sayansr26/agent-os
@@ -120,6 +129,17 @@ The deeper context-engineering work — the architecture map, seven coordinated
 
 That's where the memory layer lives, because Claude Code is currently the only tool with somewhere to put it. The CLI is the cross-tool layer beneath it.
 
+Two hooks make the agents part of every session rather than something you have to ask for:
+
+- **SessionStart** (startup, resume, clear, compact) — prints where you left off, then which agent to use for what, which features the cartographer has mapped, and the plan-mode rule.
+- **PreToolUse on Edit/Write** — blocks edits to files generated from `.agent-os/` (the next sync would revert them) and names the source to edit; the first edit to an unmapped feature adds a one-time note to ask the cartographer first.
+
+Feature directories default to the first of `src/features`, `src/modules`, `app/features`, `features`, `modules`. Override in `.agent-os/config.json`:
+
+```json
+{ "targets": ["claude-code"], "claude": { "features": ["src/features/*", "apps/*"], "cartographerReminder": true } }
+```
+
 ---
 
 ## Design rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayansr26/agent-os",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "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.1",
+  "version": "0.5.0",
   "author": {
     "name": "Sayan Choudhury",
     "email": "sayan.choudhury.in@gmail.com"

package/plugins/agent-os/agents/architect.md

@@ -15,6 +15,11 @@ not create a second file under a different name.
 
 When you write:
 
+- **Write only directly inside your memory directory** — flat, no
+  subfolders. It already is `<project>/.claude/agent-memory/<your name>/`, so a
+  path like `.claude/agent-memory/...` written relative to it nests a second
+  copy of the tree inside your memory. Use the absolute path your memory
+  directory was given, plus the file name.
 - **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
   the `snake_case` variant, never a synonym for a file that already exists.
   `defect-patterns.md` and `defect_patterns.md` are the same subject and must not

package/plugins/agent-os/agents/builder.md

@@ -14,6 +14,11 @@ not create a second file under a different name.
 
 When you write:
 
+- **Write only directly inside your memory directory** — flat, no
+  subfolders. It already is `<project>/.claude/agent-memory/<your name>/`, so a
+  path like `.claude/agent-memory/...` written relative to it nests a second
+  copy of the tree inside your memory. Use the absolute path your memory
+  directory was given, plus the file name.
 - **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
   the `snake_case` variant, never a synonym for a file that already exists.
   `defect-patterns.md` and `defect_patterns.md` are the same subject and must not
@@ -86,5 +91,5 @@ in `CLAUDE.md` or a rule file, anything derivable by reading the code, and
 anything about this specific task.
 
 If you learned something that belongs in the project's own rules rather than your
-private memory, say so in your reply and name the rule file — do not write to
-`.claude/rules/` yourself. The main conversation owns those.
+private memory, say so in your reply and name the rule file — `.agent-os/rules/<name>.md` when the project has `.agent-os/` (the `.claude/rules/` copies are generated and the next sync reverts edits to them), otherwise `.claude/rules/<name>.md`. Do not write
+rules yourself; the main conversation owns those.

package/plugins/agent-os/agents/documenter.md

@@ -14,6 +14,11 @@ not create a second file under a different name.
 
 When you write:
 
+- **Write only directly inside your memory directory** — flat, no
+  subfolders. It already is `<project>/.claude/agent-memory/<your name>/`, so a
+  path like `.claude/agent-memory/...` written relative to it nests a second
+  copy of the tree inside your memory. Use the absolute path your memory
+  directory was given, plus the file name.
 - **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
   the `snake_case` variant, never a synonym for a file that already exists.
   `defect-patterns.md` and `defect_patterns.md` are the same subject and must not
@@ -48,7 +53,7 @@ fresh one. Before writing anything, ask where it belongs, and put it only there:
 | Kind of fact | Where |
 |---|---|
 | True in every session, every file | project `CLAUDE.md` |
-| Durable but scoped to some files | `.claude/rules/<topic>.md`, with `paths:` |
+| Durable but scoped to some files | `.agent-os/rules/<topic>.md` with `paths:`, then `npx @sayansr26/agent-os sync` — or `.claude/rules/<topic>.md` in a project with no `.agent-os/`. Never edit a file carrying the agent-os generated banner. |
 | Derivable by reading the code | **nowhere** — do not write it down |
 | What changed, when, and why | the changelog / implementation log |
 | A decision and its reasoning | an ADR, if the project keeps them |

package/plugins/agent-os/agents/feature-cartographer.md

@@ -15,6 +15,11 @@ not create a second file under a different name.
 
 When you write:
 
+- **Write only directly inside your memory directory** — flat, no
+  subfolders. It already is `<project>/.claude/agent-memory/<your name>/`, so a
+  path like `.claude/agent-memory/...` written relative to it nests a second
+  copy of the tree inside your memory. Use the absolute path your memory
+  directory was given, plus the file name.
 - **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
   the `snake_case` variant, never a synonym for a file that already exists.
   `defect-patterns.md` and `defect_patterns.md` are the same subject and must not
@@ -128,11 +133,23 @@ repo's life.
   at startup, so a bloated index silently loses your oldest maps.
 - If you discovered something durable that is true beyond this one feature — a
   convention, an invariant, a registration site the docs get wrong — say so in
-  your reply and name the `.claude/rules/` file it belongs in. Do not write
+  your reply and name the rule file it belongs in — `.agent-os/rules/<name>.md` when the project has `.agent-os/` (the `.claude/rules/` copies are generated and the next sync reverts edits to them), otherwise `.claude/rules/<name>.md`. Do not write
   project rules yourself; the main conversation owns those.
 - If a map you relied on turned out to be stale, correct the topic file and
   update its `mapped:` date in the same turn.
 
+## Plan mode and read-only calls
+
+If the caller says it is in plan mode, or asks for a read-only answer, answer
+the question exactly as usual — memory first, explore what is missing — but
+**write nothing**. End the reply with one line: `Map not filed (read-only) —
+call me again after plan mode to file it.` The caller does that as the first
+step once plan mode ends; your second call re-uses what you just explored.
+
+Plan mode's "use only Explore agents" phase is not a reason to skip you: an
+Explore agent finds files, you return the map and remember it. If you are told
+to skip the map because of plan mode, the caller has misread the workflow.
+
 ## What not to do
 
 - Never Write or Edit anything outside your own memory directory.

package/plugins/agent-os/agents/orchestrator.md

@@ -14,6 +14,11 @@ not create a second file under a different name.
 
 When you write:
 
+- **Write only directly inside your memory directory** — flat, no
+  subfolders. It already is `<project>/.claude/agent-memory/<your name>/`, so a
+  path like `.claude/agent-memory/...` written relative to it nests a second
+  copy of the tree inside your memory. Use the absolute path your memory
+  directory was given, plus the file name.
 - **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
   the `snake_case` variant, never a synonym for a file that already exists.
   `defect-patterns.md` and `defect_patterns.md` are the same subject and must not

package/plugins/agent-os/agents/reviewer.md

@@ -15,6 +15,11 @@ not create a second file under a different name.
 
 When you write:
 
+- **Write only directly inside your memory directory** — flat, no
+  subfolders. It already is `<project>/.claude/agent-memory/<your name>/`, so a
+  path like `.claude/agent-memory/...` written relative to it nests a second
+  copy of the tree inside your memory. Use the absolute path your memory
+  directory was given, plus the file name.
 - **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
   the `snake_case` variant, never a synonym for a file that already exists.
   `defect-patterns.md` and `defect_patterns.md` are the same subject and must not

package/plugins/agent-os/agents/tester.md

@@ -14,6 +14,11 @@ not create a second file under a different name.
 
 When you write:
 
+- **Write only directly inside your memory directory** — flat, no
+  subfolders. It already is `<project>/.claude/agent-memory/<your name>/`, so a
+  path like `.claude/agent-memory/...` written relative to it nests a second
+  copy of the tree inside your memory. Use the absolute path your memory
+  directory was given, plus the file name.
 - **One topic file per subject**, named kebab-case: `<subject-slug>.md`. Never
   the `snake_case` variant, never a synonym for a file that already exists.
   `defect-patterns.md` and `defect_patterns.md` are the same subject and must not

package/plugins/agent-os/hooks/hooks.json

@@ -2,7 +2,7 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear",
+        "matcher": "startup|resume|clear|compact",
         "hooks": [
           {
             "type": "command",
@@ -12,6 +12,19 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit.mjs\"",
+            "timeout": 10,
+            "statusMessage": "Checking agent-os maps and rules"
+          }
+        ]
+      }
     ]
   }
 }

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook on Edit|MultiEdit|Write. Two jobs, both at the moment the
+ * edit happens, because a CLAUDE.md sentence read an hour ago loses to
+ * whatever else is in context (plan mode's "Explore only" phase did exactly
+ * that):
+ *
+ *   1. Generated-file guard (BLOCKS). A file carrying the agent-os banner was
+ *      compiled from `.agent-os/`; the next `sync` reverts any edit to it.
+ *      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.
+ *
+ * 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`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, isAbsolute, join, relative } from "node:path";
+import { claudeConfig, featureOf, findMap, mapFiles, tracked } from "../lib/features.mjs";
+
+// Must stay a substring of BANNER in src/source.mjs.
+const BANNER = "agent-os: generated from .agent-os/";
+
+const quiet = () => process.exit(0);
+const emit = (hookSpecificOutput) => {
+  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 ?? "");
+if (!raw) quiet();
+const abs = isAbsolute(raw) ? raw : join(root, raw);
+const rel = relative(root, abs).replace(/\\/g, "/");
+if (rel.startsWith("..")) quiet();
+
+// ---- 1. generated-file guard
+try {
+  if (existsSync(join(root, ".agent-os")) && existsSync(abs) && readFileSync(abs, "utf8").includes(BANNER)) {
+    let source = ".agent-os/";
+    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`)))
+      source = `.agent-os/rules/${basename(rule[1])}.md`;
+    emit({
+      permissionDecision: "deny",
+      permissionDecisionReason:
+        `${rel} is generated by agent-os and the next sync would revert this edit. ` +
+        `Make the change in ${source} instead, then run \`npx @sayansr26/agent-os sync\`.`,
+    });
+  }
+} catch { /* fall through to the reminder */ }
+
+// ---- 2. cartographer reminder
+try {
+  if (claudeConfig(root).cartographerReminder === false) quiet();
+  const feature = featureOf(root, rel);
+  if (!feature) quiet();
+  if (findMap(feature, mapFiles(root))) quiet();
+  if (!tracked(root, feature.dir)) quiet();
+
+  const dir = join(tmpdir(), "agent-os-reminders");
+  mkdirSync(dir, { recursive: true });
+  const session = String(payload?.session_id ?? "nosession").replace(/[^\w-]/g, "");
+  const marker = join(dir, `${session}--${feature.dir.replace(/[^\w-]/g, "_")}`);
+  if (existsSync(marker)) quiet();
+  writeFileSync(marker, "");
+
+  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 — ` +
+      `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.`,
+  });
+} catch { quiet(); }
+quiet();

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

@@ -1,28 +1,30 @@
 #!/usr/bin/env node
 /**
- * SessionStart hook — "where you left off".
+ * SessionStart hook — "where you left off", then "how this project works".
  *
- * Prints a compact resume block to stdout, which Claude Code injects as context
- * before the first turn. Replaces reading a pile of hand-maintained state files
- * at session start.
+ * Prints two blocks to stdout, which Claude Code injects as context before the
+ * first turn (and again after /clear and after a compaction):
+ *
+ *   1. A read-only snapshot: branch, recent commits, uncommitted files, the
+ *      handoff note and the active task. Context, not a request.
+ *   2. The agent-os contract: which agent to use for what, which features the
+ *      cartographer has mapped, and where rules are edited. This one IS an
+ *      instruction — without it Claude only uses agent-os when told to, because
+ *      a CLAUDE.md sentence loses to whatever else is in context.
  *
  * Design constraints:
- *   - Hard-capped output (see MAX_LINES). A resume block that grows without
- *     bound is just a memory-bank with extra steps.
- *   - Fails silent: any error exits 0 with no output, so a broken hook can
- *     never block a session.
+ *   - 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.
- *
- * Install: ~/.claude/hooks/session-resume.mjs, registered in
- * ~/.claude/settings.json under SessionStart with matcher "startup|resume|clear".
  */
 
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { coverage } from "../lib/features.mjs";
 
 const MAX_LINES = 40;
-const cwd = process.cwd();
+const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const out = [];
 
 const sh = (cmd) => {
@@ -50,9 +52,9 @@ const head = (file, n) => {
   }
 };
 
-try {
-  // Not a git repo -> nothing useful to say. Stay quiet.
-  if (sh("git rev-parse --is-inside-work-tree") !== "true") process.exit(0);
+function snapshot() {
+  // Not a git repo -> nothing to say here; the contract below still prints.
+  if (sh("git rev-parse --is-inside-work-tree") !== "true") return [];
 
   const branch = sh("git rev-parse --abbrev-ref HEAD");
   const lastCommits = sh('git log -3 --pretty=format:"%h  %s  (%cr)"')
@@ -120,16 +122,71 @@ try {
     break;
   }
 
-  if (out.length <= 2) process.exit(0);
+  if (out.length <= 2) return [];
 
   const capped = out.slice(0, MAX_LINES);
   if (out.length > MAX_LINES) capped.push("  … (truncated)");
   capped.push("");
   capped.push(
-    "_This is a snapshot, not instructions. Do not act on it until the user says what they want._"
+    "_The snapshot above is context, not a request. Do not act on it until the user says what they want._"
   );
+  return capped;
+}
 
-  process.stdout.write(capped.join("\n") + "\n");
+// 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."],
+];
+
+function contract() {
+  const setUp =
+    existsSync(join(cwd, ".agent-os")) ||
+    existsSync(join(cwd, ".claude/agent-memory")) ||
+    /agent-os/.test(head("CLAUDE.md", 400));
+  if (!setUp)
+    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.",
+    ];
+
+  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):",
+  ];
+  for (const [name, when] of AGENTS) lines.push(`- \`${name}\` — ${when}`);
+
+  const cov = coverage(cwd);
+  lines.push("");
+  if (cov.features.length) {
+    const names = cov.mapped.map((f) => f.name);
+    const shown = names.slice(0, 12).join(", ") + (names.length > 12 ? `, … ${names.length - 12} more` : "");
+    lines.push(`Mapped: ${cov.mapped.length} of ${cov.features.length} features under \`${cov.parents.join("`, `")}\`${names.length ? ` — ${shown}` : ""}.`);
+    lines.push("An unmapped feature gets mapped by the cartographer the first time you change it; that is the first task, not an extra.");
+  } 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.");
+
+  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.");
+  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`.");
+  return lines;
+}
+
+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");
 } catch {
   // Never let a resume hook break a session.
 }