@bonesofspring/ai-rules 0.2.22 → 0.2.24

package/presets/mavis/next/team/fixtures/metrics-scenarios/tasks/validation-failed/metrics.json

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "validation-failed-run",
+    "slug": "validation-failed",
+    "preset": "ai-rules",
+    "stack": "next",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "validation-failed-run:task",
+      "type": "task_started",
+      "at": "2026-07-31T15:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:00:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "build-verifier",
+      "role": "validation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "outcome": "validation_failed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:retry:1",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "nextAgent": "feature-developer",
+      "retryAfterFix": "build-verifier",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:1:feature-developer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "feature-developer",
+      "role": "implementation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:1:feature-developer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 180000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:retry:2",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "nextAgent": "build-verifier",
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:2:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-2",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "build-verifier",
+      "role": "validation",
+      "attempt": 2,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:2:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:06:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-2",
+      "outcome": "completed",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:done",
+      "type": "task_completed",
+      "at": "2026-07-31T15:06:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/mavis/next/team/fixtures/metrics.example.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "example-run-1",
+    "slug": "example-feature-full",
+    "preset": "ai-rules",
+    "stack": "next",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "example-run-1:task_started",
+      "type": "task_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:attempt-1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "attemptId": "example-run-1:step-0:task-analyst:attempt-1",
+      "stepIndex": 0,
+      "stepLabel": "Clarify and decompose",
+      "agent": "task-analyst",
+      "role": "planning",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:attempt-1:end",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:02:00.000Z",
+      "attemptId": "example-run-1:step-0:task-analyst:attempt-1",
+      "outcome": "completed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:task_completed",
+      "type": "task_completed",
+      "at": "2026-07-31T14:02:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/mavis/next/team/fixtures/mockup-review-fail-embedded-status.json

@@ -0,0 +1,8 @@
+{
+  "slug": "example-mockup-fail-gate",
+  "state": "awaiting_approval",
+  "currentAgent": "mockup-reviewer",
+  "awaitingHumanGate": true,
+  "retryAfterFix": null,
+  "note": "Embedded mockup FAIL: hook must NOT set retryAfterFix to feature-developer. Resume only via /task-continue."
+}

package/presets/mavis/next/team/fixtures/mockup-review-standalone.json

@@ -0,0 +1,14 @@
+{
+  "slug": "example-mockup-review-standalone",
+  "intent": "mockup-review",
+  "profile": "light",
+  "summary": "Standalone Figma mockup review (report-only)",
+  "steps": [
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone mockup-review is report-only" }
+  ]
+}

package/presets/mavis/next/team/fixtures/ux-design-standalone.json

