@bonesofspring/ai-rules 0.2.24 → 0.2.26

package/presets/mavis/nuxt/rules/design-guidance.md

@@ -0,0 +1,99 @@
+<!-- shared-core: quality/design-guidance.md -->
+
+# Design guidance (smells & patterns)
+
+Glossary of **code smells** (Fowler) and **design patterns** (GoF) for agents during implement / review / debug.
+
+Apply only within the task or MR scope. Light refactor — yes; a “big” rewrite without an explicit request — no.
+
+Name a pattern **only if** the repository already does it that way or the match is minimal. Otherwise — extract/split/move without a GoF label.
+
+Does not replace always-on Principles in `code-quality-and-refactoring` (KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition, Demeter).
+
+## When to load
+
+- **Feature delivery / implement** — assess module structure, boundaries, and duplication.
+- **Code review** — smells and pattern fit **in the MR diff**, not across the whole repo.
+- **Debug** — root cause looks like wrong abstraction, Feature Envy, Message Chains, Shotgun Surgery.
+- **Light refactor only** — improvements within boy-scout / MR scope; do not expand the task for the catalog.
+
+Agents and skills load this stem via one-liner wiring — do not copy this catalog into the agent prompt.
+
+## How to use (agent rules of thumb)
+
+1. First check against Principles (always-on): is the solution simpler, is there no premature abstraction, is the public API respected.
+2. Then mark smells **in the changed files** of the task/MR; propose a fix only if it fits a light refactor.
+3. A GoF pattern is an optional label after the structure is already clear; do not start design by picking a pattern.
+4. If a smell or pattern conflicts with stack layer boundaries — stack boundaries and existing repo patterns win.
+5. Do not require renaming “for GoF” if behavior is already correct and readable.
+
+## Code smells (Fowler, curated ≤12)
+
+Table: smell → detect hint → fix hint (one line each). No mechanical refactoring menus.
+
+| # | Smell | Detect | Fix hint |
+|---|-------|--------|----------|
+| 1 | Duplicate Code | same logic in ≥2 places | dedupe after Rule of Three |
+| 2 | Long Method / Long Module | unit does too much | extract within scope; no big rewrite |
+| 3 | Feature Envy | method touches foreign data more than its own | move logic toward the data / public API |
+| 4 | Data Clumps | the same argument groups travel together | group into a type / value object |
+| 5 | Primitive Obsession | raw string/int instead of domain concepts | typed ids / value objects when the domain needs them |
+| 6 | Speculative Generality | unused hooks, flags, “for later” abstractions | remove (YAGNI) |
+| 7 | Message Chains | `a.b.c.d` chains | Demeter; facade / module public API |
+| 8 | Middle Man | class almost only forwards calls | remove pass-through **or** keep as a boundary |
+| 9 | Divergent Change | one module changes for different reasons | split by reasons to change |
+| 10 | Shotgun Surgery | one semantic change spreads across many files | consolidate responsibility |
+| 11 | Inappropriate Intimacy | access to foreign internals / private details | public API / ports / facades only |
+| 12 | Refused Bequest / Parallel Inheritance | subtype ignores base; mirrored class hierarchies | composition; do not grow parallel trees |
+
+**Skip Fowler (not in core):** Lazy Class, Incomplete Library Class, Comments-as-smell dogma, full 70+ catalog, step-by-step recipe menus.
+
+Smell conflict priority: Inappropriate Intimacy and Message Chains (module boundaries) > Duplicate Code (after Rule of Three) > Long Method inside an already correct module.
+
+## Design patterns (GoF, curated ≤8)
+
+Suggest only when repo already uses the shape or the match is minimal. Prefer extract-function over naming Strategy for the label alone.
+
+Patterns below are the **allowed minimum** for agents; the rest of GoF is Skip by default.
+
+| Pattern | When to suggest | Anti-trigger |
+|---------|-----------------|--------------|
+| Strategy | interchangeable algorithms already (or clearly soon) chosen by policy | one algorithm with no policy branching |
+| Adapter | wrap external / foreign API under a local port | extra wrapper around your own API |
+| Facade | simplify a multi-step subsystem behind a public API | facade turns into a god-object |
+| Factory Method | polymorphic creation already accepted in repo style | factory for every trivial `new` |
+| Decorator | additive behavior without exploding subclass hierarchies | decorator “for layers” with no real need |
+| Observer | events / subscriptions already exist in the architecture | homemade pub/sub with no repo precedent |
+| Template Method | shared algorithm skeleton + variable hooks | inheritance for a couple of differing lines |
+| Composite | tree of homogeneous nodes (UI/domain), as already in the repo | Composite on a flat list with no hierarchy |
+
+If unsure between two patterns — choose the simpler extract/compose without a name; the label may be added on review if the repo already speaks that way.
+
+## Skip / avoid by default
+
+| Catalog | Skip |
+|---------|------|
+| GoF | Singleton, Abstract Factory, Flyweight, Memento, Interpreter, Visitor, Bridge, Prototype |
+| GoF (conditional) | Command, Chain of Responsibility, State — mention **only if** the repo already uses them |
+| Fowler | everything beyond the 12 smells above |
+| DDD | Aggregates, bounded-context maps, event sourcing, CQRS — **not in core** |
+| DDD (pointer) | ubiquitous language anti-pattern — expand in `feature-delivery-workflow`, not here |
+| GRASP | Larman list as separate rules — skip (covered by SOLID/CUPID) |
+| Clean Code dogma | hard caps on function lines / “exactly one assert” — skip |
+
+Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agents`) — one catalog: `design-guidance`.
+
+## Out of scope for this stem
+
+- Full GoF (23) and full Fowler catalog.
+- Stack-specific recipes (module paths, lint commands) — only in the adapter **Stack notes**.
+- Security, a11y, perf — separate review rules; here only structural smells/patterns.
+- A fourth always-on rule — forbidden; this stem is requestable / agent-load only.
+
+## Cross-refs
+
+- Always-on Principles: `code-quality-and-refactoring`.
+- DIP / ports vs adapters: stack `architecture-boundaries` (stack details — in adapter Stack notes).
+- Ubiquitous language: `feature-delivery-workflow` (lineage).
+- MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
+- Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).

package/presets/mavis/nuxt/rules/feature-delivery-workflow.md

@@ -0,0 +1,49 @@
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (end-to-end order)
+
+Typical feature with data and UI. Concrete directories and rule stems — in the adapter **Stack notes**.
+
+## Checklist (abstract order)
+
+1. **Domain / types** — Domain/types-layer entities and contracts; layer public API.
+2. **Transport / DTO** — DTOs and mappers Domain ↔ transport (must not leak into UI).
+3. **Services / Data** — repository / API-service implementations via the stack’s public clients.
+4. **State** — store / ViewModel / use cases; no direct HTTP and no DTOs in UI.
+5. **UI** — thin views/components; data via state; design system. If the prompt or `brief.md` contains a `figma.com` URL, **mockup review must complete** (or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue`) **before UI work**. When required-signal and **no** `figma.com`, **`ux-design.md` must exist** (not `INCOMPLETE`) before UI work — else blocked, hand back to analyst. Non-UI tasks no-op these gates.
+6. **Tests** — unit for mappers / non-trivial logic; e2e/UI per stack convention.
+7. **Completion** — stack post-change gate (lint/build) + package/toolchain rules. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated repo-relative paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
+
+## Data flow (orientation)
+
+```mermaid
+flowchart LR
+  DTO[DTO] --> Mappers[Mappers]
+  Mappers --> Domain[Domain]
+  Domain --> Service[Service / Repo]
+  Service --> State[Store / VM]
+  State --> UI[UI]
+```
+
+## Partial scenarios
+
+| Task | Minimum |
+|------|---------|
+| API / model only | Domain + DTO + mapper + service/repo; unit for mapper |
+| State only | Protocols/services; no HTTP in UI |
+| UI only | Existing state; no DTOs |
+| Tests only | Specs per convention; do not change production without need |
+
+## Anti-patterns (shared)
+
+- DTO / transport types in UI or presentation state.
+- Low-level HTTP / concrete client from UI bypassing the service.
+- Deep-import of another module/feature’s internal files.
+- Breaking layer boundaries for brevity.
+- **Ubiquitous language:** Domain/type names and boundaries reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need; presentation must not dictate the model vocabulary.
+- When assessing structure, smells, or pattern choice — load requestable **`design-guidance`** (not always-on); do not copy the catalog into the feature checklist.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
+
+## Zone → rules matrix
+
+Filled in the stack adapter: concrete globs/paths and `.mdc` / topic `.md` names.

