@bonesofspring/ai-rules 0.2.25 → 0.2.26

package/presets/opencode/nuxt/rules/reference-features.md

@@ -0,0 +1,45 @@
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features
+
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
+
+## Reference table
+
+Replace placeholders with **real** paths after `ai-rules init` / team agreement:
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| UI / Presentation | **TBD** | components, styles/data helpers, barrel |
+| State / ViewModel | **TBD** | slice/VM, selectors, types |
+| API / Data | **TBD** | service/repo, mappers, barrel |
+| Domain / Types | **TBD** | domain types, public export |
+| Unit tests | **TBD** | `*.spec` / XCTest naming |
+| E2E / UI tests | **TBD** | cases/plans, page objects / accessibility IDs |
+
+## 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
+
+After init the team maintains **local** gotchas, patterns, and decisions in a consumer-owned store (not in shared core and not only in root `AGENTS.md`):
+
+| Section | What to record |
+|---------|----------------|
+| Gotchas | Recurring traps, fragile spots, “do not do X in this repo” |
+| 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 (`.ai.local/conventions.md`). The file is **not** always-on.
+
+## Related rules
+
+- `code-quality-and-refactoring` — repeat patterns, no deep-import.
+- `feature-delivery-workflow` — layer order.
+- skill `feature-delivery` — end-to-end scenario.
+
+> Concrete path tables, globs, and dogfood checklists live in the stack adapter **Stack notes**.

package/presets/opencode/nuxt/rules/script-setup-conventions.md

@@ -0,0 +1,7 @@
+# Script setup conventions
+
+- Prefer `<script setup lang="ts">` for pages/components/layouts.
+- Named composables / helpers: follow repo naming (`useX`); export functions consistently with neighbors.
+- Prefer `const fn = () =>` / concise handlers where the file already does; do not churn style across untouched files.
+- Auto-imports (`#imports`) OK when Nuxt resolves them — do not invent symbols; verify against `.nuxt/` / docs (`vue-nuxt-anti-hallucination`).
+- Keep business orchestration in composables/stores; keep SFC scripts thin.

package/presets/opencode/nuxt/rules/security-nuxt.md

@@ -0,0 +1,28 @@
+# Security (Nuxt)
+
+## Secrets & config
+
+- Private secrets: `runtimeConfig` (server-only). Public: `runtimeConfig.public` only.
+- Never ship API keys / tokens in client bundles, composables without guard, or `public` config.
+- `.env` / `.env.*` — do not commit secrets; document required keys without values.
+
+## Server (Nitro)
+
+- Validate/authorize in `server/api/**` and `server/middleware/**`.
+- Do not trust client body/query; sanitize inputs.
+- Prefer server proxies for third-party secrets rather than exposing keys to the browser.
+
+## XSS / templates
+
+- Prefer text interpolation; avoid `v-html` unless sanitized and necessary.
+- User-generated content — follow existing sanitize helpers in the repo.
+
+## Auth / CSRF / cookies
+
+- Follow project auth middleware / session patterns; do not invent ad-hoc cookie auth.
+- Cookie flags (`HttpOnly`, `Secure`, `SameSite`) — match security baseline of the repo.
+- CSRF: use established Nuxt/server pattern already in the codebase when mutating state.
+
+## Agent requirement
+
+When touching auth, forms, env, or `server/api`, load this rule and prefer agent `security-reviewer` for risky changes.

package/presets/opencode/nuxt/rules/store-pinia.md

