@bonesofspring/ai-rules 0.2.24 → 0.2.26

package/presets/claude/android-kotlin/rules/tooling-and-review/preset-twin-sync.md

@@ -4,7 +4,7 @@ paths:
   - packages/ai-rules/presets/**/*
   - .claude/**/*
   - .cursor/rules/**/*
-  - .cursor/team/tasks/**/*
+  - .ai.local/team/tasks/**/*
 ---
 
 <!-- shared-core: meta/preset-twin-sync.md -->
@@ -32,7 +32,16 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 
 | Stack | Cursor SoT | Mavis derive | Manifest |
 |-------|------------|--------------|----------|
-| `next` | `presets/cursor/next/**` | `presets/mavis/next/**` via `generate-mavis-next.mjs` | **Required** `adapter-map.json` |
+| `next` | `presets/cursor/next/**` | `presets/mavis/next/**` via `generate-mavis.mjs --stack next` | **Required** `adapter-map.json` |
+| `nuxt` | `presets/cursor/nuxt/**` | `presets/mavis/nuxt/**` via `generate-mavis.mjs --stack nuxt` | **Required** `adapter-map.json` |
+| `svelte` | `presets/cursor/svelte/**` | `presets/mavis/svelte/**` via `generate-mavis.mjs --stack svelte` | **Required** `adapter-map.json` |
+| `ios-swift` | `presets/cursor/ios-swift/**` | `presets/mavis/ios-swift/**` via `generate-mavis.mjs --stack ios-swift` | **Required** `adapter-map.json` |
+| `android-kotlin` | `presets/cursor/android-kotlin/**` | `presets/mavis/android-kotlin/**` via `generate-mavis.mjs --stack android-kotlin` | **Required** `adapter-map.json` |
+| `go` | `presets/cursor/go/**` | `presets/mavis/go/**` via `generate-mavis.mjs --stack go` | **Required** `adapter-map.json` |
+| `java` | `presets/cursor/java/**` | `presets/mavis/java/**` via `generate-mavis.mjs --stack java` | **Required** `adapter-map.json` |
+| `mcp-ts` | `presets/cursor/mcp-ts/**` | `presets/mavis/mcp-ts/**` via `generate-mavis.mjs --stack mcp-ts` | **Required** `adapter-map.json` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/**` | `presets/mavis/php-hexagonal/**` via `generate-mavis.mjs --stack php-hexagonal` | **Required** `adapter-map.json` |
+| `php-laravel` | `presets/cursor/php-laravel/**` | `presets/mavis/php-laravel/**` via `generate-mavis.mjs --stack php-laravel` | **Required** `adapter-map.json` |
 
 Mavis is a **third platform adapter**, not a Claude-style topic twin:
 
@@ -40,13 +49,22 @@ Mavis is a **third platform adapter**, not a Claude-style topic twin:
 _shared/core  →  cursor/<stack>  →  mavis/<stack>
 ```
 
-Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
+Regenerate with `node packages/ai-rules/scripts/generate-mavis.mjs --stack <stack>`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
 
 ## OpenCode derivation (not a Claude twin)
 
 | Stack | Cursor SoT | OpenCode derive | Manifest |
 |-------|------------|-----------------|----------|
-| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode-next.mjs` | **Required** `adapter-map.json` |
+| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode.mjs --stack next` | **Required** `adapter-map.json` |
+| `nuxt` | `presets/cursor/nuxt/**` | `presets/opencode/nuxt/**` via `generate-opencode.mjs --stack nuxt` | **Required** `adapter-map.json` |
+| `svelte` | `presets/cursor/svelte/**` | `presets/opencode/svelte/**` via `generate-opencode.mjs --stack svelte` | **Required** `adapter-map.json` |
+| `ios-swift` | `presets/cursor/ios-swift/**` | `presets/opencode/ios-swift/**` via `generate-opencode.mjs --stack ios-swift` | **Required** `adapter-map.json` |
+| `android-kotlin` | `presets/cursor/android-kotlin/**` | `presets/opencode/android-kotlin/**` via `generate-opencode.mjs --stack android-kotlin` | **Required** `adapter-map.json` |
+| `go` | `presets/cursor/go/**` | `presets/opencode/go/**` via `generate-opencode.mjs --stack go` | **Required** `adapter-map.json` |
+| `java` | `presets/cursor/java/**` | `presets/opencode/java/**` via `generate-opencode.mjs --stack java` | **Required** `adapter-map.json` |
+| `mcp-ts` | `presets/cursor/mcp-ts/**` | `presets/opencode/mcp-ts/**` via `generate-opencode.mjs --stack mcp-ts` | **Required** `adapter-map.json` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/**` | `presets/opencode/php-hexagonal/**` via `generate-opencode.mjs --stack php-hexagonal` | **Required** `adapter-map.json` |
+| `php-laravel` | `presets/cursor/php-laravel/**` | `presets/opencode/php-laravel/**` via `generate-opencode.mjs --stack php-laravel` | **Required** `adapter-map.json` |
 
 OpenCode is a **fourth platform adapter** with a **native** install root (`.opencode/`), not a Claude-style topic twin and not an owned overlay like `.mavis/`:
 
@@ -54,7 +72,7 @@ OpenCode is a **fourth platform adapter** with a **native** install root (`.open
 _shared/core  →  cursor/<stack>  →  opencode/<stack>
 ```
 
-Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
+Regenerate with `node packages/ai-rules/scripts/generate-opencode.mjs --stack <stack>`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
 
 ## Same-PR checklist
 
@@ -62,8 +80,8 @@ Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; val
 2. Update Claude twin: body + `paths:` (from Cursor `globs:` / requestable triggers); drop `alwaysApply`.
 3. Update mapping table row if stem/path changed.
 4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
-5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`).
-6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`).
+5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`).
+6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`).
 
 ## Twin depth
 
@@ -84,7 +102,7 @@ Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; val
 - **php-hexagonal:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts; mapping table required).
 - **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
 - **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
-- **mavis/next:** `cursor/next` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
-- **opencode/next:** `cursor/next` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
+- **mavis/<stack>:** `cursor/<stack>` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
+- **opencode/<stack>:** `cursor/<stack>` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/claude/android-kotlin/rules/tooling-and-review/technical-retro.md

@@ -2,7 +2,7 @@
 description: Agent role for a technical retrospective (retro) of the team / sprint. On-demand — prefer the /technical-retro slash command.
 paths:
   - .claude/commands/**/*
