@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/mavis/go/skills/spec-discovery/SKILL.md

@@ -0,0 +1,53 @@
+# Spec discovery
+
+Requestable — **not** always-on. Load **only** in **task-analyst author mode** when the user or AC asks research-before-spec (including `/spec-start` with that intent). Never default consume `/task`. Not a pipeline step.
+
+Load **`product-specs`** (and **`product-specs-authoring`** after this skill if authoring follows). Do **not** invent product behavior. Do **not** create a second spec-file tree.
+
+## Load policy
+
+1. Pick a **subset** of methods that fit the task — not all 11 every time.
+2. **`claim-ledger` is mandatory** whenever this skill runs.
+3. Write chronological notes to `.ai.local/team/tasks/<slug>/.memlog.md` (append-only). Do **not** mutate `status.json` / `metrics.json`.
+4. Discovery output lives in memlog + `brief.md` sections. Then hand off to skill **`spec-authoring`** (or stop if `specMode: none`).
+
+Backend / MCP stacks: skip UI-only examples; prefer `analog-scan`, `code-archaeology`, `problem-define`, `assumption-audit`, `claim-ledger`.
+
+## Methods
+
+| Method | Produces | Skip when |
+|--------|----------|-----------|
+| **intake-capture** | Raw idea, origin, first unknowns → memlog + brief Research inputs | User prompt + AC already complete |
+| **index-locator** | Related INDEX rows + linked spec paths + gaps | `specMode: none` or INDEX absent without consume intent |
+| **code-archaeology** | Observed behavior labeled `inferred`/`draft` with path citations | Greenfield with no relevant code |
+| **research-pack-scan** | Claims from `team/tasks/<slug>/research/**` or user-supplied paths | No research paths cited |
+| **evidence-against** | Reasons the idea may fail | Internal spike with no product/external risk |
+| **problem-define** | Who hurts, goals, non-goals, cost of inaction → brief | Brief Goal + Out of scope already exhaustive |
+| **concept-shape** | 2–3 approach options + appetite (small/medium/large); no API design | `architecture.md` exists or one obvious path |
+| **working-backwards-check** | Headline + 5 customer objections + verdict `forged` / `needs-heat` / `cracked` | Consume mode with approved specs |
+| **assumption-audit** | Assumption register → brief Assumptions + `open_questions` | Never skip in author mode (keep lightweight) |
+| **analog-scan** | 2–3 repo analogs via `reference-features` / code search | No plausible analog |
+| **claim-ledger** | Markdown table `source → claim` for every product-behavior claim | **Never skip** when this skill is loaded |
+
+## Claim ledger (required)
+
+Block spec authoring until every product-behavior claim has a source:
+
+```markdown
+| Source | Claim |
+|--------|-------|
+| brief AC-3 | Checkout shows empty cart copy |
+| code-archaeology inferred | Empty state uses an illustration |
+```
+
+Sources: AC / user / UI copy / labeled code inference / research path. Unsourced claims → `open_questions`.
+
+## Memlog
+
+Path: `.ai.local/team/tasks/<slug>/.memlog.md`. Chronological `## YYYY-MM-DD` headings. Optional tags: `decision`, `assumption`, `override`, `event`, `claim`.
+
+## Forbidden
+
+- 108-technique catalogs, HTML composers, party-mode, five `assess.*` slash commands, Python memlog runtime.
+- Dummy INDEX rows when `specMode: none`.
+- Dumping the whole `docs/specs/**` tree — locator is INDEX → linked page + optional `feature.md`.

package/presets/mavis/go/skills/technical-retro/SKILL.md

