@bonesofspring/ai-rules 0.2.24 → 0.2.26

package/presets/opencode/svelte/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/opencode/svelte/rules/http-client.md

@@ -0,0 +1,10 @@
+# HTTP client
+
+- One HTTP stack for the app: wrap **`fetch`** (or the shared client already in `src/lib/clients/**`).
+- Do not mix ad-hoc `axios`/`ky` in features if a shared client exists.
+- Services in `src/lib/api/**` call the wrapper — UI/stores do not own transport.
+- In `load` / form actions, prefer the provided `event.fetch` for same-origin SSR cookie forwarding when calling own endpoints.
+- Map responses to domain models in services/mappers before stores/runes.
+- Errors: use project transport error types from `$lib/types`; narrow with `instanceof` when available.
+- Base URL / auth: from `$env/*` / existing client factories — do not hardcode secrets.
+- Calling relative `/api/*` (`+server.ts` BFF) from the client is fine when that is the repo pattern — still through services.

package/presets/opencode/svelte/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 `.opencode/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/opencode/svelte/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/opencode/svelte/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/opencode/svelte/rules/navigation-router-stack.md

@@ -0,0 +1,34 @@
+# Navigation (stack)
+
+For this preset the canon is **SvelteKit** (`svelte-app-core`, `sveltekit-routing`).
+
+## Check in the repo
+
+1. `package.json` workspace with `svelte.config.*` — `@sveltejs/kit` / `svelte` majors.
+2. How neighbors already navigate: `goto`, `invalidate`, `beforeNavigate`, `<a href>`, wrappers.
+3. Do not mix in Next (`next/navigation`) or Nuxt (`navigateTo`, `<NuxtLink>`) by default.
+
+## API
+
+| Need | Prefer |
+|------|--------|
+| Programmatic navigate | `goto` from `$app/navigation` |
+| Refresh load data | `invalidate` / `invalidateAll` |
+| Guards | `beforeNavigate` / `afterNavigate` |
+| Links in UI | see `navigation-router-ui` |
+
+Verify exports against installed `@sveltejs/kit` — mark `// VERIFY` if unsure (`svelte-sveltekit-anti-hallucination`).
+
+## Incorrect
+
+```ts
+import { useRouter } from 'next/navigation'
+await navigateTo('/items')
+```
+
+## Correct
+
+```ts
+import { goto } from '$app/navigation'
+await goto('/items')
+```

package/presets/opencode/svelte/rules/navigation-router-ui.md

@@ -0,0 +1,19 @@
+# Navigation (UI)
+
+- Prefer native **`<a href="…">`** (and design-system Link wrappers that render anchors).
+- Active state: follow repo pattern (`page.url`, `$app/state` / `$app/stores` as version allows — verify).
+- Prefetch: use Kit data-sveltekit-* attributes / patterns already in the repo — do not invent.
+- Do not use `next/link`, `<NuxtLink>`, or `RouterLink` as defaults in this preset.
+- Programmatic navigation from UI handlers → `goto` (`navigation-router-stack`).
+
+## Incorrect
+
+```svelte
+<a on:click|preventDefault={() => location.href = '/x'}>Go</a>
+```
+
+## Correct
+
+```svelte
+<a href="/x">Go</a>
+```

package/presets/opencode/svelte/rules/no-rest-props-spread.md

@@ -0,0 +1,26 @@
+# No rest-props spread
+
+- Prefer **explicit props** via `$props()` (Svelte 5) or typed props — name what the component accepts.
+- Do **not** default to `{...props}` / `$$restProps` / bulk forwarding of unknown bags onto DOM or child components.
+- Narrow exceptions OK when following an established neighbor pattern (e.g. design-system polymorphic wrapper) — document why in a short comment.
+- Analogue of next `no-props-spread` / nuxt `no-v-bind-spread` — **do not** ship those stems in this preset.
+
+## Incorrect
+
+```svelte
+<script lang="ts">
+  let props = $props()
+</script>
+
+<button {...props}>…</button>
+```
+
+## Correct
+
+```svelte
+<script lang="ts">
+  let { label, onclick }: { label: string; onclick?: () => void } = $props()
+</script>
+
+<button type="button" {onclick}>{label}</button>
+```

