@bonesofspring/ai-rules 0.2.24 → 0.2.25

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Quad-install Next: shared root `AGENTS.md`
+
+- Cursor, Claude, Mavis, and OpenCode **next** presets now ship the **same** `REPO_AGENTS.md` (presence-based load + per-tool pipeline caveat + local overlay). Last `init` still overwrites the file; content no longer depends on which tool ran last.
+- `clean <tool>` leaves root `AGENTS.md` when another tool install is still present.
+- `init multi --preset next` installs all four platforms in one command (Mavis/OpenCode skipped on stacks they have not released).
+- Consumers: `npx @bonesofspring/ai-rules init multi --preset next` on Next repos.
+
 ### OpenCode platform (experimental Next-only)
 
 - New platform **`opencode`**: `npx @bonesofspring/ai-rules init opencode --preset next` installs **`.opencode/**`** plus root `AGENTS.md` and merges MCP into **`opencode.json`**. `clean opencode` is manifest/hash-safe. The CLI never writes `~/.config/opencode/**`.

package/README.md

@@ -6,10 +6,7 @@ Node 18+.
 
 ```bash
 # from the project root
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init claude --preset next
-npx @bonesofspring/ai-rules init mavis --preset next
-npx @bonesofspring/ai-rules init opencode --preset next
+npx @bonesofspring/ai-rules init multi --preset next
 npx @bonesofspring/ai-rules clean cursor
 npx @bonesofspring/ai-rules clean mavis
 npx @bonesofspring/ai-rules clean opencode
@@ -38,7 +35,7 @@ If `.cursor` does not appear, check the command output for errors and confirm yo
 - optional dirs when present: `agents/`, `hooks/`, `skills/`, `team/`
 - Cursor root files: `hooks.json`, `BUGBOT.md`, `AGENTS.md`, `MCP.md`, `mcp.json`
 - Claude: `CLAUDE.md`, `MCP.md` under `.claude/`; project `.mcp.json` at repo root
-- **Both tools:** repo-root `AGENTS.md` (from preset `REPO_AGENTS.md`)
+- **Shared root `AGENTS.md`:** removed only when no other tool install remains (Cursor, Claude, Mavis, or OpenCode markers still on disk)
 
 Any other files you added under `.cursor/` or `.claude/` (notes, local overrides, IDE state) are **left intact**. Older releases that deleted the whole tool directory are no longer the behavior.
 
@@ -60,7 +57,21 @@ Where things go on `init`:
 
 **Mavis (MiniMax Code, experimental Next-only):** `ai-rules init mavis --preset next` writes ai-rules-owned **`.mavis/**`** plus root `AGENTS.md`. MCP merges into **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`. `clean mavis` is manifest-owned: unchanged hashes are removed; modified files stay. See [`docs/MAVIS.md`](docs/MAVIS.md), [`presets/mavis/README.md`](presets/mavis/README.md), and [`docs/MAVIS-COMPATIBILITY.md`](docs/MAVIS-COMPATIBILITY.md).
 
-**OpenCode (experimental Next-only):** `ai-rules init opencode --preset next` writes native **`.opencode/**`** plus root `AGENTS.md` and merges MCP into **`opencode.json`**. `clean opencode` is manifest-owned. The CLI never writes `~/.config/opencode/**`. Last `init` wins on root `AGENTS.md` if several tools are installed. See [`docs/OPENCODE.md`](docs/OPENCODE.md), [`presets/opencode/README.md`](presets/opencode/README.md), and [`docs/OPENCODE-COMPATIBILITY.md`](docs/OPENCODE-COMPATIBILITY.md).
+**OpenCode (experimental Next-only):** `ai-rules init opencode --preset next` writes native **`.opencode/**`** plus root `AGENTS.md` and merges MCP into **`opencode.json`**. `clean opencode` is manifest-owned. The CLI never writes `~/.config/opencode/**`. All four next platforms ship the **same** root `AGENTS.md` (last `init` still overwrites, content does not change). See [`docs/OPENCODE.md`](docs/OPENCODE.md), [`presets/opencode/README.md`](presets/opencode/README.md), and [`docs/OPENCODE-COMPATIBILITY.md`](docs/OPENCODE-COMPATIBILITY.md).
+
+### Multi-tool on one branch (Next)
+
+Install all four from the app root (`init multi` is the one-shot), then commit the four trees plus root `AGENTS.md`. Living exceptions belong in **`.ai.local/`** (init never touches it).
+
+```bash
+npx @bonesofspring/ai-rules init multi --preset next
+```
+
+Per-tool: `init cursor|claude|mavis|opencode --preset next`. On stacks other than `next`, `init multi` still installs Cursor and Claude and **skips** Mavis/OpenCode until those platforms list the stack in `releasedStacks`.
+
+**Shared:** stack rules (packaged per tool), root `AGENTS.md`, `.ai.local/` overlay.
+
+**Not shared:** `/task` pipelines. Each tool writes `.tool/team/tasks/<slug>/` (`status.json` is not cross-tool). Cursor auto-chains via `hooks.json` / `subagentStop`. Claude ships `chain-team-phases.sh` without `hooks.json`. Mavis and OpenCode are semi-auto: `printf '{"status":"completed"}' | bash .tool/hooks/chain-team-phases.sh`. Mavis/OpenCode remain Next-only.
 
 Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `mockup-review` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — Figma mockup reviewer via agent `mockup-reviewer`); `ux-design` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — behavioral UX via `task-analyst`, no agent); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
 

package/bin/cli.js

@@ -11,6 +11,9 @@ const { cmdInitOpencode, cmdCleanOpencode } = require('./opencode-install');
 const PRESET_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const DEFAULT_PRESET = 'next';
 const TOOLS = new Set(['cursor', 'claude', 'mavis', 'opencode']);
+/** Meta-target: `init multi` runs every platform that has released the preset. */
+const INIT_TARGETS = new Set([...TOOLS, 'multi']);
+const MULTI_INSTALL_ORDER = ['cursor', 'claude', 'mavis', 'opencode'];
 
 const PRESETS = {
   cursor: {
@@ -53,8 +56,8 @@ function printHelp() {
   console.log(`@bonesofspring/ai-rules
 
 Usage:
-  ai-rules init <cursor|claude|mavis|opencode> [--preset <name>]
-  ai-rules init <cursor|claude|mavis|opencode> <preset-name>
+  ai-rules init <cursor|claude|mavis|opencode|multi> [--preset <name>]
+  ai-rules init <cursor|claude|mavis|opencode|multi> <preset-name>
   ai-rules clean <cursor|claude|mavis|opencode> [--cwd <dir>]
 
 Options:
@@ -70,9 +73,10 @@ Notes:
   Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
   Mavis init copies into .mavis/ (ai-rules-owned) plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into .mavis/mcp.json only (never ~/.minimax/**).
   OpenCode init copies into .opencode/ plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into <cwd>/opencode.json (never ~/.config/opencode/**).
-  All init targets also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
+  All init targets also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite; all next platforms ship the same file).
+  init multi installs every platform that has released the preset (cursor, claude, plus mavis/opencode when listed in releasedStacks). Not a clean target.
   When <cwd>/docs/specs/ is absent, init also seeds INDEX.md stub + _templates/* from package assets (never overwrites an existing INDEX).
-  clean removes tool dirs/files and <cwd>/AGENTS.md (shared across tools — re-init the other tool to restore).
+  clean removes tool dirs/files. Shared <cwd>/AGENTS.md is removed only when no other tool install remains.
   Command forms: "init cursor --preset next", "init cursor next", "--preset next init cursor", "cursor init --preset next".
 
 Examples:
@@ -99,6 +103,7 @@ Examples:
   npx @bonesofspring/ai-rules init claude --preset php-laravel
   npx @bonesofspring/ai-rules init mavis --preset next
   npx @bonesofspring/ai-rules init opencode --preset next
+  npx @bonesofspring/ai-rules init multi --preset next
   npx @bonesofspring/ai-rules clean mavis
   npx @bonesofspring/ai-rules clean opencode
   npx @bonesofspring/ai-rules clean cursor
@@ -158,7 +163,7 @@ function parseArgs(argv) {
 }
 
 /**
- * Supports: init cursor, cursor init, init cursor next (positional preset).
+ * Supports: init cursor, cursor init, init cursor next (positional preset), init multi.
  */
 function normalizeInitClean(parsed) {
   const positional = [...parsed._];
@@ -166,11 +171,11 @@ function normalizeInitClean(parsed) {
   let tool;
   let presetFromPositional;
 
-  if (positional.length >= 2 && TOOLS.has(positional[0]) && positional[1] === 'init') {
+  if (positional.length >= 2 && INIT_TARGETS.has(positional[0]) && positional[1] === 'init') {
     command = 'init';
     tool = positional[0];
     presetFromPositional = positional[2];
-  } else if (positional.length >= 2 && positional[0] === 'init' && TOOLS.has(positional[1])) {
+  } else if (positional.length >= 2 && positional[0] === 'init' && INIT_TARGETS.has(positional[1])) {
     command = 'init';
     tool = positional[1];
     presetFromPositional = positional[2];
@@ -391,6 +396,23 @@ function removeFileIfExists(filePath) {
   }
 }
 
+/** Markers that mean a tool install is still present (directory leftovers do not count). */
+const TOOL_INSTALL_MARKERS = {
+  '.cursor': ['.cursor/AGENTS.md', '.cursor/hooks.json', '.cursor/rules'],
+  '.claude': ['.claude/CLAUDE.md', '.claude/rules'],
+  '.mavis': ['.mavis/.ai-rules-install.json', '.mavis/AGENTS.md'],
+  '.opencode': ['.opencode/.ai-rules-install.json', '.opencode/AGENTS.md'],
+};
+
+function otherToolInstallPresent(cwd, exceptRoot) {
+  return Object.entries(TOOL_INSTALL_MARKERS).some(([root, markers]) => {
+    if (root === exceptRoot) {
+      return false;
+    }
+    return markers.some((rel) => fs.existsSync(path.join(cwd, rel)));
+  });
+}
+
 function listPresetNames(presetsRoot) {
   if (!fs.existsSync(presetsRoot)) {
     return [];
@@ -491,6 +513,53 @@ function resolvePresetName(tool, preset, packageRoot) {
   return { name, base, presetsRoot };
 }
 
+function loadReleasedStacks(platform) {
+  if (platform === 'cursor' || platform === 'claude') {
+    return null;
+  }
+  const contractPath = path.join(getPackageRoot(), 'presets', platform, 'platform-contract.json');
+  if (!fs.existsSync(contractPath)) {
+    return [];
+  }
+  try {
+    const contract = JSON.parse(fs.readFileSync(contractPath, 'utf8'));
+    return Array.isArray(contract.releasedStacks) ? contract.releasedStacks : [];
+  } catch {
+    return [];
+  }
+}
+
+function cmdInitMulti(preset, cwdOption) {
+  const presetName = preset === undefined || preset === '' ? DEFAULT_PRESET : preset;
+  const invalid = validatePresetName(presetName);
+  if (invalid) {
+    console.error(invalid);
+    process.exit(1);
+  }
+
+  const installed = [];
+  const skipped = [];
+  for (const tool of MULTI_INSTALL_ORDER) {
+    const released = loadReleasedStacks(tool);
+    if (released && released.length > 0 && !released.includes(presetName)) {
+      skipped.push(tool);
+      console.log(
+        `Skipping ${tool}: preset "${presetName}" is not released yet (released: ${released.join(', ')})`,
+      );
+      continue;
+    }
+    console.log(`\n=== init ${tool} --preset ${presetName} ===`);
+    cmdInit(tool, presetName, cwdOption);
+    installed.push(tool);
+  }
+  if (installed.length === 0) {
+    console.error(`multi: no platforms installed for preset "${presetName}".`);
+    process.exit(1);
+  }
+  const skipNote = skipped.length > 0 ? `; skipped ${skipped.join(', ')}` : '';
+  console.log(`\nDone. multi installed ${installed.join(', ')}${skipNote}`);
+}
+
 function cmdInit(tool, preset, cwdOption) {
   if (tool === 'mavis') {
     cmdInitMavis({
@@ -701,14 +770,14 @@ function cmdClean(tool, cwdOption) {
   if (tool === 'mavis') {
     cmdCleanMavis({
       cwdOption,
-      helpers: { resolveTargetCwd },
+      helpers: { resolveTargetCwd, otherToolInstallPresent },
     });
     return;
   }
   if (tool === 'opencode') {
     cmdCleanOpencode({
       cwdOption,
-      helpers: { resolveTargetCwd },
+      helpers: { resolveTargetCwd, otherToolInstallPresent },
     });
     return;
   }
@@ -751,6 +820,10 @@ function cmdClean(tool, cwdOption) {
   }
 
   for (const destRel of Object.values(cfg.repoRootFiles || {})) {
+    if (destRel === 'AGENTS.md' && otherToolInstallPresent(cwd, toolRoot)) {
+      console.log('Kept shared AGENTS.md (another tool install is still present)');
+      continue;
+    }
     removeFileIfExists(path.join(cwd, destRel));
     removedParts.push(destRel);
   }
@@ -783,14 +856,24 @@ function main() {
   const { command, tool, preset } = normalizeInitClean(parsed);
 
   if (command === 'init') {
-    if (!tool || !TOOLS.has(tool)) {
-      console.error('Missing or invalid tool. Use: init cursor|claude|mavis|opencode [--preset next]');
+    if (!tool || !INIT_TARGETS.has(tool)) {
+      console.error(
+        'Missing or invalid tool. Use: init cursor|claude|mavis|opencode|multi [--preset next]',
+      );
       process.exit(1);
     }
+    if (tool === 'multi') {
+      cmdInitMulti(preset, parsed.cwd);
+      return;
+    }
     cmdInit(tool, preset, parsed.cwd);
     return;
   }
   if (command === 'clean') {
+    if (tool === 'multi') {
+      console.error('clean multi is not supported. Clean each tool: cursor, claude, mavis, opencode.');
+      process.exit(1);
+    }
     if (!tool || !TOOLS.has(tool)) {
       console.error('Missing or invalid tool. Use: clean cursor|claude|mavis|opencode');
       process.exit(1);

package/bin/mavis-install.js

@@ -374,7 +374,7 @@ function removeEmptyDirs(dir) {
 }
 
 function cmdCleanMavis({ cwdOption, helpers }) {
-  const { resolveTargetCwd } = helpers;
+  const { resolveTargetCwd, otherToolInstallPresent } = helpers;
   const cwd = resolveTargetCwd(cwdOption);
   const manifestPath = path.join(cwd, MANIFEST_REL);
   if (!fs.existsSync(manifestPath)) {
@@ -409,6 +409,10 @@ function cmdCleanMavis({ cwdOption, helpers }) {
       continue;
     }
     const current = sha256File(abs);
+    if (rel === 'AGENTS.md' && otherToolInstallPresent && otherToolInstallPresent(cwd, '.mavis')) {
+      console.log('Kept shared AGENTS.md (another tool install is still present)');
+      continue;
+    }
     if (current === installedHash) {
       fs.unlinkSync(abs);
     } else {

package/bin/opencode-install.js

@@ -461,7 +461,7 @@ function removeEmptyDirs(dir) {
 }
 
 function cmdCleanOpencode({ cwdOption, helpers }) {
-  const { resolveTargetCwd } = helpers;
+  const { resolveTargetCwd, otherToolInstallPresent } = helpers;
   const cwd = resolveTargetCwd(cwdOption);
   const manifestPath = path.join(cwd, MANIFEST_REL);
   if (!fs.existsSync(manifestPath)) {
@@ -496,6 +496,10 @@ function cmdCleanOpencode({ cwdOption, helpers }) {
       continue;
     }
     const current = sha256File(abs);
+    if (rel === 'AGENTS.md' && otherToolInstallPresent && otherToolInstallPresent(cwd, '.opencode')) {
+      console.log('Kept shared AGENTS.md (another tool install is still present)');
+      continue;
+    }
     if (current === installedHash) {
       fs.unlinkSync(abs);
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "Presets of Cursor, Claude, Mavis, and OpenCode rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",

package/presets/claude/next/REPO_AGENTS.md

@@ -5,17 +5,30 @@ Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`, `
 ## Cross-tool setup
 
 - Treat this file as the **shared** entry for any agent (Cursor, Claude Code, Mavis, OpenCode, or other).
+- All four platforms ship **the same** root file. `init` overwrites it; content does not depend on which tool ran last.
 - Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md` — use them when that tool is installed.
 - Install:
 
 ```bash
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init claude --preset next
-npx @bonesofspring/ai-rules init mavis --preset next
-npx @bonesofspring/ai-rules init opencode --preset next
+npx @bonesofspring/ai-rules init multi --preset next
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas belong in `team/conventions.md`, not here.
+Per-tool: `init cursor|claude|mavis|opencode --preset next`. `init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). `clean` of one tool leaves this file if another tool install remains. Living gotchas belong in `team/conventions.md` and `.ai.local/conventions.md`, not here.
+
+## Presence-based load
+
+When the tree exists, read the tool map, then the essential rules. Do not preload the full catalog.
+
+- If `.cursor/` exists: read `.cursor/AGENTS.md`.
+- If `.claude/` exists: read `.claude/CLAUDE.md`.
+- If `.mavis/` exists: read `.mavis/AGENTS.md`, then `.mavis/rules/next-app-core.md`, `.mavis/rules/package-manager.md`, `.mavis/rules/code-quality-and-refactoring.md`, `.mavis/rules/ai-local-overlay.md`.
+- If `.opencode/` exists: read `.opencode/AGENTS.md`, then `.opencode/rules/next-app-core.md`, `.opencode/rules/package-manager.md`, `.opencode/rules/code-quality-and-refactoring.md`, `.opencode/rules/ai-local-overlay.md`.
+
+Mavis has no native rule discovery without those root paths. OpenCode has no `alwaysApply` engine — the four `.opencode/rules/*.md` files above are the always-on set.
+
+## Pipelines are per-tool
+
+`/task` slug, `status.json`, and `metrics.json` live under `.tool/team/tasks/<slug>/`. They are **not** shared across Cursor, Claude, Mavis, and OpenCode.
 
 ## Commands (test / lint / build)
 
@@ -51,3 +64,11 @@ Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/sk
 ## Living conventions
 
 Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**, **`.mavis/team/conventions.md`**, and/or **`.opencode/team/conventions.md`** (fill after init; not overwritten on every dogfood sync when already present).
+
+## Local overlay (`.ai.local/`) — MANDATORY
+
+A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
+
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
+
+Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.

package/presets/cursor/next/REPO_AGENTS.md

@@ -5,17 +5,30 @@ Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`, `
 ## Cross-tool setup
 
 - Treat this file as the **shared** entry for any agent (Cursor, Claude Code, Mavis, OpenCode, or other).
+- All four platforms ship **the same** root file. `init` overwrites it; content does not depend on which tool ran last.
 - Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md` — use them when that tool is installed.
 - Install:
 
 ```bash
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init claude --preset next
-npx @bonesofspring/ai-rules init mavis --preset next
-npx @bonesofspring/ai-rules init opencode --preset next
+npx @bonesofspring/ai-rules init multi --preset next
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas belong in `team/conventions.md`, not here.
+Per-tool: `init cursor|claude|mavis|opencode --preset next`. `init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). `clean` of one tool leaves this file if another tool install remains. Living gotchas belong in `team/conventions.md` and `.ai.local/conventions.md`, not here.
+
+## Presence-based load
+
+When the tree exists, read the tool map, then the essential rules. Do not preload the full catalog.
+
+- If `.cursor/` exists: read `.cursor/AGENTS.md`.
+- If `.claude/` exists: read `.claude/CLAUDE.md`.
+- If `.mavis/` exists: read `.mavis/AGENTS.md`, then `.mavis/rules/next-app-core.md`, `.mavis/rules/package-manager.md`, `.mavis/rules/code-quality-and-refactoring.md`, `.mavis/rules/ai-local-overlay.md`.
+- If `.opencode/` exists: read `.opencode/AGENTS.md`, then `.opencode/rules/next-app-core.md`, `.opencode/rules/package-manager.md`, `.opencode/rules/code-quality-and-refactoring.md`, `.opencode/rules/ai-local-overlay.md`.
+
+Mavis has no native rule discovery without those root paths. OpenCode has no `alwaysApply` engine — the four `.opencode/rules/*.md` files above are the always-on set.
+
+## Pipelines are per-tool
+
+`/task` slug, `status.json`, and `metrics.json` live under `.tool/team/tasks/<slug>/`. They are **not** shared across Cursor, Claude, Mavis, and OpenCode.
 
 ## Commands (test / lint / build)
 

package/presets/mavis/next/MAVIS.md

@@ -5,6 +5,7 @@ under `.mavis/skills/**`. This file is ai-rules-owned (`.mavis/AGENTS.md`),
 not a MiniMax-reserved filename.
 
 Root `AGENTS.md` is the compatibility floor. Read it first, then this file.
+Do not write `~/.minimax/**`.
 
 ## How to load
 

package/presets/mavis/next/REPO_AGENTS.md

@@ -1,47 +1,38 @@
 # Next.js — agent instructions
 
-Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`,
-`.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
-
-**.mavis/** is an ai-rules-owned namespace, not a MiniMax-native discovery path.
-When this Mavis preset is installed, read `.mavis/AGENTS.md` on every turn.
-Do not write `~/.minimax/**`. Do not mutate
-`.mavis/team/tasks/<slug>/status.json` or `metrics.json` — the chain runner
-owns those files.
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`, `.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
 
 ## Cross-tool setup
 
-- Treat this file as the **shared** entry for any agent (Cursor, Claude Code,
-  Mavis / MiniMax Code, OpenCode, or other).
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, Mavis, OpenCode, or other).
+- All four platforms ship **the same** root file. `init` overwrites it; content does not depend on which tool ran last.
+- Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md` — use them when that tool is installed.
 - Install:
 
 ```bash
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init claude --preset next
-npx @bonesofspring/ai-rules init mavis --preset next
-npx @bonesofspring/ai-rules init opencode --preset next
+npx @bonesofspring/ai-rules init multi --preset next
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`).
-Living gotchas belong in `team/conventions.md`, not here.
+Per-tool: `init cursor|claude|mavis|opencode --preset next`. `init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). `clean` of one tool leaves this file if another tool install remains. Living gotchas belong in `team/conventions.md` and `.ai.local/conventions.md`, not here.
+
+## Presence-based load
+
+When the tree exists, read the tool map, then the essential rules. Do not preload the full catalog.
 
-## Mavis compatibility entry
+- If `.cursor/` exists: read `.cursor/AGENTS.md`.
+- If `.claude/` exists: read `.claude/CLAUDE.md`.
+- If `.mavis/` exists: read `.mavis/AGENTS.md`, then `.mavis/rules/next-app-core.md`, `.mavis/rules/package-manager.md`, `.mavis/rules/code-quality-and-refactoring.md`, `.mavis/rules/ai-local-overlay.md`.
+- If `.opencode/` exists: read `.opencode/AGENTS.md`, then `.opencode/rules/next-app-core.md`, `.opencode/rules/package-manager.md`, `.opencode/rules/code-quality-and-refactoring.md`, `.opencode/rules/ai-local-overlay.md`.
 
-After install, also read:
+Mavis has no native rule discovery without those root paths. OpenCode has no `alwaysApply` engine — the four `.opencode/rules/*.md` files above are the always-on set.
 
-- `.mavis/AGENTS.md` — Mavis load map, roles, and procedures
-- `.mavis/rules/next-app-core.md`
-- `.mavis/rules/package-manager.md`
-- `.mavis/rules/code-quality-and-refactoring.md`
-- `.mavis/rules/ai-local-overlay.md`
+## Pipelines are per-tool
 
-Launch roles with `mcode exec --file .mavis/agents/<role>.md`. Start work with
-the task procedure in `.mavis/commands/task.md`.
+`/task` slug, `status.json`, and `metrics.json` live under `.tool/team/tasks/<slug>/`. They are **not** shared across Cursor, Claude, Mavis, and OpenCode.
 
 ## Commands (test / lint / build)
 
-Working directory for app scripts: **`app/`**. Detect the package manager from
-lockfile / `packageManager` (`package-manager` rule).
+Working directory for app scripts: **`app/`**. Detect the package manager from lockfile / `packageManager` (`package-manager` rule).
 
 | Gate | Typical command |
 |------|-----------------|
@@ -50,14 +41,12 @@ lockfile / `packageManager` (`package-manager` rule).
 | Unit tests | project unit script under `app/` |
 | Build | project `build` under `app/` |
 
-After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent
-`build-verifier`.
+After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent `build-verifier`.
 
 ## Security basics
 
 - Do not commit secrets (`.env`, tokens, credentials).
-- Review destructive git (`reset --hard`, force-push) before running; respect
-  shell hooks.
+- Review destructive git (`reset --hard`, force-push) before running; respect shell hooks.
 - Do not weaken CI or skip hooks unless the user explicitly asks.
 
 ## Tool entry points
@@ -65,7 +54,7 @@ After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent
 | Tool | Map |
 |------|-----|
 | Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
-| Claude Code | `.claude/CLAUDE.md` (optional if Claude Code not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
 | Mavis | `.mavis/AGENTS.md` (optional if Mavis not installed) |
 | OpenCode | `.opencode/AGENTS.md` (optional if OpenCode not installed) |
 
@@ -74,23 +63,12 @@ Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/sk
 
 ## Living conventions
 
-Gotchas, local patterns, and team decisions:
-**`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**,
-**`.mavis/team/conventions.md`**, and/or **`.opencode/team/conventions.md`**
-(fill after init; not overwritten on every dogfood sync when already present).
+Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**, **`.mavis/team/conventions.md`**, and/or **`.opencode/team/conventions.md`** (fill after init; not overwritten on every dogfood sync when already present).
 
 ## Local overlay (`.ai.local/`) — MANDATORY
 
-A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in
-monorepos. **All agents MUST read and apply it on every turn.** Rules there
-override preset rules; in conflicts, the local rule wins.
-`override: kill <preset-rule-name>` drops the named preset rule from the
-agent's context entirely.
+A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
 
-Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with
-higher priority than preset rules. Living gotchas live in
-`.ai.local/conventions.md`.
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
 
-Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules`
-package. The `ai-local-overlay` rule is the mechanism; this `MANDATORY`
-section is the reinforcement.
+Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.

package/presets/mavis/next/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "mavis",
   "stack": "next",
   "semanticSource": "cursor/next",
-  "sourceRevision": "be606e26d6d0e3f27c2a753e4025925670bc42f6e41d53ec9efc47cdb3a7be7f",
+  "sourceRevision": "8d8f6a3ac169783aef7a31559b7c2e286fe15a9424c6957b54a3396fc347ac47",
   "entries": [
     {
       "source": "AGENTS.md",
@@ -33,9 +33,9 @@
       "source": "REPO_AGENTS.md",
       "target": "REPO_AGENTS.md",
       "category": "entry",
-      "disposition": "transform",
+      "disposition": "copy",
       "loadMode": "root-entry",
-      "reason": "Root AGENTS.md compatibility floor plus explicit .mavis/AGENTS.md pointer"
+      "reason": "Canonical cross-tool root AGENTS.md; identical for all platforms"
     },
     {
       "source": "agents/accessibility-reviewer.md",

package/presets/opencode/next/REPO_AGENTS.md

@@ -1,48 +1,38 @@
 # Next.js — agent instructions
 
-Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`,
-`.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
-
-When this OpenCode preset is installed, read `.opencode/AGENTS.md` on every
-turn. Do not write `~/.config/opencode/**`. Do not mutate
-`.opencode/team/tasks/<slug>/status.json` or `metrics.json` — the chain
-runner owns those files.
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`, `.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
 
 ## Cross-tool setup
 
-- Treat this file as the **shared** entry for any agent (Cursor, Claude Code,
-  Mavis, OpenCode, or other).
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, Mavis, OpenCode, or other).
+- All four platforms ship **the same** root file. `init` overwrites it; content does not depend on which tool ran last.
+- Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md` — use them when that tool is installed.
 - Install:
 
 ```bash
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init claude --preset next
-npx @bonesofspring/ai-rules init mavis --preset next
-npx @bonesofspring/ai-rules init opencode --preset next
+npx @bonesofspring/ai-rules init multi --preset next
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`).
-Living gotchas belong in `team/conventions.md`, not here.
+Per-tool: `init cursor|claude|mavis|opencode --preset next`. `init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). `clean` of one tool leaves this file if another tool install remains. Living gotchas belong in `team/conventions.md` and `.ai.local/conventions.md`, not here.
+
+## Presence-based load
+
+When the tree exists, read the tool map, then the essential rules. Do not preload the full catalog.
 
-## OpenCode load map
+- If `.cursor/` exists: read `.cursor/AGENTS.md`.
+- If `.claude/` exists: read `.claude/CLAUDE.md`.
+- If `.mavis/` exists: read `.mavis/AGENTS.md`, then `.mavis/rules/next-app-core.md`, `.mavis/rules/package-manager.md`, `.mavis/rules/code-quality-and-refactoring.md`, `.mavis/rules/ai-local-overlay.md`.
+- If `.opencode/` exists: read `.opencode/AGENTS.md`, then `.opencode/rules/next-app-core.md`, `.opencode/rules/package-manager.md`, `.opencode/rules/code-quality-and-refactoring.md`, `.opencode/rules/ai-local-overlay.md`.
 
-After install, also read:
+Mavis has no native rule discovery without those root paths. OpenCode has no `alwaysApply` engine — the four `.opencode/rules/*.md` files above are the always-on set.
 
-- `.opencode/AGENTS.md` — OpenCode load map, roles, and procedures
-- `.opencode/rules/next-app-core.md`
-- `.opencode/rules/package-manager.md`
-- `.opencode/rules/code-quality-and-refactoring.md`
-- `.opencode/rules/ai-local-overlay.md`
+## Pipelines are per-tool
 
-Do **not** preload the full `.opencode/rules/` catalog. Native agents live in
-`.opencode/agents/`; skills in `.opencode/skills/`; slash commands in
-`.opencode/commands/` (`/task`). After a producer receipt run
-`bash .opencode/hooks/chain-team-phases.sh`.
+`/task` slug, `status.json`, and `metrics.json` live under `.tool/team/tasks/<slug>/`. They are **not** shared across Cursor, Claude, Mavis, and OpenCode.
 
 ## Commands (test / lint / build)
 
-Working directory for app scripts: **`app/`**. Detect the package manager from
-lockfile / `packageManager` (`package-manager` rule).
+Working directory for app scripts: **`app/`**. Detect the package manager from lockfile / `packageManager` (`package-manager` rule).
 
 | Gate | Typical command |
 |------|-----------------|
@@ -51,14 +41,12 @@ lockfile / `packageManager` (`package-manager` rule).
 | Unit tests | project unit script under `app/` |
 | Build | project `build` under `app/` |
 
-After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent
-`build-verifier`.
+After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent `build-verifier`.
 
 ## Security basics
 
 - Do not commit secrets (`.env`, tokens, credentials).
-- Review destructive git (`reset --hard`, force-push) before running; respect
-  shell hooks.
+- Review destructive git (`reset --hard`, force-push) before running; respect shell hooks.
 - Do not weaken CI or skip hooks unless the user explicitly asks.
 
 ## Tool entry points
@@ -66,7 +54,7 @@ After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent
 | Tool | Map |
 |------|-----|
 | Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
-| Claude Code | `.claude/CLAUDE.md` (optional if Claude Code not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
 | Mavis | `.mavis/AGENTS.md` (optional if Mavis not installed) |
 | OpenCode | `.opencode/AGENTS.md` (optional if OpenCode not installed) |
 
@@ -75,23 +63,12 @@ Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/sk
 
 ## Living conventions
 
-Gotchas, local patterns, and team decisions:
-**`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**,
-**`.mavis/team/conventions.md`**, and/or **`.opencode/team/conventions.md`**
-(fill after init; not overwritten on every dogfood sync when already present).
+Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**, **`.mavis/team/conventions.md`**, and/or **`.opencode/team/conventions.md`** (fill after init; not overwritten on every dogfood sync when already present).
 
 ## Local overlay (`.ai.local/`) — MANDATORY
 
-A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in
-monorepos. **All agents MUST read and apply it on every turn.** Rules there
-override preset rules; in conflicts, the local rule wins.
-`override: kill <preset-rule-name>` drops the named preset rule from the
-agent's context entirely.
+A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
 
-Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with
-higher priority than preset rules. Living gotchas live in
-`.ai.local/conventions.md`.
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
 
-Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules`
-package. The `ai-local-overlay` rule is the mechanism; this `MANDATORY`
-section is the reinforcement.
+Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.

package/presets/opencode/next/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "opencode",
   "stack": "next",
   "semanticSource": "cursor/next",
-  "sourceRevision": "be606e26d6d0e3f27c2a753e4025925670bc42f6e41d53ec9efc47cdb3a7be7f",
+  "sourceRevision": "8d8f6a3ac169783aef7a31559b7c2e286fe15a9424c6957b54a3396fc347ac47",
   "entries": [
     {
       "source": "AGENTS.md",
@@ -33,9 +33,9 @@
       "source": "REPO_AGENTS.md",
       "target": "REPO_AGENTS.md",
       "category": "entry",
-      "disposition": "transform",
+      "disposition": "copy",
       "loadMode": "root-entry",
-      "reason": "Root AGENTS.md is OpenCode native always-on plus cross-tool pointers"
+      "reason": "Canonical cross-tool root AGENTS.md; identical for all platforms"
     },
     {
       "source": "agents/accessibility-reviewer.md",

package/scripts/fixtures/cli-golden/claude/next.json

@@ -122,7 +122,7 @@
     ".claude/team/fixtures/ux-design-standalone.json": "528aeb9db4c310d1b5e3eacae0ad39a4fd1dd49c04154b064e7027981488a07a",
     ".claude/team/tasks/.gitkeep": "aca85ed348a49b11d68188be6ab245b521e5a706bbe0fbca1a28abfdc7155893",
     ".mcp.json": "f68a14db68a491a982975a3e6cc985057072a68eebdcedf33d8ac2a4a3b284ca",
-    "AGENTS.md": "8c90523299194b7796390550c66e7d3442daa385fe5647761deea05e4cab7dc3",
+    "AGENTS.md": "0eaef34cabb183f665f25bc85863cbd528967589f49e808a71196748f882a085",
     "docs/specs/INDEX.md": "cab59f2093e6aaa376246a56d53e4268cb59070a6b10e87a94895192c35f422d",
     "docs/specs/_templates/feature.md": "83c47b90334c555fb5144749837e2ddfe1cae5bb89031f885ba98671075d59e7",
     "docs/specs/_templates/page.md": "a668c584e28edd52afaf3f9f8f898a75e43cb82fa12822c7a016033441e12e54"

package/scripts/fixtures/cli-golden/cursor/next.json

@@ -124,7 +124,7 @@
     ".cursor/team/fixtures/mockup-review-standalone.json": "edda49b1298e94f9a33496317e9f6ccbbb047659e044e05ba35669bfe800eda6",
     ".cursor/team/fixtures/ux-design-standalone.json": "528aeb9db4c310d1b5e3eacae0ad39a4fd1dd49c04154b064e7027981488a07a",
     ".cursor/team/tasks/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-    "AGENTS.md": "de61cddb2fb50d27150ba5427a9c445373d62fe6be136b9da07b130e6fe12c2e",
+    "AGENTS.md": "0eaef34cabb183f665f25bc85863cbd528967589f49e808a71196748f882a085",
     "docs/specs/INDEX.md": "cab59f2093e6aaa376246a56d53e4268cb59070a6b10e87a94895192c35f422d",
     "docs/specs/_templates/feature.md": "83c47b90334c555fb5144749837e2ddfe1cae5bb89031f885ba98671075d59e7",
     "docs/specs/_templates/page.md": "a668c584e28edd52afaf3f9f8f898a75e43cb82fa12822c7a016033441e12e54"

package/scripts/fixtures/cli-golden/mavis/next.json

@@ -3,7 +3,7 @@
   "tool": "mavis",
   "preset": "next",
   "files": {
-    ".mavis/AGENTS.md": "66e2d2528ee0e35118fbcd7e9542c2aeab9b47408803dd6bbd9b1ace1c7af57f",
+    ".mavis/AGENTS.md": "a7e41d4012a72d183e07f48f7d811b1f6e1373ceedac7a46bfe4066bae931294",
     ".mavis/MCP.md": "e224fc1d22001949a240a66004da1524939a2b81431425d60ed17167c01a9fdf",
     ".mavis/agents/README.md": "62aa541b25f260a4a0f932ee844752bf92c7279c2c72b6db1d1e2c84bc0fff16",
     ".mavis/agents/accessibility-reviewer.md": "1781f56dd6384c2b47f6148ae244f2ddf527f4e48ebf8fd8aae36d22db82903f",
@@ -117,7 +117,7 @@
     ".mavis/team/fixtures/mockup-review-standalone.json": "edda49b1298e94f9a33496317e9f6ccbbb047659e044e05ba35669bfe800eda6",
     ".mavis/team/fixtures/ux-design-standalone.json": "528aeb9db4c310d1b5e3eacae0ad39a4fd1dd49c04154b064e7027981488a07a",
     ".mavis/team/tasks/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-    "AGENTS.md": "98fb17139dd1e665cddc7e3d8ae75971b10e88ae36fbcf181897820b4ec5c426",
+    "AGENTS.md": "0eaef34cabb183f665f25bc85863cbd528967589f49e808a71196748f882a085",
     "docs/specs/INDEX.md": "cab59f2093e6aaa376246a56d53e4268cb59070a6b10e87a94895192c35f422d",
     "docs/specs/_templates/feature.md": "83c47b90334c555fb5144749837e2ddfe1cae5bb89031f885ba98671075d59e7",
     "docs/specs/_templates/page.md": "a668c584e28edd52afaf3f9f8f898a75e43cb82fa12822c7a016033441e12e54"

package/scripts/fixtures/cli-golden/opencode/next.json

@@ -116,7 +116,7 @@
     ".opencode/team/fixtures/mockup-review-standalone.json": "edda49b1298e94f9a33496317e9f6ccbbb047659e044e05ba35669bfe800eda6",
     ".opencode/team/fixtures/ux-design-standalone.json": "528aeb9db4c310d1b5e3eacae0ad39a4fd1dd49c04154b064e7027981488a07a",
     ".opencode/team/tasks/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-    "AGENTS.md": "2a301d7bb2565b2935d816a91dffe0fb837aeb1511857cde0eef4400394bcc48",
+    "AGENTS.md": "0eaef34cabb183f665f25bc85863cbd528967589f49e808a71196748f882a085",
     "docs/specs/INDEX.md": "cab59f2093e6aaa376246a56d53e4268cb59070a6b10e87a94895192c35f422d",
     "docs/specs/_templates/feature.md": "83c47b90334c555fb5144749837e2ddfe1cae5bb89031f885ba98671075d59e7",
     "docs/specs/_templates/page.md": "a668c584e28edd52afaf3f9f8f898a75e43cb82fa12822c7a016033441e12e54",

package/scripts/generate-mavis-next.mjs

@@ -231,15 +231,15 @@ function main() {
 
     if (source === 'REPO_AGENTS.md') {
       const target = 'REPO_AGENTS.md';
-      writeFile(target, buildRepoAgents(sourceText));
+      writeFile(target, sourceText);
       entries.push(
         entry({
           source,
           target,
           category: 'entry',
-          disposition: 'transform',
+          disposition: 'copy',
           loadMode: 'root-entry',
-          reason: 'Root AGENTS.md compatibility floor plus explicit .mavis/AGENTS.md pointer',
+          reason: 'Canonical cross-tool root AGENTS.md; identical for all platforms',
           sourceText,
         }),
       );
@@ -407,106 +407,6 @@ function dropLeadingHeading(text) {
     .replace(/^Short Cursor entry point\.[^\n]*\n+/, '');
 }
 
-function buildRepoAgents(_sourceText) {
-  return `# Next.js — agent instructions
-
-Cross-tool repo-root guide. Tool-specific maps stay under \`.cursor/AGENTS.md\`,
-\`.claude/CLAUDE.md\`, \`.mavis/AGENTS.md\`, and \`.opencode/AGENTS.md\`.
-
-**.mavis/** is an ai-rules-owned namespace, not a MiniMax-native discovery path.
-When this Mavis preset is installed, read \`.mavis/AGENTS.md\` on every turn.
-Do not write \`~/.minimax/**\`. Do not mutate
-\`.mavis/team/tasks/<slug>/status.json\` or \`metrics.json\` — the chain runner
-owns those files.
-
-## Cross-tool setup
-
-- Treat this file as the **shared** entry for any agent (Cursor, Claude Code,
-  Mavis / MiniMax Code, OpenCode, or other).
-- Install:
-
-\`\`\`bash
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init claude --preset next
-npx @bonesofspring/ai-rules init mavis --preset next
-npx @bonesofspring/ai-rules init opencode --preset next
-\`\`\`
-
-\`init\` overwrites this file from the preset (\`REPO_AGENTS.md\` → \`AGENTS.md\`).
-Living gotchas belong in \`team/conventions.md\`, not here.
-
-## Mavis compatibility entry
-
-After install, also read:
-
-- \`.mavis/AGENTS.md\` — Mavis load map, roles, and procedures
-- \`.mavis/rules/next-app-core.md\`
-- \`.mavis/rules/package-manager.md\`
-- \`.mavis/rules/code-quality-and-refactoring.md\`
-- \`.mavis/rules/ai-local-overlay.md\`
-
-Launch roles with \`mcode exec --file .mavis/agents/<role>.md\`. Start work with
-the task procedure in \`.mavis/commands/task.md\`.
-
-## Commands (test / lint / build)
-
-Working directory for app scripts: **\`app/\`**. Detect the package manager from
-lockfile / \`packageManager\` (\`package-manager\` rule).
-
-| Gate | Typical command |
-|------|-----------------|
-| Lint JS | \`yarn lint:js\` (or project equivalent) from \`app/\` |
-| Lint CSS | \`yarn lint:css\` from \`app/\` |
-| Unit tests | project unit script under \`app/\` |
-| Build | project \`build\` under \`app/\` |
-
-After code edits: invoke **\`post-change-lint\`** (requestable). Full gate: agent
-\`build-verifier\`.
-
-## Security basics
-
-- Do not commit secrets (\`.env\`, tokens, credentials).
-- Review destructive git (\`reset --hard\`, force-push) before running; respect
-  shell hooks.
-- Do not weaken CI or skip hooks unless the user explicitly asks.
-
-## Tool entry points
-
-| Tool | Map |
-|------|-----|
-| Cursor | \`.cursor/AGENTS.md\` (optional if Cursor not installed) |
-| Claude Code | \`.claude/CLAUDE.md\` (optional if Claude Code not installed) |
-| Mavis | \`.mavis/AGENTS.md\` (optional if Mavis not installed) |
-| OpenCode | \`.opencode/AGENTS.md\` (optional if OpenCode not installed) |
-
-Rules: \`.cursor/rules/\`, \`.claude/rules/\`, \`.mavis/rules/\`, or \`.opencode/rules/\`.
-Skills: \`.cursor/skills/\`, \`.claude/skills/\`, \`.mavis/skills/\`, or \`.opencode/skills/\`.
-
-## Living conventions
-
-Gotchas, local patterns, and team decisions:
-**\`.cursor/team/conventions.md\`**, **\`.claude/team/conventions.md\`**,
-**\`.mavis/team/conventions.md\`**, and/or **\`.opencode/team/conventions.md\`**
-(fill after init; not overwritten on every dogfood sync when already present).
-
-## Local overlay (\`.ai.local/\`) — MANDATORY
-
-A \`.ai.local/\` directory MAY exist at the repo root or at any nesting depth in
-monorepos. **All agents MUST read and apply it on every turn.** Rules there
-override preset rules; in conflicts, the local rule wins.
-\`override: kill <preset-rule-name>\` drops the named preset rule from the
-agent's context entirely.
-
-Plain markdown rules under \`.ai.local/rules/*.md\` are read by the agent with
-higher priority than preset rules. Living gotchas live in
-\`.ai.local/conventions.md\`.
-
-Authoring guide: \`docs/LOCAL-OVERLAY.md\` in the \`@bonesofspring/ai-rules\`
-package. The \`ai-local-overlay\` rule is the mechanism; this \`MANDATORY\`
-section is the reinforcement.
-`;
-}
-
 function stripInstallSection(body) {
   const index = body.search(/^## Install\r?\n/m);
   if (index < 0) {
@@ -535,6 +435,7 @@ under \`.mavis/skills/**\`. This file is ai-rules-owned (\`.mavis/AGENTS.md\`),
 not a MiniMax-reserved filename.
 
 Root \`AGENTS.md\` is the compatibility floor. Read it first, then this file.
+Do not write \`~/.minimax/**\`.
 
 ## How to load
 

package/scripts/generate-opencode-next.mjs

@@ -341,15 +341,15 @@ function main() {
 
     if (source === 'REPO_AGENTS.md') {
       const target = 'REPO_AGENTS.md';
-      writeFile(target, buildRepoAgents());
+      writeFile(target, sourceText);
       entries.push(
         entry({
           source,
           target,
           category: 'entry',
-          disposition: 'transform',
+          disposition: 'copy',
           loadMode: 'root-entry',
-          reason: 'Root AGENTS.md is OpenCode native always-on plus cross-tool pointers',
+          reason: 'Canonical cross-tool root AGENTS.md; identical for all platforms',
           sourceText,
         }),
       );
@@ -541,107 +541,6 @@ function dropLeadingHeading(text) {
     .replace(/^Short Cursor entry point\.[^\n]*\n+/, '');
 }
 
-function buildRepoAgents() {
-  return `# Next.js — agent instructions
-
-Cross-tool repo-root guide. Tool-specific maps stay under \`.cursor/AGENTS.md\`,
-\`.claude/CLAUDE.md\`, \`.mavis/AGENTS.md\`, and \`.opencode/AGENTS.md\`.
-
-When this OpenCode preset is installed, read \`.opencode/AGENTS.md\` on every
-turn. Do not write \`~/.config/opencode/**\`. Do not mutate
-\`.opencode/team/tasks/<slug>/status.json\` or \`metrics.json\` — the chain
-runner owns those files.
-
-## Cross-tool setup
-
-- Treat this file as the **shared** entry for any agent (Cursor, Claude Code,
-  Mavis, OpenCode, or other).
-- Install:
-
-\`\`\`bash
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init claude --preset next
-npx @bonesofspring/ai-rules init mavis --preset next
-npx @bonesofspring/ai-rules init opencode --preset next
-\`\`\`
-
-\`init\` overwrites this file from the preset (\`REPO_AGENTS.md\` → \`AGENTS.md\`).
-Living gotchas belong in \`team/conventions.md\`, not here.
-
-## OpenCode load map
-
-After install, also read:
-
-- \`.opencode/AGENTS.md\` — OpenCode load map, roles, and procedures
-- \`.opencode/rules/next-app-core.md\`
-- \`.opencode/rules/package-manager.md\`
-- \`.opencode/rules/code-quality-and-refactoring.md\`
-- \`.opencode/rules/ai-local-overlay.md\`
-
-Do **not** preload the full \`.opencode/rules/\` catalog. Native agents live in
-\`.opencode/agents/\`; skills in \`.opencode/skills/\`; slash commands in
-\`.opencode/commands/\` (\`/task\`). After a producer receipt run
-\`bash .opencode/hooks/chain-team-phases.sh\`.
-
-## Commands (test / lint / build)
-
-Working directory for app scripts: **\`app/\`**. Detect the package manager from
-lockfile / \`packageManager\` (\`package-manager\` rule).
-
-| Gate | Typical command |
-|------|-----------------|
-| Lint JS | \`yarn lint:js\` (or project equivalent) from \`app/\` |
-| Lint CSS | \`yarn lint:css\` from \`app/\` |
-| Unit tests | project unit script under \`app/\` |
-| Build | project \`build\` under \`app/\` |
-
-After code edits: invoke **\`post-change-lint\`** (requestable). Full gate: agent
-\`build-verifier\`.
-
-## Security basics
-
-- Do not commit secrets (\`.env\`, tokens, credentials).
-- Review destructive git (\`reset --hard\`, force-push) before running; respect
-  shell hooks.
-- Do not weaken CI or skip hooks unless the user explicitly asks.
-
-## Tool entry points
-
-| Tool | Map |
-|------|-----|
-| Cursor | \`.cursor/AGENTS.md\` (optional if Cursor not installed) |
-| Claude Code | \`.claude/CLAUDE.md\` (optional if Claude Code not installed) |
-| Mavis | \`.mavis/AGENTS.md\` (optional if Mavis not installed) |
-| OpenCode | \`.opencode/AGENTS.md\` (optional if OpenCode not installed) |
-
-Rules: \`.cursor/rules/\`, \`.claude/rules/\`, \`.mavis/rules/\`, or \`.opencode/rules/\`.
-Skills: \`.cursor/skills/\`, \`.claude/skills/\`, \`.mavis/skills/\`, or \`.opencode/skills/\`.
-
-## Living conventions
-
-Gotchas, local patterns, and team decisions:
-**\`.cursor/team/conventions.md\`**, **\`.claude/team/conventions.md\`**,
-**\`.mavis/team/conventions.md\`**, and/or **\`.opencode/team/conventions.md\`**
-(fill after init; not overwritten on every dogfood sync when already present).
-
-## Local overlay (\`.ai.local/\`) — MANDATORY
-
-A \`.ai.local/\` directory MAY exist at the repo root or at any nesting depth in
-monorepos. **All agents MUST read and apply it on every turn.** Rules there
-override preset rules; in conflicts, the local rule wins.
-\`override: kill <preset-rule-name>\` drops the named preset rule from the
-agent's context entirely.
-
-Plain markdown rules under \`.ai.local/rules/*.md\` are read by the agent with
-higher priority than preset rules. Living gotchas live in
-\`.ai.local/conventions.md\`.
-
-Authoring guide: \`docs/LOCAL-OVERLAY.md\` in the \`@bonesofspring/ai-rules\`
-package. The \`ai-local-overlay\` rule is the mechanism; this \`MANDATORY\`
-section is the reinforcement.
-`;
-}
-
 function stripInstallSection(body) {
   const index = body.search(/^## Install\r?\n/m);
   if (index < 0) {

package/scripts/test-cli-init-clean.mjs

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { runInit, snapshotInstall } from './lib/cli-golden.mjs';
+import { runInit, sha256File, snapshotInstall } from './lib/cli-golden.mjs';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const packageDirectory = path.resolve(scriptDirectory, '..');
@@ -116,7 +116,7 @@ assert.equal(manifest.docsSeed.seeded, true);
 const existingAgents = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-mavis-agents-'));
 fs.writeFileSync(path.join(existingAgents, 'AGENTS.md'), '# consumer agents\n');
 runInit(cli, existingAgents, 'mavis', 'next');
-assert.match(fs.readFileSync(path.join(existingAgents, 'AGENTS.md'), 'utf8'), /Mavis compatibility entry/);
+assert.match(fs.readFileSync(path.join(existingAgents, 'AGENTS.md'), 'utf8'), /Presence-based load/);
 
 const specsExist = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-mavis-specs-'));
 fs.mkdirSync(path.join(specsExist, 'docs', 'specs'), { recursive: true });
@@ -261,7 +261,7 @@ assert.equal(ocManifest.docsSeed.seeded, true);
 const ocAgents = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-opencode-agents-'));
 fs.writeFileSync(path.join(ocAgents, 'AGENTS.md'), '# consumer agents\n');
 runInit(cli, ocAgents, 'opencode', 'next');
-assert.match(fs.readFileSync(path.join(ocAgents, 'AGENTS.md'), 'utf8'), /OpenCode load map/);
+assert.match(fs.readFileSync(path.join(ocAgents, 'AGENTS.md'), 'utf8'), /Presence-based load/);
 
 const ocSpecs = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-opencode-specs-'));
 fs.mkdirSync(path.join(ocSpecs, 'docs', 'specs'), { recursive: true });
@@ -341,6 +341,68 @@ if (!fs.existsSync(ocGoldenPath)) {
   assert.deepEqual(ocFiles, expectedOc.files, 'opencode/next golden drifted');
 }
 
+const canonicalRepoAgents = fs.readFileSync(
+  path.join(packageDirectory, 'presets', 'cursor', 'next', 'REPO_AGENTS.md'),
+  'utf8',
+);
+for (const platform of ['claude', 'mavis', 'opencode']) {
+  const other = fs.readFileSync(
+    path.join(packageDirectory, 'presets', platform, 'next', 'REPO_AGENTS.md'),
+    'utf8',
+  );
+  assert.equal(other, canonicalRepoAgents, `${platform}/next/REPO_AGENTS.md must match cursor SoT`);
+}
+
+const lastInitHashes = [];
+const lastInitDirs = [];
+for (const tool of ['cursor', 'claude', 'mavis', 'opencode']) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `ai-rules-last-init-${tool}-`));
+  lastInitDirs.push(dir);
+  runInit(cli, dir, tool, 'next');
+  lastInitHashes.push(sha256File(path.join(dir, 'AGENTS.md')));
+  assert.match(fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf8'), /Presence-based load/);
+  assert.match(fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf8'), /Pipelines are per-tool/);
+}
+assert.equal(new Set(lastInitHashes).size, 1, 'root AGENTS.md must be identical after any last init');
+
+const mixed = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-quad-clean-'));
+runInit(cli, mixed, 'cursor', 'next');
+runInit(cli, mixed, 'mavis', 'next');
+assert.match(fs.readFileSync(path.join(mixed, 'AGENTS.md'), 'utf8'), /Presence-based load/);
+const keepCursor = runClean(mixed, 'cursor');
+assert.match(keepCursor, /Kept shared AGENTS.md/);
+assert.equal(fs.existsSync(path.join(mixed, 'AGENTS.md')), true);
+runClean(mixed, 'mavis');
+assert.equal(fs.existsSync(path.join(mixed, 'AGENTS.md')), false);
+
+const cursorOnly = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-cursor-only-clean-'));
+runInit(cli, cursorOnly, 'cursor', 'next');
+runClean(cursorOnly, 'cursor');
+assert.equal(fs.existsSync(path.join(cursorOnly, 'AGENTS.md')), false);
+
+const multiDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-init-multi-'));
+const multiOut = runInit(cli, multiDir, 'multi', 'next');
+assert.match(multiOut, /Done\. multi installed cursor, claude, mavis, opencode/);
+assert.equal(fs.existsSync(path.join(multiDir, '.cursor', 'AGENTS.md')), true);
+assert.equal(fs.existsSync(path.join(multiDir, '.claude', 'CLAUDE.md')), true);
+assert.equal(fs.existsSync(path.join(multiDir, '.mavis', 'AGENTS.md')), true);
+assert.equal(fs.existsSync(path.join(multiDir, '.opencode', 'AGENTS.md')), true);
+assert.match(fs.readFileSync(path.join(multiDir, 'AGENTS.md'), 'utf8'), /init multi --preset next/);
+
+const multiNuxt = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-init-multi-nuxt-'));
+const multiNuxtOut = runInit(cli, multiNuxt, 'multi', 'nuxt');
+assert.match(multiNuxtOut, /Skipping mavis/);
+assert.match(multiNuxtOut, /Skipping opencode/);
+assert.match(multiNuxtOut, /Done\. multi installed cursor, claude; skipped mavis, opencode/);
+assert.equal(fs.existsSync(path.join(multiNuxt, '.cursor', 'AGENTS.md')), true);
+assert.equal(fs.existsSync(path.join(multiNuxt, '.claude', 'CLAUDE.md')), true);
+assert.equal(fs.existsSync(path.join(multiNuxt, '.mavis')), false);
+assert.equal(fs.existsSync(path.join(multiNuxt, '.opencode')), false);
+
+const multiClean = runCli(multiDir, ['clean', 'multi']);
+assert.equal(multiClean.status, 1);
+assert.match(`${multiClean.stderr}${multiClean.stdout}`, /clean multi is not supported/);
+
 for (const dir of [
   isolatedHome,
   fresh,
@@ -360,6 +422,11 @@ for (const dir of [
   ocMissing,
   ocRollback,
   ocGoldenDir,
+  mixed,
+  cursorOnly,
+  multiDir,
+  multiNuxt,
+  ...lastInitDirs,
 ]) {
   fs.rmSync(dir, { recursive: true, force: true });
 }