@@ -0,0 +1,49 @@
+# Technical Retro
+
+## Inputs
+
+Ask for missing period, focus, task slug, participants, or format constraints. If a slug is provided, read `.ai.local/team/tasks/<slug>/` artifacts and local git status/diff. Do not invent facts not present in artifacts or the user's message.
+
+## Facilitation Principles
+
+- Focus on process and system behavior, not blame.
+- Separate facts, interpretations, and proposed actions.
+- Balance what worked with what slowed delivery.
+- Keep action items concrete, owned, and measurable.
+
+## Default Structure
+
+1. Goal and scope.
+2. Timeline or factual observations.
+3. What worked.
+4. What hurt quality, speed, or confidence.
+5. Root causes for the top one or two issues.
+6. Experiments and action items.
+
+## Agent Team Block
+
+For `/task` pipelines, include router, analyst, developer, **build-verifier** (go test), reviewer, QA/integration tests, hooks, and rules.
+
+## Wrong-turn taxonomy (optional)
+
+When artifacts or the user mention agent mistakes, tag incidents:
+
+| Kind | Signal |
+|------|--------|
+| `correction` | User pushback («no», «don't», «actually») |
+| `retry` | Same tool/approach 2+ times before success |
+| `waste` | Many searches before the right file |
+| `reversal` | Edit then revert / delete |
+| `dead-end` | Env/tool failure (missing binary, wrong path) |
+
+Severity: **high** (explicit correction / large waste) · **med** · **low**. Confidence 0–100 — be honest; low-confidence items are optional.
+
+## Preset feedback loop
+
+If the same issue appeared in **2+** tasks (or **3+** for packaging a new rule/skill — Rule of Three), add section **Preset updates**:
+
+- Proposed change to `.mavis/rules/`, `.mavis/agents/`, `.mavis/skills/`, or **`.ai.local/conventions.md`** (prefer conventions for project gotchas)
+- One concrete snippet or file path
+- Whether it belongs in always-on vs globs vs skill vs conventions (see `PRESET-CONTRIBUTION` → Building blocks)
+
+Do not apply preset or conventions changes without user approval.

package/presets/mavis/go/skills/unit-testing/SKILL.md

@@ -0,0 +1,9 @@
+# Unit testing (Go)
+
+1. Prefer table-driven `testing` packages beside code under test.
+2. Fake outbound ports for use cases; no real DB/network.
+3. Follow `tests-unit.md`; heal with `unit-test-healer` when red.
+
+## Agents
+
+`unit-test-planner` → `unit-test-generator` → `unit-test-healer`.

package/presets/mavis/go/skills/write-adr/SKILL.md

@@ -0,0 +1,36 @@
+# Write ADR
+
+On-demand skill for durable architecture decisions. Stack-agnostic sections — fill with project-specific paths and links.
+
+## When to use
+
+- Choosing between non-trivial alternatives (storage, layering, library, API shape).
+- Recording a decision that future agents/humans should not silently reverse.
+- User asks for an ADR, decision log, or “why did we pick X”.
+
+## Template
+
+Create (or append) a short markdown ADR in the repo’s agreed location (e.g. `docs/adr/`, `.ai.local/team/`, wiki). Suggested filename: `NNNN-short-title.md`.
+
+```markdown
+# ADR NNNN: <Title>
+
+## Context
+What problem / constraint / force requires a decision?
+
+## Decision
+What we chose (one clear option). Include rejected alternatives briefly if useful.
+
+## Consequences
+Positive and negative outcomes; follow-up work; what becomes harder.
+
+## Links
+Related PRs, issues, rules, prior ADRs, diagrams.
+```
+
+## Guidelines
+
+- Prefer one decision per ADR.
+- Keep Context factual; Decision imperative and short.
+- Link living gotchas to `.ai.local/conventions.md` when the decision becomes a recurring local pattern.
+- Do not put ADR bodies only in root `AGENTS.md` (overwrite on init).

package/presets/mavis/go/team/README.md

@@ -0,0 +1,77 @@
+# Agent team artifacts
+
+Shared `/task` runtime for Cursor, Claude, Mavis, and OpenCode. Seeded at **`.ai.local/team/`**. Overlay must not load this tree as rules.
+
+`init` refreshes README + fixtures. It never overwrites `tasks/<slug>/`. `clean <tool>` never deletes `.ai.local/`.
+
+## Layout
+
+```
+.ai.local/team/
+  README.md
+  active-task.json           # current slug pointer (runtime)
+  fixtures/                  # pipeline profile examples
+  tasks/<slug>/
+    pipeline.json            # router-owned plan
+    status.json              # hook-owned lifecycle
+    metrics.json             # hook-owned append-only ledger
+    artifact-manifest.json   # producer receipts
+    brief.md, decomposition.md, implementation.md, review.md, …
+    .memlog.md               # optional agent notes (hook does not parse)
+```
+
+Bootstrap a slug by **writing** `pipeline.json` (editor Write tool). Do not `mkdir -p` from a sandboxed Shell. The hook owns `status.json` / `metrics.json`; agents must not patch lifecycle fields.
+
+## pipeline.json
+
+```json
+{
+  "slug": "order-history-date-filter",
+  "intent": "feature",
+  "specMode": "consume",
+  "summary": "Add date filter to Order History",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
+    { "agent": "build-verifier", "label": "Validation gate" },
+    { "agent": "code-reviewer", "label": "Code review" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}
+```
+
+| Field | Notes |
+|-------|--------|
+| `agent` | kebab-case, or an array when `parallel: true` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only` |
+| `skipIf` | `debugger.fixed` \| `ci-investigator.resolved` |
+| `model` | optional `cheap` \| `standard` \| `strong` |
+| `specMode` | `consume` \| `generate` \| `none` — `brief.md` `## Spec mode` wins |
+
+## status.json
+
+Prefer `phase: executing`. States: `in_progress`, `completed`, `awaiting_approval` (`/task-continue`), `changes_requested`, `validation_failed`.
+
+## Commands
+
+```bash
+/task <description>
+/task-continue <slug>
+/technical-retro <slug>
+```
+
+After a human gate, close wait via the **installed** hook (do not hand-edit `pipelineIndex`):
+
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .mavis/hooks/chain-team-phases.sh
+```
+
+Same JSON on Claude, Mavis, or OpenCode: `bash .<tool>/hooks/chain-team-phases.sh`.
+
+## Contracts
+
+- Manifest schema: shared core `agent-team/agent-artifact-contracts.md`. Read it first; producers upsert only their IDs.
+- Metrics: append-only allowlisted events — `agent-team/agent-task-metrics.md`. Aggregate: `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .ai.local/team`.
+- Commit `.ai.local/team/` templates (and slugs if you want them in clones).

package/presets/mavis/go/team/fixtures/bugfix-standard.json

@@ -0,0 +1,37 @@
+{
+  "slug": "example-bugfix-standard",
+  "intent": "bugfix",
+  "profile": "standard",
+  "summary": "Regression fix with review",
+  "steps": [
+    {
+      "agent": "debugger",
+      "label": "Root cause"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Fix if needed",
+      "skipIf": "debugger.fixed"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "go test / go vet / golangci-lint"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "playwright-test-planner",
+      "reason": "Go backend uses integration-test-* — not in this bugfix path"
+    },
+    {
+      "agent": "xcuitest-test-planner",
+      "reason": "Go backend uses integration-test-* — not in this bugfix path"
+    }
+  ]
+}

package/presets/mavis/go/team/fixtures/feature-full.json

@@ -0,0 +1,61 @@
+{
+  "slug": "example-feature-full",
+  "intent": "feature",
+  "specMode": "consume",
+  "profile": "full",
+  "summary": "Multi-layer Go use case with integration-test coverage",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Clarify and decompose"
+    },
+    {
+      "agent": "solution-architect",
+      "label": "Design boundaries",
+      "model": "strong"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Implement + unit tests",
+      "scope": "unit-in-dev"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "go test / go vet / golangci-lint",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "Integration tests",
+      "scope": "e2e-only"
+    },
+    {
+      "agent": "integration-test-planner",
+      "label": "Plan integration coverage"
+    },
+    {
+      "agent": "integration-test-generator",
+      "label": "Generate integration tests"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
+  ],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "accessibility-reviewer",
+      "reason": "Go backend has no UI surface"
+    }
+  ]
+}

package/presets/mavis/go/team/fixtures/feature-light.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-light",
+  "intent": "feature",
+  "profile": "light",
+  "summary": "Trivial single-package change with explicit AC",
+  "steps": [
+    { "agent": "feature-developer", "label": "Implement", "model": "cheap" },
+    { "agent": "build-verifier", "label": "go test / go vet / golangci-lint", "model": "cheap" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "task-analyst", "reason": "Explicit AC and single-package scope" },
+    { "agent": "code-reviewer", "reason": "Light profile — non-trivial module/service changes should use standard" },
+    { "agent": "qa-tester", "reason": "No integration-test AC" }
+  ]
+}

package/presets/mavis/go/team/fixtures/memlog.example.md

@@ -0,0 +1,9 @@
+# Memlog example
+
+Append-only. Agents write; `/task-continue` may read. The hook does not parse this file.
+
+## 2026-08-13
+
+- `decision`: specMode=generate; research-before-spec requested
+- `claim`: empty-cart copy lives in the empty-state handler (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/mavis/ios-swift/MAVIS.md

@@ -0,0 +1,79 @@
+# iOS Swift stack — Mavis agent team
+
+Short Mavis entry. Detailed rules live under `.mavis/rules/*.md`; procedures
+under `.mavis/skills/**`. This file is ai-rules-owned (`.mavis/AGENTS.md`),
+not a MiniMax-reserved filename.
+
+Root `AGENTS.md` is the compatibility floor. Read it first, then this file.
+Do not write `~/.minimax/**`.
+
+## How to load
+
+- Rules and skills: follow the explicit paths in this file and root `AGENTS.md`.
+  Native project discovery without a reference is unconfirmed.
+- Roles: `mcode exec --file .mavis/agents/<role>.md --output-format json`.
+- Commands: natural-language procedures in `.mavis/commands/`, or
+  `mcode exec --file .mavis/commands/task.md "<task>"`.
+- After a producer receipt, run `bash .mavis/hooks/chain-team-phases.sh`.
+  Agents must not write lifecycle fields in `status.json` / `metrics.json`.
+
+## Essential rules (read every turn)
+
+- `.mavis/rules/ios-app-core.md`
+- `.mavis/rules/architecture-boundaries.md`
+- `.mavis/rules/code-quality-and-refactoring.md`
+- `.mavis/rules/ai-local-overlay.md`
+
+See `.mavis/rules/README.md` for the full catalog and loading strategy.
+
+**Platform docs:** published with the `@bonesofspring/ai-rules` package
+(`docs/MAVIS.md`, `docs/MAVIS-COMPATIBILITY.md`) — **not** copied into
+the consumer repo. Source: https://github.com/bonesofspring/ai-rules
+
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root (cross-tool setup, commands, security, living conventions pointers).
+
+## Quick start
+
+| Task | Where to look |
+|------|----------------|
+| Any new work request | `/task` → `commands/task.md` + `agent-team-orchestrator.md` (+ `agent-team-intake.md` on-demand) |
+| New end-to-end feature | skill `feature-delivery` + `feature-delivery-workflow.md` |
+| Stack and layers | `ios-app-core.md` |
+| Reference Features | `reference-features.md` (examples `Features/Orders/…`; replace with real paths) |
+| Toolchain / schemes | `xcode-tooling.md` (requestable) |
+| After Swift edits | `post-change-build.md` (**requestable**, required after edits; full gate — `build-verifier`) |
+| Code review MR | skill `code-review` + `code-review-mr.md` |
+| UI tests | skill `xcuitest-e2e` + agents `xcuitest-test-*` |
+| Security / Keychain | `security-ios.md` |
+| SwiftUI lifecycle | `swiftui-ui.md` (`.task`, ownership) |
+| Validation before review | agent `build-verifier` (for this preset: also check chain≠next) |
+| Technical retro | `/technical-retro` + skill `technical-retro` |
+
+## Dogfood (5 scenarios)
+
+1. `/task` — new Feature under `Features/<Name>`.
+2. ViewModel bug — debugger + unit test.
+3. Mapper — unit-test-planner/generator.
+4. UI flow — xcuitest trio.
+5. Auth/Keychain — security-reviewer + `security-ios.md`.
+
+## When to use `/task`
+
+- Implementation, bugfix, migration, tests, MR review, CI-fix — **prefer `/task`**.
+- Simple one-liner with no architectural risk — may skip the pipeline if the user explicitly asks.
+- “How does X work?” questions — agent `codebase-analyzer` (explain-as-is) or answer without `/task`.
+
+## Pipeline routing
+
+Intent detection, profiles (`full` / `standard` / `light`), and default steps — **only** in `agents/task-router.md`. Schema and rename map (Playwright → XCUITest) — `agents/README.md`.
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init mavis --preset ios-swift
+```
+
+Copies rules, commands, agents, hooks, skills, `MAVIS.md` → `.mavis/AGENTS.md`,
+`MCP.md`, `mcp.json` → `.mavis/mcp.json`, plus `REPO_AGENTS.md` → root `AGENTS.md`.
+Seeds `.ai.local/team/`.
+Import MCP from `.mavis/mcp.json` in the MiniMax Code UI.

package/presets/mavis/ios-swift/MCP.md

@@ -0,0 +1,35 @@
+# MCP (preset `ios-swift`, Mavis)
+
+Staged at `.mavis/mcp.json` on `ai-rules init mavis --preset ios-swift`.
+
+## Servers
+
+| Name | Package | Purpose |
+|------|---------|---------|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Swift / SwiftUI / Apple frameworks docs |
+| `figma` | remote `https://mcp.figma.com/mcp` | Design context → SwiftUI; OAuth in MiniMax Code (manual import) |
+
+Playwright / Chrome DevTools are **not** part of the ios preset (browser e2e is forbidden for the agent team).
+
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token).
+
+
+## Agent usage
+
+Load requestable rule `mcp-usage`. The **session MCP catalog** is source of truth (this file and `mcp.json` are hints). Discover tool schemas before calling; never invent them.
+
+**Context7 (shipped):** query docs when a third-party API is not confirmed by lockfile + sibling files. Use the installed major. Cap ≤3 doc queries per question. If Context7 is down, mark `// VERIFY` and continue — do not block.
+
+## Local overlay (not shipped)
+
+`init` **merges** `mcpServers`: preset keys are updated; extra local servers are kept. User-level MCP is never touched. Prefer user-level MCP if you do not want overlay servers in the project file.
+
+Use an overlay only when it is **ready** (`serverStatus` not `error` / `needsAuth` / `loading`) **and** the task fits. Absence is not a blocker unless the user required that MCP as source of truth.
+
+| Kind | Typical aliases | When |
+|------|-----------------|------|
+| Observability | `sentry`, `datadog`, `plugin-datadog-*` | production error, event/trace id, APM |
+| Tickets | `linear`, `jira`, `notion`, `plugin-notion-*` | ticket/page URL; read-only; task-folder artifacts remain SoT |
+| GitHub MCP | `github` | optional; native `gh` remains SoT for PRs and checks |
+
+Do **not** require Storybook, Playwright, or Chrome DevTools MCP as delivery gates on this preset.

package/presets/mavis/ios-swift/README.md

@@ -0,0 +1,16 @@
+# iOS Swift preset (Mavis)
+
+Sibling adapter derived from `presets/cursor/ios-swift`. Platform id `mavis`;
+runtime `mcode`. Consumer install root is `.mavis/` (ai-rules-owned).
+
+Mapping: `adapter-map.json`. Do not derive this tree from Claude.
+
+```bash
+npx @bonesofspring/ai-rules init mavis --preset ios-swift
+```
+
+Install id: `ios-swift`. Listed in `platform-contract.json` `releasedStacks`.
+
+`init` writes `.mavis/**` plus root `AGENTS.md` and seeds `.ai.local/team/`.
+No `hooks.json` / Bugbot; chain with `bash .mavis/hooks/chain-team-phases.sh`.
+`clean mavis` does not delete `.ai.local/`.

package/presets/mavis/ios-swift/REPO_AGENTS.md

@@ -0,0 +1,72 @@
+# iOS Swift — agent instructions
+
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`, `.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, Mavis, OpenCode, or other).
+- All four platforms ship **the same** root file. `init` overwrites it; content does not depend on which tool ran last.
+- Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md` — use them when that tool is installed.
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init multi --preset ios-swift
+```
+
+Per-tool: `init cursor|claude|mavis|opencode --preset ios-swift`. `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/ios-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/ios-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)
+
+| Gate | Typical command |
+|------|-----------------|
+| Build | `xcodebuild` (scheme/workspace as in project docs) |
+| Lint | **SwiftLint** (config in repo; see `xcode-tooling` / conventions) |
+| Format | SwiftFormat when configured |
+| Tests | `xcodebuild test` slice for the changed target |
+
+After code edits: invoke **`post-change-build`** (requestable). Full gate: agent `build-verifier`.
+
+## Security basics
+
+- Do not commit secrets (API keys, Keychain dumps, `.env`).
+- Review destructive git before running; respect shell hooks.
+- Do not skip signing / CI gates unless the user explicitly asks.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
+| Mavis | `.mavis/AGENTS.md` (optional if Mavis not installed) |
+| OpenCode | `.opencode/AGENTS.md` (optional if OpenCode not installed) |
+
+Rules: `.cursor/rules/`, `.claude/rules/`, `.mavis/rules/`, or `.opencode/rules/`.
+Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/skills/`.
+
+## Living conventions
+
+Gotchas, local patterns, and team decisions: **`.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.