-  - .claude/team/**/*
+  - .ai.local/team/**/*
 ---
 
 <!-- shared-core: review/technical-retro.md -->

package/presets/claude/android-kotlin/rules/tooling-and-review/ux-design.md

@@ -2,7 +2,7 @@
 description: Behavioral UX design checklist (IA, flows, states). On-demand — load via task-analyst / skill ux-design.
 paths:
   - .claude/commands/**/*
-  - .claude/team/**/*
+  - .ai.local/team/**/*
 ---
 
 <!-- shared-core: review/ux-design.md -->

package/presets/claude/android-kotlin/rules/ui-and-accessibility/viewmodels.md

@@ -6,7 +6,7 @@ paths:
 
 # State and ViewModels
 
-- Follow the repo’s **MVI / unidirectional** pattern on the project ViewModel base (name lives in consumer `team/conventions.md`).
+- Follow the repo’s **MVI / unidirectional** pattern on the project ViewModel base (name lives in consumer `.ai.local/conventions.md`).
 - Single source of UI state (StateFlow / immutable state holder); reduce via pure updates where practical.
 - Expose intents/events for user actions; do not mutate state from composables directly.
 - Side effects (navigation, one-shots) follow existing effect channels — do not invent a parallel bus.

package/presets/claude/android-kotlin/skills/ci-investigation/SKILL.md