package/presets/mavis/nuxt/rules/http-client.md

@@ -0,0 +1,9 @@
+# HTTP client
+
+- One HTTP stack for the app: wrap **`$fetch` / ofetch** (or the client already used in `lib/clients/**`).
+- Do not mix ad-hoc `fetch`/`axios` in features if a shared client exists.
+- Services in `api/**` call the wrapper — UI/stores do not own transport.
+- Map responses to domain models in services/mappers before Pinia.
+- Errors: use project transport error types from `~/types` / `@/types`; narrow with `instanceof` when available.
+- Base URL / auth headers: from `runtimeConfig` / existing client factories — do not hardcode secrets.
+- Calling Nitro `/api/*` from the client is fine when that is the BFF pattern — still through services.

package/presets/mavis/nuxt/rules/layer-barrel-exports.md

@@ -0,0 +1,67 @@
+# Barrel exports for layers with a public API
+
+## When to apply
+
+For **any layer** (directory, package, bounded context) that has:
+
+- a **root barrel** — single import point for external consumers;
+- deep imports into the layer **forbidden** from outside (ESLint `no-restricted-imports`, `public-imports.md` rules).
+
+Example alias/entry points across projects: `@/api`, `@/types`, `@/core`, `@/store`, `packages/foo`.
+
+## Two barrel levels
+
+1. **Local** — `index.ts` of a module/feature inside the layer.
+2. **Root public API** — layer barrel (e.g. `src/<layer>/index.ts`).
+
+**Inside** the layer — relative imports and paths between submodules. **Outside** — only the root barrel and **explicitly allowed** secondary entry points (if fixed in project rules, e.g. `@/types/enums`).
+
+## What to re-export outward
+
+Only symbols that **must be available** to layer consumers: public functions/services/facades, contract types, constants and helpers needed by other layers or tests.
+
+**Do not re-export:** internal adapters, mappers, transport details, intermediate objects used to assemble a facade inside the layer.
+
+Grouping in the root barrel — **per repository convention** (orient on neighboring modules of the same layer).
+
+## Agent checklist (required)
+
+When adding or substantially extending a **module inside a regulated layer**:
+
+1. Identify the layer, its **root barrel**, and extra entry points (`public-imports.md`).
+2. Create/update the **local** `index.ts` — public symbols only.
+3. If the layer has a **facade/aggregator** (`*ApiService.ts`, `rootReducer`, …) — wire the module there.
+4. Add a **re-export** of new public symbols in the layer’s **root barrel**.
+5. **Verify:** grep for the symbol name or path `./<Module>` in the root barrel; no deep imports from outside the layer.
+
+The module is **not ready** until the checklist passes.
+
+## How to find regulated layers in the repository
+
+1. `public-imports.md` rules in `.mavis/rules/`.
+2. ESLint `no-restricted-imports` — `@/<layer>/*` patterns with barrel exception.
+3. `architecture-boundaries.md`, project README.
+
+## In this repository
+
+| Layer | Root barrel | Import rule |
+|-------|-------------|-------------|
+| API | `api/index.ts` | `public-imports.md` |
+| Types | `types/index.ts` | `public-imports.md` (+ `@/types/enums`) |
+| Core | `core/index.ts` | ESLint: `@/core/index` |
+
+Two-level illustration (API): local `services/.../<Feature>/index.ts` → facade `*ApiService.ts` → `api/index.ts`.
+## Incorrect
+
+```ts
+// api/index.ts — leaking internals
+export { mapCardResponse } from './services/CardsApi/cardResponseMappers'
+export { rawCardsClient } from './clients/rawCardsClient'
+```
+
+## Correct
+
+```ts
+// api/index.ts — public facade only
+export { cardsApi } from './services/CardsApi'
+```

