@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/mavis/next/rules/react-ui.md

@@ -1,6 +1,7 @@
 # General component rules
 
 - Use **functional components** with hooks, no classes.
+- Export as `export const ComponentName = ({ ... }: IProps) => …` (arrow + props type). No `FC` / `React.FC`.
 - A component should:
   - stay as "thin" as possible on business logic;
   - delegate state to store/hooks when needed in multiple places;
@@ -9,6 +10,41 @@
 - For repeated logic, create `useSomething` hooks nearby or in `src/ui/hooks/**`.
  - When accessing store, API, shared helpers, and utilities, components and hooks must use only their **public API** (for example, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), not internal implementation files of other modules.
 
+# Conditional rendering
+
+- Prefer **decomposition over conditionals**: a component with more than one or two branches (nested ternaries, long `&&` chains, several early returns) should extract each branch into a child under `./components/<Name>/`, keeping the parent a thin switch.
+- Keep the condition in the parent; the child receives resolved props.
+- No nested ternaries in JSX. For not-ready / empty / error, use an early return or a dedicated `EmptyState` / `ErrorState` component.
+- A `variant` / `mode` flag that renders two unrelated layouts is **two** components, not one.
+
+## Incorrect
+
+```tsx
+export const OrderPanel = ({ order }: Props) => (
+  <div>
+    {order == null ? (
+      <Spinner />
+    ) : order.items.length === 0 ? (
+      <p>No items</p>
+    ) : order.status === 'paid' ? (
+      <PaidList items={order.items} />
+    ) : (
+      <UnpaidList items={order.items} />
+    )}
+  </div>
+)
+```
+
+## Correct
+
+```tsx
+export const OrderPanel = ({ order }: Props) => {
+  if (order == null) return <Spinner />
+  if (order.items.length === 0) return <EmptyState />
+  return <OrderItems order={order} />
+}
+```
+
 # File structure
 
 For a page/large block:
@@ -63,7 +99,7 @@ For a reusable component:
 # Props and typing
 
 - **Do not pass props via spread** (`<Foo {...x} />`). Only explicit attributes; details and exceptions — `no-props-spread.md` (in `app/src/ui` ESLint catches this too).
-- Describe props with `type Props = { ... }` or `interface Props { ... }`.
+- Describe props with a local `interface` / `type` named as the repo does (`interface IProps` / `type TProps`); match the neighboring component. No `FC` / `React.FC`.
 - Do not use `any`; when needed:
   - generics (`<T>`), `unknown`, type predicates and user-defined type guards.
 - For domain entities use types from `@/types` (and enums from `@/types/enums`), not redefined locally (`public-imports.md`).

package/presets/mavis/next/rules/reference-features.md

@@ -34,7 +34,7 @@ After init the team maintains **local** gotchas, patterns, and decisions in a co
 | Patterns | Local patterns beyond the reference table |
 | Decisions | Short ADR links / product decisions that affect code |
 
-Path pointer and stack tables — in the preset adapter (`team/conventions.md`). The file is **not** always-on.
+Path pointer and stack tables — in the preset adapter (`.ai.local/conventions.md`). The file is **not** always-on.
 
 ## Related rules
 
@@ -43,3 +43,39 @@ Path pointer and stack tables — in the preset adapter (`team/conventions.md`).
 - skill `feature-delivery` — end-to-end scenario.
 
 > Concrete path tables, globs, and dogfood checklists live in the stack adapter **Stack notes**.
