@bonesofspring/ai-rules 0.2.26 → 0.2.28

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 | Compact hedge for parent + per-agent "Rules to load" block is V2-safe | `AGENTS.md` + explicit Read (authoritative for subagents) |
+
+## 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,133 @@
+# 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`; union preset `instructions`; fill missing `permission.bash` keys) |
+
+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, user MCP servers, extra instruction paths) are preserved. Re-init still unions preset instruction paths and fills bash keys the file does not already set.
+
+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. The preset uses three mechanisms:
+
+| Mechanism | Role | V2-safe? |
+|-----------|------|----------|
+| Root `AGENTS.md` + `.opencode/AGENTS.md` | Always-on core (essential rules + entry maps) for the **parent** | yes |
+| `opencode.json` `instructions` | Compact hedge (`alwaysOn` paths + `.opencode/AGENTS.md`) for the **parent**; re-init unions preset paths into the consumer list | V1 yes, V2 uncertain (kept narrow) |
+| `## Rules to load (subagent context)` block in every `.opencode/agents/*.md` | Authoritative for **subagents** (`Task`/`@name`); alwaysOn + stack zone rules filtered to existing stems | yes |
+
+`bin/opencode-install.js` `mergeOpencodeConfig` on re-init **unions** preset `instructions` paths into the existing list and **fills missing** `permission.bash` keys. Extra consumer paths and same-key bash overrides stay. An empty `instructions: []` receives the preset paths. A non-array `instructions` value is left as-is.
+
+| Kind | How it loads |
+|------|----------------|
+| Essential rules | Root `AGENTS.md` + `.opencode/AGENTS.md` list 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`. Each ships the **rules-to-load block** so subagents see the always-on + zone set |
+| MCP | `opencode.json` `mcp` — preset ships context7 / playwright / chrome-devtools / figma; merge keeps extras |
+| Harness enforcement | `opencode.json` `permission.bash` — universal `git commit/push deny` + JS-stack `npm/npx/pnpm/bun ask` + `npx jest* deny` |
+| 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.