package/presets/mavis/nuxt/rules/mcp-usage.md

@@ -0,0 +1,86 @@
+<!-- shared-core: quality/mcp-usage.md -->
+
+# MCP usage
+
+Requestable protocol for **shipped** and **local-overlay** MCP servers. Agents load this stem via one-liner wiring — do not copy tool schemas into prompts; discover them at runtime.
+
+Does not replace Figma mockup-review (that checklist stays on `mockup-review`). Does not add pipeline agents or required handoff stems.
+
+## Presence (runtime catalog is SoT)
+
+1. Inspect the **session MCP catalog** (server names + `serverStatus`). Project `mcp.json` / `.mcp.json` is a hint, not proof the server is up (user-level and plugin servers never appear there).
+2. Treat `error`, `needsAuth`, and `loading` as **unavailable**. Authenticate only when this task needs that server.
+3. **Discover tool schemas before calling.** Never invent tool names or arguments from memory.
+4. Match overlay servers by **documented aliases** or exact catalog ids. Prefer a ready `plugin-*` id over an unknown similarly named server; if several match, ask rather than guessing.
+5. If two servers expose the same product (plugin + project entry), use the **ready** one; do not call both.
+
+## Classes
+
+| Class | Who adds it | Policy |
+|-------|-------------|--------|
+| **Shipped** | Preset `mcp.json` | Assume it should be there; call when the task fits; degrade if down (do not block unless noted below) |
+| **Local overlay** | Consumer project or user MCP | Use only when present **and** the task fits. Never a required pipeline step |
+
+Shipped in every preset: **Context7** (library docs). Other shipped servers are stack-specific — see adapter **Stack notes**.
+
+## Context7 (shipped)
+
+**When to call** (after lockfile / manifest + sibling files still do not confirm the symbol):
+
+- Third-party API that would otherwise get `// VERIFY: lib.symbol @ version`
+- Version-sensitive framework or SDK APIs
+- Migrations / major upgrades
+- Library is in the lockfile but the signature is unclear
+
+**When not to call:** repo public API; a sibling file already imports the symbol; a trivial call already in this module.
+
+**Flow:**
+
+1. Discover server `context7`.
+2. Resolve a library id, then query docs (read the live schema; typical names `resolve-library-id` then `query-docs`).
+3. Put the **installed major** from the project manifest into the query.
+4. Cap: **≤3 doc queries per question**.
+5. Source priority: lockfile / sibling code **>** Context7 **>** training data. If docs disagree with the installed major, keep the installed API.
+6. If Context7 is down: `// VERIFY` (or stack equivalent) and say MCP was unavailable. **Do not block** the task.
+
+## Local overlay protocol
+
+If a matching server is ready and a **task signal** fires → discover and use. Otherwise continue from files / native tools (`gh`, repo docs, source).
+
+Absence of an overlay is **not** `BLOCKED` unless the user required that MCP as source of truth.
+
+### Observability (Sentry, Datadog, similar)
+
+**Signal:** production error, event/trace id, APM / latency, pasted dashboard or issue URL.
+
+Use the **first ready** observability MCP. Do not invent metrics or stack traces. Do not require two observability servers.
+
+### Tickets (Linear, Jira, Notion, similar)
+
+**Signal:** ticket/page URL in the prompt or brief, or an explicit “pull from \<tracker\>”.
+
+Read-only by default. Task-folder artifacts (`brief.md`, `decomposition.md`) remain SoT — do not replace them with a tracker page. Write back to the tracker **only** if the user asked.
+
+### Component-library overlay
+
+**Signal:** UI component public API, stories, controls, or explicit component-docs MCP.
+
+If such a server is ready, use it for documented props/variants instead of inventing them. If it is down, read story/source files. **Block** only when the user required that MCP as SoT.
+
+Usual aliases and runtime needs live in frontend **Stack notes**. Do not ship this server in preset `mcp.json`.
+
+### GitHub MCP
+
+Native `gh` / git remain SoT for PRs and checks. A GitHub MCP may be used when present; do not require it.
+
+## Figma
+
+Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plugin** and a project `figma` server are both present, use the ready one and do not duplicate calls.
+
+## Forbidden
+
+- Secrets in `mcp.json` / `.mcp.json`
+- New pipeline agents or required handoffs for overlay MCP
+- Treating overlay absence as blocked (except user-required SoT)
+- Tracker/admin write tools without an explicit ask
+- Calling overlay MCP “just in case” on unrelated tasks

