@bonesofspring/ai-rules 0.2.23 → 0.2.25

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## 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/**`.
+- Source: `presets/opencode/next/` derived from `presets/cursor/next` (`adapter-map.json`, `generate-opencode-next.mjs`). `platform-contract.json` `releasedStacks: ["next"]`; nine other stacks deferred.
+- Native OpenCode discovery for agents, skills, and slash commands. Rules under `.opencode/rules/` are lazy-loaded from `AGENTS.md` (no `alwaysApply`/`globs` engine). Pipeline hook is manual `chain-team-phases.sh` (no `hooks.json` plugin in v1).
+- Docs: [`docs/OPENCODE.md`](docs/OPENCODE.md) (consumer), [`docs/OPENCODE-COMPATIBILITY.md`](docs/OPENCODE-COMPATIBILITY.md) (docs-floor evidence). Gates: `check-opencode-*`, `test-opencode-context-budget` wired into `check:preset-structure`.
+- Review follow-up: team-agent write-scope lead-in is role-specific; consumer `OPENCODE.md` no longer uses broken relative doc links; orchestrator uses OpenCode `mode`/`permission` wording; `build-verifier` preset-structure lists OpenCode/Mavis derive gates; Cursor/Claude `REPO_AGENTS.md` keep OpenCode/Mavis pointers so mixed-tool `init` does not drop them.
+- Consumers: re-run `npx @bonesofspring/ai-rules init opencode --preset next` after publish. Cursor/Claude/Mavis installs unchanged.
+
 ### Mavis platform (MiniMax Code, experimental Next-only)
 
 - New platform **`mavis`** (`mcode` runtime): `npx @bonesofspring/ai-rules init mavis --preset next` installs **`.mavis/**`** plus root `AGENTS.md`. `clean mavis` is manifest/hash-safe. MCP merges to **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`.

package/README.md

@@ -1,16 +1,15 @@
 # @bonesofspring/ai-rules
 
-Presets for Cursor, Claude Code, and **Mavis / MiniMax Code (experimental Next-only)**:
+Presets for Cursor, Claude Code, **Mavis / MiniMax Code (experimental Next-only)**, and **OpenCode (experimental Next-only)**:
 
 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 multi --preset next
 npx @bonesofspring/ai-rules clean cursor
 npx @bonesofspring/ai-rules clean mavis
+npx @bonesofspring/ai-rules clean opencode
 ```
 
 Global: `npm i -g @bonesofspring/ai-rules`, then `ai-rules ...`.
@@ -36,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.
 
@@ -58,6 +57,22 @@ 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/**`. 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).
 
 ## Product specs (`docs/specs/`)

package/bin/cli.js

@@ -5,11 +5,15 @@
 const fs = require('fs');
 const path = require('path');
 const { cmdInitMavis, cmdCleanMavis } = require('./mavis-install');
+const { cmdInitOpencode, cmdCleanOpencode } = require('./opencode-install');
 
 /** Single path segment: letters, digits, dot, underscore, hyphen; no separators or "..". */
 const PRESET_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const DEFAULT_PRESET = 'next';
-const TOOLS = new Set(['cursor', 'claude', 'mavis']);
+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: {
@@ -52,9 +56,9 @@ function printHelp() {
   console.log(`@bonesofspring/ai-rules
 
 Usage:
-  ai-rules init <cursor|claude|mavis> [--preset <name>]
-  ai-rules init <cursor|claude|mavis> <preset-name>
-  ai-rules clean <cursor|claude|mavis> [--cwd <dir>]
+  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:
   --preset <name>   Preset name (default: ${DEFAULT_PRESET})
@@ -68,9 +72,11 @@ Notes:
   Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
   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/**).
-  Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
+  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 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:
@@ -96,7 +102,10 @@ Examples:
   npx @bonesofspring/ai-rules init claude --preset php-hexagonal
   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
 `);
 }
@@ -154,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._];
@@ -162,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];
@@ -387,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 [];
@@ -487,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({
@@ -501,9 +574,21 @@ function cmdInit(tool, preset, cwdOption) {
     });
     return;
   }
+  if (tool === 'opencode') {
+    cmdInitOpencode({
+      preset,
+      cwdOption,
+      helpers: {
+        resolveTargetCwd,
+        seedDocsSpecsIfAbsent,
+        getPackageRoot,
+      },
+    });
+    return;
+  }
   const cfg = PRESETS[tool];
   if (!cfg) {
-    console.error(`Unknown tool: ${tool}. Use cursor, claude, or mavis.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, mavis, or opencode.`);
     process.exit(1);
   }
 
@@ -685,13 +770,20 @@ function cmdClean(tool, cwdOption) {
   if (tool === 'mavis') {
     cmdCleanMavis({
       cwdOption,
-      helpers: { resolveTargetCwd },
+      helpers: { resolveTargetCwd, otherToolInstallPresent },
+    });
+    return;
+  }
+  if (tool === 'opencode') {
+    cmdCleanOpencode({
+      cwdOption,
+      helpers: { resolveTargetCwd, otherToolInstallPresent },
     });
     return;
   }
   const cfg = PRESETS[tool];
   if (!cfg) {
-    console.error(`Unknown tool: ${tool}. Use cursor, claude, or mavis.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, mavis, or opencode.`);
     process.exit(1);
   }
   const cwd = resolveTargetCwd(cwdOption);
@@ -728,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);
   }
@@ -760,16 +856,26 @@ 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 [--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');
+      console.error('Missing or invalid tool. Use: clean cursor|claude|mavis|opencode');
       process.exit(1);
     }
     cmdClean(tool, parsed.cwd);

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 {