@@ -18,7 +18,7 @@ description: Investigates failing CI checks on PRs and branches — ./gradlew, k
 
 ## Artifact
 
-Write `ci-report.md` under the task slug folder (`.claude/team/tasks/<slug>/`):
+Write `ci-report.md` under the task slug folder (`.ai.local/team/tasks/<slug>/`):
 
 - Failed check name and log excerpt
 - Root cause classification

package/presets/claude/android-kotlin/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 `.claude/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
 
@@ -32,7 +32,7 @@ Lead with findings ordered by severity. Required shape (also in `code-review`):
 - 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 `.claude/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/claude/android-kotlin/skills/debug-investigation/SKILL.md

@@ -45,7 +45,7 @@ If **three** fix attempts fail, or the same symptom returns after two supposed f
 
 ### Artifacts
 
-For agent team tasks, write `.claude/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/claude/android-kotlin/skills/feature-delivery/SKILL.md

@@ -28,7 +28,7 @@ Implement only the current AC / decomposition task. Clarify ambiguity before cod
 
 ## Preset packaging note
 
-When editing **ai-rules android-kotlin preset** sources (agents, hooks, rules) rather than an app Feature: keep Cursor and Claude trees in sync where applicable, and **fork / verify hook handoffs** (`hooks/chain-team-phases.sh`, guard scripts, team path conventions) so Cursor (`.cursor/team`) and Claude (`.claude/team`) do not regress against each other or against the next preset templates.
+When editing **ai-rules android-kotlin preset** sources (agents, hooks, rules) rather than an app Feature: keep Cursor and Claude trees in sync where applicable, and **fork / verify hook handoffs** (`hooks/chain-team-phases.sh`, guard scripts, team path conventions) so Cursor (`.ai.local/team`) and Claude (`.ai.local/team`) do not regress against each other or against the next preset templates.
 
 ## Handoff
 

package/presets/claude/android-kotlin/skills/mockup-review/SKILL.md

@@ -26,4 +26,4 @@ Load requestable rule `mockup-review` and follow its review dimensions, node cap
 
 ## Output
 
-Write `.claude/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/claude/android-kotlin/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 `.claude/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: `.claude/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/claude/android-kotlin/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 `.claude/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 `.claude/rules/`, `.claude/agents/`, `.claude/skills/`, or **`.claude/team/conventions.md`** (prefer conventions for project gotchas)
+- Proposed change to `.claude/rules/`, `.claude/agents/`, `.claude/skills/`, or **`.ai.local/conventions.md`** (prefer conventions for project gotchas)
 - One concrete snippet or file path
 - Whether it belongs in session-start vs `paths:` vs skill vs conventions (see `PRESET-CONTRIBUTION` → Building blocks)
 

package/presets/claude/android-kotlin/skills/unit-testing/SKILL.md

@@ -15,7 +15,7 @@ Follow `testing/unit.md` (Cursor `.mdc` / Claude `testing/unit.md` depending on
 
 ## Planner
 
-Write or update `.claude/team/tasks/<slug>/unit-test-plan.md`.
+Write or update `.ai.local/team/tasks/<slug>/unit-test-plan.md`.
 
 Each scenario needs a Russian `test` / `@Test` title (capital letter after each sentence). Cover mappers, use cases, ViewModel state branches, and mocked client/repository behavior per AC.
 

package/presets/claude/android-kotlin/skills/ux-design/SKILL.md

@@ -33,4 +33,4 @@ Load requestable rule `ux-design` and follow its required-signal vs advisory rul
 
 ## Output
 
-Write `.claude/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/claude/android-kotlin/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/claude/android-kotlin/team/README.md

@@ -1,62 +1,77 @@
-# Agent team artifacts (android-kotlin)
+# Agent team artifacts
 