package/presets/mavis/nuxt/rules/mockup-review.md

@@ -0,0 +1,107 @@
+<!-- shared-core: review/mockup-review.md -->
+
+# Mockup review checklist
+
+On-demand reviewer checklist for Figma mockups. **Procedure:** skill `mockup-review`. **Agent:** `mockup-reviewer`. Do not inline this checklist into the agent prompt.
+
+Stack-agnostic: no app-source globs, Playwright, or `xcodebuild`. Breakpoint **examples** live in adapter **Stack notes** only — do not FAIL on exact pixels.
+
+## When to load
+
+- Pipeline step `mockup-reviewer` (standalone intent `mockup-review` or embedded after analyst)
+- Prompt or `brief.md` contains a `figma.com` URL on a UI-capable stack
+- User asks to review a mockup / Figma file (not a code MR)
+
+## Inputs
+
+1. Task `artifact-manifest.json`, then prompt Figma URL(s); `brief.md` / `decomposition.md` when present
+2. Skill `mockup-review` + this rule
+3. If plugin skills `figma-use` / `figma-design-to-code` are installed: **reference** them for URL parse and MCP invocation only — do not copy their bodies; do not run design-to-code
+
+## MCP-first
+
+Required when MCP is up: `get_metadata`, `get_design_context`, `search_design_system`, `get_variable_defs`, `get_screenshot`. Optional: `get_libraries`, `get_code_connect_map`.
+
+**Forbidden:** `use_figma`, `create_new_file`, `generate_*`, `weave_*`, `upload_assets`, `send_code_connect_mappings`. FigJam URL → `BLOCKED_MCP` / out of scope (do not call `get_figjam` unless the URL is a FigJam board — then still `BLOCKED_MCP`).
+
+Cite `fileKey` + node IDs. Screenshots are supporting evidence, not a second reviewer. No screenshot-only path.
+
+**Node caps:** ≤12 screen-level frames; `get_metadata` depth ≤3 named-frame levels; ≤3 screenshots (prefer one per small/medium/large). `search_design_system` once; `get_variable_defs` once per file. No node-id on URL: pick top-level frames matching the feature name; if still unbounded → `BLOCKED_MCP` (or `PASS_WITH_NOTES` only if MCP returned a tiny file) — do not dump the whole file.
+
+**Degradation:** MCP unavailable or OAuth fail → verdict `BLOCKED_MCP`. Do **not** invent DS compliance claims.
+
+## Review dimensions
+
+### DS components (AC-4)
+
+When an attached library is detectable (`search_design_system` / `get_metadata`): list **library component instances vs custom frames** with file/node references. Flag substitutions where a DS equivalent exists.
+
+- Critical DS reimplementation (custom frame where an attached-library component exists) → **FAIL**
+- One-off frame, no DS equivalent; mixed/unpublished library → WARN or notes (`PASS_WITH_NOTES`)
+- No attached library detectable → notes only; do not invent DS claims (`PASS_WITH_NOTES`)
+
+Confidence: `high` (MCP library match) / `low` (unpublished or mixed) — prefer `PASS_WITH_NOTES` over FAIL when confidence is low.
+
+### Tokens (AC-5)
+
+When variables/styles are available (`get_variable_defs`, style metadata): flag fills, strokes, spacing, or typography that use raw values instead of bound variables/styles.
+
+- Isolated unbound values → **WARN** (`PASS_WITH_NOTES`)
+- Wholesale token ignore on a library-attached file (systemic; treat as critical DS with AC-4) → **FAIL**
+
+### Quality (AC-6)
+
+Cover at minimum, each item PASS / WARN / FAIL eligible:
+
+- Layer/frame naming hygiene
+- Auto-layout vs absolute positioning for responsive regions
+- Text style usage
+- Component variant/property correctness
+- Detached or orphaned component instances
+
+Naming hygiene, minor detached instances, text-style drift → **WARN**. Detached **core** DS component that is a substitution → **FAIL** (same as AC-4 critical). Absolute layout on a region that is the only «responsive» evidence → WARN unless it also fails viewports.
+
+### Feature coverage (AC-7)
+
+Map **flows → screens/frames**, **actions → interactive elements**, and **states** (empty, loading, error, success, disabled/validation). List explicit **missing** items. Label scope **`inferred`** when only a URL is provided (no brief AC).
+
+- Missing **core** flow or primary action from brief AC (or labeled `inferred` primary flow from the URL) → **FAIL**
+- Missing empty/loading/error/success on a form/list called out in AC → **FAIL**
+- Missing secondary states (disabled/validation) not in AC → **WARN**
+
+### Viewports (AC-8)
+
+Verify **≥3 viewport representations** (small / medium / large) via dedicated frames, Figma viewport presets, or responsive component variants.
+
+- Fewer than 3 → **FAIL**
+- 3 exist but sizes ≠ stack example buckets → **WARN** only (no exact pixel enforcement in core)
+
+## Severity (v1)
+
+Isolated **WARN** never blocks. Overall verdict = worst FAIL > BLOCKED_MCP > PASS_WITH_NOTES > PASS. Multiple WARNs without FAIL → `PASS_WITH_NOTES`, not FAIL.
+
+## Report headings
+
+Write `mockup-review.md` with these headings (must match the agent template):
+
+```markdown
+# Mockup review: <slug>
+
+## Verdict
+PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP
+
+## Scope
+- Figma fileKey / node IDs
+- MCP: available | unavailable (reason)
+- Feature scope source: brief AC | prompt | inferred
+
+## Critical (must fix)
+## Warnings (should fix)
+## Suggestions
+## DS compliance (AC-4, AC-5)
+## Quality (AC-6)
+## Feature coverage (AC-7)
+## Viewport matrix (AC-8)
+## AC coverage
+| Criterion | Status | Notes |
+```

