@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "Presets of Cursor, Claude, Mavis, and OpenCode rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -23,7 +23,9 @@
   "files": [
     "README.md",
     "CHANGELOG.md",
+    "LICENSE",
     "bin",
+    "docs",
     "presets",
     "scripts"
   ],
@@ -35,10 +37,12 @@
     "check:hook-only-lifecycle": "bash scripts/check-hook-only-lifecycle.sh",
     "check:local-overlay": "bash scripts/check-local-overlay.sh",
     "check:preset-i18n": "AI_RULES_I18N_FAIL=1 AI_RULES_I18N_SOFT=0 bash scripts/check-preset-i18n.sh",
+    "check:frontmatter": "node scripts/check-frontmatter.mjs",
     "check:shared-core-drift": "bash scripts/check-shared-core-drift.sh",
     "check:product-specs": "bash scripts/check-product-specs.sh",
     "check:product-specs:dogfood": "bash scripts/check-product-specs.sh ../../dogfood/mcp-ts-sample",
     "check:rule-eval": "node scripts/check-rule-eval.mjs",
+    "check:generated-drift": "node scripts/check-generated-drift.mjs",
     "test:cli-mcp-merge": "node scripts/test-cli-mcp-merge.mjs",
     "test:cli-init-clean": "node scripts/test-cli-init-clean.mjs",
     "test:chain-coverage": "node scripts/test-chain-team-phases-coverage.mjs",
@@ -53,7 +57,10 @@
     "check:opencode-adapter-map": "node scripts/check-opencode-adapter-map.mjs --self-test",
     "check:opencode-token-budget": "node scripts/check-opencode-token-budget.mjs",
     "check:opencode-local-overlay": "node scripts/check-opencode-local-overlay.mjs",