@@ -0,0 +1,61 @@
+# General principles
+
+- Use **Pinia** (`defineStore`) — setup or options store, as neighbors do in the repo.
+- Module: `@pinia/nuxt` (or the installed equivalent) — check `package.json` / `nuxt.config`.
+- Store **domain models**, not raw API DTOs.
+- DTO → domain mapping — in `api/**` (or server mappers) **before** writing to the store.
+- Separate server state (API data) from local UI state (filters/flags) — UI-only may live in a composable/`ref` on the page if that is the repo convention.
+
+# Forbidden in this preset
+
+- RTK / Redux: `createSlice`, `createAsyncThunk`, RTK Query, `useDispatch` / `useSelector`, stem `store-rtk`.
+- Raw `$fetch` / `fetch` from the store bypassing `~/api` / `@/api` services (except narrow documented repo exceptions).
+
+# Structure
+
+- One domain module — its own file under `stores/**` (e.g. `stores/profile.ts`).
+- Export: `useXStore` via `defineStore('x', …)`.
+- State: explicit type; careful initialization.
+- Getters — derived from domain state; actions call services from `~/api` / `@/api` (`public-imports`).
+
+# Async
+
+```ts
+// Incorrect — raw HTTP + DTO in state
+export const useProfileStore = defineStore('profile', {
+  actions: {
+    async load() {
+      this.profile = await $fetch('/api/profile')
+    },
+  },
+})
+
+// Correct
+import { profileApi } from '~/api'
+
+export const useProfileStore = defineStore('profile', {
+  state: (): { profile: Profile | null } => ({ profile: null }),
+  actions: {
+    async load() {
+      this.profile = await profileApi.getProfile()
+    },
+  },
+})
+```
+
+# Typing and errors
+
+- Domain types from `~/types` / `@/types`.
+- Transport errors — contracts from `@/types` / the accepted client error class (`http-client`), not invented axios shapes.
+- In UI: `storeToRefs` for state; call actions directly on the store.
+
+# Testing
+
+- Cover important stores (init, transitions, actions with mocked API).
+- Unit: Vitest; mock `~/api` services.
+
+# Agent requirement
+
+- Do not put HTTP/transport in components.
+- Strictly type state/actions.
+- Follow neighboring store style.

package/presets/opencode/nuxt/rules/technical-retro.md

@@ -0,0 +1,11 @@
+<!-- shared-core: review/technical-retro.md -->
+
+# Technical retro — rule alias
+
+Full scenario (including the **“Agent work”** block for a slug from team tasks) lives in the slash command:
+
+**`commands/technical-retro.md`** → `/technical-retro`
+
+When a task has `metrics.json`, use the local aggregation script and state the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not score malformed artifacts or gate wait as agent work.
+
+Use this rule only if the command is unavailable. Do not duplicate the command contents in the response — follow the command file and skill `technical-retro`.

package/presets/opencode/nuxt/rules/tests-e2e-structure.md