package/presets/mavis/nuxt/rules/navigation-router-stack.md

@@ -0,0 +1,55 @@
+# Navigation and routing: project stack first
+
+**For any task involving navigation, page transitions, URLs, redirects, breadcrumbs, protected routes, or programmatic route changes** — before proposing code or imports, **do not** default to a “typical Vue SPA”. You must **explicitly check the target repository stack** and use **one** mechanism consistent with the project.
+
+## Dependencies: what to check first
+
+1. **`package.json`** at the app root (the package with `nuxt.config.*` / the one that builds and deploys). Inspect **`dependencies`** and, if needed, **`peerDependencies`**:
+   - **`nuxt`** — Nuxt 3 (file-based routing); version matters for API nuances (check docs for that major).
+   - **`vue-router`** without Nuxt — separate SPA routing; do not replace its API with Nuxt calls (`navigateTo`, `<NuxtLink>`) without checking.
+   - **`nuxt`** and a separate manual `createRouter` at once — may be legacy or hybrid; **do not** pick an API by default — see “Routing implementation in the project” below.
+
+2. **Monorepo / workspaces** — routing may not live in the root `package.json`. Open **`package.json` of the workspace** that holds `pages/` and `nuxt.config.*`.
+
+3. **Installation fact** — when in doubt, check the lockfile (`bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or `node_modules`: confirm the declared package is actually installed.
+
+## Routing implementation in the project (code and structure)
+
+Before proposing a navigation pattern, **check how it is already done in the repository**:
+
+1. **Route tree**
+   - **Nuxt 3 file-based routing:** **`pages/`** directory (`.vue`), layouts in **`layouts/`**, middleware in **`middleware/`**, `definePageMeta`.
+   - **Nuxt 4 note:** `app/` may be `srcDir` — confirm via `nuxt.config`; **do not** confuse with Next `app/` + `page.tsx`.
+   - Plain **Vue Router SPA:** route config (`router/index.ts`, `createRouter`) without Nuxt file routing.
+
+2. **Entry points and wrappers**
+   - Search the code: **`navigateTo`**, **`<NuxtLink>`**, **`useRouter` / `useRoute`** (Nuxt auto-import), **`from 'vue-router'`**, **`createRouter`**, **`RouterLink`**.
+   - Where routes are declared (Nuxt file structure vs explicit `routes` in SPA).
+
+3. **Shared project abstractions**
+   - Link wrappers (`~/components/...`, design-system Link), path helpers, route constants — **use them**, do not duplicate raw API.
+
+4. **Neighboring feature files**
+   - New navigation code — same style as pages/composables in that area (`navigateTo` / `<NuxtLink>` vs `vue-router` as in neighboring imports).
+
+## How to decide what to use (summary)
+
+1. **Dependencies** — see section above; they define the allowed package set.
+2. **Structure** — Nuxt `pages/` vs Vue Router SPA by directories and config.
+3. **Actual code** — which imports and wrappers already dominate in the app.
+
+## What to use (short matrix)
+
+| Stack | Programmatic navigation / path read | Links |
+|-------|-------------------------------------|-------|
+| **Nuxt 3 file-based routing** | `navigateTo`, `useRouter`, `useRoute`, `useRouter().push` (per Nuxt docs for your version) | `<NuxtLink>` |
+| **Vue Router SPA (no Nuxt)** | `vue-router` (`useRouter`, `useRoute`, `router.push`, …) | `<RouterLink>` / `<router-link>` |
+
+**Do not:** add `react-router-dom` or `next/navigation` / `next/link` in a Nuxt project; import Next hooks (`usePathname`, `useSearchParams` from `next/navigation`); mix manual `createRouter` and Nuxt file routing without a clear reason in the codebase.
+
+## Agent requirement
+
+- Before generating or reviewing navigation code, **briefly state the conclusion** (e.g. “dependencies: `nuxt`; code uses `<NuxtLink>` / `navigateTo` everywhere → use the same”) and follow it.
+- **Required check:** current **`dependencies`** in the relevant workspace `package.json` + **how routes and imports are already implemented** (repo search, neighboring files). Do not rely on a single signal alone (e.g. only the presence of a `pages/` folder).
+- If the stack is unclear (hybrid) — **check lockfile / installed packages** and **dominant imports**, then pick the API.
+- For **this** preset the baseline is **`nuxt-app-core.md`** + **`nuxt-pages-routing.md`**: Nuxt 3; prefer **`navigateTo`**, **`useRouter` / `useRoute`**, **`<NuxtLink>`**.

package/presets/mavis/nuxt/rules/navigation-router-ui.md

@@ -0,0 +1,10 @@
+# Navigation in UI components
+
+Before links, programmatic navigation, or URL work in UI:
+
+1. **`package.json`** of the app workspace — `nuxt` vs plain `vue-router` SPA.
+2. **Neighboring imports** in the same feature (`navigateTo`, `<NuxtLink>`, `useRouter` / `useRoute` vs `from 'vue-router'`).
+3. **Project wrappers** (`~/components/...` Link) — preferred over raw router API.
+4. **Default (preset):** Nuxt 3 file-based routing → `navigateTo` + `<NuxtLink>` + `useRouter` / `useRoute` (`nuxt-app-core.md`, `nuxt-pages-routing.md`).
+
+Full audit (route tree, hybrids, lockfile): **`navigation-router-stack.md`** — when editing `pages/**`, `layouts/**`, `middleware/**`, `nuxt.config.*`.

package/presets/mavis/nuxt/rules/no-type-assertion-as-import-export.md

@@ -0,0 +1,51 @@
+# Do not use `as` for type assertion on export and import (except necessary cases)
+
+## What this is about
+
+This is about TypeScript **type assertion**: expressions like `value as Type`.
+
+**Not covered by this rule** (not assertion — module syntax):
+
+- rename on export: `export { foo as bar }`, `export { default as Baz } from '...'`;
+- rename on import: `import { foo as bar } from '...'`;
+- `import type { Foo as Bar }` — type alias in a type import.
+
+## Requirement
+
+- On the **public module boundary** (what is **exported** from a file / barrel, and what is immediately **assigned from imported symbols** with a forced cast) **do not use** `as Type` to “force-fit” types when normal typing would work.
+
+## Prefer instead of `as`
+
+- an explicit annotation: `const x: T = ...` / `function f(): T`;
+- **generics** on functions and classes;
+- **`satisfies`** (when you need to check compatibility without narrowing to `any`);
+- narrowing **`unknown`** after checks (type guards, `zod`, etc.);
+- fixing **source types/DTOs/mappers**, not an assertion on the way out.
+
+## When `as` is allowed
+
+- interaction with **untyped** or incorrectly typed external modules where there is no reasonable alternative;
+- narrow spots after **validation**, if a type guard still cannot be expressed without noise (prefer guard/`satisfies` anyway);
+- **`as const`** — when literal types are needed and wide inference breaks the contract (a separate mechanism; use on purpose, not as a substitute for API typing).
+- a **`catch (error)`** block after HTTP via the shared client: prefer narrowing with **`instanceof`** on the **transport error class** from `@/types` (which one — follow the existing implementation) and work with the narrowed type; bare **`as` to the same type** — only if `instanceof` is unavailable (different throw source) and deliberately.
+
+## Examples
+
+```typescript
+// ❌ Bad: assertion on exported API
+export const config = loadRaw() as AppConfig
+
+// ✅ Better: annotation + check or mapper
+export const config: AppConfig = mapToAppConfig(loadRaw())
+
+// ❌ Bad: immediately after import we “break” the type
+import { getData } from './api'
+export const data = getData() as MyDto[]
+
+// ✅ Better: type getData / wrap with a type-safe function
+```
+
+## Agent requirement
+
+On review and code generation **do not add** new `as Type` on exported entities and on the import → export chain without clear need; when possible fix the type contract at the source.
+- In stores and services when handling API errors, first consider **`instanceof`** on the transport error class from `@/types` following existing code (`http-client.md`, `store-pinia.md`).

package/presets/mavis/nuxt/rules/no-v-bind-spread.md

@@ -0,0 +1,7 @@
+# No bulk `v-bind` object spread
+
+- **Forbidden:** `<Child v-bind="propsObject" />` / `v-bind="rest"` as a way to dump unknown prop bags.
+- **Prefer:** explicit prop bindings (`:title="title" :count="count"`).
+- Exception: intentional passthrough on a thin wrapper documented in-repo (rare); prefer `fallthroughAttributes` / explicit `inheritAttrs` patterns already used by neighbors.
+- Do not "simplify" templates by packing props into a reactive object solely for `v-bind`.
+- Analogue of next `no-props-spread` for Vue SFCs.

package/presets/mavis/nuxt/rules/nuxt-app-core.md

@@ -0,0 +1,40 @@
+# Stack and environment
+
+Concrete versions — **from `package.json` and configs of the target repository**. Preset frame: Nuxt 3, Vue 3, TypeScript; runner/e2e/mocks/UI/APM — as established in the repo.
+
+# Project structure
+
+| Path | Purpose |
+|------|---------|
+| `pages/**` | File-based routes |
+| `components/**` | UI components (SFC) |
+| `composables/**` | Vue `use*` facades |
+| `stores/**` | Pinia stores |
+| `api/**` | Client services + mappers (barrel) |
+| `lib/clients/**`, `api/clients/**` | HTTP (`$fetch` / ofetch) |
+| `server/api/**` | Nitro server routes (BFF) |
+| `types/**` | Domain types (barrel) |
+| `tests/e2e/**` | Playwright e2e |
+
+**Aliases:** prefer `~/`, accept `@/`, respect `#imports` (do not invent auto-import symbols). Scripts cwd — **repository root** (where `nuxt.config.*` lives), not a Next-style `app/` wrapper.
+
+# Architectural layers
+
+| Layer | Directory | Details |
+|-------|-----------|---------|
+| UI | `pages/**`, `components/**`, `layouts/**` | `vue-ui`, `architecture-boundaries-ui` |
+| Composables | `composables/**` | thin orchestration; no raw HTTP |
+| Store | `stores/**` | `store-pinia` — `defineStore` only |
+| API | `api/**` | `api-services`, `http-client` |
+| HTTP | `lib/clients/**`, `api/clients/**` | wrap `$fetch` |
+| Server | `server/api/**` | `security-nuxt`; not a substitute for `api/**` |
+| Types | `types/**` | `public-imports`, `types-jsdoc` |
+
+Boundaries — **`architecture-boundaries`**. Imports `~/types` / `@/types`, `~/api` / `@/api` — **`public-imports`**. **Forbidden:** RTK / `store-rtk`, React/RSC defaults, `app/src/**` paths as the canon.
+
+# Agent work
+
+- Architecture and imports: `architecture-boundaries`, `public-imports`
+- Features: `feature-delivery-workflow` + skill `feature-delivery`
+- After edits: **invoke** `post-change-lint` (requestable); package manager: `package-manager`
+- Copy neighbor patterns; prefer `unknown` over `any`

package/presets/mavis/nuxt/rules/nuxt-pages-routing.md

@@ -0,0 +1,31 @@
+# Nuxt pages & routing
+
+Canonical layout: **Nuxt 3 project root** — `pages/`, `layouts/`, `middleware/`.  
+Nuxt 4 may use `app/` as `srcDir`; mention only as a note — **do not** default globs/examples to Next-style `app/src/**`.
+
+## Routing
+
+- File-based routes under `pages/**`.
+- Layouts in `layouts/**`; select via `definePageMeta({ layout: '…' })`.
+- Route middleware in `middleware/**` (`defineNuxtRouteMiddleware`).
+- Navigation helpers: `<NuxtLink>`, `navigateTo`, `useRouter`, `useRoute` — not `next/link` / `next/navigation`.
+- Server/API routes: `server/api/**` (Nitro) — see `security-nuxt`; domain client services stay in `api/**`.
+
+## Data on pages
+
+- Prefer composables + Pinia for client orchestration.
+- `useFetch` / `useAsyncData` OK when that is the repo pattern — still map to domain models; no raw DTO sprawl in templates.
+- Secrets only via `runtimeConfig` server-side.
+
+## Incorrect
+
+```ts
+import { useRouter } from 'next/navigation'
+```
+
+## Correct
+
+```ts
+const router = useRouter()
+await navigateTo('/items')
+```

package/presets/mavis/nuxt/rules/package-manager.md

@@ -0,0 +1,13 @@
+# Package manager (terminal)
+
+Before **`npm install` / `yarn` / `pnpm` / `bun`** and **`… run …`**, detect the repository package manager and **use only that one**.
+
+## How to detect
+
+1. **`packageManager`** in `package.json` (repository root; in a monorepo — the workspace root where scripts / `nuxt.config.*` live).
+2. **Lockfile** nearby: `yarn.lock` → yarn; `pnpm-lock.yaml` → pnpm; `package-lock.json` → npm; `bun.lock(b)` → bun.
+3. If ambiguous — where `node_modules` lives and which lockfile CI uses.
+
+## Stack notes
+
+Working directory for scripts — **repository root** (directory with `nuxt.config.*`), **not** Next `app/`. Examples: `yarn lint:js`, `pnpm run typecheck`. Do not guess — check the files.