-    "test:opencode-context-budget": "node scripts/test-opencode-context-budget.mjs"
+    "test:opencode-context-budget": "node scripts/test-opencode-context-budget.mjs",
+    "test:probe-mavis-capabilities": "node scripts/test-probe-mavis-capabilities.mjs",
+    "generate:mavis": "node scripts/generate-mavis.mjs",
+    "generate:opencode": "node scripts/generate-opencode.mjs"
   },
   "engines": {
     "node": ">=18"

package/presets/_shared/README.md

@@ -1,48 +1,33 @@
 # Shared preset core (`presets/_shared`)
 
-Stack-agnostic **prose and checklists** for all installable presets: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (`cursor/<stack>`, `claude/<stack>`).
-
-**Not an installable preset.** CLI `init` copies only under `presets/cursor/<name>/` or `presets/claude/<name>/` — this sibling is never shipped to consumer apps.
-
-## Layers
+Stack-agnostic prose for all installable stacks. **Not an `--preset`.** `init` copies only `presets/<platform>/<stack>/`.
 
 ```text
-Core (_shared/core)     → stack-agnostic prose
-Stack (cursor|claude/<stack>) → domain / tooling deltas
-Platform adapter        → .mdc frontmatter | .md + paths:
+_shared/core  →  cursor/<stack>   (SoT)
+              →  claude/<stack>   (twin, same PR)
+              →  mavis/<stack>    (generated)
+              →  opencode/<stack> (generated)
 ```
 
-See meta-rules: `core/meta/preset-layering.md`, `preset-twin-sync.md`, `preset-token-budget.md`, `preset-pr-checklist.md`, `preset-no-cross-stack-leakage.md`.
-
-**Contributing:** [`../../docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md) (full guide: layers, SoT, new stack, platform artifacts, PR checklist).
-
-## Sync model
-
-1. Edit core under `core/**` when changing shared principles.
-2. Update every consumer that carries `<!-- shared-core: <path> -->` in the **same PR**.
-3. Cursor `presets/cursor/<stack>/` is SoT per stack; Claude twins are derived in the same PR.
-4. Dogfood: `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (packages → root `.cursor/`).
-
-### Sync modes (marker semantics)
-
-| Mode | Marker | Adapter body | Typical stems |
-|------|--------|--------------|---------------|
-| **Embed** | `<!-- shared-core: … -->` | Core prose + optional `## Stack notes` only for deltas | `quality/*`, `meta/preset-*`, thin review/intake aliases |
-| **Lineage** | same marker | **Stack-specific** body; core is abstract SoT / checklist reference | `architecture/feature-delivery-workflow`, `architecture/reference-features.template`, `agent-team/agent-team-orchestrator` |
+Meta-rules: `core/meta/preset-*.md`. Guide: [`docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md).
 
-Do **not** expect lineage adapters to byte-match core. Embed adapters should match core after stripping frontmatter and `## Stack notes` — verify with `scripts/check-shared-core-drift.sh`.
+## Sync
 
-## Folder map
+1. Edit `core/**` for shared principles.
+2. Update every `<!-- shared-core: … -->` consumer in the **same PR**.
+3. **Embed** adapters must match core (minus frontmatter / `## Stack notes`). **Lineage** adapters are stack-specific; do not expect a byte match.
+4. Gate: `scripts/check-shared-core-drift.sh`. Dogfood: `scripts/sync-dogfood-cursor.sh`.
 
-| Dir | Contents |
-|-----|----------|
-| `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8); requestable `mcp-usage`; embed `debug-investigation`; inline-embed `verification-before-completion` (no standalone adapter — shipped via `agents/feature-developer.md` + `agents/build-verifier.md` + `skills/debug-investigation/SKILL.md`) |
-| `core/agent-team/` | Orchestrator + intake (pipeline language); lineage `task-classification` |
-| `core/architecture/` | Feature-delivery abstract + reference-features template + product-specs (+ product-specs-authoring) + assets/docs-specs templates |
-| `core/review/` | Code-review MR + technical-retro alias + mockup-review checklist + ux-design checklist; lineage `receiving-code-review` |
-| `core/testing/` | Test principles: behavior vs. implementation, locale-aware titles, isolation/mocks, fixture reuse, e2e scenario ↔ test traceability, page objects, PREFIX-XXX identifiers, selector priority |
-| `core/meta/` | Author-facing preset meta-rules |
+`/task` templates live in each stack’s `team/` and seed **`.ai.local/team/`** — not this folder.
 
-## CLI note
+## Folders
 
-Do **not** nest `_shared` under `cursor/` or `claude/`. Do not pass `_shared` as `--preset`.
+| Dir | What |
+|-----|------|
+| `core/quality/` | Slim always-on quality; requestable discipline / design / MCP |
+| `core/agent-team/` | Orchestrator, intake, classification, artifact + metrics contracts |
+| `core/architecture/` | Feature-delivery, reference-features, product-specs |
+| `core/review/` | MR review, retro, mockup, UX |
+| `core/testing/` | Unit/e2e principles |
+| `core/meta/` | Author-facing preset rules |
+| `assets/docs-specs/` | `init` seed for absent `docs/specs/` |

package/presets/_shared/core/agent-team/agent-artifact-contracts.md

@@ -1,9 +1,6 @@
 # Agent artifact contracts
 
-Each pipeline slug has one context index and receipt ledger:
-
-- Cursor: `.cursor/team/tasks/<slug>/artifact-manifest.json`
-- Claude: `.claude/team/tasks/<slug>/artifact-manifest.json`
+Each pipeline slug has one context index and receipt ledger at `.ai.local/team/tasks/<slug>/artifact-manifest.json`.
 
 Markdown remains the narrative evidence. The manifest identifies authoritative inputs and outputs; it does not duplicate report contents or replace `pipeline.json`, `status.json`, or `metrics.json`.
 
@@ -109,7 +106,7 @@ A producer finishes its step by upserting only its owned artifact entry and term
 | `api-contract-reviewer` | `api-contract-review` | `api-contract-review.md` |
 | `qa-tester` / unit or e2e planners | stack-native test IDs | plan/spec paths named in the agent prompt |
 | `tech-writer` | `documentation` | `documentation.md` |
-| `openspec-author` | `openspec-change` | `openspec/changes/<change-id>/**`, optional `.cursor/team/tasks/<slug>/openspec-change.md` |
+| `openspec-author` | `openspec-change` | `openspec/changes/<change-id>/**`, optional `.ai.local/team/tasks/<slug>/openspec-change.md` |
 | `qa-tester` | `qa` | stack-native (e.g. `qa-report.md`, `qa-screenshot.png`) |
 | `unit-test-planner` | `unit-test-plan` | `unit-test-plan.md` |
 | `unit-test-generator` | `unit-test-spec` | `*.spec.ts` / `*.test.ts` / `*Tests.swift` |
@@ -158,10 +155,7 @@ Optional JSON on the producer receipt and, for `feature-developer`, YAML frontma
 
 ## Memlog
 
-Optional append-only file beside slug artifacts:
-
-- Cursor: `.cursor/team/tasks/<slug>/.memlog.md`
-- Claude: `.claude/team/tasks/<slug>/.memlog.md`
+Optional append-only file beside slug artifacts: `.ai.local/team/tasks/<slug>/.memlog.md`.
 
 Agent-written chronological markdown (`## YYYY-MM-DD` headings). Suggested line tags: `decision`, `assumption`, `override`, `event`, `claim`. Writers: `task-analyst`, `feature-developer`. `/task-continue` may read it. The hook does **not** parse memlog and does **not** treat it as `status.json` / `metrics.json`.
 

package/presets/_shared/core/agent-team/agent-team-orchestrator.md

@@ -1,6 +1,6 @@
 # Agent team orchestrator
 
-Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.cursor/team/tasks/<slug>/` (Claude: `.claude/team/tasks/<slug>/`).
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.ai.local/team/tasks/<slug>/`.
 
 Work request without `/task` — see **agent-team-intake** (when to suggest the router instead of coding directly).
 
@@ -99,7 +99,7 @@ Do not calculate durations in agents. For parallel steps, never attribute a stop
 
 ## Artifact context index and receipts
 
-Each slug has one `artifact-manifest.json`: `.cursor/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. The full schema and completion conventions live in **agent-artifact-contracts**.
+Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. The full schema and completion conventions live in **agent-artifact-contracts**.
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest points to authoritative paths and records producer, status, timestamps, outcome, and evidence paths.

package/presets/_shared/core/architecture/reference-features.template.md

@@ -32,7 +32,7 @@ After init the team maintains **local** gotchas, patterns, and decisions in a co
 | Patterns | Local patterns beyond the reference table |
 | Decisions | Short ADR links / product decisions that affect code |
 
-Path pointer and stack tables — in the preset adapter (`team/conventions.md`). The file is **not** always-on.
+Path pointer and stack tables — in the preset adapter (`.ai.local/conventions.md`). The file is **not** always-on.
 
 ## Related rules
 

package/presets/_shared/core/meta/preset-layering.md

@@ -7,7 +7,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on set (3–5), stack examples in **Stack notes** |
 | **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule

package/presets/_shared/core/meta/preset-pr-checklist.md

@@ -7,10 +7,10 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **SoT:** edits in `packages/…` (not only root `.cursor/`)
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
-- [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`; see `preset-twin-sync` § Mavis derivation)
-- [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`; see `preset-twin-sync` § OpenCode derivation)
+- [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`; see `preset-twin-sync` § Mavis derivation)
+- [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
-- [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
+- [ ] **Token budget:** Cursor `alwaysApply` and Claude session-start both **3–5** (extra slots reserved for `ai-local-overlay`); body sum ≤200 (stretch ≤170); meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
 - [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.

package/presets/_shared/core/meta/preset-token-budget.md

@@ -6,19 +6,19 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | Platform | Always-on | Cap |
 |----------|-----------|-----|
-| Cursor | `alwaysApply: true` | **≤ 4** |
-| Claude | rules **without** `paths:` | **exactly 3** |
-| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
-| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| Cursor | `alwaysApply: true` | **3–5** |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
 
-**Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
+Caps are **aligned** across platforms: minimum **3** (base invariants), maximum **5**. Slots beyond the base invariants are reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` / Claude `paths:`, or a non-root load mode on Mavis / OpenCode.
 
-**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
 
 Session-start body budget:
-- Claude trio: ≤140 lines total (stretch ≤120).
-- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
-- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
+- Claude session-start: ≤200 lines total (stretch ≤170).
+- Cursor always-on: ≤200 lines total (stretch ≤170).
+- Mavis / OpenCode: ≤5 root-entry rule files; combined root `AGENTS.md` + platform entry ≤200 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 
@@ -34,4 +34,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## Verifier
 
-build-verifier **FAIL** if Cursor `alwaysApply` count exceeds 4, Claude session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.
+build-verifier **FAIL** if Cursor `alwaysApply` count or Claude session-start count is outside **3–5** (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/_shared/core/meta/preset-twin-sync.md

@@ -21,7 +21,16 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 
 | Stack | Cursor SoT | Mavis derive | Manifest |
 |-------|------------|--------------|----------|
-| `next` | `presets/cursor/next/**` | `presets/mavis/next/**` via `generate-mavis-next.mjs` | **Required** `adapter-map.json` |
+| `next` | `presets/cursor/next/**` | `presets/mavis/next/**` via `generate-mavis.mjs --stack next` | **Required** `adapter-map.json` |
+| `nuxt` | `presets/cursor/nuxt/**` | `presets/mavis/nuxt/**` via `generate-mavis.mjs --stack nuxt` | **Required** `adapter-map.json` |
+| `svelte` | `presets/cursor/svelte/**` | `presets/mavis/svelte/**` via `generate-mavis.mjs --stack svelte` | **Required** `adapter-map.json` |
+| `ios-swift` | `presets/cursor/ios-swift/**` | `presets/mavis/ios-swift/**` via `generate-mavis.mjs --stack ios-swift` | **Required** `adapter-map.json` |
+| `android-kotlin` | `presets/cursor/android-kotlin/**` | `presets/mavis/android-kotlin/**` via `generate-mavis.mjs --stack android-kotlin` | **Required** `adapter-map.json` |
+| `go` | `presets/cursor/go/**` | `presets/mavis/go/**` via `generate-mavis.mjs --stack go` | **Required** `adapter-map.json` |
+| `java` | `presets/cursor/java/**` | `presets/mavis/java/**` via `generate-mavis.mjs --stack java` | **Required** `adapter-map.json` |
+| `mcp-ts` | `presets/cursor/mcp-ts/**` | `presets/mavis/mcp-ts/**` via `generate-mavis.mjs --stack mcp-ts` | **Required** `adapter-map.json` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/**` | `presets/mavis/php-hexagonal/**` via `generate-mavis.mjs --stack php-hexagonal` | **Required** `adapter-map.json` |
+| `php-laravel` | `presets/cursor/php-laravel/**` | `presets/mavis/php-laravel/**` via `generate-mavis.mjs --stack php-laravel` | **Required** `adapter-map.json` |
 
 Mavis is a **third platform adapter**, not a Claude-style topic twin:
 
@@ -29,13 +38,22 @@ Mavis is a **third platform adapter**, not a Claude-style topic twin:
 _shared/core  →  cursor/<stack>  →  mavis/<stack>
 ```
 
-Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
+Regenerate with `node packages/ai-rules/scripts/generate-mavis.mjs --stack <stack>`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
 
 ## OpenCode derivation (not a Claude twin)
 
 | Stack | Cursor SoT | OpenCode derive | Manifest |
 |-------|------------|-----------------|----------|
-| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode-next.mjs` | **Required** `adapter-map.json` |
+| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode.mjs --stack next` | **Required** `adapter-map.json` |
+| `nuxt` | `presets/cursor/nuxt/**` | `presets/opencode/nuxt/**` via `generate-opencode.mjs --stack nuxt` | **Required** `adapter-map.json` |
+| `svelte` | `presets/cursor/svelte/**` | `presets/opencode/svelte/**` via `generate-opencode.mjs --stack svelte` | **Required** `adapter-map.json` |
+| `ios-swift` | `presets/cursor/ios-swift/**` | `presets/opencode/ios-swift/**` via `generate-opencode.mjs --stack ios-swift` | **Required** `adapter-map.json` |
+| `android-kotlin` | `presets/cursor/android-kotlin/**` | `presets/opencode/android-kotlin/**` via `generate-opencode.mjs --stack android-kotlin` | **Required** `adapter-map.json` |
+| `go` | `presets/cursor/go/**` | `presets/opencode/go/**` via `generate-opencode.mjs --stack go` | **Required** `adapter-map.json` |
+| `java` | `presets/cursor/java/**` | `presets/opencode/java/**` via `generate-opencode.mjs --stack java` | **Required** `adapter-map.json` |
+| `mcp-ts` | `presets/cursor/mcp-ts/**` | `presets/opencode/mcp-ts/**` via `generate-opencode.mjs --stack mcp-ts` | **Required** `adapter-map.json` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/**` | `presets/opencode/php-hexagonal/**` via `generate-opencode.mjs --stack php-hexagonal` | **Required** `adapter-map.json` |
+| `php-laravel` | `presets/cursor/php-laravel/**` | `presets/opencode/php-laravel/**` via `generate-opencode.mjs --stack php-laravel` | **Required** `adapter-map.json` |
 
 OpenCode is a **fourth platform adapter** with a **native** install root (`.opencode/`), not a Claude-style topic twin and not an owned overlay like `.mavis/`:
 
@@ -43,7 +61,7 @@ OpenCode is a **fourth platform adapter** with a **native** install root (`.open
 _shared/core  →  cursor/<stack>  →  opencode/<stack>
 ```
 
-Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
+Regenerate with `node packages/ai-rules/scripts/generate-opencode.mjs --stack <stack>`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
 
 ## Same-PR checklist
 
@@ -51,8 +69,8 @@ Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; val
 2. Update Claude twin: body + `paths:` (from Cursor `globs:` / requestable triggers); drop `alwaysApply`.
 3. Update mapping table row if stem/path changed.
 4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
-5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`).
-6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`).
+5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`).
+6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`).
 
 ## Twin depth
 
@@ -73,7 +91,7 @@ Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; val
 - **php-hexagonal:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts; mapping table required).
 - **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
 - **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
-- **mavis/next:** `cursor/next` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
-- **opencode/next:** `cursor/next` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
+- **mavis/<stack>:** `cursor/<stack>` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
+- **opencode/<stack>:** `cursor/<stack>` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/_shared/core/quality/code-quality-and-refactoring.md

@@ -12,6 +12,12 @@
 - **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
 - **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
 
+# Over-abstraction guardrails
+
+- **No unnecessary constants:** do not hoist a one-off literal, string, or boolean into a named constant. Inline it, or use an existing token/enum when the value is meaningful and reused. Named constants are for shared, semantic, or repeated values.
+- **No invented utilities:** do not add a `utils`/helper for a single call site or a thin pass-through wrapper. Inline it or extend the existing helper; a new shared utility is justified only after the Rule of Three.
+- **Decompose over conditionals:** a unit (function, component, hook) that accumulates several branches (`if` / ternary / `switch`) should be split into smaller units with one reason to change instead of piling up conditions.
+
 # Refactoring during changes
 
 - Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.

package/presets/claude/android-kotlin/CLAUDE.md

@@ -35,4 +35,4 @@ See @rules/README.md for mapping and loading strategy.
 npx @bonesofspring/ai-rules init claude --preset android-kotlin
 ```
 
-Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `skills/**`, `hooks/**`, `team/**`, `MCP.md` into `.claude/`, plus `mcp.json` → **`.mcp.json`** and `REPO_AGENTS.md` → root **`AGENTS.md`**. Skill: `write-adr` (on-demand).
+Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `skills/**`, `hooks/**`, `MCP.md` into `.claude/`; seeds `.ai.local/team/` from `team/` (slugs preserved), plus `mcp.json` → **`.mcp.json`** and `REPO_AGENTS.md` → root **`AGENTS.md`**. Skill: `write-adr` (on-demand).

package/presets/claude/android-kotlin/README.md

@@ -1,32 +1,9 @@
-# Preset: android-kotlin (Claude)
+# Android Kotlin preset (Claude Code)
 
-Claude twin of the Cursor **android-kotlin** preset. Topic rules under `rules/` map 1:1 from Cursor `.mdc` SoT — see `rules/README.md`.
+Twin of `presets/cursor/android-kotlin/`. Map Gradle modules in `.ai.local/conventions.md`.
 
 ```bash
 npx @bonesofspring/ai-rules init claude --preset android-kotlin
 ```
 
-| In the preset | Where `init claude --preset android-kotlin` copies |
-|---------------|---------------------------------------------------|
-| `CLAUDE.md` | `.claude/CLAUDE.md` |
-| `rules/**` | `.claude/rules/**` |
-| `agents/**`, `skills/**`, `commands/**`, `hooks/**`, `team/**` | `.claude/…` |
-| `mcp.json` | **`.mcp.json`** at repo root |
-| `MCP.md` | `.claude/MCP.md` |
-| `REPO_AGENTS.md` | root `AGENTS.md` |
-
-Session-start trio (no `paths:`): `stack/android-app-core.md`, `architecture/boundaries.md`, `tooling-and-review/code-quality.md`.
-
-## Layout placeholders
-
-Same vendor-neutral layout as Cursor SoT: `applications/`, `core/`, `features/<name>/{api,impl}/`, `build-logic/`, `gradle/libs.versions.toml`. Map local type names and module paths in **`team/conventions.md`** after install.
-
-## Install troubleshooting
-
-- **Gradle wrapper:** discover `./gradlew` or the wrapper script from repo docs/CI; see `tooling-and-review/gradle-tooling.md`.
-- **Modules / variants / flavors:** resolve Gradle module paths and the CI build variant before reproducing failures; document local names in `team/conventions.md`.
-- **Multimodule:** narrow compile/test tasks to changed modules; full validation — agent `build-verifier`.
-
-## Parity with Cursor
-
-SoT = `presets/cursor/android-kotlin/`. Update Claude twin in the **same PR** as Cursor edits.
+`team/` seeds **`.ai.local/team/`**. MCP → **`.mcp.json`**. Catalog: [`rules/README.md`](./rules/README.md).

package/presets/claude/android-kotlin/REPO_AGENTS.md

@@ -1,19 +1,34 @@
 # Android Kotlin — agent instructions
 
-Cross-tool repo-root guide for the **android-kotlin** multimodule preset. Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+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, or other).
-- Tool maps live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` when that tool is installed.
+- 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 android-kotlin
-npx @bonesofspring/ai-rules init claude --preset android-kotlin
+npx @bonesofspring/ai-rules init multi --preset android-kotlin
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas and local type names belong in `team/conventions.md`, not here.
+Per-tool: `init cursor|claude|mavis|opencode --preset android-kotlin`. `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 `.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/android-app-core.md`, `.mavis/rules/architecture-boundaries.md`, `.mavis/rules/code-quality-and-refactoring.md`, `.mavis/rules/ai-local-overlay.md`.
+- If `.opencode/` exists: read `.opencode/AGENTS.md`, then `.opencode/rules/android-app-core.md`, `.opencode/rules/architecture-boundaries.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 shared
+
+`/task` slug, `status.json`, and `metrics.json` live under `.ai.local/team/tasks/<slug>/`. Cursor, Claude, Mavis, and OpenCode share this folder (including `init multi`).
 
 ## Commands (test / lint / build)
 
@@ -40,9 +55,20 @@ After code edits: invoke **`post-change-build`** (requestable) + **`gradle-tooli
 |------|-----|
 | Cursor | `.cursor/AGENTS.md` (optional if Cursor 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) |
 
-Rules: `.cursor/rules/` or `.claude/rules/`. Skills: `.cursor/skills/` or `.claude/skills/`. UI tests: `instrumentation-test-*` (never Playwright/XCUITest as required handoffs).
+Rules: `.cursor/rules/`, `.claude/rules/`, `.mavis/rules/`, or `.opencode/rules/`.
+Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/skills/`.
 
 ## Living conventions
 
-Local type names (ViewModel base, DI holders, design-system package), flavors, and wrapper quirks: **`.cursor/team/conventions.md`** and/or **`.claude/team/conventions.md`** (fill after init).
+Gotchas, local patterns, and team decisions: **`.ai.local/conventions.md`** (fill after init; `init` does not overwrite it).
+
+## 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/claude/android-kotlin/agents/README.md

@@ -1,6 +1,6 @@
 # Agents (android-kotlin)
 
-Full agent-team roster (~22). Production-write policy matches ios-swift mobile depth with Gradle + instrumentation.
+Full agent-team roster (~24). Production-write policy matches ios-swift mobile depth with Gradle + instrumentation.
 
 ## Rename map (from next / ios-swift / java)
 

package/presets/claude/android-kotlin/agents/accessibility-reviewer.md

@@ -9,8 +9,8 @@ You are an accessibility reviewer for an **Android Kotlin / Jetpack Compose** (a
 
 ## Inputs
 
-1. `.claude/team/tasks/<slug>/brief.md` — acceptance criteria and UI scope.
-2. `.claude/team/tasks/<slug>/decomposition.md` — UI-related tasks.
+1. `.ai.local/team/tasks/<slug>/brief.md` — acceptance criteria and UI scope.
+2. `.ai.local/team/tasks/<slug>/decomposition.md` — UI-related tasks.
 3. Git diff for changed Views / UI under `features/**/Presentation/**` (and design-system if touched).
 4. `ui-and-accessibility/compose.md` and project a11y conventions.
 
@@ -26,7 +26,7 @@ You are an accessibility reviewer for an **Android Kotlin / Jetpack Compose** (a
 
 ## Output
 
-Write `.claude/team/tasks/<slug>/a11y-review.md`:
+Write `.ai.local/team/tasks/<slug>/a11y-review.md`:
 
 ```markdown
 # Accessibility review: <slug>
@@ -56,7 +56,7 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation or UI diff scope, and prior review artifacts when present.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation or UI diff scope, and prior review artifacts when present.
 - **Owned outputs:** `a11y-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `a11y-review`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/android-kotlin/agents/api-contract-reviewer.md

@@ -9,7 +9,7 @@ You are an API contract reviewer for a layered **Android Kotlin** Feature module
 
 ## Inputs
 
-1. `.claude/team/tasks/<slug>/brief.md`, `decomposition.md`, `architecture.md` if present.
+1. `.ai.local/team/tasks/<slug>/brief.md`, `decomposition.md`, `architecture.md` if present.
 2. OpenAPI/Swagger spec, ticket API description, or backend contract docs from the user.
 3. Changed files: DTO models, mappers, API clients/services, mocks/fixtures under Data (and Domain entities).
 
@@ -27,7 +27,7 @@ Apply `api-and-data/networking.md`, `architecture/boundaries.md`, `architecture/
 
 ## Output
 
-Write `.claude/team/tasks/<slug>/api-contract-review.md`:
+Write `.ai.local/team/tasks/<slug>/api-contract-review.md`:
 
 ```markdown
 # API contract review: <slug>
@@ -59,7 +59,7 @@ Write the owned terminal receipt described under **Artifact contract**.
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, and other authoritative prior artifacts for this step.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, and other authoritative prior artifacts for this step.
 - **Owned outputs:** `api-contract-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `api-contract-review`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/android-kotlin/agents/build-verifier.md

@@ -11,8 +11,8 @@ You **validate** Android/Kotlin implementation quality — do not edit productio
 
 ## Inputs
 
-1. `.claude/team/tasks/<slug>/brief.md` and `decomposition.md`.
-2. `.claude/team/tasks/<slug>/pipeline.json` — step context and `scope`.
+1. `.ai.local/team/tasks/<slug>/brief.md` and `decomposition.md`.
+2. `.ai.local/team/tasks/<slug>/pipeline.json` — step context and `scope`.
 3. Git diff / changed files (Kotlin/Android modules or preset paths).
 
 ## App / feature validation (default)
@@ -37,7 +37,7 @@ When validating **android-kotlin preset** changes (or `scope: preset-structure-v
 
 ### FAIL (android-kotlin packaging)
 
-1. **Token budget:** Cursor `alwaysApply: true` count ≤ **3**; Claude rules without `paths:` === **3** (**exclude `**/README.md`**). Meta `preset-*` rules must **not** be always-on.
+1. **Token budget:** Cursor `alwaysApply: true` count 3–5; Claude rules without `paths:` 3–5 (**exclude `**/README.md`**). Meta `preset-*` rules must **not** be always-on.
 2. **Chain fork:** `hooks/chain-team-phases.sh` byte-≠ every other stack (Cursor + Claude).
 3. **Forbidden handoff strings** in android-kotlin `chain-team-phases.sh` (Cursor + Claude): `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`, `xcuitest-test-`, positive `xcodebuild` / `SwiftLint` as required handoffs, positive yarn `lint:js` / `lint:css`.
 4. **Required handoff stems:** `AGENT_HANDOFF` includes `instrumentation-test-planner` (or generator/healer); `build-verifier` prose mentions `gradle-tooling` and/or `post-change-build`.
@@ -45,7 +45,7 @@ When validating **android-kotlin preset** changes (or `scope: preset-structure-v
 6. **Twin presence (hard):** Cursor rule → Claude twin + mapping row — **FAIL** if missing.
 7. **Mapping / README:** `claude/android-kotlin/rules/README.md` mapping table present.
 8. **shared-core consumers:** if `_shared/core/**` changed, matching embeds updated (or intentional fork documented).
-9. **Session-start body budget:** sum of the 3 always-on / session-start bodies ≤ **140** lines.
+9. **Session-start body budget:** sum of the intended always-on / session-start bodies ≤ **200** lines.
 10. **Embed drift:** `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1`.
 11. **Root AGENTS template:** ship `REPO_AGENTS.md` → **FAIL** if missing.
 12. **Hooks cookbook:** `hooks.json` must **not** reference `hooks/examples/`.
@@ -65,7 +65,7 @@ When validating **android-kotlin preset** changes (or `scope: preset-structure-v
 
 ## Output
 
-Write `.claude/team/tasks/<slug>/validation-report.md` with verdict, commands, failures, changed files.
+Write `.ai.local/team/tasks/<slug>/validation-report.md` with verdict, commands, failures, changed files.
 
 ## On completion
 
@@ -75,7 +75,7 @@ Write the owned validation receipt (`completed` or `validation_failed`). Do not
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied.
 - **Owned outputs:** `validation-report.md`; upsert only the assigned manifest entry; preserve foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs; emit `completed` or `validation_failed`.
 - **Shared state:** never mutate `status.json` or `metrics.json`.

package/presets/claude/android-kotlin/agents/ci-investigator.md

@@ -12,7 +12,7 @@ Use the **`ci-investigation` skill** for the investigation loop.
 ## Inputs
 
 1. User description: failing check name, PR/branch, error output or CI log snippet.
-2. `.claude/team/tasks/<slug>/pipeline.json` and `brief.md` if present.
+2. `.ai.local/team/tasks/<slug>/pipeline.json` and `brief.md` if present.
 3. Local reproduction: same scheme, configuration, and destination CI uses (`tooling-and-review/gradle-tooling.md`).
 
 ## Process
@@ -22,7 +22,7 @@ Use the **`ci-investigation` skill** for the investigation loop.
 3. Reproduce locally when feasible (`./gradlew build` / `./gradlew test` / lint scripts as in repo CI).
 4. Inspect changed files in the git diff related to the failure.
 5. Apply **minimal** fix — do not refactor unrelated code.
-6. Document in `.claude/team/tasks/<slug>/ci-report.md`:
+6. Document in `.ai.local/team/tasks/<slug>/ci-report.md`:
 
 ```markdown
 # CI report: <slug>
@@ -70,7 +70,7 @@ If a Sentry/Datadog (or similar) MCP is ready and the task is a production error
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, and other authoritative prior artifacts for this step.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, and other authoritative prior artifacts for this step.
 - **Owned outputs:** `ci-report.md` plus any minimal CI fix paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `ci-report`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.