package/presets/opencode/svelte/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 slices and services when handling API errors, first consider **`instanceof`** on the transport error class from `@/types` following existing code (`http-client.md`, `store-svelte.md`).

package/presets/opencode/svelte/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` (SvelteKit root / workspace root where scripts / `svelte.config.*` live).
+2. **Lockfile** beside it: `yarn.lock` → yarn; `pnpm-lock.yaml` → pnpm; `package-lock.json` → npm; `bun.lock(b)` → bun.
+3. If ambiguous — where `node_modules` is and which lockfile CI uses.
+
+## Stack notes
+
+Working directory for scripts — **SvelteKit root** (directory with `svelte.config.*`), **not** Next `app/` and do not assume `nuxt.config.*`. Examples: `yarn lint:js`, `pnpm run check`. Do not guess — check the files.

package/presets/opencode/svelte/rules/playwright-agents.md

@@ -0,0 +1,74 @@
+# Playwright Agents in this project
+
+In this repository, Playwright Agents (planner, generator, healer) **must follow the existing e2e structure**:
+
+- **Test directory**: `tests/e2e`
+- **Test plans (specs)**: `*.cases.md` files under `tests/e2e/**`
+- **Executable tests**: `*.spec.ts` files under `tests/e2e/**`
+- **Seed test**: `tests/e2e/seed.spec.ts`
+
+Do **not** introduce separate top-level `specs/` and `tests/` folders for real test coverage. Those may be used only as temporary sandboxes if explicitly requested.
+
+## Planner (test plans)
+
+When acting as a **Planner** (or working with the Playwright planner agent):
+
+- **Treat `*.cases.md` as the canonical test plan files**, equivalent to Playwright's `specs/*.md`.
+- **Location**:
+  - For a feature/domain, use the corresponding `*.cases.md` file under `tests/e2e`, e.g.:
+    - `tests/e2e/OrderHistory/order-history.cases.md`
+    - `tests/e2e/BillingReport/invoice-list.cases.md`
+- **Content requirements**:
+  - Group scenarios by feature and subfeature using headings.
+  - For each scenario include:
+    - clear title,
+    - preconditions,
+    - ordered steps,
+    - expected results.
+  - Write in concise business language, but precise enough for automatic test generation.
+- **Seed**:
+  - Assume environment is prepared by `tests/e2e/seed.spec.ts` (login, baseURL, mocks, etc.).
+
+When asked to "generate a test plan" for a feature, **create or update the appropriate `*.cases.md` file in `tests/e2e/**`**, not in a separate `specs/` folder.
+
+## Generator (tests from plans)
+
+When acting as a **Generator** (or working with the Playwright generator agent):
+
+- **Source of truth for scenarios**:
+  - Use the relevant `*.cases.md` file under `tests/e2e/**` as the test plan.
+- **Target for tests**:
+  - Generate or update `*.spec.ts` files under the same folder, e.g.:
+    - plan: `tests/e2e/OrderHistory/order-history.cases.md`
+    - tests: `tests/e2e/OrderHistory/order-history.spec.ts` (or additional `*.spec.ts` in that folder if needed).
+- **Structure**:
+  - Use `test.describe` to group by top-level plan sections (feature / user flow).
+  - Use `test(...)` titles that match scenario names from the plan.
+  - Prefer Page Object and fluent interfaces that already exist in this project, for example:
+    - `tests/e2e/OrderHistory/OrderHistoryPage.ts`
+    - shared helpers under `tests/e2e/_shared/`.
+- **Seed**:
+  - If a seed test is needed, use `tests/e2e/seed.spec.ts` as the reference for environment setup.
+
+Do **not** generate Playwright tests into a separate `tests/` folder by default. Keep all e2e tests under `tests/e2e/**` to respect project conventions.
+
+## Healer (fixing tests)
+
+When acting as a **Healer** (or working with the Playwright healer agent):
+
+- Operate only on `*.spec.ts` files under `tests/e2e/**`.
+- Use `*.cases.md` in the same folder as **documentation of the intended behavior**:
+  - Do not weaken or change business assertions in tests in a way that conflicts with the corresponding `*.cases.md`.
+  - Prefer updating locators, waits, and flow details to match the UI while keeping the scenario semantics intact.
+- When multiple specs are involved, prioritize:
+  - the spec file in the same folder as the failing test,
+  - then shared utilities in `tests/e2e/_shared/`.
+
+Healer should keep tests aligned with the existing test plans (`*.cases.md`) and with the page objects and helpers already used in the project.
+
+
+## Stack notes (SvelteKit)
+
+- E2E root: `tests/e2e/`.
+- Default baseURL: `http://localhost:5173`.
+- Prefer Playwright `webServer` → `vite dev` or `vite build && vite preview`.

package/presets/opencode/svelte/rules/post-change-lint.md

@@ -0,0 +1,37 @@
+# Linters after code changes
+
+**Requestable, but required on code changes:** the rule is not always-on (context savings); after source edits the agent **must** follow this checklist.
+
+## When to apply
+
+After **any** source change under `src/routes/**`, `src/lib/**`, `src/hooks.*.ts`, `src/params/**`, `tests/**` (Svelte/TS/JS, CSS, `<style>`).
+
+Exceptions: docs, CI configs, `.opencode/rules/**`, when application executable code did not change.
+
+**Pipeline exception:** if the task goes through the agent team and the next step is `build-verifier`, the developer may limit lint/check to **changed files**; the full run is `build-verifier`’s duty. In single-agent mode (no pipeline) — always a full run.
+
+## Required commands
+
+Working directory — **SvelteKit root** (where `svelte.config.*` lives). Package manager — **`package-manager`**.
+
+1. **`lint:js`** — full project ESLint (`eslint-plugin-svelte` when configured).
+2. **`lint:css`** — full Stylelint.
+
+Point lint on a single file **does not replace** a full run before finishing the task (except the pipeline exception above).
+
+## Algorithm
+
+1. Finish code edits.
+2. Run **`lint:js`** and **`lint:css`** from SvelteKit root.
+3. Analyze the full output; fix errors/warnings in changed files; for Stylelint — autofix if available.
+4. Repeat until exit code 0 or record a blocker in the user reply.
+5. **`check`** (`svelte-kit sync && svelte-check`) when TypeScript / `.svelte` / SvelteKit config changed. CI-level: **`lint`** (= `lint:js` + `lint:css` + `check`).
+
+**Type/svelte gate script name is `check`**, not Next’s `type-check` and not Nuxt’s `typecheck`. Binary — `svelte-check`; package script — **`check`**.
+
+## What to fix
+
+- **Errors** — required.
+- **Warnings** — required in task files; outside scope — mention if they block a zero exit code.
+
+Configs: `eslint.config.js` / `eslint.config.mjs` / `.eslintrc*`, `.stylelintrc*` (CSS property order — `css-property-order-stylelint`).

package/presets/opencode/svelte/rules/preset-layering.md

@@ -0,0 +1,27 @@
+<!-- shared-core: meta/preset-layering.md -->
+
+# Preset layering
+
+Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in consumer apps.
+
+## Layers
+
+| Layer | Where | What to put |
+|-------|-------|-------------|
+| **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
+
+## Where to put a new rule
+
+1. Shared principles for all stacks → **core** + adapters with `<!-- shared-core: … -->`.
+2. Only one of the installable stacks (`next` / `nuxt` / `svelte` / `ios-swift` / `android-kotlin` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (not in `_shared`).
+3. Only Cursor, Claude, Mavis, or OpenCode packaging → platform artifact / frontmatter; do not duplicate semantics.
+
+## SoT
+
+- Packages path — SoT; root `.cursor/` — dogfood sync.
+- Per stack: **Cursor** `presets/cursor/<stack>/` → Claude twin same PR.
+- `_shared` is **not** a `--preset` and is not copied by CLI `init`.
+
+See also: `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`.