@@ -0,0 +1,72 @@
+<!-- shared-core: testing/testing-principles.md -->
+
+# Testing principles
+
+Stack-agnostic; concrete paths, runners, and selectors live in the stack adapter (`## Stack notes`).
+
+## Behavior vs. implementation
+
+- Verify **behavior and business rules**, not implementation or internal details.
+
+## File naming
+
+- For **new** tests use `*.spec.ts` / `*.spec.tsx`. Do not rename existing `*.test.ts` / `*.test.tsx` without a separate task (legacy).
+
+## Runner and matchers
+
+- Use the project's runner (Jest or Vitest are common); components — the project's Testing Library integration. Reuse existing matchers — no new micro-framework.
+
+## Test title locale
+
+- Consumer apps **may use the project locale** (often Russian) — clear business phrases stating what is checked and the expected outcome.
+- When ESLint enforces the locale (e.g. `jest/valid-title`): each sentence must start with a **capital letter** (including after `.`, `!`, `?`); a space after `.` followed by a lowercase letter is forbidden ("capital after period" violation).
+
+Good (Russian locale in consumer app):
+
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
+
+Bad (no capital after period; or wrong locale for configured ESLint):
+
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `it('Returns empty list when user is guest', () => {})` (wrong locale if ESLint enforces Russian)
+
+## Isolation and mocks
+
+- Mock at the **public-contract boundary**; use the project's accepted HTTP/API/store mock approach. Do not mock what is part of the feature's public contract if that breaks the test's meaning.
+
+## Coverage of cross-cutting modules
+
+- When changing a **shared cross-cutting module** (e.g. HTTP client body parsing, headers, error / auth handling) — **update or add behavior tests** covering success, error, and edge branches relevant to the module under change.
+
+## Data transformation coverage
+
+- Data transformation functions with computed fields and branches must have unit tests covering edge cases (boundary values, missing fields, unexpected value combinations).
+
+## Reuse fixtures over ad-hoc random data
+
+- Prefer shared fixtures / handlers from the project's accepted mocks module; do not duplicate interfaces in tests. Use the API response types (DTO types) and the **target domain types** from the project's public type surface.
+
+## E2E: one canonical scenario plan per feature
+
+- For each feature keep a **single canonical scenario plan** (distinct from implementation specs; the stack adapter names the file — typically `*.cases.md`).
+
+## E2E: scenario ↔ test traceability
+
+- Every scenario has a corresponding test. **Do not weaken** assertions to match an outdated implementation — tests must reflect business expectations from the plan. Colocate plan and executable tests in the same directory.
+
+## E2E: page objects / shared helpers
+
+- Prefer page objects and shared helpers over scattered selectors and per-test setup duplication.
+
+## E2E: stable identifiers (PREFIX-XXX)
+
+- When scenarios need stable IDs, prefix the title with `PREFIX-XXX`: `PREFIX` = first letters of words in the entity under test (Latin uppercase); `XXX` = sequential number with three digits and leading zeros. Within one `PREFIX`, numbers must form a consistent sequence with no duplicates.
+- Example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+
+## E2E: selector priority
+
+- Prefer role/label selectors for accessibility and forms; fall back to `data-testid` for stable elements. Use a **hierarchical naming convention** on page roots and key interactive elements (stack adapter defines the scheme — typically `{parent}__{element}`).
+
+## 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.

package/presets/opencode/nuxt/rules/tests-unit.md

@@ -0,0 +1,72 @@
+<!-- shared-core: testing/testing-principles.md -->
+
+# Testing principles
+
+Stack-agnostic; concrete paths, runners, and selectors live in the stack adapter (`## Stack notes`).
+
+## Behavior vs. implementation
+
+- Verify **behavior and business rules**, not implementation or internal details.
+
+## File naming
+
+- For **new** tests use `*.spec.ts` / `*.spec.tsx`. Do not rename existing `*.test.ts` / `*.test.tsx` without a separate task (legacy).
+
+## Runner and matchers
+
+- Use the project's runner (Jest or Vitest are common); components — the project's Testing Library integration. Reuse existing matchers — no new micro-framework.
+
+## Test title locale
+
+- Consumer apps **may use the project locale** (often Russian) — clear business phrases stating what is checked and the expected outcome.
+- When ESLint enforces the locale (e.g. `jest/valid-title`): each sentence must start with a **capital letter** (including after `.`, `!`, `?`); a space after `.` followed by a lowercase letter is forbidden ("capital after period" violation).
+
+Good (Russian locale in consumer app):
+
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
+
+Bad (no capital after period; or wrong locale for configured ESLint):
+
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `it('Returns empty list when user is guest', () => {})` (wrong locale if ESLint enforces Russian)
+
+## Isolation and mocks
+
+- Mock at the **public-contract boundary**; use the project's accepted HTTP/API/store mock approach. Do not mock what is part of the feature's public contract if that breaks the test's meaning.
+
+## Coverage of cross-cutting modules
+
+- When changing a **shared cross-cutting module** (e.g. HTTP client body parsing, headers, error / auth handling) — **update or add behavior tests** covering success, error, and edge branches relevant to the module under change.
+
+## Data transformation coverage
+
+- Data transformation functions with computed fields and branches must have unit tests covering edge cases (boundary values, missing fields, unexpected value combinations).
+
+## Reuse fixtures over ad-hoc random data
+
+- Prefer shared fixtures / handlers from the project's accepted mocks module; do not duplicate interfaces in tests. Use the API response types (DTO types) and the **target domain types** from the project's public type surface.
+
+## E2E: one canonical scenario plan per feature
+
+- For each feature keep a **single canonical scenario plan** (distinct from implementation specs; the stack adapter names the file — typically `*.cases.md`).
+
+## E2E: scenario ↔ test traceability
+
+- Every scenario has a corresponding test. **Do not weaken** assertions to match an outdated implementation — tests must reflect business expectations from the plan. Colocate plan and executable tests in the same directory.
+
+## E2E: page objects / shared helpers
+
+- Prefer page objects and shared helpers over scattered selectors and per-test setup duplication.
+
+## E2E: stable identifiers (PREFIX-XXX)
+
+- When scenarios need stable IDs, prefix the title with `PREFIX-XXX`: `PREFIX` = first letters of words in the entity under test (Latin uppercase); `XXX` = sequential number with three digits and leading zeros. Within one `PREFIX`, numbers must form a consistent sequence with no duplicates.
+- Example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+
+## E2E: selector priority
+
+- Prefer role/label selectors for accessibility and forms; fall back to `data-testid` for stable elements. Use a **hierarchical naming convention** on page roots and key interactive elements (stack adapter defines the scheme — typically `{parent}__{element}`).
+
+## 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.

