@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/docs/LOCAL-OVERLAY.md

@@ -0,0 +1,186 @@
+# Local overlay (`.ai.local/`)
+
+Consumer-owned rules with priority over `@bonesofspring/ai-rules` presets. Works for **Cursor**, **Claude Code**, **Mavis**, and **OpenCode** from the same files.
+
+## TL;DR
+
+Put a `.ai.local/` directory in your repo. Write rules as plain markdown. The `ai-local-overlay` preset rule (installed by `init`) tells the model to read and apply your files **with priority** over preset rules.
+
+```text
+.ai.local/
+├── rules/
+│   ├── our-stack.md        # applied like a rule
+│   └── testing-policy.md   # applied like a rule
+├── conventions.md          # living gotchas (highest priority)
+└── team/                   # shared agent-team pipeline artifacts (not rules)
+    ├── README.md
+    ├── fixtures/
+    └── tasks/<slug>/
+```
+
+No IDE config, no `@include`, no codegen. Same files work in Cursor, Claude Code, Mavis, and OpenCode.
+
+## How it works
+
+1. `init cursor|claude|mavis|opencode --preset <stack>` (or `init multi`) installs `ai-local-overlay`. Cursor: `alwaysApply: true`. Claude: `paths:` on `**/.ai.local/**`. Mavis/OpenCode: listed as a root-entry rule in `AGENTS.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md`.
+2. On session start the rule asks the model to probe `.ai.local/` and read every file under `rules/` and `conventions.md`. Do **not** load `team/**` as rules — that tree is the shared `/task` pipeline (Cursor, Claude, Mavis, and OpenCode). `team/` lives only at the **repo root** `.ai.local/team/`, not in nested package overlays.
+3. If a local rule conflicts with a preset rule, **the local rule wins**.
+4. **Deeper wins** in monorepos: walk `packages/*/.ai.local/` and apply all levels; the model treats the deepest one as the most recent guidance.
+
+## How to write `.ai.local/rules/*.md`
+
+One file = one rule. Plain markdown. **No YAML frontmatter** — the format is shared across IDEs, so each file uses a tiny markdown header for scoping.
+
+### Skeleton
+
+```markdown
+# <Short title>
+
+<One-paragraph summary of what this rule is for.>
+
+## When to apply
+
+<globs or "always-on">
+
+## Body
+
+<The actual rule. Same style as `packages/ai-rules/presets/_shared/core/quality/*.md`: short sections, bullets, code examples.>
+
+## Why
+
+<Optional: link to an ADR, issue, or one-line rationale.>
+```
+
+### `## When to apply` — the only meta you need
+
+| You want | Write |
+|---|---|
+| Only on matching files | `globs: app/src/api/**` |
+| On matching files in multiple folders | `globs: app/src/api/**, app/src/types/api/**` |
+| Always (until the context gets crowded) | `glob: always` |
+| Replace a preset rule entirely | `glob: <same as preset>`, body says "use this instead of <preset rule>" |
+| Disable a preset rule | `glob: <same as preset>`, body contains `override: kill <preset-rule-name>` |
+
+Lines before `## Body` are removed automatically by the model and used as scope. Everything from `## Body` onward is the rule body.
+
+### What to put in the body
+
+- **Start with an imperative opening line.** Models comply better with explicit "do this" than with descriptive prose. Use one of:
+  - `Apply this rule on every turn.`
+  - `Never do X when Y.`
+  - `When X, always do Y.`
+- Match the style of preset rules: short sections, bullets, code examples.
+- Cite the preset rule you're overriding (e.g. "supersedes `code-quality-and-refactoring#principles`").
+- Keep it under ~120 lines. If it grows, split into multiple files.
+- Avoid `any` and unverifiable third-party API references — same discipline as preset rules.
+
+### Mandatory patterns (recommended)
+
+If your rule is **always-on** (most local rules are), use this header verbatim so the model treats it as mandatory:
+
+```markdown
+# <Short title>
+
+**Apply this rule on every turn. Do not skip.**
+
+## When to apply
+
+glob: always
+
+## Body
+
+<rule>
+```
+
+The combination of:
+- imperative first paragraph
+- `glob: always`
+- explicit "do not skip"
+
+gets the highest compliance in practice. If the rule is **on-demand**, replace `glob: always` with `globs: <comma-separated globs>` and keep the imperative opening.
+
+### Worked example
+
+`.ai.local/rules/our-monorepo.md`:
+
+```markdown
+# Our monorepo layout
+
+**Apply this rule on every turn when working in `apps/` or `packages/`.**
+
+This repo is a pnpm + Turbo monorepo. Apps live in `apps/*`, shared packages in `packages/*`.
+
+## When to apply
+
+globs: apps/**/*, packages/**/*
+
+## Body
+
+- Use workspace protocol (`workspace:*`) for cross-package dependencies.
+- Do not import from `apps/*` into `packages/*` — packages are leaf-level.
+- Tests: each package owns its own runner; never run `pnpm test` at the root.
+- Migration scripts live in `scripts/migrations/` and must be idempotent.
+
+## Why
+
+Decision: monorepo split (ADR-0042). The "apps vs packages" boundary is enforced by ESLint, not by folder names alone.
+```
+
+## How to write `.ai.local/conventions.md`
+
+A single markdown file (no header conventions). Three sections, in this order:
+
+```markdown
+# Local conventions
+
+## Gotchas
+
+- <One bullet per non-obvious trap.>
+
+## Patterns
+
+- <Local patterns beyond the preset's `reference-features.md`.>
+
+## Decisions
+
+- <Short links to ADRs / product choices that affect code.>
+```
+
+This is the **upgrade path** of the old per-tool `.cursor/team/conventions.md` (and Claude/Mavis/OpenCode twins). If both exist, `.ai.local/conventions.md` wins. Pipeline task slugs live in `.ai.local/team/`, not in `conventions.md`.
+
+### Migration backups
+
+When `init` relocates a legacy per-tool `team/` directory it copies every entry to `.ai.local/.rollback/legacy-team-<timestamp>/<tool>/` before removing the original. That directory ships its own `.gitignore`, so backups never reach a commit and your root `.gitignore` is left alone.
+
+Backups are not pruned automatically. They do not accumulate on their own — once a legacy directory has been drained, later `init` runs find only the pointer `README.md` and back nothing up — but if you repeatedly re-create legacy `team/` directories you will collect one stamped directory per migration. Delete `.ai.local/.rollback/` by hand once you have confirmed the move.
+
+## Monorepos
+
+Drop `.ai.local/` at any nesting depth. The model walks from root to leaf and applies all levels; deeper wins.
+
+```text
+.ai.local/                                # global: applies everywhere
+packages/web/.ai.local/                   # override: only for `packages/web`
+packages/worker/.ai.local/                # override: only for the worker
+```
+
+If the same rule name appears in two levels, the deeper one wins.
+
+## Limitations
+
+- Cursor, Claude, Mavis, and OpenCode do **not** natively read `.ai.local/`. The `ai-local-overlay` rule makes the model do it. Reliability is high but not 100%.
+- Changes to `.ai.local/` mid-session require a session restart.
+- "Priority" is **contextual**, not enforced. If the model already internalized a preset rule, the local rule may not fully override it.
+- Local rules consume your context window. Keep them tight.
+
+## When to upgrade to a preset change
+
+If you find yourself writing the same `.ai.local` rule across multiple repos, **propose it as a preset rule** in `packages/ai-rules/presets/_shared/core/` (or stack-specific). Local overlay is for repo-specific overrides, not for re-distributing preset rules.
+
+## See also
+
+- `packages/ai-rules/presets/cursor/next/rules/ai-local-overlay.mdc`
+- `packages/ai-rules/presets/claude/next/rules/tooling-and-review/ai-local-overlay.md`
+- `packages/ai-rules/presets/mavis/next/rules/ai-local-overlay.md`
+- `packages/ai-rules/presets/opencode/next/rules/ai-local-overlay.md`
+- `packages/ai-rules/docs/PRESET-CONTRIBUTION.md` — for contributing to the preset itself

package/docs/MAVIS-COMPATIBILITY.md

@@ -0,0 +1,174 @@
+# Mavis compatibility evidence
+
+This report separates documented MiniMax Code capabilities from observations
+made by `scripts/probe-mavis-capabilities.mjs`. The probe uses only the supplied
+`--workdir` plus an ephemeral isolated `HOME` for child processes; it does not
+inspect or mutate `~/.minimax/**` or user-global MCP configuration.
+
+## Evidence state
+
+- Evidence date: 2026-09-03
+- Probe host: macOS/Darwin 25.5.0 arm64
+- Actual `mcode` CLI version (snapshot, **not a pin**): **0.2.7** via
+  `~/.minimax-code/bin/mcode --version`
+- MiniMax Code desktop (snapshot, **not a pin**): **3.0.65 (3.0.65.130)**
+- Logged-in isolated probe: **completed** (`probeStatus: completed`, exit 0).
+  Auth was copied into an ephemeral `HOME` (`cli-auth`,
+  `local-runtime.auth.json`, `config.yaml`). Operator `~/.minimax` mtime did
+  not change. MCP commands were not executed.
+- Probe model for `exec` (this run only): `minimax/MiniMax-M2.7-highspeed`.
+  Default unscoped `exec` on this account used `minimax/MiniMax-M3` earlier.
+  `--model` requires `provider/model` (optionally `#variant`).
+- Current decision: **capability floor GO** for WP-B. Native discovery, hooks,
+  project MCP, slash commands, and `mcode init` (TTY-only) remain fallback.
+- Version policy: do **not** hard-require `3.0.65`, `3.0.65.130`, or `0.2.7`.
+
+The package script is intentionally not exposed yet. Run the focused harness
+directly until the probe has succeeded on a supported MiniMax test machine:
+
+```bash
+node scripts/test-probe-mavis-capabilities.mjs
+node scripts/probe-mavis-capabilities.mjs \
+  --mcode /absolute/path/to/mcode \
+  --workdir /absolute/path/to/new-or-empty-isolated-directory
+```
+
+The work directory must be new or empty. The probe refuses a non-empty
+directory, runs `mcode init` there, copies sentinel inputs into that directory,
+and uses explicit `mcode exec` arguments. Child processes receive an isolated
+`HOME` under the system temp directory so even a misbehaving executable cannot
+write the operator's `~/.minimax/**`.
+
+## Capability matrix
+
+Allowed status values are `confirmed`, `partial`, `unknown`, and
+`no-equivalent`. Architecture §1.3 unknowns stay `unknown` until a real `mcode`
+run produces reproducible evidence. Fake-executable results are not used to
+promote a row to `confirmed`.
+
+| Capability | Status | Evidence or inspection command | Observation | Selected fallback |
+|---|---|---|---|---|
+| CLI version identification | `confirmed` | `mcode --version` | Prints `0.2.7` | Record in probe JSON; do not pin |
+| Root `AGENTS.md` consumption | `confirmed` | Isolated `mcode exec --output-format json` after fixture `AGENTS.md` | `MAVIS_AGENTS_SENTINEL` returned | Root `AGENTS.md` is the compatibility entry |
+| Explicit role file | `confirmed` | `mcode exec --file agents/probe-agent.md --output-format json` | `MAVIS_AGENT_FILE_SENTINEL` returned | Attach roles with `--file` |
+| Deterministic structured output | `confirmed` | Same `exec` without `--output-schema` | `type=exec.result` JSON wrapper; `--output-schema` file path is rejected (inline object only) and model schema enforcement is unreliable | Parse the `exec.result` wrapper; do not require `--output-schema` for P0–P2 |
+| `mcode init` | `unknown` | `mcode init <workdir>` | Exit 1: interactive mode requires a TTY | Ship `REPO_AGENTS.md` → root `AGENTS.md`; do not depend on `init` |
+| Project rule discovery (no root reference) | `unknown` | `exec` with `rules/probe.md` on disk and no fixture `AGENTS.md` reference | Exec succeeded; rule sentinel absent | Explicit root `AGENTS.md` reference; `.mavis/rules/**` is ai-rules-owned |
+| Project rule discovery (explicit root reference) | `confirmed` | Root `AGENTS.md` references `rules/probe.md` | `MAVIS_RULE_SENTINEL` returned | Explicit reference |
+| Workspace agent discovery | `unknown` | `exec` without `--file` while `agents/probe-agent.md` is on disk | Exec succeeded; agent sentinel absent | Explicit `--file` |
+| Workspace Skill discovery (no root reference) | `unknown` | `exec` with skill on disk and no root reference | Exec succeeded; skill sentinel absent | Explicit root reference |
+| Workspace Skill discovery (explicit root reference) | `confirmed` | Root `AGENTS.md` references `skills/probe/SKILL.md` | `MAVIS_SKILL_SENTINEL` returned | Explicit reference |
+| Plugin Skill format | `confirmed` | Official plugin documentation | `skills/**/SKILL.md` is documented inside plugin packages | Optional plugin packaging remains deferred |
+| Plugin MCP format | `confirmed` | Official plugin and MCP documentation | Plugin `*.mcp.json` is documented | Optional plugin packaging remains deferred |
+| Project-scoped MCP path | `unknown` | Documented inspection only: `mcode mcp list --human`, `mcode mcp tools <server>`, `mcode mcp auth status` | No automated command was run; no global config was read or written | Repo-local `.mavis/mcp.json` staging plus manual import |
+| Project hooks / completion callback | `unknown` | Desktop/manual documentation inspection | No native path or event schema is assumed | Explicit manual/semi-auto chain runner |
+| External `pipeline.json` ingestion | `unknown` | Native Team manual checklist | Not run | File pipeline remains the audit source of truth |
+| File-defined slash commands | `unknown` | Desktop/manual inspection | No registration API is assumed | Natural-language procedure plus explicit `exec --file` |
+| Native Team | `partial` | Official Team documentation | Leader/Worker/Verifier are documented; bridge controls are unverified | Semi-auto file lifecycle |
+
+Official documentation used for the confirmed plugin rows and the partial Team
+row:
+
+- <https://agent.minimax.io/docs/code/agents/plugins.md>
+- <https://agent.minimax.io/docs/code/agents/mcp.md>
+- <https://agent.minimax.io/docs/code/agents/team.md>
+- <https://agent.minimax.io/docs/techblog/agent-team.md>
+
+These references confirm package formats and documented Team roles, not
+project-local discovery, automatic registration, hook APIs, or the deferred
+plugin's runtime behavior.
+
+No native MiniMax project path (including `.minimax/rules/` or `.mavis/rules/`
+as a MiniMax convention) is claimed.
+
+## Automated probe contract
+
+The JSON document has stable key and capability ordering and no timestamps.
+Commands replace the executable and work directory with `<MCODE>` and
+`<WORKDIR>`. Observations redact:
+
+- the supplied executable, work directory, isolated probe `HOME`, and operator
+  home paths;
+- bearer values;
+- values labeled as API keys, tokens, secrets, or passwords;
+- user-specific paths ending in `/.minimax`.
+
+Every capability includes `status`, `command`, `exitCode`, `observation`, and
+`executed`. Missing or unsupported executables emit evidence with
+`probeStatus: "blocked"` and exit code `2`. A non-empty `--workdir` is refused
+with the same blocked status and does not invoke `mcode`.
+
+The automated harness covers:
+
+- a nonexistent fresh work directory and a pre-created empty work directory;
+- a non-empty work directory (refused, fixture file preserved);
+- missing and unsupported executables;
+- CLI version capture;
+- native discovery of rules, skills, and agents *without* an explicit root
+  `AGENTS.md` reference;
+- root `AGENTS.md`, referenced rule, and referenced Skill sentinels;
+- explicit `mcode exec --file`;
+- structured JSON output with an output schema;
+- deterministic output and secret/path redaction;
+- absence of `~/.minimax/**` writes under an isolated test `HOME` (the fake
+  executable writes a canary under `$HOME/.minimax` during `init`; the probe
+  overrides `HOME` so the operator/test home stays untouched).
+
+## Manual compatibility checklist
+
+Complete this table twice: oldest supported and current stable. Use a new empty
+work directory for every run. Do not treat fake-executable output as a row in
+this table.
+
+| Field | Oldest supported | Current stable |
+|---|---|---|
+| Desktop version | pending (do not infer from current) | 3.0.65 (3.0.65.130) — snapshot only, not a floor |
+| `mcode --version` | pending (do not infer from current) | 0.2.7 — snapshot only, not a floor |
+| OS version | pending | darwin 25.5.0 arm64 |
+| Probe JSON evidence path | pending | team `mavis-probe-evidence.json` (2026-09-03) |
+| Root AGENTS sentinel | pending | confirmed |
+| Explicit agent-file sentinel | pending | confirmed |
+| Structured schema output | pending | wrapper JSON confirmed; `--output-schema` not required |
+| Native project rule discovery | pending | unknown (no sentinel without reference) |
+| Native workspace agent discovery | pending | unknown (no sentinel without `--file`) |
+| Native workspace Skill discovery | pending | unknown without reference; referenced skill confirmed |
+| Team Leader/Worker/Verifier | pending | partial (official docs only) |
+| Team pause/resume | pending | pending |
+| Verifier rejection/revision | pending | pending |
+| Stable task/run identity | pending | pending |
+| Completion callback or pollable state | pending | pending |
+
+For MCP, record only documentation and UI observations. Do not read, edit, or
+back up `~/.minimax/mcp.json` as part of this compatibility work. The listed
+`mcode mcp` commands are inspection references for later maintainer
+adjudication, not automated probe steps.
+
+## Go / no-go adjudication
+
+GO requires all of the following. Versions come from probe JSON for that run
+and are observational. **Do not** compile `3.0.65` / `3.0.65.130` into package
+code or fail CI when the desktop patch changes.
+
+1. root `AGENTS.md` reliably returns its sentinel;
+2. explicit `mcode exec --file` returns the role sentinel;
+3. structured output is deterministic enough to parse (`exec.result` wrapper;
+   `--output-schema` is optional and not required for P0–P2);
+4. plugin Skill/MCP format remains confirmed;
+5. every unknown capability has either empirical confirmation or the fallback
+   in the matrix is accepted.
+
+Hard no-go triggers:
+
+- root `AGENTS.md` is not consumed;
+- explicit `mcode exec --file` cannot execute the role fallback;
+- the tested CLI or desktop version cannot be identified;
+- required evidence can be obtained only by reading or mutating real
+  user-global MCP state.
+
+**Capability floor GO (2026-09-03).** Isolated logged-in probe completed:
+root `AGENTS.md`, referenced rule/skill, and `--file` role sentinels
+returned; CLI version identified; operator `~/.minimax` mtime unchanged.
+Accepted fallbacks: no native project discovery without explicit
+references; `mcode init` is TTY-only; `--output-schema` is not required;
+project MCP / hooks / slash commands remain unknown. Desktop 3.0.65 and
+CLI 0.2.7 stay snapshots, not pins. WP-B is authorized.

package/docs/MAVIS.md

@@ -0,0 +1,120 @@
+# Mavis (MiniMax Code) adapter
+
+Experimental preset for [MiniMax Code](https://agent.minimax.io/) (`mcode`). Platform id is **`mavis`**. Consumer install root is **`.mavis/`** — an ai-rules-owned namespace, **not** a MiniMax-native discovery path.
+
+All **10** installable stacks are in `releasedStacks`: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, `php-laravel`.
+
+## Install
+
+From the **target project root** (where `app/` or `package.json` lives):
+
+```bash
+npx @bonesofspring/ai-rules init mavis --preset next
+npx @bonesofspring/ai-rules init mavis --preset nuxt
+```
+
+All four platforms at once: `npx @bonesofspring/ai-rules init multi --preset <stack>`.
+
+What lands:
+
+| Source (package) | Consumer path |
+|------------------|---------------|
+| `REPO_AGENTS.md` | `./AGENTS.md` (compatibility floor) |
+| `MAVIS.md` | `.mavis/AGENTS.md` (Mavis load map) |
+| `rules/`, `agents/`, `skills/`, `commands/`, `hooks/` | `.mavis/<dir>/` |
+| `team/` | `.ai.local/team/` (shared pipeline artifacts; not `.mavis/team/`) |
+| `mcp.json` | `.mavis/mcp.json` (merge; manual UI import) |
+
+Remove only what this install owns:
+
+```bash
+npx @bonesofspring/ai-rules clean mavis
+```
+
+`clean mavis` is **manifest-owned**: unchanged hashes are removed; files you edited stay. Without a valid `.mavis/.ai-rules-install.json`, clean is fail-safe (nothing removed).
+
+The CLI **never** writes `~/.minimax/**`.
+
+Quad-install with Cursor, Claude, and OpenCode: `init multi --preset next` (or four per-tool inits) copies the **same** root `AGENTS.md`. `clean mavis` leaves that file if another tool install remains. `/task` pipelines are **shared** — artifacts live under `.ai.local/team/` (not removed by `clean`).
+
+## How to run agents
+
+Native workspace discovery without an explicit reference is **unconfirmed**. Use explicit paths:
+
+```bash
+# Role
+mcode exec --file .mavis/agents/task-analyst.md --output-format json "<brief>"
+
+# Procedure (slash-command equivalent)
+mcode exec --file .mavis/commands/task.md "<task description>"
+```
+
+**Every turn:** read root `AGENTS.md`, then `.mavis/AGENTS.md`, then the essential rules listed there.
+
+Parse `mcode exec --output-format json` as the `exec.result` wrapper (see [compatibility](./MAVIS-COMPATIBILITY.md)); `--output-schema` is optional and not required for this preset.
+
+## Task pipeline (semi-auto)
+
+File-based orchestration under `.ai.local/team/` mirrors Cursor/Claude:
+
+1. Start work via the task procedure (`.mavis/commands/task.md`) or `task-router` agent.
+2. Producers write artifacts and upsert `artifact-manifest.json` receipts.
+3. **Do not** mutate `status.json` / `metrics.json` lifecycle fields from agent prompts — the chain hook owns them.
+4. After each producer receipt, run the chain runner:
+
+```bash
+printf '%s\n' '{"status":"completed","attemptId":"<from-status.json>"}' \
+  | bash .mavis/hooks/chain-team-phases.sh
+```
+
+Human gates pause with `awaitingHumanGate: true` in `status.json`. Resume via `.mavis/commands/task-continue.md` (invokes hook action `end_human_gate`). There is **no** shipped `hooks.json` — project hooks are **unknown** on MiniMax; this is intentional semi-auto fallback.
+
+Full team layout: `.ai.local/team/README.md`.
+
+## MCP
+
+Preset servers are staged in **`.mavis/mcp.json`** only. Import or enable them in the MiniMax Code UI (project MCP path is **unknown** — do not assume auto-load). Extra local servers survive re-init when the file is valid JSON (same merge rules as Cursor/Claude). See `.mavis/MCP.md` and rule `mcp-usage.md`.
+
+## Capability summary
+
+Honest labels from WP-A probe. Full matrix: [`MAVIS-COMPATIBILITY.md`](./MAVIS-COMPATIBILITY.md).
+
+| Area | Status | What we do |
+|------|--------|------------|
+| Root `AGENTS.md` | **confirmed** | Compatibility entry; reference rules/skills explicitly |
+| `mcode exec --file` | **confirmed** | Attach agents/commands |
+| Referenced rule/skill | **confirmed** | When root entry points at `.mavis/rules/` or `.mavis/skills/` |
+| Structured JSON output | **confirmed** | Parse `exec.result` wrapper |
+| Project rules/agents/skills (no reference) | **unknown** | Explicit paths only |
+| `mcode init` | **unknown** | TTY-only; use `ai-rules init mavis` |
+| Project MCP auto-load | **unknown** | `.mavis/mcp.json` + manual import |
+| Project hooks / slash commands | **unknown** | Manual chain + `exec --file` |
+| Native Team lifecycle | **partial** | File pipeline is SoT; hook is single lifecycle writer |
+
+Desktop/CLI versions in the compatibility doc are **operator snapshots**, not package pins.
+
+## Local overlay
+
+`.ai.local/rules/*.md` at repo root (or monorepo parents) override preset rules. See [`LOCAL-OVERLAY.md`](./LOCAL-OVERLAY.md).
+
+## Maintainer docs
+
+| Doc | Purpose |
+|-----|---------|
+| [`presets/mavis/README.md`](../presets/mavis/README.md) | Source tree, contract, validation scripts |
+| [`presets/mavis/platform-contract.json`](../presets/mavis/platform-contract.json) | `releasedStacks`, paths, capability statuses |
+| [`MAVIS-COMPATIBILITY.md`](./MAVIS-COMPATIBILITY.md) | Probe evidence and go/no-go |
+| [`PRESET-CONTRIBUTION.md`](./PRESET-CONTRIBUTION.md) | Sibling adapter authoring |
+
+Validate after preset edits:
+
+```bash
+cd packages/ai-rules
+bash scripts/check-preset-structure.sh
+node scripts/check-mavis-platform-contract.mjs --self-test
+node scripts/check-mavis-adapter-map.mjs --self-test
+```
+
+## Released stacks
+
+`init mavis --preset <stack>` and `init multi --preset <stack>` install Mavis for every stack in `presets/mavis/platform-contract.json` `releasedStacks` (all 10). Per-stack always-on rules live in `scripts/lib/stack-platform-profiles.mjs`. Derive with `node scripts/generate-mavis.mjs --stack <stack>` from Cursor SoT — never from Claude.

package/docs/OPENCODE-COMPATIBILITY.md

@@ -0,0 +1,54 @@
+# OpenCode compatibility evidence
+
+This report separates **official OpenCode documentation** from a live isolated CLI probe. A logged-in `opencode` probe has **not** been run yet. Do not promote a row to `confirmed` from guesswork. Rows marked **confirmed (docs)** cite first-party docs; they are not a substitute for an isolated exec probe.
+
+## Evidence state
+
+- Evidence date: 2026-09-07
+- Probe host: n/a (docs-only floor)
+- Isolated `opencode` exec probe: **not run**
+- Current decision: **docs floor GO** for all 10 released stacks (`next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, `php-laravel`). Glob-rules, `instructions` V2 resolution, and plugin-hooks stay fallback.
+- Version policy: do **not** pin OpenCode CLI or TUI versions in `platform-contract.json`.
+
+Official docs used:
+
+- [Rules / AGENTS.md](https://opencode.ai/docs/rules/)
+- [Agents](https://opencode.ai/docs/agents/)
+- [Skills](https://opencode.ai/docs/skills/)
+- [Commands](https://opencode.ai/docs/commands/)
+- [MCP](https://opencode.ai/docs/mcp-servers/)
+- [Plugins](https://opencode.ai/docs/plugins/)
+
+## Capability matrix
+
+Allowed status values are `confirmed`, `partial`, `unknown`, and `no-equivalent`. `unknown` / `no-equivalent` must not declare `nativePath`.
+
+| Capability | Status | Evidence | Observation | Selected fallback |
+|---|---|---|---|---|
+| CLI version identification | `unknown` | no isolated `opencode --version` | Not probed | Do not pin |
+| Root `AGENTS.md` consumption | `confirmed` | opencode.ai/docs/rules | Native project instructions | Root `AGENTS.md` is the always-on entry |
+| Explicit role file | `confirmed` | opencode.ai/docs/agents | `.opencode/agents/<name>.md` | Native `@name` / Task |
+| Deterministic structured output | `unknown` | no probe | — | Do not require a JSON schema from agents |
+| `opencode` `/init` | `unknown` | docs describe `/init`; not used by this package | TTY / interactive | Use `ai-rules init opencode` |
+| Project rule discovery (no reference) | `no-equivalent` | no `.opencode/rules` alwaysApply/globs engine | `.mdc` globs do not exist | Lazy `Read` from `AGENTS.md` catalog |
+| Project rule discovery (explicit root reference) | `confirmed` | docs “Referencing External Files” | Agent can `Read` listed paths | Essential four rules in `AGENTS.md` |
+| Workspace agent discovery | `confirmed` | opencode.ai/docs/agents | `.opencode/agents/` | Native |
+| Workspace Skill discovery | `confirmed` | opencode.ai/docs/skills | `.opencode/skills/<name>/SKILL.md` | Native `skill` tool |
+| Project MCP | `confirmed` | opencode.ai/docs/mcp-servers | `opencode.json` `mcp` | Merge on init |
+| Project hooks (`hooks.json`) | `unknown` | plugins exist; this preset does not ship them | No `subagentStop` analog | Manual `chain-team-phases.sh` |
+| Slash commands | `confirmed` | opencode.ai/docs/commands | `.opencode/commands/<name>.md` | Native `/task` |
+| Plugin / skill / MCP combo | `confirmed` | skills + mcp docs | MCP inflates context | Gate unused servers in operator config |
+| Native Team lifecycle | `partial` | file pipeline is ai-rules SoT | No native team runtime | Hook owns `status.json` / `metrics.json` |
+| `opencode.json` `instructions` globs | `unknown` | V1 docs load globs; V2 may not resolve | Do not depend on this field | `AGENTS.md` + explicit Read |
+
+## What we do not claim
+
+- Cursor `alwaysApply` / `globs` on OpenCode
+- Claude topic-folder twins as the OpenCode source
+- Auto-registration of `hooks.json` or a TypeScript plugin in v1
+- `init opencode --dry-run` / manifest preview (v1 is apply + rollback only)
+- Writes to `~/.config/opencode/**` or `~/.opencode/**`
+
+## Follow-up probe (optional)
+
+When a maintainer has a logged-in OpenCode CLI, add an isolated probe (empty workdir, ephemeral `HOME`) and update this matrix. Until then, docs-confirmed rows stay labelled as such in [`OPENCODE.md`](./OPENCODE.md).

package/docs/OPENCODE.md

@@ -0,0 +1,123 @@
+# OpenCode adapter
+
+Experimental preset for [OpenCode](https://opencode.ai/). Platform id is **`opencode`**. Consumer files land under **`.opencode/`** (native agents / skills / commands) plus root **`AGENTS.md`** and **`opencode.json`**.
+
+All **10** installable stacks are in `releasedStacks`: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, `php-laravel`.
+
+## Install
+
+From the **target project root** (where `app/` or `package.json` lives):
+
+```bash
+npx @bonesofspring/ai-rules init opencode --preset next
+npx @bonesofspring/ai-rules init opencode --preset go
+```
+
+All four platforms at once: `npx @bonesofspring/ai-rules init multi --preset <stack>`.
+
+What lands:
+
+| Source (package) | Consumer path |
+|------------------|---------------|
+| `REPO_AGENTS.md` | `./AGENTS.md` (native always-on + load map) |
+| `OPENCODE.md` | `.opencode/AGENTS.md` (OpenCode load map) |
+| `rules/`, `agents/`, `skills/`, `commands/`, `hooks/` | `.opencode/<dir>/` |
+| `team/` | `.ai.local/team/` (shared pipeline artifacts; not `.opencode/team/`) |
+| `opencode.json` | `./opencode.json` (merge `mcp` only) |
+
+Remove only what this install owns:
+
+```bash
+npx @bonesofspring/ai-rules clean opencode
+```
+
+`clean opencode` is **manifest-owned**: unchanged hashes are removed; files you edited stay. Without a valid `.opencode/.ai-rules-install.json`, clean is fail-safe (nothing removed). Extra keys in `opencode.json` (models, permissions, user MCP servers) are preserved.
+
+The CLI **never** writes `~/.config/opencode/**`.
+
+Quad-install with Cursor, Claude, or Mavis: `init multi --preset next` copies the **same** root `AGENTS.md` (last `init` still overwrites; content does not change). `clean opencode` leaves that file if another tool install remains. `/task` pipelines are **shared** — artifacts live under `.ai.local/team/` (not removed by `clean`).
+
+## How to load
+
+OpenCode has **no** `.mdc` `alwaysApply` / `globs` engine. Do **not** rely on `opencode.json` `instructions` as the only always-on path (V2 may ignore it).
+
+| Kind | How it loads |
+|------|----------------|
+| Essential rules | Root `AGENTS.md` lists four paths — **Read immediately** |
+| Other rules | Lazy `Read` of `.opencode/rules/<stem>.md` when the task matches |
+| Agents | Native `.opencode/agents/*.md` (`@name` / Task). `mode: subagent` |
+| Skills | Native `.opencode/skills/<name>/SKILL.md` (`skill` tool) |
+| Commands | Native `/task`, `/task-continue`, `/technical-retro`, `/spec-start` |
+| MCP | `opencode.json` → `mcp` |
+
+**Every turn:** read root `AGENTS.md`, then `.opencode/AGENTS.md`, then the four essential rules. Probe `.ai.local` (see [`LOCAL-OVERLAY.md`](./LOCAL-OVERLAY.md)).
+
+Do not pin a model in this preset — use the operator’s OpenCode provider config.
+
+## Task pipeline (semi-auto)
+
+File-based orchestration under `.ai.local/team/` mirrors Cursor/Claude:
+
+1. Start work with `/task` (`.opencode/commands/task.md`).
+2. Producers write artifacts and upsert `artifact-manifest.json` receipts.
+3. **Do not** mutate `status.json` / `metrics.json` lifecycle fields from agent prompts — the chain runner owns them.
+4. After each producer receipt, run:
+
+```bash
+printf '%s\n' '{"status":"completed","attemptId":"<from-status.json>"}' \
+  | bash .opencode/hooks/chain-team-phases.sh
+```
+
+Human gates pause with `awaitingHumanGate: true`. Resume with `/task-continue`. There is **no** shipped `hooks.json` or OpenCode plugin in v1.
+
+Full team layout: `.ai.local/team/README.md`.
+
+## MCP
+
+Preset servers merge into project **`opencode.json`** `mcp`:
+
+- Cursor `command` + `args` → `{ "type": "local", "command": [...] }`
+- Cursor `url` → `{ "type": "remote", "url": "..." }`
+
+Extra local servers survive re-init when the file is valid JSON. See `.opencode/MCP.md` and rule `mcp-usage.md`.
+
+## Capability summary
+
+Labels from official OpenCode docs (live CLI probe not yet run). Full matrix: [`OPENCODE-COMPATIBILITY.md`](./OPENCODE-COMPATIBILITY.md).
+
+| Area | Status | What we do |
+|------|--------|------------|
+| Root `AGENTS.md` | **confirmed** (docs) | Native always-on; reference rules explicitly |
+| `.opencode/agents` / `skills` / `commands` | **confirmed** (docs) | Native discovery |
+| `opencode.json` MCP | **confirmed** (docs) | Merge `mcp` |
+| Glob / alwaysApply rules | **no-equivalent** | Lazy Read catalog under `.opencode/rules/` |
+| `hooks.json` / subagentStop | **unknown** | Manual `chain-team-phases.sh` |
+| Native Team lifecycle | **partial** | File pipeline is SoT; hook is single lifecycle writer |
+
+Do not pin OpenCode CLI or TUI versions in the contract.
+
+## Local overlay
+
+`.ai.local/rules/*.md` at repo root (or monorepo parents) override preset rules. See [`LOCAL-OVERLAY.md`](./LOCAL-OVERLAY.md).
+
+## Maintainer docs
+
+| Doc | Purpose |
+|-----|---------|
+| [`presets/opencode/README.md`](../presets/opencode/README.md) | Source tree, contract, validation scripts |
+| [`presets/opencode/platform-contract.json`](../presets/opencode/platform-contract.json) | `releasedStacks`, paths, capability statuses |
+| [`OPENCODE-COMPATIBILITY.md`](./OPENCODE-COMPATIBILITY.md) | Evidence and go/no-go |
+| [`PRESET-CONTRIBUTION.md`](./PRESET-CONTRIBUTION.md) | Sibling adapter authoring |
+
+Validate after preset edits:
+
+```bash
+cd packages/ai-rules
+bash scripts/check-preset-structure.sh
+node scripts/check-opencode-platform-contract.mjs --self-test
+node scripts/check-opencode-adapter-map.mjs --self-test
+```
+
+## Released stacks
+
+`init opencode --preset <stack>` and `init multi --preset <stack>` install OpenCode for every stack in `presets/opencode/platform-contract.json` `releasedStacks` (all 10). Per-stack always-on rules and `permission.edit` allow-lists live in `scripts/lib/stack-platform-profiles.mjs`. Derive with `node scripts/generate-opencode.mjs --stack <stack>` from Cursor SoT — never from Claude.