-Artifact directory for the Android 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
 
 ```
-.claude/team/
-  active-task.json
-  fixtures/
+.ai.local/team/
+  README.md
+  active-task.json           # current slug pointer (runtime)
+  fixtures/                  # pipeline profile examples
   tasks/<slug>/
-    pipeline.json
-    status.json
-    brief.md
-    decomposition.md
-    .memlog.md
-    …
+    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)
 ```
 
-## Fixtures
-
-| Fixture | Notes |
-|---------|-------|
-| `feature-full.json` | Full profile; QA scope `e2e-only` = **Android instrumentation** |
-| `feature-light.json` | developer → build-verifier |
-| `bugfix-standard.json` | debugger → developer (skipIf) → verifier → reviewer |
-
-### `skipped[]` in fixtures
-
-`pipeline.json` / fixture `skipped` is **documentation of forbidden or non-applicable template stems** from other stacks (Playwright, XCUITest, JVM `integration-test-*`) — **not** agents that ran and were skipped at runtime, and **not** steps to schedule. Routers must never promote these stems into `steps[]`. For UI-test-only intents use `instrumentation-test-*`.
-
-**Never** schedule Playwright-only steps without skip rationale. Use `instrumentation-test-*` for UI-test-only intents.
-
-## Creating task dirs
-
-Bootstrap `tasks/<slug>/` by **writing** artifacts (Write tool), not Shell `mkdir`. Cursor sandbox → `Operation not permitted` otherwise (worse on Desktop/Documents).
-
+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": []
+}
+```
 
-## specMode, applyReadiness, memlog
+| 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 |
 
-- **`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`.
+## status.json
 
-## Artifact manifest and receipts
+Prefer `phase: executing`. States: `in_progress`, `completed`, `awaiting_approval` (`/task-continue`), `changes_requested`, `validation_failed`.
 
-Each slug stores one context index at `.claude/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.
+## Commands
 
-Producer/consumer rules:
+```bash
+/task <description>
+/task-continue <slug>
+/technical-retro <slug>
+```
 
-- 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.
+After a human gate, close wait via the **installed** hook (do not hand-edit `pipelineIndex`):
 
-## Local metrics ledger
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .claude/hooks/chain-team-phases.sh
+```
 
-`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. 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.
+Same JSON on Claude, Mavis, or OpenCode: `bash .<tool>/hooks/chain-team-phases.sh`.
 
-`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`.
+## Contracts
 
-Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .claude/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts.
+- 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/claude/go/README.md

@@ -1,38 +1,9 @@
-# Go hexagonal preset (Claude)
+# Go hexagonal preset (Claude Code)
 
-Derived twin of `presets/cursor/go/`. Mapping: [`rules/README.md`](./rules/README.md).
-
-## Install
+Twin of `presets/cursor/go/`.
 
 ```bash
 npx @bonesofspring/ai-rules init claude --preset go
 ```
 
-| Path | Contents |
-|------|------------|
-| `CLAUDE.md` | Thin session entry |
-| `rules/**` | Topic `.md` + `paths:` (session-start = 3) |
-| `agents/**` | **21** roles (+ `codebase-analyzer`) |
-| `skills/**` | **7** skills (incl. `integration-testing`) |
-| `commands/**` | task, task-continue, technical-retro |
-| `hooks/**` | guard-shell + chain-team-phases |
-| `team/**` | fixtures + README |
-| `mcp.json` + `MCP.md` | Context7 + Figma → project-root `.mcp.json` |
-
-## Session-start (exactly 3, no `paths:`)
-
-`stack/go-app-core`, `architecture/boundaries`, `tooling-and-review/code-quality`.
-
-## Preset taxonomy & contributing
-
-- **Layers:** Core → Stack → Platform — [`../../_shared/README.md`](../../_shared/README.md)
-- **Contribution guide:** [`../../../docs/PRESET-CONTRIBUTION.md`](../../../docs/PRESET-CONTRIBUTION.md)
-- **Core→stack / Cursor map:** [`rules/README.md`](./rules/README.md)
-
-## Sync with Cursor
-
-SoT = `presets/cursor/go/`. Update this twin **in the same PR** when Cursor changes.
-
-## Cross-tool root AGENTS
-
-`REPO_AGENTS.md` → project-root `AGENTS.md` on init. Living conventions: `team/conventions.md`. Skill `write-adr` on-demand.
+`team/` seeds **`.ai.local/team/`**. No Playwright / XCUITest. Dogfood: `dogfood/go-hexagonal`. Catalog: [`rules/README.md`](./rules/README.md).