package/presets/opencode/nuxt/rules/types-jsdoc.md

@@ -0,0 +1,36 @@
+# Type documentation in `types`
+
+When adding or substantially changing types in this layer **follow the JSDoc style already used in the repository** (see examples: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
+
+## Language and form
+
+- Comment text — **in Russian**, short and to the point: what the type or field means in the domain or API contract.
+- **Do not rely** on tags like `@param`, `@returns`, `@see`, `@deprecated` for type descriptions — they are **not used** in this layer; plain `/** … */` text is enough.
+
+## Exported `type` / `interface`
+
+- Immediately **before the declaration** — a `/** … */` block.
+- If you need to explain data source, constraints, or non-obvious bits — a **second paragraph** in the same block (blank line between paragraphs in JSDoc).
+- For **nested** objects in the same file, each such type gets its own block above its declaration.
+
+## Fields
+
+- Every **public** property — a **one-line** `/** … */` on the line immediately **above** the field.
+- If a field **does not come from the backend “as is”** but is computed or enriched on the frontend (mapper, selector, UI) — start the description with the **`[computed]`** prefix (as in `TUserProfile`, treatment-plan types).
+- For data formats, state that **in the text**: e.g. date `YYYY-MM-DD`, example display string in quotes.
+
+## Classes and other declarations
+
+- For **classes** (e.g. transport errors), when changing the public API — a short block above the class and **comments on public fields** by the same rules as interface properties.
+
+## `enum`
+
+- In `enums.ts` historically often **without JSDoc** on each member; for new enums a short description **above the enum itself** is OK if purpose is not obvious from the name. UI labels — as usual, via `*Names` objects next to the enum.
+
+## Agent practice
+
+- When adding a new type or field, **do not leave** new public fields unexplained if the meaning is not 100% equal to the name.
+- When editing a file that already has such comments, **keep the same style**, do not mix with English or “tag-style” blocks.
+- Do not inflate comments: one–two phrases per type, one line per field — normal; exception — a truly complex domain caveat.
+
+See also imports and barrel: `public-imports.md`.

package/presets/opencode/nuxt/rules/ux-design.md

@@ -0,0 +1,99 @@
+<!-- shared-core: review/ux-design.md -->
+
+# UX design checklist
+
+On-demand behavioral UX checklist (IA, named flows, state matrix). **Procedure:** skill `ux-design`. **Producer:** `task-analyst` (not a pipeline agent). Do not inline this checklist into the analyst prompt.
+
+Stack-agnostic: no app-source globs, Playwright, or `xcodebuild`. Form-factor **examples** live in adapter **Stack notes** only.
+
+## When to load
+
+- Standalone `/task` intent `ux-design` (modes `synthesize` | `review`; profile `light`; steps only `task-analyst`)
+- Embedded on a UI-capable stack when **required-signal** or advisory UI AC fires on `feature` / `refactor` / `spike` / `spec-gen`
+- Required-signal (any one): the user asked for UX, **or** AC explicitly require flows/states, **or** intent is `spec-gen` / `/spec-start` for a **page/feature**. Else **advisory** (notes only; skip if no UI surface)
+- **Do not** load for backend-only AC even on a UI stack. Classify `mockup-review` (Figma) before `ux-design` before `review-only`
+
+## Inputs
+
+1. Task `artifact-manifest.json`, then prompt / `brief.md` / `decomposition.md` when present
+2. Skill `ux-design` + this rule
+3. Approved `docs/specs` only as product-behavior SoT **after** UX synthesis maps via Spec feed — do not write INDEX here
+
+## Forbidden Figma MCP
+
+Do **not** call Figma MCP. Only `mockup-reviewer` reads Figma. Forbidden by name: `get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`.
+
+When `figma.com` is present and required-signal fires, emit a **thin** `ux-design.md` from AC only (IA/flows the mockup must cover; no visual or DS claims). If the user only pasted a URL and AC are visual, the UX file may be omitted; `mockup-review.md` coverage stands.
+
+Do **not** write BMAD-style `DESIGN.md` or a second visual spine. One experience artifact: `ux-design.md`.
+
+## Modes
+
+| Mode | When |
+|------|------|
+| `synthesize` | Design UX from a brief/AC (standalone «разработай UX» / embedded required-signal) | <!-- i18n-keep: E4 -->
+| `review` | Critique a brief/wireframe/description **without** Figma («ревью UX»). Figma + review-not-implement remains intent `mockup-review` | <!-- i18n-keep: E4 -->
+
+## Required vs advisory
+
+- **Required** when required-signal fires (user-asked-ux / ac-requires-flows-states / spec-gen-page-feature)
+- **Advisory** otherwise (UI AC without those signals). Advisory `INCOMPLETE` → notes only; DoR may complete
+- Skip the skill when there is no UI surface or the prompt is empty of UX-relevant AC
+
+## Verdicts
+
+`PASS` | `PASS_WITH_NOTES` | `INCOMPLETE`. Never copy the mockup FAIL-only hook (`changes_requested` + do-not-retry-developer). Incomplete UX is an analyst/DoR problem.
+
+| Verdict | Required step | Advisory step | Standalone intent `ux-design` |
+|---------|---------------|---------------|-------------------------------|
+| `PASS` / `PASS_WITH_NOTES` | Analysis may complete DoR | Analysis may complete | `completed` |
+| `INCOMPLETE` | DoR **not** met: `open_questions` / blocked analysis; existing `after:task-analyst` gate | Notes only; DoR may complete | `completed` (report-only) |
+
+**Block (`INCOMPLETE` as DoR failure) only when the step was required and primary flows *or* the empty/error/loading matrix are missing.** Isolated missing microcopy or optional protagonist names never block.
+
+## Surface-closure
+
+Each stated need → a surface; each surface → a flow that lands there. If closure fails, list probes under **Open probes** — **do not invent** screens, flows, or copy to fill gaps.
+
+## Spec feed
+
+Analyst remains the **only** writer of `docs/specs` INDEX and page/feature files. Map `ux-design.md` → templates **after** UX synthesis (UX before `spec-authoring` author mode):
+
+| `ux-design.md` heading | Page template | Feature template |
+|------------------------|---------------|------------------|
+| Scope + IA | **Overview** | **Overview** |
+| Entry / actors | **Entry / actors** | — (page-level) |
+| Primary flows | **Primary flows** | **Shared behavior / constraints** when a flow is cross-page |
+| States | **States** (loading/empty/error/success) | **Cross-cutting states** when shared |
+| Interaction notes + microcopy direction | Inform **Acceptance criteria**; leftover → **Edge cases** | Shared constraints |
+| Accessibility floor (behavioral) | Testable AC without pixels; else Edge cases | Shared constraints |
+| Surface-closure probes | Analyst `open_questions` — **do not** invent spec rows | Same |
+
+## Manifest
+
+When produced, append `ux-design.md` to the **`analysis`** entry `authoritativePaths` and `evidencePaths`. Do **not** add a new default producer row for v1 (`ux-designer` is deferred).
+
+## Report headings
+
+Write `ux-design.md` with these headings (must match the architecture artifact contract):
+
+```markdown
+# UX design: <slug>
+## Mode
+synthesize | review
+## Verdict
+PASS | PASS_WITH_NOTES | INCOMPLETE
+## Scope
+- Form factor: web | ios | android | mixed
+- Figma present: yes | no
+- Required-signal: user-asked-ux | ac-requires-flows-states | spec-gen-page-feature | advisory
+## Information architecture
+## Entry / actors
+## Primary flows
+## States
+## Interaction notes
+## Microcopy direction
+## Accessibility floor (behavioral)
+## Spec feed
+## Open probes
+```

package/presets/opencode/nuxt/rules/vue-a11y-coding.md

@@ -0,0 +1,9 @@
+# Vue accessibility
+
+- Semantic HTML first (`button`, `nav`, `main`, headings hierarchy).
+- Interactive controls keyboard-reachable; visible focus.
+- Images: meaningful `alt` (or empty alt for decorative).
+- Forms: label association; error text linked via `aria-describedby` / native validation patterns used in repo.
+- Prefer project a11y eslint (`eslint-plugin-vuejs-accessibility` when present) over inventing ARIA.
+- Modals/dialogs: focus trap + Escape — follow existing component patterns.
+- Do not rely on color alone for status.

package/presets/opencode/nuxt/rules/vue-nuxt-anti-hallucination.md

@@ -0,0 +1,62 @@
+# Vue / Nuxt / Pinia anti-hallucination
+
+These rows **OVERRIDE** generation for the listed patterns. Before inventing an import, composable, or store helper: verify against `package.json` (installed majors), `nuxt.config.*`, and sibling files. If unsure, mark `// VERIFY: lib.symbol @ version` and surface the uncertainty — do not silently stub.
+
+Routing-specific rows stay in **`nuxt-pages-routing`**. This rule covers broader Vue / Nuxt / Pinia phantoms across the app tree.
+
+## 1. Phantom / wrong Nuxt imports
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `import { useRouter } from 'next/navigation'` / `next/router` | Nuxt auto-import `useRouter` / `useRoute` / `navigateTo` |
+| `import Link from 'next/link'` / `<Link>` from Next | `<NuxtLink>` |
+| `import Image from 'next/image'` | `<NuxtImg>` / project image helper (check `@nuxt/image`) |
+| Invented: `nuxt/app/router`, `nuxt/server-only`, `nuxt/auth` | Real `#app` / `#imports` / documented Nuxt APIs for **installed** major |
+| `defineNuxtConfig` options copied from blogs without checking major | Match installed Nuxt + existing `nuxt.config.*` |
+| Pages Router Next APIs (`getServerSideProps`) in Nuxt | `useAsyncData` / `useFetch` / server routes / Pinia — mirror siblings |
+
+## 2. SSR / client boundary
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Reading secrets via `useRuntimeConfig().apiSecret` in client-only UI blindly | Private keys under `runtimeConfig` (server); public under `runtimeConfig.public` |
+| Using `window` / `document` in setup without client guards | `onMounted`, `import.meta.client`, `<ClientOnly>` |
+| Pinia stores that assume browser storage during SSR without pattern | Persist plugins / cookie patterns already in repo; guard client APIs |
+| Importing Node-only modules into universal SFC setup | Keep in `server/**` or server-only utils |
+
+## 3. Vue patterns
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| React hooks in Vue SFCs (`useState`/`useEffect` from `react`) | `ref` / `reactive` / `computed` / `watch` / lifecycle (`onMounted`, …) |
+| `import { useEffectEvent } from 'vue'` (phantom) | Real Vue APIs for installed major; else local pattern + `VERIFY` |
+| Options API churn in a `<script setup>` codebase | Follow neighbor SFCs (`script-setup-conventions`) |
+| Phantom packages: `@vue/nonexistent`, invented `~/composables/useServerQuery` | Only lockfile packages + composables that exist |
+
+## 4. Pinia phantoms
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| RTK APIs: `createSlice`, `createAsyncThunk`, `useDispatch` | `defineStore` + actions (`store-pinia`) |
+| Invented helpers: `definePiniaApi`, `store.injectEndpoints` | Documented Pinia + patterns from existing `stores/**` |
+| Deep imports breaking public API: `~/stores/foo/internal` | Public store module / naming used by siblings |
+| Storing raw transport DTOs in state | Domain models from `~/types` after mapper in `api/**` |
+
+## 5. Navigation / data / fetch
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Raw `$fetch` / `fetch` from SFC bypassing `~/api` | Services via `~/api` / `@/api` (`api-services`, `http-client`) |
+| Invented `useFetch` option names siblings never use | Copy from sibling; verify Nuxt data-fetching docs for installed major |
+| Axios error shapes when the client is ofetch/`$fetch` | Transport errors from project types / ofetch patterns |
+| Assuming `baseURL` without checking Nitro / runtimeConfig | Match `lib/clients` / existing client wrapper |
+
+## 6. Version drift / auto-imports
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Bleeding-edge Nuxt/Vue APIs without checking `package.json` | Confirm majors; copy a compiling sibling |
+| Inventing `#imports` symbols that are not generated | Check `.nuxt/imports` / docs; explicit import if missing |
+| Mixing Vue 2 Options-only APIs into Vue 3 Nuxt 3 apps | Vue 3 idioms used in repo |
+
+When a row conflicts with a verified sibling pattern in this repo, **the sibling wins** — update this banlist in a preset PR rather than inventing a third path.

package/presets/opencode/nuxt/rules/vue-ui.md

@@ -0,0 +1,27 @@
+# Vue UI (Nuxt)
+
+- Prefer **SFC** with `<script setup lang="ts">` (`script-setup-conventions`).
+- Explicit `defineProps` / `defineEmits` (typed); no bulk `v-bind="object"` (`no-v-bind-spread`).
+- Styles: scoped / CSS modules / design tokens — as neighbors; property order — `css-property-order-stylelint`.
+- Data: read Pinia / composables; **do not** call HTTP from SFC — only via `~/api` / store actions.
+- Navigation: `<NuxtLink>`, `navigateTo`, `useRouter` / `useRoute` — not `next/link` / `next/navigation`.
+- A11y: `vue-a11y-coding`.
+- UI boundaries: `architecture-boundaries-ui` — no DTO in templates; map in `api/**`.
+
+## Incorrect
+
+```vue
+<script setup lang="ts">
+const data = await $fetch('/api/items')
+</script>
+```
+
+## Correct
+
+```vue
+<script setup lang="ts">
+import { useItemsStore } from '~/stores/items'
+const store = useItemsStore()
+onMounted(() => { void store.load() })
+</script>
+```

package/presets/opencode/nuxt/skills/README.md

@@ -0,0 +1,21 @@
+# `.opencode/skills` (preset nuxt)
+
+Project skills for Cursor. They keep long workflows out of always-on rules while preserving the same team conventions as the Claude preset.
+
+| Skill | When to use |
+|-------|-------------|
+| `feature-delivery` | End-to-end feature work across types, API, store, UI, tests |
+| `spec-authoring` | Author or bootstrap docs/specs (INDEX, page/feature templates); `/spec-start` / analyst author mode |
+| `spec-discovery` | Opt-in research-before-spec in analyst author mode (claim ledger; not default `/task` consume) |
+| `mockup-review` | Figma mockup review: DS, coverage, viewports (standalone or embedded) |
+| `ux-design` | Behavioral UX synthesis/review via task-analyst (standalone or embedded; no Figma MCP) |
+| `code-review` | MR/diff review using project architecture and test standards |
+| `debug-investigation` | Reproducing and fixing bugs with root-cause evidence |
+| `ci-investigation` | Diagnosing and fixing failing CI checks on PRs/branches |
+| `unit-testing` | Planning, generating, or healing unit test coverage |
+| `playwright-e2e` | Planning, generating, or healing Playwright e2e coverage |
+| `technical-retro` | Technical retrospective for a task, sprint, incident, or agent pipeline |
+| `write-adr` | Author an Architecture Decision Record (context / decision / consequences) |
+| `vue-performance` | Implementer checklist: bundle, SSR/payload/client, memo, waterfalls, CWV (not a perf audit agent) |
+
+Skills are copied to `.opencode/skills/` by `ai-rules init opencode --preset nuxt`.

package/presets/opencode/nuxt/skills/ci-investigation/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ci-investigation
+description: Investigates failing CI checks on PRs and branches — lint, typecheck, unit, e2e — with local reproduction and minimal fixes. Use when CI is red or for ci-fix pipeline tasks.
+---
+
+# CI Investigation
+
+## Workflow
+
+1. Identify the **first failing check** (lint, typecheck, unit, e2e, build).
+2. Capture error output — ignore cascading failures until root cause is found.
+3. Reproduce locally with the same commands CI uses from repository root:
+   - `lint:js`, `lint:css`, `typecheck`
+   - targeted unit test file or suite
+   - affected Playwright spec if e2e failed
+4. Inspect git diff for changed files related to the failure.
+5. Apply **minimal fix** — no unrelated refactors.
+
+## Artifact
+
+Write `ci-report.md` under the task slug folder:
+
+- Failed check name and link/log excerpt
+- Root cause classification
+- Fix applied (or handoff to feature-developer)
+- Validation commands and results
+
+
+## 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 a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
+## Handoff Rules
+
+- Config-only or one-line fixes → fix in place, re-run check.
+- Missing tests or architecture work → document and route to `feature-developer` or `qa-tester`.
+- Flaky e2e → prefer `playwright-test-healer` after ci-investigator identifies the spec.
+
+## Validation
+
+Always re-run the failing command locally before marking complete. If environment blocks execution, state the exact command and blocker.

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

@@ -0,0 +1,44 @@
+---
+name: code-review
+description: Reviews pull requests, merge requests, git diffs, and branch changes using the preset's architecture, import, UI, API, and testing standards. Use when the user asks for review or when code-reviewer runs in an agent pipeline.
+---
+
+# Code Review
+
+## Inputs
+
+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
+
+1. Understand the intent and affected layers.
+2. Check correctness and regressions first.
+3. Verify architecture boundaries: UI does not know DTO/transport, store does not depend on UI, API services do not pull UI/store.
+4. Check public imports through `@/types` and `@/api`, plus barrel updates for new public symbols.
+5. Review UI consistency, styling conventions, and prop shape.
+6. Check tests: unit for mapper/domain logic, behavior tests for HTTP client changes, e2e plan/spec updates for user flows.
+7. **Reuse lens:** flag new helpers that duplicate existing utilities; prefer adjacent shared modules over copy-paste.
+8. **Efficiency lens:** unnecessary work, sequential ops that should be parallel, hot-path bloat, no-op store updates, overly broad reads.
+9. Report validation gaps: lint, stylelint, typecheck, or relevant tests not run.
+
+## Output
+
+Lead with findings ordered by severity. Required shape (also in `code-review-mr`):
+
+- Each finding: **`path:line`** — problem — impact — concrete fix direction.
+- Severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- Vague («looks risky») is not a finding — cite evidence or ask for surrounding context.
+- 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 `.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
+
+<!-- shared-core: review/receiving-code-review.md -->
+
+When **implementing** review comments (not when issuing them): verify each item against the codebase before changing code; do not perform agreement (`You're absolutely right!`). Unclear items → ask, do not guess.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.