@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/cursor/nuxt/skills/code-review/SKILL.md

@@ -7,7 +7,7 @@ description: Reviews pull requests, merge requests, git diffs, and branch change
 
 ## Inputs
 
-Use the local repository as the source of truth: `git status`, `git diff`, task artifacts under `.cursor/team/tasks/<slug>/` when present, and opened files. Do not invent hosting metadata such as labels, CI status, or reviewers.
+Use the local repository as the source of truth: `git status`, `git diff`, task artifacts under `.ai.local/team/tasks/<slug>/` when present, and opened files. Do not invent hosting metadata such as labels, CI status, or reviewers.
 
 ## Review Order
 
@@ -31,7 +31,7 @@ Lead with findings ordered by severity. Required shape (also in `code-review-mr`
 - End with a verdict line: **`Safe to merge | needs changes | reject`**.
 - If there are no findings, say so and call out remaining test or validation risk.
 
-For agent team tasks, write `.cursor/team/tasks/<slug>/review.md` and upsert the owned terminal receipt (`completed` or `changes_requested`); do not mutate `status.json`.
+For agent team tasks, write `.ai.local/team/tasks/<slug>/review.md` and upsert the owned terminal receipt (`completed` or `changes_requested`); do not mutate `status.json`.
 
 ## Receiving review feedback
 

package/presets/cursor/nuxt/skills/debug-investigation/SKILL.md

@@ -34,7 +34,7 @@ If **three** fix attempts fail, or the same symptom returns after two supposed f
 
 ### Artifacts
 
-For agent team tasks, write `.cursor/team/tasks/<slug>/debug-report.md` with:
+For agent team tasks, write `.ai.local/team/tasks/<slug>/debug-report.md` with:
 
 - Reproduction steps or evidence source.
 - Root cause.

package/presets/cursor/nuxt/skills/mockup-review/SKILL.md

@@ -26,4 +26,4 @@ Load requestable rule `mockup-review` and follow its review dimensions, node cap
 
 ## Output
 
-Write `.cursor/team/tasks/<slug>/mockup-review.md` and upsert manifest entry id `mockup-review` (producer `mockup-reviewer`). Receipt mapping is in the agent prompt.
+Write `.ai.local/team/tasks/<slug>/mockup-review.md` and upsert manifest entry id `mockup-review` (producer `mockup-reviewer`). Receipt mapping is in the agent prompt.

package/presets/cursor/nuxt/skills/spec-discovery/SKILL.md

@@ -13,7 +13,7 @@ Load **`product-specs`** (and **`product-specs-authoring`** after this skill if
 
 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 `.cursor/team/tasks/<slug>/.memlog.md` (append-only). Do **not** mutate `status.json` / `metrics.json`.
+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`.
@@ -49,7 +49,7 @@ Sources: AC / user / UI copy / labeled code inference / research path. Unsourced
 
 ## Memlog
 
-Path: `.cursor/team/tasks/<slug>/.memlog.md`. Chronological `## YYYY-MM-DD` headings. Optional tags: `decision`, `assumption`, `override`, `event`, `claim`.
+Path: `.ai.local/team/tasks/<slug>/.memlog.md`. Chronological `## YYYY-MM-DD` headings. Optional tags: `decision`, `assumption`, `override`, `event`, `claim`.
 
 ## Forbidden
 

package/presets/cursor/nuxt/skills/technical-retro/SKILL.md

@@ -7,7 +7,7 @@ description: Facilitates technical retrospectives for tasks, sprints, incidents,
 
 ## Inputs
 
-Ask for missing period, focus, task slug, participants, or format constraints. If a slug is provided, read `.cursor/team/tasks/<slug>/` artifacts and local git status/diff. Do not invent facts not present in artifacts or the user's message.
+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
 
@@ -47,7 +47,7 @@ Severity: **high** (explicit correction / large waste) · **med** · **low**. Co
 
 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 `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, or **`.cursor/team/conventions.md`** (prefer conventions for project gotchas)
+- Proposed change to `.cursor/rules/`, `.cursor/agents/`, `.cursor/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)
 

package/presets/cursor/nuxt/skills/unit-testing/SKILL.md

@@ -15,7 +15,7 @@ Follow **`tests-unit.mdc`** (Cursor) or **`rules/testing/tests-unit.md`** (Claud
 
 ## Planner
 
-Write or update `.cursor/team/tasks/<slug>/unit-test-plan.md` (or `.claude/team/...`).
+Write or update `.ai.local/team/tasks/<slug>/unit-test-plan.md` (or `.ai.local/team/...`).
 
 Each scenario needs a Russian `it()` title (capital letter after each sentence). Cover mappers, Pinia actions, client behavior branches, and component interactions per AC.
 

package/presets/cursor/nuxt/skills/ux-design/SKILL.md

@@ -33,4 +33,4 @@ Load requestable rule `ux-design` and follow its required-signal vs advisory rul
 
 ## Output
 
-Write `.cursor/team/tasks/<slug>/ux-design.md` and append that path to the **`analysis`** manifest entry (`authoritativePaths` / `evidencePaths`). Do **not** create a new producer row. Receipt stays on `analysis`: required `INCOMPLETE` (missing primary flows or empty/error/loading matrix) → DoR not met; advisory `INCOMPLETE` → notes only. Never copy the mockup FAIL-only hook.
+Write `.ai.local/team/tasks/<slug>/ux-design.md` and append that path to the **`analysis`** manifest entry (`authoritativePaths` / `evidencePaths`). Do **not** create a new producer row. Receipt stays on `analysis`: required `INCOMPLETE` (missing primary flows or empty/error/loading matrix) → DoR not met; advisory `INCOMPLETE` → notes only. Never copy the mockup FAIL-only hook.

package/presets/cursor/nuxt/skills/write-adr/SKILL.md

@@ -15,7 +15,7 @@ On-demand skill for durable architecture decisions. Stack-agnostic sections —
 
 ## Template
 
-Create (or append) a short markdown ADR in the repo’s agreed location (e.g. `docs/adr/`, `.cursor/team/`, wiki). Suggested filename: `NNNN-short-title.md`.
+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>
@@ -37,5 +37,5 @@ Related PRs, issues, rules, prior ADRs, diagrams.
 
 - Prefer one decision per ADR.
 - Keep Context factual; Decision imperative and short.
-- Link living gotchas to `team/conventions.md` when the decision becomes a recurring local pattern.
+- 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/cursor/nuxt/team/README.md

@@ -1,36 +1,28 @@
 # Agent team artifacts
 
-Artifact directory for the Cursor “agent team” pipeline.
+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
 
 ```
-.cursor/team/
-  active-task.json
-  fixtures/                  # pipeline profile examples (feature-full, feature-light, bugfix-standard)
-  tasks/
-    <slug>/
-      pipeline.json
-      status.json
-      metrics.json             # schema-v1 append-only event ledger (see Local metrics ledger)
-      brief.md
-      decomposition.md
-      debug-report.md          # fixApplied: true/false
-      validation-report.md     # build-verifier: PASS | FAIL
-      architecture.md
-      migration-plan.md
-      ci-report.md
-      a11y-review.md
-      perf-report.md
-      security-review.md
-      api-contract-review.md
-      unit-test-plan.md
-      documentation.md
-      review.md
-      .memlog.md             # append-only agent notes (optional)
+.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)
 ```
 
-## pipeline.json schema
+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
 {
@@ -42,8 +34,7 @@ Artifact directory for the Cursor “agent team” pipeline.
     { "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" },
-    { "agent": "qa-tester", "label": "E2E", "scope": "e2e-only" }
+    { "agent": "code-reviewer", "label": "Code review" }
   ],
   "humanGates": ["after:task-analyst"],
   "autoChain": true,
@@ -51,98 +42,36 @@ Artifact directory for the Cursor “agent team” pipeline.
 }
 ```
 
-### Step fields
-
-| Field | Description |
-|-------|-------------|
-| `agent` | kebab-case name or array when `parallel: true` |
-| `label` | Human-readable step name |
-| `scope` | Passed to agents (e.g. `unit-in-dev`, `e2e-only`) |
+| 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` |
-| `parallel` | Invoke all `agent` values in one parent turn |
-
-Optional top-level **`specMode`:** `consume` | `generate` | `none` (router echo; `brief.md` `## Spec mode` wins).
-
-## status.json (pipeline mode)
-
-```json
-{
-  "slug": "order-history-date-filter",
-  "intent": "feature",
-  "pipelineIndex": 0,
-  "currentAgent": "task-analyst",
-  "phase": "executing",
-  "state": "in_progress",
-  "awaitingHumanGate": false,
-  "retryAfterFix": null,
-  "activeAttempts": {},
-  "lastCompletedAttempt": null,
-  "parallelCompleted": [],
-  "parallelOutcomes": {},
-  "updatedAt": "2026-05-29T12:00:00.000Z"
-}
-```
-
-### phase
-
-Prefer **`executing`** for pipeline mode. Legacy: `analysis`, `development`, `review`, `testing`, `done`.
+| `model` | optional `cheap` \| `standard` \| `strong` |
+| `specMode` | `consume` \| `generate` \| `none` — `brief.md` `## Spec mode` wins |
 
-### state
+## status.json
 
-| Value | Description |
-|-------|-------------|
-| `in_progress` | Current step running |
-| `completed` | Current step finished |
-| `awaiting_approval` | Human gate; use `/task-continue` |
-| `changes_requested` | Reviewer requires fixes |
-| `validation_failed` | build-verifier failed |
-| `approved` | Legacy continue |
+Prefer `phase: executing`. States: `in_progress`, `completed`, `awaiting_approval` (`/task-continue`), `changes_requested`, `validation_failed`.
 
-## Workflow entry
+## Commands
 
 ```bash
-/task <task description>
+/task <description>
 /task-continue <slug>
 /technical-retro <slug>
 ```
 
-## Creating task dirs
-
-Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook owns `status.json` lifecycle; parent may only create a minimal bootstrap if missing. Do **not** use Shell `mkdir -p` — Cursor’s default sandbox returns `Operation not permitted` (especially for repos on macOS Desktop/Documents).
-
-## Git
-
-Commit task artifacts if you want them to survive `ai-rules clean cursor`. Or copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
-
-## specMode, applyReadiness, memlog
-
-- **`specMode`:** `consume` | `generate` | `none` — primary in `brief.md` `## Spec mode`; optional top-level `pipeline.json` `specMode`. `none` skips INDEX/author mode (spike/research).
-- **`applyReadiness`:** YAML frontmatter on developer `implementation.md`; JSON-shaped `{ "state": "blocked"|"ready"|"all_done", "contextFiles": [] }` on the analyst receipt (analyst may emit `blocked` pre-gate). See `agent-artifact-contracts`.
-- **Memlog:** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/team/tasks/<slug>/.memlog.md`) — append-only, agent-written; `/task-continue` may read. Hook does not parse it. Example: `fixtures/memlog.example.md`.
-
-## Artifact manifest and receipts
-
-Each slug stores one context index at `.cursor/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.
-
-Producer/consumer rules:
-
-- Read the manifest first and use only the authoritative inputs needed by the current step; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` when it is missing or stale, and report that gap.
-- Producers upsert only their stable entry IDs, preserve foreign entries, and finish with `completed`, `blocked`, `changes_requested`, or `validation_failed` receipt evidence.
-- The router owns `pipeline.json` and its routing entry; analyst, developer, verifier, and reviewer own their named outputs and receipts. Consumers do not edit another producer's receipt.
-- Agents do not mutate `status.json` or `metrics.json`. The orchestration runtime/hook is their single writer. Parallel receipt merges are serialized by the parent/orchestrator.
-
-## Local metrics ledger
-
-`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. Policy SoT: `presets/_shared/core/agent-team/agent-task-metrics.md`. The orchestration runtime writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
-
-`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic; `parallelOutcomes` holds per-agent outcomes for the current parallel join until the step advances. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
-
-After a human gate, `/task-continue` closes wait via the installed hook (do not hand-edit `pipelineIndex` first):
+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 .cursor/hooks/chain-team-phases.sh
 ```
 
-That appends `human_gate_ended` before the next `attempt_started`. Claude twins use the same payload against `.claude/hooks/chain-team-phases.sh`. Other installable stacks ship the same ledger contract in their `team/README.md`.
+Same JSON on Claude, Mavis, or OpenCode: `bash .<tool>/hooks/chain-team-phases.sh`.
+
+## Contracts
 
-Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .cursor/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts. For retros, see `/technical-retro` → **Metrics evidence**.
+- 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/cursor/php-hexagonal/AGENTS.md

@@ -20,11 +20,11 @@
 npx @bonesofspring/ai-rules init cursor --preset php-hexagonal
 ```
 
-Copies rules/agents/hooks/skills/commands/team + `REPO_AGENTS.md` → root `AGENTS.md`.
+Copies rules/agents/hooks/skills/commands + seeds `.ai.local/team/` + `REPO_AGENTS.md` → root `AGENTS.md`.
 
 ## Inventory
 
-- **21 agents** — see `agents/README.md` (no a11y / Playwright / XCUITest)
+- **22 agents** — see `agents/README.md` (no a11y / Playwright / XCUITest)
 - **10 skills** — `feature-delivery`, `spec-authoring`, `spec-discovery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`
 - **3 commands** — `/task`, `/task-continue`, `/technical-retro`
 

package/presets/cursor/php-hexagonal/README.md

@@ -1,26 +1,9 @@
-# Preset `php-hexagonal` (Cursor)
+# PHP hexagonal preset (Cursor)
 
-Installable Cursor preset for **PHP hexagonal** services (PSR / Composer-first; Laravel & Symfony as documented variants).
+PSR / Composer hexagonal PHP (Laravel and Symfony as documented variants). For a Laravel app prefer `--preset php-laravel`.
 
 ```bash
 npx @bonesofspring/ai-rules init cursor --preset php-hexagonal
 ```
 
-## Layout
-
-| Path | Role |
-|------|------|
-| `rules/*.mdc` | Cursor SoT (34 stems); always-on trio ≤140 lines |
-| `agents/` | 21 agents + README (no a11y / Playwright / XCUITest) |
-| `skills/` | 8 skills + README |
-| `commands/` | 5 slash commands |
-| `team/` | conventions + fixtures (`feature-full`, `feature-light`, `bugfix-standard`) |
-| `hooks/` + `hooks.json` | Shell guard + team chain (byte-forked) — **Cursor-only** |
-| `REPO_AGENTS.md` | → consumer root `AGENTS.md` |
-| `AGENTS.md` | Cursor quick-start map + dogfood scenarios |
-| `BUGBOT.md` | Bugbot review priorities (PHP) — **Cursor-only** |
-| `MCP.md` / `mcp.json` | Context7 only |
-
-**Platform asymmetry:** `BUGBOT.md` and `hooks.json` ship only on Cursor. Claude twin uses `CLAUDE.md` (no `hooks.json` / no `BUGBOT.md`).
-
-Claude twin: `presets/claude/php-hexagonal/`. Contribution: `docs/PRESET-CONTRIBUTION.md`.
+`team/` seeds **`.ai.local/team/`**. No Playwright / XCUITest / a11y agents. Twin: `presets/claude/php-hexagonal/`. Dogfood: `dogfood/php-hexagonal`. Catalog: [`rules/README.md`](./rules/README.md).

package/presets/cursor/php-hexagonal/REPO_AGENTS.md

@@ -1,18 +1,34 @@
 # PHP — agent instructions
 
-Cross-tool repo-root guide for the **php-hexagonal** preset (PSR / Composer-first). Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`, `.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
 
 ## Cross-tool setup
 
-- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, or other).
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, Mavis, OpenCode, or other).
+- All four platforms ship **the same** root file. `init` overwrites it; content does not depend on which tool ran last.
+- Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md` — use them when that tool is installed.
 - Install:
 
 ```bash
-npx @bonesofspring/ai-rules init cursor --preset php-hexagonal
-npx @bonesofspring/ai-rules init claude --preset php-hexagonal
+npx @bonesofspring/ai-rules init multi --preset php-hexagonal
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`).
+Per-tool: `init cursor|claude|mavis|opencode --preset php-hexagonal`. `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/php-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/php-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 / verify)
 
@@ -36,11 +52,22 @@ Static analysis / format — only tools already configured in the repo/CI.
 
 | Tool | Map |
 |------|-----|
-| Cursor | `.cursor/AGENTS.md` |
-| Claude Code | `.claude/CLAUDE.md` |
+| Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
+| Mavis | `.mavis/AGENTS.md` (optional if Mavis not installed) |
+| OpenCode | `.opencode/AGENTS.md` (optional if OpenCode not installed) |
 
-Rules: `.cursor/rules/` or `.claude/rules/`. Integration tests: `integration-test-*` (never Playwright/XCUITest).
+Rules: `.cursor/rules/`, `.claude/rules/`, `.mavis/rules/`, or `.opencode/rules/`.
+Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/skills/`.
 
 ## Living conventions
 
-Gotchas and team decisions: `.cursor/team/conventions.md` and/or `.claude/team/conventions.md` (fill after init; fixtures ship with the preset).
+Gotchas, local patterns, and team decisions: **`.ai.local/conventions.md`** (fill after init; `init` does not overwrite it).
+
+## Local overlay (`.ai.local/`) — MANDATORY
+
+A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
+
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
+
+Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.

package/presets/cursor/php-hexagonal/agents/README.md

@@ -26,7 +26,7 @@ Role subagents for the Cursor agent-team pipeline (PHP hexagonal).
 
 ## Frontmatter `readonly`
 
-All agents use **`readonly: false`** (need writes under `.cursor/team/**`). Production restrictions live in the prompt body.
+All agents use **`readonly: false`** (need writes under `.ai.local/team/**`). Production restrictions live in the prompt body.
 
 ## Model matrix (frontmatter `model`)
 

package/presets/cursor/php-hexagonal/agents/api-contract-reviewer.md

@@ -15,7 +15,7 @@ Review **HTTP/gRPC contract alignment** for PHP hexagonal services.
 
 ## Output
 
-`.cursor/team/tasks/<slug>/api-contract-review.md` — gaps, severity, suggested fixes (no code edits).
+`.ai.local/team/tasks/<slug>/api-contract-review.md` — gaps, severity, suggested fixes (no code edits).
 
 ## Non-scope
 

package/presets/cursor/php-hexagonal/agents/build-verifier.md

@@ -12,7 +12,7 @@ You are the build verifier for **PHP hexagonal** services (and for **ai-rules pr
 1. Detect Composer from `composer.json` / `composer.lock`; prefer Composer scripts when present.
 2. Run from module/project root: `composer test` or `vendor/bin/phpunit` (or Pest if that is the repo default / CI).
 3. If present in **repo or CI**: formatter + static analysis (PHP-CS-Fixer, Pint, PHPStan, Psalm, or project-equivalent) per `php-tooling` / `post-change-test`. Mirror CI gates locally when configs/scripts exist; do **not** invent a tool the repo does not use.
-4. Write `.cursor/team/tasks/<slug>/validation-report.md` with commands + results.
+4. Write `.ai.local/team/tasks/<slug>/validation-report.md` with commands + results.
 5. On failure: emit receipt outcome `validation_failed` — do **not** patch production code (developer retries).
 
 **Never** require Playwright, XCUITest, `lint:js`/`lint:css`, `xcodebuild`/`SwiftLint`, `mvn`, or `gradlew` as the PHP gate.
@@ -36,7 +36,7 @@ Hard gates for the **php-hexagonal** stack (and peers):
 | Gate | FAIL when |
 |------|-----------|
 | **twin-map** | `php-hexagonal` missing from `STACKS`, or Cursor↔Claude orphan/missing twins |
-| **token-budget** | Cursor `alwaysApply` ≠ 3 or Claude session-start (excl. README) ≠ 3, or trio body sum > 140 |
+| **token-budget** | Cursor/Claude always-on count outside 3–5 (extra slots = `ai-local-overlay`), or body sum > 200 |
 | **leakage** | `PHP_FORBIDDEN_*` hits (Playwright/XCUITest/`lint:js`/`accessibility-reviewer` / `mockup-reviewer` as required handoffs) |
 | **chain fork** | `hooks/chain-team-phases.sh` byte-identical to **next**, **ios-swift**, **go**, **java**, **mcp-ts**, or **php-laravel** (same platform) |
 
@@ -58,7 +58,7 @@ Document PASS/FAIL in `validation-report.md`.
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.
 - **Owned outputs:** `validation-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `validation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `validation_failed`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/php-hexagonal/agents/code-reviewer.md

@@ -5,14 +5,14 @@ readonly: false
 model: fast
 ---
 
-You are a senior PHP hexagonal code reviewer. Write only review artifacts under `.cursor/team/**`; do not modify production code.
+You are a senior PHP hexagonal code reviewer. Write only review artifacts under `.ai.local/team/**`; do not modify production code.
 
 ## Inputs
 
-1. `.cursor/team/tasks/<slug>/brief.md`
-2. `.cursor/team/tasks/<slug>/decomposition.md`
+1. `.ai.local/team/tasks/<slug>/brief.md`
+2. `.ai.local/team/tasks/<slug>/decomposition.md`
 3. Git diff (`git diff`, `git status`)
-4. `.cursor/team/tasks/<slug>/validation-report.md` if present
+4. `.ai.local/team/tasks/<slug>/validation-report.md` if present
 
 Apply skill `code-review` and `code-review-mr.mdc`. Weigh `architecture-boundaries.mdc`, `domain-layer.mdc`, `application-usecases.mdc`, `ports-interfaces.mdc`, `adapters-driving.mdc`, `adapters-driven.mdc`, `composition-root.mdc`, `php-conventions.mdc`, `tests-unit.mdc`, `tests-integration.mdc`, `security-php.mdc`.
 
@@ -37,7 +37,7 @@ You **issue** reviews. Implementers acting on your findings must verify each ite
 
 ## Artifact
 
-Write `.cursor/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update the owned terminal receipt accordingly.
+Write `.ai.local/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update the owned terminal receipt accordingly.
 
 ## Design guidance
 
@@ -45,7 +45,7 @@ Write `.cursor/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANG
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation, validation evidence, and the scoped git diff.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation, validation evidence, and the scoped git diff.
 - **Owned outputs:** `review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/php-hexagonal/agents/debugger.md

@@ -20,7 +20,7 @@ Use the **`debug-investigation` skill** for the investigation loop.
 - Xcode / lldb / Instruments as required path
 - Playwright browser debugging
 
-Write `.cursor/team/tasks/<slug>/debug-report.md`.
+Write `.ai.local/team/tasks/<slug>/debug-report.md`.
 
 
 ## 3-fix architecture gate

package/presets/cursor/php-hexagonal/agents/feature-developer.md

@@ -37,7 +37,7 @@ Implement PHP features following hexagonal boundaries.
 
 When editing ai-rules `presets/**/php-hexagonal/**`, keep Cursor/Claude twins in sync and preserve chain fork ≠ next/ios-swift/go/java/mcp-ts (see `preset-no-cross-stack-leakage`).
 
-Update `.cursor/team/tasks/<slug>/implementation.md` and the owned implementation receipt.
+Update `.ai.local/team/tasks/<slug>/implementation.md` and the owned implementation receipt.
 
 ## Design guidance
 
@@ -75,7 +75,7 @@ applyReadiness:
 
 **Code Map + Suggested Review Order:** when this WP spans **>1 layer or module**, add to `implementation.md` a Code Map (3–8 annotated paths) and Suggested Review Order lines `concern | path:line | ≤15 words`. Omit for single-file / single-layer WPs.
 
-**Memlog:** append implementation decisions to `.cursor/team/tasks/<slug>/.memlog.md` (append-only).
+**Memlog:** append implementation decisions to `.ai.local/team/tasks/<slug>/.memlog.md` (append-only).
 
 
 
@@ -86,7 +86,7 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
 - **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/php-hexagonal/agents/integration-test-generator.md

@@ -19,4 +19,4 @@ You are the **integration-test-generator** for PHP hexagonal services.
 
 ## Artifacts
 
-Write plans/results under `.cursor/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).
+Write plans/results under `.ai.local/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).

package/presets/cursor/php-hexagonal/agents/integration-test-healer.md

@@ -19,4 +19,4 @@ You are the **integration-test-healer** for PHP hexagonal services.
 
 ## Artifacts
 
-Write plans/results under `.cursor/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).
+Write plans/results under `.ai.local/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).

package/presets/cursor/php-hexagonal/agents/integration-test-planner.md

@@ -19,4 +19,4 @@ You are the **integration-test-planner** for PHP hexagonal services.
 
 ## Artifacts
 
-Write plans/results under `.cursor/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).
+Write plans/results under `.ai.local/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).

package/presets/cursor/php-hexagonal/agents/migration-specialist.md

@@ -13,7 +13,7 @@ You plan migrations for **PHP modules** (toolchain, deps, layout refactors). Do
 
 ## Deliverable
 
-Write `.cursor/team/tasks/<slug>/migration-plan.md`:
+Write `.ai.local/team/tasks/<slug>/migration-plan.md`:
 
 1. Current vs target (PHP version, Composer plugins, major deps).
 2. Phased steps with rollback.

package/presets/cursor/php-hexagonal/agents/openspec-author.md

@@ -22,8 +22,8 @@ If `openspec/` is absent in the repo, stop and report `blocked` with the message
 
 ## Inputs
 
-1. `.cursor/team/tasks/<slug>/{brief.md, decomposition.md, architecture.md}` (Claude: `.claude/team/tasks/<slug>/`).
-2. `.cursor/team/tasks/<slug>/artifact-manifest.json` — read first, consume `artifactInputIds`.
+1. `.ai.local/team/tasks/<slug>/{brief.md, decomposition.md, architecture.md}` (Claude: `.ai.local/team/tasks/<slug>/`).
+2. `.ai.local/team/tasks/<slug>/artifact-manifest.json` — read first, consume `artifactInputIds`.
 3. `openspec/config.yaml` — schema, context block, `rules.proposal | specs | design | tasks`. **Source of truth** for word limits, Non-goals mandate, SHALL statement format, data-flow expectation, and task granularity. Never fork.
 4. `openspec/specs/<capability>/spec.md` — surviving applied specs (the "as-is" target).
 5. `openspec/changes/archive/<YYYY-MM-DD>-<change-id>/` — prior decisions (D-1..) and open questions (OQ-1..) reusable across changes.
@@ -122,14 +122,14 @@ If `scope` carries multiple phases (e.g. `openspec:<change-id>:propose+apply`),
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and available architecture/migration/review artifacts.
-- **Owned outputs:** `openspec/changes/<change-id>/**` (proposal.md, design.md, tasks.md, .openspec.yaml, specs/<capability>/spec.md delta) plus the team slot `openspec-change.md` in `.cursor/team/tasks/<slug>/` when the orchestrator asks for a summary handoff. Preserve all foreign entries; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `openspec-change`).
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and available architecture/migration/review artifacts.
+- **Owned outputs:** `openspec/changes/<change-id>/**` (proposal.md, design.md, tasks.md, .openspec.yaml, specs/<capability>/spec.md delta) plus the team slot `openspec-change.md` in `.ai.local/team/tasks/<slug>/` when the orchestrator asks for a summary handoff. Preserve all foreign entries; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `openspec-change`).
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths under `openspec/changes/<change-id>/**`, attach `openspec validate <change-id> --type change --strict` exit code + deltas-only summary, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 
 ## Output
 
-When invoked directly (no pipeline), write the spec handoff at `.cursor/team/tasks/<slug>/openspec-change.md`:
+When invoked directly (no pipeline), write the spec handoff at `.ai.local/team/tasks/<slug>/openspec-change.md`:
 
 ```markdown
 # OpenSpec change: <change-id>

package/presets/cursor/php-hexagonal/agents/performance-auditor.md

@@ -15,7 +15,7 @@ Audit PHP performance risks on the task scope.
 
 ## Output
 
-`.cursor/team/tasks/<slug>/perf-report.md`. No production edits. Not Instruments/Xcode.
+`.ai.local/team/tasks/<slug>/perf-report.md`. No production edits. Not Instruments/Xcode.
 
 
 ## MCP usage

package/presets/cursor/php-hexagonal/agents/qa-tester.md

@@ -17,7 +17,7 @@ Ensure test coverage for the PHP task scope.
 - Introduce Playwright/XCUITest
 - Put SQL into use-case unit tests
 
-Coordinate with existing plans under `.cursor/team/tasks/<slug>/`.
+Coordinate with existing plans under `.ai.local/team/tasks/<slug>/`.
 
 ## Design guidance