@@ -0,0 +1,15 @@
+{
+  "slug": "example-ux-design-standalone",
+  "intent": "ux-design",
+  "profile": "light",
+  "summary": "Standalone behavioral UX design (analyst + skill ux-design; report-only; no developer)",
+  "steps": [
+    { "agent": "task-analyst", "label": "UX design (skill ux-design)" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone ux-design is report-only" },
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; not a mockup review" }
+  ]
+}

package/presets/mavis/platform-contract.json

@@ -0,0 +1,131 @@
+{
+  "schemaVersion": 1,
+  "id": "mavis",
+  "runtimeExecutable": "mcode",
+  "sourceRoot": "presets/mavis",
+  "managedRoot": ".mavis",
+  "releasedStacks": ["next"],
+  "entryFiles": [
+    {
+      "source": "REPO_AGENTS.md",
+      "destination": "AGENTS.md"
+    },
+    {
+      "source": "MAVIS.md",
+      "destination": ".mavis/AGENTS.md"
+    }
+  ],
+  "directoryMappings": [
+    {
+      "source": "rules",
+      "destination": ".mavis/rules"
+    },
+    {
+      "source": "agents",
+      "destination": ".mavis/agents"
+    },
+    {
+      "source": "skills",
+      "destination": ".mavis/skills"
+    },
+    {
+      "source": "commands",
+      "destination": ".mavis/commands"
+    },
+    {
+      "source": "hooks",
+      "destination": ".mavis/hooks"
+    },
+    {
+      "source": "team",
+      "destination": ".mavis/team"
+    }
+  ],
+  "mcp": {
+    "source": "mcp.json",
+    "fallbackDestination": ".mavis/mcp.json",
+    "mode": "fallback-manual-import"
+  },
+  "docsSeed": {
+    "source": "presets/_shared/assets/docs-specs",
+    "behavior": "absent-only"
+  },
+  "cleanStrategy": "manifest-owned",
+  "nativeCapabilities": {
+    "cliVersion": {
+      "status": "confirmed",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "rootAgents": {
+      "status": "confirmed",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "explicitAgentFile": {
+      "status": "confirmed",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "structuredOutput": {
+      "status": "confirmed",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "referencedRule": {
+      "status": "confirmed",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "referencedSkill": {
+      "status": "confirmed",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "freshInit": {
+      "status": "unknown",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "nativeProjectRules": {
+      "status": "unknown",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "nativeWorkspaceSkills": {
+      "status": "unknown",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "nativeWorkspaceAgents": {
+      "status": "unknown",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "projectMcp": {
+      "status": "unknown",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "projectHooks": {
+      "status": "unknown",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "slashCommands": {
+      "status": "unknown",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "pluginSkillMcp": {
+      "status": "confirmed",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    },
+    "nativeTeam": {
+      "status": "partial",
+      "evidence": "docs/MAVIS-COMPATIBILITY.md",
+      "nativePath": null
+    }
+  }
+}

package/presets/opencode/README.md

@@ -0,0 +1,61 @@
+# OpenCode platform adapter
+
+Sibling of `presets/cursor/`, `presets/claude/`, and `presets/mavis/`.
+Platform id is **`opencode`**. The external runtime executable is **`opencode`**.
+
+This directory is the **source** tree. Consumer installs land under **`.opencode/`**
+(native OpenCode discovery for agents, skills, and commands) plus root
+`AGENTS.md` and `opencode.json`.
+
+Do not write `~/.config/opencode/**` from init, clean, or probes.
+
+## Status
+
+`platform-contract.json` `releasedStacks` lists installable stacks. **`next`**
+is released (`npx @bonesofspring/ai-rules init opencode --preset next`).
+Additional stacks ship after the Next pilot.
+
+Derivation (approved architecture):
+
+```text
+_shared/core  →  cursor/<stack>  →  opencode/<stack>
+                 cursor/<stack>  →  claude/<stack>   (unchanged twin)
+                 cursor/<stack>  →  mavis/<stack>    (unchanged)
+```
+
+OpenCode sources are **not** derived from Claude. Cursor remains the semantic
+source of truth.
+
+## Compatibility floor
+
+See [`docs/OPENCODE.md`](../../docs/OPENCODE.md) (consumer guide) and
+[`docs/OPENCODE-COMPATIBILITY.md`](../../docs/OPENCODE-COMPATIBILITY.md).
+Statuses come from official OpenCode docs until a live CLI probe exists.
+`unknown` / `no-equivalent` capabilities must not declare a native path.
+
+Native (documented):
+
+- root `AGENTS.md`
+- `.opencode/agents/`, `.opencode/skills/`, `.opencode/commands/`
+- `opencode.json` `mcp`
+
+Fallback (no Cursor-style rule engine / no `hooks.json`):
+
+- `.opencode/rules/**` — lazy `Read` from `AGENTS.md` catalog
+- pipeline lifecycle — `bash .opencode/hooks/chain-team-phases.sh` after receipts
+
+## Files
+
+| Path | Role |
+|------|------|
+| `platform-contract.json` | Machine-readable adapter declaration |
+| `next/` | Released Next.js stack (`releasedStacks: ["next"]`) |
+
+Validate:
+
+```bash
+node scripts/check-opencode-platform-contract.mjs
+node scripts/check-opencode-platform-contract.mjs --self-test
+node scripts/generate-opencode-next.mjs
+node scripts/check-opencode-adapter-map.mjs
+```

package/presets/opencode/next/MCP.md

@@ -0,0 +1,36 @@
+# MCP (preset `next`, OpenCode)
+
+Merged into project `opencode.json` `mcp` on `ai-rules init opencode --preset next`.
+
+## Servers
+
+| Name | Package | Purpose |
+|------|---------|---------|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Next/React/TS and library docs (fewer stale APIs in agent answers) |
+| `playwright` | `@playwright/mcp` | Browser automation for e2e agents (`playwright-test-*`) and selector checks |
+| `chrome-devtools` | `chrome-devtools-mcp` | Live DOM/network/performance when debugging UI |
+| `figma` | remote `https://mcp.figma.com/mcp` | Design context → code (layouts, tokens, Code Connect); OAuth in OpenCode (operator MCP config) |
+
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment — higher Context7 rate limits. Figma — OAuth on first connect (do not write the token into config).
+
+
+## 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 |
+| Storybook | `storybook`, `user-storybook`, `plugin-storybook`, `storybook-mcp-addon` | component docs/stories/controls; needs Storybook running; not shipped |
+
+**Browser split (this preset):** Playwright MCP → e2e agents and selectors. Chrome DevTools MCP → `debugger` / `performance-auditor` against a running app. Not interchangeable.

package/presets/opencode/next/OPENCODE.md

@@ -0,0 +1,65 @@
+# Next.js stack — OpenCode agent team
+
+Short OpenCode entry. Native discovery: `.opencode/agents/`,
+`.opencode/skills/`, `.opencode/commands/`. Rule files under
+`.opencode/rules/*.md` are **not** auto-loaded.
+
+Root `AGENTS.md` is native always-on. Read it first, then this file.
+
+## How to load
+
+- Essential rules: Read immediately (paths below). Do not preload the catalog.
+- Other rules: lazy `Read` `.opencode/rules/<stem>.md` when the task matches.
+- Agents: native `@name` / Task from `.opencode/agents/`.
+- Commands: native `/task` from `.opencode/commands/`.
+- After a producer receipt, run `bash .opencode/hooks/chain-team-phases.sh`.
+  Agents must not write lifecycle fields in `status.json` / `metrics.json`.
+
+## Essential rules (read every turn)
+
+- `.opencode/rules/next-app-core.md`
+- `.opencode/rules/package-manager.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+
+See `.opencode/rules/README.md` for the full catalog and loading strategy.
+
+**Platform docs:** published with the `@bonesofspring/ai-rules` package
+(`docs/OPENCODE.md`, `docs/OPENCODE-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 task | `/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 | `next-app-core.md` |
+| Reference features | `reference-features.md` (fill paths in the repo) |
+| After code edits | `post-change-lint.md` (**requestable**, but required after edits; full gate — `build-verifier`) |
+| Code review MR | skill `code-review` + `code-review-mr.md` |
+| Security (auth/forms/env) | `security-next.md` + agent `security-reviewer` |
+| Validation before review | agent `build-verifier` |
+| Technical retro | `/technical-retro` + skill `technical-retro` |
+
+## When to use `/task`
+
+- Implementation, bugfix, migration, tests, MR review, CI fix — **prefer `/task`**.
+- Simple one-liner without architectural risk — may skip the pipeline if the user explicitly asks.
+- Questions «как работает X» (how does X work) — agent `codebase-analyzer` (explain-as-is) or answer without `/task`. <!-- i18n-keep: E4 -->
+
+## Pipeline routing
+
+Intent detection, profiles (`full` / `standard` / `light`), and default steps — **only** in `agents/task-router.md`. Schema and examples — `agents/README.md`.
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init opencode --preset next
+```
+
+Copies rules, commands, agents, hooks, skills, team, `OPENCODE.md` →
+`.opencode/AGENTS.md`, `MCP.md`, `opencode.json` → project `opencode.json`
+(`mcp` merge), plus `REPO_AGENTS.md` → root `AGENTS.md`.

package/presets/opencode/next/README.md

@@ -0,0 +1,16 @@
+# Next.js preset (OpenCode)
+
+Sibling adapter derived from `presets/cursor/next`. Platform id `opencode`;
+runtime `opencode`. Consumer install root is `.opencode/` (native agents,
+skills, commands) plus root `AGENTS.md` and `opencode.json`.
+
+Mapping: `adapter-map.json`. Do not derive this tree from Claude.
+
+```bash
+npx @bonesofspring/ai-rules init opencode --preset next
+```
+
+`releasedStacks` currently lists **`next`** only.
+
+Omitted from this pilot: `BUGBOT.md`, `hooks.json`, hook examples, and
+unwired `guard-shell-command.sh`.

package/presets/opencode/next/REPO_AGENTS.md

@@ -0,0 +1,97 @@
+# Next.js — 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`.
+
+When this OpenCode preset is installed, read `.opencode/AGENTS.md` on every
+turn. Do not write `~/.config/opencode/**`. Do not mutate
+`.opencode/team/tasks/<slug>/status.json` or `metrics.json` — the chain
+runner owns those files.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code,
+  Mavis, OpenCode, or other).
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset next
+npx @bonesofspring/ai-rules init claude --preset next
+npx @bonesofspring/ai-rules init mavis --preset next
+npx @bonesofspring/ai-rules init opencode --preset next
+```
+
+`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`).
+Living gotchas belong in `team/conventions.md`, not here.
+
+## OpenCode load map
+
+After install, also read:
+
+- `.opencode/AGENTS.md` — OpenCode load map, roles, and procedures
+- `.opencode/rules/next-app-core.md`
+- `.opencode/rules/package-manager.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+
+Do **not** preload the full `.opencode/rules/` catalog. Native agents live in
+`.opencode/agents/`; skills in `.opencode/skills/`; slash commands in
+`.opencode/commands/` (`/task`). After a producer receipt run
+`bash .opencode/hooks/chain-team-phases.sh`.
+
+## Commands (test / lint / build)
+
+Working directory for app scripts: **`app/`**. Detect the package manager from
+lockfile / `packageManager` (`package-manager` rule).
+
+| Gate | Typical command |
+|------|-----------------|
+| Lint JS | `yarn lint:js` (or project equivalent) from `app/` |
+| Lint CSS | `yarn lint:css` from `app/` |
+| Unit tests | project unit script under `app/` |
+| Build | project `build` under `app/` |
+
+After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent
+`build-verifier`.
+
+## Security basics
+
+- Do not commit secrets (`.env`, tokens, credentials).
+- Review destructive git (`reset --hard`, force-push) before running; respect
+  shell hooks.
+- Do not weaken CI or skip hooks 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 Code 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:
+**`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**,
+**`.mavis/team/conventions.md`**, and/or **`.opencode/team/conventions.md`**
+(fill after init; not overwritten on every dogfood sync when already present).
+
+## 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 is the mechanism; this `MANDATORY`
+section is the reinforcement.