package/presets/claude/go/REPO_AGENTS.md

@@ -1,19 +1,34 @@
 # Go — agent instructions
 
-Cross-tool repo-root guide. 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).
-- Tool maps live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` when that tool is installed.
+- 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 go
-npx @bonesofspring/ai-rules init claude --preset go
+npx @bonesofspring/ai-rules init multi --preset go
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas belong in `team/conventions.md`, not here.
+Per-tool: `init cursor|claude|mavis|opencode --preset go`. `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/go-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/go-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)
 
@@ -40,9 +55,20 @@ After code edits: invoke **`post-change-test`** (requestable). Full gate: agent
 |------|-----|
 | 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/`. Skills: `.cursor/skills/` or `.claude/skills/`.
+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`** and/or **`.claude/team/conventions.md`** (fill after init).
+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/claude/go/agents/api-contract-reviewer.md

@@ -15,7 +15,7 @@ Review **HTTP/gRPC contract alignment** for Go hexagonal services.
 
 ## Output
 
-`.claude/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/claude/go/agents/build-verifier.md

@@ -12,7 +12,7 @@ You are the build verifier for **Go hexagonal** services (and for **ai-rules pre
 1. Run from module root: `go test ./...`, `go vet ./...`.
 2. If present: `golangci-lint` / `staticcheck` per repo docs (`go-tooling`, `post-change-test`).
 3. Optional `-race` when concurrency touched.
-4. Write `.claude/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`, or `xcodebuild`/`SwiftLint` as the Go gate.
@@ -48,7 +48,7 @@ Document PASS/FAIL in `validation-report.md`.
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/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/claude/go/agents/code-reviewer.md

@@ -5,14 +5,14 @@ readonly: false
 model: fast
 ---
 
-You are a senior Go hexagonal code reviewer. Write only review artifacts under `.claude/team/**`; do not modify production code.
+You are a senior Go hexagonal code reviewer. Write only review artifacts under `.ai.local/team/**`; do not modify production code.
 
 ## Inputs
 
-1. `.claude/team/tasks/<slug>/brief.md`
-2. `.claude/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. `.claude/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`, `go-conventions.mdc`, `tests-unit.mdc`, `tests-integration.mdc`, `security-go.mdc`.
 
@@ -37,7 +37,7 @@ You **issue** reviews. Implementers acting on your findings must verify each ite
 
 ## Artifact
 
-Write `.claude/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 `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANG
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/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/claude/go/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 `.claude/team/tasks/<slug>/debug-report.md`.
+Write `.ai.local/team/tasks/<slug>/debug-report.md`.
 
 
 ## 3-fix architecture gate

package/presets/claude/go/agents/feature-developer.md

@@ -37,7 +37,7 @@ Implement Go features following hexagonal boundaries.
 
 When editing ai-rules `presets/**/go/**`, keep Cursor/Claude twins in sync and preserve chain fork ≠ next/ios-swift.
 
-Update `.claude/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 `.claude/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 `.claude/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/claude/go/agents/integration-test-generator.md

@@ -19,4 +19,4 @@ You are the **integration-test-generator** for Go 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/claude/go/agents/integration-test-healer.md

@@ -19,4 +19,4 @@ You are the **integration-test-healer** for Go 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/claude/go/agents/integration-test-planner.md

@@ -19,4 +19,4 @@ You are the **integration-test-planner** for Go 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`).