+
+## Stack notes
+
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
+
+Taxonomy / shared core: [`presets/_shared/README.md`](../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
+
+## Reference table
+
+Replace **TBD** with real paths after team agreement (or on `ai-rules init` in the target repo):
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| UI page | **TBD** `app/src/ui/pages/<Example>/` | `components/`, `*.data.ts`, `styles.ts`, barrel |
+| Store slice | **TBD** `app/src/store/slices/<example>/` | slice, thunks, selectors, types |
+| API service | **TBD** `app/src/api/services/<example>/` | service, mappers, barrel |
+| Types module | **TBD** `app/src/types/<example>/` | domain types, JSDoc, barrel export |
+| Unit tests | **TBD** mirrored under `app/__tests__/unit/<rel>` | `*.spec.ts`, describe/it naming |
+| E2E area | **TBD** `app/__tests__/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
+
+## How to use
+
+1. Identify affected layers from `decomposition.md` or the task.
+2. Open the reference from the table (after paths are filled).
+3. Mirror naming, file order, import patterns, and tests.
+4. If there is no reference — pick the **closest** existing feature of the same layer and record the choice in the handoff.
+
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.ai.local/conventions.md`** (shared across tools; `.ai.local/team/**` is pipeline artifacts, not rules). Consumer-owned; not always-on. See root `AGENTS.md` § Living conventions.
+
+## Related rules
+
+- `code-quality-and-refactoring.mdc` — repeat patterns, no deep-import.
+- `feature-delivery-workflow.mdc` — layer order.
+- skill `feature-delivery` — end-to-end scenario.

package/presets/mavis/next/rules/store-rtk.md

@@ -11,13 +11,14 @@
 # Slice structure
 
 - Each domain module — its own slice in `app/src/store/slices/**`.
-- A slice exports:
-  - default `reducer`;
-  - `actions` as named exports;
-  - selectors `selectSomething(state: RootState): Type`.
+- A slice exports — follow the repo's shape:
+  - a named slice (`xxxSlice`) re-exported through a per-slice barrel (`index.ts`), **or** a default `reducer`;
+  - actions as named exports;
+  - selectors named as in the repo (`selectSomething(state: RootState): Type`, or a curried `xxxSelector = (args) => (state) => …`); memoize derived values with `createSelector`.
 - State:
   - explicit state type;
-  - careful `initialState` initialization.
+  - careful `initialState` initialization;
+  - typed root state — use the repo's `RootState` if present, otherwise the local `IRootState` interface neighboring slices use.
 
 # Async and side effects
 

package/presets/mavis/next/rules/tests-e2e-structure.md

@@ -70,3 +70,18 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 ## E2E: keep plans and selectors in sync with UI
 
 - When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.
+
+## Stack notes
+
+- Runner: Playwright (`@playwright/test`).
+- E2E folder: `app/__tests__/e2e/**`.
+- Placement mirrors source paths: `app/src/<rel>` → `app/__tests__/e2e/<rel>`. Use the deepest folder of the source under test; page-wide scenarios mirror the page folder.
+- Scenario plans: `*.cases.md` files — canonical source of scenarios.
+- Tests: `*.spec.ts` files — Playwright scenario implementations.
+- Shared utilities and abstractions: `app/__tests__/e2e/_shared/**` — constants, fluent interfaces, helpers.
+- Root exceptions that do not mirror a single source module: `_shared/`, `smoke.spec.ts`, and `seed.spec.ts`.
+- `data-testid` naming scheme: `{parent}__{element}` — example `history-page__title`, `history-page__recognition-banner__attach-files-button`.
+- `PREFIX-XXX` example: `OrderHistory` → `OH`, `BillingReport` → `BR`; Russian example — `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed).
+- Page object example filename: `OrderHistoryPage.ts` (the seed test pointer lives at `app/__tests__/e2e/seed.spec.ts`).
+- Cross-reference: See also **`playwright-agents.mdc`** for the e2e planner / generator / healer agents.
+- `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.

package/presets/mavis/next/rules/tests-unit.md

@@ -70,3 +70,36 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 ## E2E: keep plans and selectors in sync with UI
 
 - When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.
+
+## Stack notes
+
+- `render` from `@testing-library/react` for component tests.
+- `userEvent` from `@testing-library/user-event` for interactions.
+- DOM matchers as wired in the project (`toBeInTheDocument`, `toHaveTextContent`, …).
+- `jest/valid-title` ESLint rule in `app/eslint.config.mjs` enforces the Russian capital-after-period rule (when configured).
+- `@/types` and `@/api` imports — types come from the public API surface, never duplicated in tests.
+- `app/src/mocks/**` — shared fixtures and MSW handlers live here (or repo equivalent).
+- Unit-test placement mirrors source paths: `app/src/<rel>` → `app/__tests__/unit/<rel>`. Do not colocate `*.spec.ts(x)` or `*.test.ts(x)` under `app/src/**`.
+- HTTP-client behavior tests live under the mirrored `app/__tests__/unit/lib/clients/**` path (prefer `*.spec.ts`).
+- UI tests live under the mirrored `app/__tests__/unit/ui/**` path. Import the source under test through the `@/` alias.
+- `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.
+
+## Incorrect
+
+Title violates capital-after-period rule (Russian locale). The rule's enforcement (`jest/valid-title`) will reject this in CI.
+
+```ts
+it('возвращает пустой список. пользователь не авторизован', () => { <!-- i18n-keep: E5 -->
+  expect(result).toEqual([]);
+});
+```
+
+## Correct
+
+Title respects capital-after-period rule.
+
+```ts
+it('Возвращает пустой список. Пользователь не авторизован', () => { <!-- i18n-keep: E5 -->
+  expect(result).toEqual([]);
+});
+```

package/presets/mavis/next/rules/ux-design.md

@@ -97,3 +97,7 @@ PASS | PASS_WITH_NOTES | INCOMPLETE
 ## Spec feed
 ## Open probes
 ```
+
+## Stack notes
+
+Form-factor **web**: browser chrome, responsive layout, pointer + keyboard. Do not FAIL on exact pixels; name surfaces (page, modal, drawer) as in the product.

package/presets/mavis/next/skills/README.md

@@ -1,6 +1,6 @@
 # `.mavis/skills` (preset next)
 
-Project skills for Cursor. They keep long workflows out of always-on rules while preserving the same team conventions as the Claude preset.
+Long workflows stay here, not in always-on rules. Same skill set as the Claude twin.
 
 | Skill | When to use |
 |-------|-------------|

package/presets/mavis/next/skills/code-review/SKILL.md

@@ -2,7 +2,7 @@
 
 ## Inputs
 
-Use the local repository as the source of truth: `git status`, `git diff`, task artifacts under `.mavis/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
 
@@ -26,7 +26,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 `.mavis/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/mavis/next/skills/debug-investigation/SKILL.md

@@ -24,3 +24,31 @@ If **three** fix attempts fail, or the same symptom returns after two supposed f
 - Broad refactor during a bugfix.
 - Fix only where the error surfaces if invalid data originates elsewhere.
 - Claim `fixApplied: true` without re-running the failing check (see `quality/verification-before-completion.md`).
+
+## Stack notes
+
+### Artifacts
+
+For agent team tasks, write `.ai.local/team/tasks/<slug>/debug-report.md` with:
+
+- Reproduction steps or evidence source.
+- Root cause.
+- Fix scope.
+- Regression coverage.
+- Remaining risk.
+
+Agent team: upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
+### MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If Chrome DevTools MCP is ready and the app is running, use it for console, network, and runtime evidence.
+
+Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools MCP for live-app debug and performance (app must be running). Storybook MCP if present and the work is component docs/stories.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+### Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/mavis/next/skills/mockup-review/SKILL.md

@@ -21,4 +21,4 @@ Load requestable rule `mockup-review` and follow its review dimensions, node cap
 
 ## Output
 
-Write `.mavis/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/mavis/next/skills/spec-discovery/SKILL.md

@@ -8,7 +8,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 `.mavis/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`.
@@ -44,7 +44,7 @@ Sources: AC / user / UI copy / labeled code inference / research path. Unsourced
 
 ## Memlog
 
-Path: `.mavis/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/mavis/next/skills/technical-retro/SKILL.md

@@ -2,7 +2,7 @@
 
 ## Inputs
 
-Ask for missing period, focus, task slug, participants, or format constraints. If a slug is provided, read `.mavis/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
 
@@ -42,7 +42,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 `.mavis/rules/`, `.mavis/agents/`, `.mavis/skills/`, or **`.mavis/team/conventions.md`** (prefer conventions for project gotchas)
+- Proposed change to `.mavis/rules/`, `.mavis/agents/`, `.mavis/skills/`, or **`.ai.local/conventions.md`** (prefer conventions for project gotchas)
 - One concrete snippet or file path
 - Whether it belongs in always-on vs globs vs skill vs conventions (see `PRESET-CONTRIBUTION` → Building blocks)
 

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

@@ -12,7 +12,7 @@ Follow **`tests-unit.md`** (Cursor) or **`rules/testing/tests-unit.md`** (Claude
 
 ## Planner
 
-Write or update `.mavis/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, thunks, client behavior branches, and component interactions per AC. Record the mirrored target path under `app/__tests__/unit/`.
 

package/presets/mavis/next/skills/ux-design/SKILL.md

@@ -28,4 +28,4 @@ Load requestable rule `ux-design` and follow its required-signal vs advisory rul
 
 ## Output
 
-Write `.mavis/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/mavis/next/skills/write-adr/SKILL.md

@@ -10,7 +10,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/`, `.mavis/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>
@@ -32,5 +32,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/mavis/next/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
 
 ```
-.mavis/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:** `.mavis/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 `.mavis/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 .mavis/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 .mavis/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/mavis/nuxt/MAVIS.md

@@ -0,0 +1,69 @@
+# Nuxt 3 stack — Mavis agent team
+
+Short Mavis entry. Detailed rules live under `.mavis/rules/*.md`; procedures
+under `.mavis/skills/**`. This file is ai-rules-owned (`.mavis/AGENTS.md`),
+not a MiniMax-reserved filename.
+
+Root `AGENTS.md` is the compatibility floor. Read it first, then this file.
+Do not write `~/.minimax/**`.
+
+## How to load
+
+- Rules and skills: follow the explicit paths in this file and root `AGENTS.md`.
+  Native project discovery without a reference is unconfirmed.
+- Roles: `mcode exec --file .mavis/agents/<role>.md --output-format json`.
+- Commands: natural-language procedures in `.mavis/commands/`, or
+  `mcode exec --file .mavis/commands/task.md "<task>"`.
+- After a producer receipt, run `bash .mavis/hooks/chain-team-phases.sh`.
+  Agents must not write lifecycle fields in `status.json` / `metrics.json`.
+
+## Essential rules (read every turn)
+
+- `.mavis/rules/nuxt-app-core.md`
+- `.mavis/rules/package-manager.md`
+- `.mavis/rules/code-quality-and-refactoring.md`
+- `.mavis/rules/ai-local-overlay.md`
+
+See `.mavis/rules/README.md` for the full catalog and loading strategy.
+
+**Platform docs:** published with the `@bonesofspring/ai-rules` package
+(`docs/MAVIS.md`, `docs/MAVIS-COMPATIBILITY.md`) — **not** copied into
+the consumer repo. Source: https://github.com/bonesofspring/ai-rules
+
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root (cross-tool setup, commands, security, living conventions pointers).
+
+## Quick start
+
+| Task | Where to look |
+|------|----------------|
+| Any new work 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 | `nuxt-app-core.md` |
+| Reference features | `reference-features.md` (fill in repo paths) |
+| 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-nuxt.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 with no architecture risk — may skip the pipeline if the user explicitly asks.
+- “How does X work?” questions — agent `codebase-analyzer` (explain-as-is) or answer without `/task`.
+
+## Pipeline routing
+
+Intent detection, profiles (`full` / `standard` / `light`), and default steps — **only** in `agents/task-router.md`. Schema and examples — `agents/README.md`.
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init mavis --preset nuxt
+```
+
+Copies rules, commands, agents, hooks, skills, `MAVIS.md` → `.mavis/AGENTS.md`,
+`MCP.md`, `mcp.json` → `.mavis/mcp.json`, plus `REPO_AGENTS.md` → root `AGENTS.md`.
+Seeds `.ai.local/team/`.
+Skills: `write-adr`, `vue-performance` (on-demand). Import MCP from `.mavis/mcp.json`
+in the MiniMax Code UI.

package/presets/mavis/nuxt/MCP.md

@@ -0,0 +1,36 @@
+# MCP (preset `nuxt`, Mavis)
+
+Staged at `.mavis/mcp.json` on `ai-rules init mavis --preset nuxt`.
+
+## Servers
+
+| Name | Package | Why |
+|------|---------|-----|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Vue/Nuxt/TS and library docs (fewer stale APIs in agent replies) |
+| `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 MiniMax Code (manual import) |
+
+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 the 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/mavis/nuxt/README.md

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