@bonesofspring/ai-rules 0.2.23 → 0.2.24

package/presets/opencode/next/opencode.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@upstash/context7-mcp@4.0.2"
+      ]
+    },
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@playwright/mcp@0.0.79"
+      ]
+    },
+    "chrome-devtools": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "chrome-devtools-mcp@1.7.0"
+      ]
+    },
+    "figma": {
+      "type": "remote",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}

package/presets/opencode/next/rules/README.md

@@ -0,0 +1,20 @@
+# OpenCode Next rules
+
+Plain Markdown. OpenCode does **not** auto-load these files. Root `AGENTS.md`
+and `.opencode/AGENTS.md` list four essential paths to Read immediately; the
+rest are lazy-loaded when the task matches.
+
+Do not put this catalog into `opencode.json` `instructions` as the only
+always-on path (V2 may ignore that field).
+
+## Essential (entry-critical)
+
+`next-app-core`, `package-manager`, `code-quality-and-refactoring`,
+`ai-local-overlay`.
+
+## Requestable
+
+All other `*.md` files in this directory. Same stems as Cursor
+`rules/README.md`.
+
+Shared-core markers (`<!-- shared-core: … -->`) are preserved from Cursor.

package/presets/opencode/next/rules/agent-team-intake.md

@@ -0,0 +1,11 @@
+<!-- shared-core: agent-team/agent-team-intake.md -->
+
+# Agent team intake
+
+When the user message looks like a **work request** (implement, add, fix, refactor, review MR, write tests, spike) — not a question about how code works:
+
+1. Prefer **`/task <their request>`** or invoke **task-router** first.
+2. Do not jump straight to coding without router + pipeline when scope is non-trivial.
+3. Pure questions (“how does X work”, “explain”) — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
+
+Exceptions: user explicitly says “no pipeline”, “just do it”, or continues an active slug.

package/presets/opencode/next/rules/agent-team-orchestrator.md

@@ -0,0 +1,214 @@
+<!-- shared-core: agent-team/agent-team-orchestrator.md -->
+
+# Agent team orchestrator
+
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.opencode/team/tasks/<slug>/` (Claude: `.claude/team/tasks/<slug>/`).
+
+Work request without `/task` — see **agent-team-intake** (when to suggest the router instead of coding directly).
+
+## Entry points
+
+| Command | When |
+|---------|------|
+| **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After human gate or pause |
+| `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
+| `/technical-retro [slug]` | Retro with agent team block |
+
+## Roles (shared catalog)
+
+Roster of specialists is **stack-specific** (agent names and write scopes differ). See **Stack notes** in the stack adapter for the live Roles table. Common patterns:
+
+| Kind | Examples (names vary by stack) |
+|------|--------------------------------|
+| Planning | `task-router`, `task-analyst` (plus skill `ux-design` for behavioral UX **where the stack has a UI surface**), `solution-architect`, `migration-specialist` |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer and `mockup-reviewer` **only when the stack has a UI surface** |
+| Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
+| Docs | `tech-writer` |
+
+**OpenCode frontmatter:** all team pipeline agents use `mode: subagent` and `permission.edit` so they can write team artifacts (`edit: allow` for implementers; deny except `.opencode/team/**` for reviewers/planners). Production/app restrictions live in the agent prompt body. See `agents/README.md`.
+
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`; schema SoT: **agent-artifact-contracts**.
+
+## Stack notes
+
+Roles, write scopes, and OpenCode `mode` / `permission` packaging — **`agents/README.md`**.
+
+## Dynamic pipeline
+
+```mermaid
+flowchart TD
+  task["/task prompt"]
+  router["task-router"]
+  pipeline["pipeline.json"]
+  step0["steps 0..N"]
+  gate{"humanGates?"}
+  hook["subagentStop hook"]
+  retro["/technical-retro"]
+
+  task --> router
+  router --> pipeline
+  pipeline --> step0
+  step0 --> gate
+  gate -->|"/task-continue"| step0
+  step0 --> hook
+  hook --> step0
+  step0 --> retro
+```
+
+**Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
+
+## Routing decision contract
+
+Keep top-level `profile` (`light` | `standard` | `full`) and add a top-level `routingDecision` object:
+
+```json
+{
+  "profile": "standard",
+  "routingDecision": {
+    "complexity": "moderate",
+    "riskFlags": ["behavior-regression"],
+    "routingReasons": [
+      "The failure needs root-cause analysis before a bounded fix.",
+      "Behavior changes require validation and independent review."
+    ],
+    "estimatedWorkPackages": 1,
+    "openDecisionCount": 0
+  }
+}
+```
+
+| Field | Contract |
+|-------|----------|
+| `complexity` | `low` \| `moderate` \| `high`; classify scope and coordination, not perceived coding difficulty |
+| `riskFlags` | Array of concrete signals such as `public-contract`, `cross-layer`, `security-sensitive`, `migration`, `destructive`, `concurrency-state`, `external-dependency`, `unclear-acceptance-criteria`, `broad-test-surface`, `behavior-regression` |
+| `routingReasons` | Non-empty, auditable facts from the request; each reason explains a profile, gate, specialist, skip, or checkpoint choice |
+| `estimatedWorkPackages` | Integer ≥1; count meaningful independently verifiable delivery scopes, not files or agents |
+| `openDecisionCount` | Integer ≥0; unresolved product/architecture/contract choices at routing time |
+
+Rubric:
+
+- `low`: one bounded scope, explicit acceptance criteria, reversible change, no risk flags or open decisions. Use `light` only when stack verification policy permits.
+- `moderate`: several files or adjacent concerns, a regression/refactor with known boundaries, or one contained risk flag. Usually `standard`.
+- `high`: cross-layer/public-contract work, migration/destructive/security/concurrency risk, broad test surface, multiple work packages, or unclear acceptance criteria. Usually `full`.
+- Increase the profile when risk, open decisions, or required checkpoints demand it; do not lower complexity merely because the implementation is familiar.
+- Do not write generic reasons such as “standard by default.” Name the observed signal and the routing consequence.
+
+Existing pipelines without `routingDecision` remain valid; routers emit it for new pipelines. The block is documentary routing evidence in P0 and does not change hook behavior.
+
+## Metrics lifecycle
+
+For local metrics policy and the `metrics.json` ledger, see **agent-task-metrics**. The orchestration runtime records `task_started` and one `attempt_started` before each invocation; the hook records host-clock terminal and human-gate events. Keep active attempt identities in `status.json.activeAttempts` so parallel completions can be bound safely.
+
+Do not calculate durations in agents. For parallel steps, never attribute a stop using `currentAgent` alone: use a stable runtime identity, the sole active attempt, or an explicit receipt marked with fallback confidence.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json`: `.opencode/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. The full schema and completion conventions live in **agent-artifact-contracts**.
+
+- Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
+- Markdown remains detailed evidence; the manifest points to authoritative paths and records producer, status, timestamps, outcome, and evidence paths.
+- Agents upsert only entries they own and preserve foreign entries. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite unrelated state, gate, retry, attempt, timestamp, or metrics fields.
+- Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
+
+## status.json (pipeline mode)
+
+```json
+{
+  "slug": "...",
+  "intent": "feature",
+  "pipelineIndex": 0,
+  "currentAgent": "task-analyst",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
+  "parallelCompleted": [],
+  "parallelOutcomes": {}
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `activeAttempts` | Transient timing bridge keyed by `attemptId` |
+| `lastCompletedAttempt` | Diagnostic pointer to the latest finished attempt |
+| `parallelCompleted` | Agents that have stopped in the current parallel step |
+| `parallelOutcomes` | Per-agent `{ outcome, attemptId, confidence }` for the current parallel join; cleared when the step advances or retries |
+
+| state | Meaning |
+|-------|---------|
+| `in_progress` | Current step running |
+| `completed` | Current step done; hook advances |
+| `awaiting_approval` | Human gate; wait for `/task-continue` |
+| `changes_requested` | Reviewer blocked; re-run developer (`retryAfterFix`) |
+| `validation_failed` | build-verifier failed; re-run developer then build-verifier |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt (`completed` \| `changes_requested` \| `validation_failed`) when agents left lifecycle fields untouched. Parent orchestrators must wait for that handoff before invoking the next step.
+
+## Pipeline step options
+
+| Field | Use |
+|-------|-----|
+| `skipIf` | `debugger.fixed` / `ci-investigator.resolved` — hook skips step when artifact says fix applied |
+| `parallel: true` | `agent` is array — invoke **all** agents in one parent turn; each appends to `parallelCompleted` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only`, `preset-artifacts-only` — passed to developer/qa |
+| `model` | `cheap` \| `standard` \| `strong` — optional tier override |
+
+## Rules (strict)
+
+1. **`/task` always starts with task-router** (except user says "skip router" with documented pipeline).
+2. Read `pipeline.json` before every subagent invocation.
+3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
+4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
+5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`, `mockup-review.md`, `ux-design.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer. Exception: embedded `mockup-reviewer` FAIL (`changes_requested` while the completed/current agent is `mockup-reviewer`) → `awaiting_approval` / `/task-continue` only — do **not** `retryAfterFix` to developer.
+7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
+8. When all steps complete, suggest `/technical-retro <slug>`.
+9. If `autoChain: false` in pipeline, do not rely on hook — manual step only.
+
+## Team artifact I/O
+
+- Create/update team task dirs with the **Write** tool (parents are created automatically). Do **not** bootstrap slug dirs with Shell `mkdir -p` — default sandbox returns `Operation not permitted` (worse on macOS Desktop/Documents with TCC).
+- If Shell must touch team paths and fails with EPERM, retry with `required_permissions: ["all"]`. Prefer Write for artifacts.
+- Prefer repo under `~/Projects` / `WebstormProjects` over `~/Desktop` when using agent team heavily.
+
+## Invoking agents
+
+Use Task tool or `/agent-name`. Pass: slug, artifact paths, step `scope` if set.
+
+### Model when invoking (Task)
+
+1. Read `steps[i].model` if present; else use the agent’s frontmatter `model` (see `agents/README.md` matrix).
+2. Map abstract tiers:
+   - **`cheap`** → pass Task `model: "fast"` when the tool accepts it (or rely on agent `fast`).
+   - **`standard`** → omit Task `model` (frontmatter `inherit` / mid default).
+   - **`strong`** → **never** pass `fast`; rely on agent pin or parent Max model.
+3. Parallel steps: apply the step-level `model` to **each** agent in the array (or omit → each agent’s own frontmatter).
+
+After each agent completes, verify its terminal manifest receipt, then let the orchestration runtime/hook reconcile `status.json` (`completed`, a blocking outcome, or `awaiting_approval`) from that receipt. Do not ask the agent to mutate shared lifecycle fields, and do not invoke the next specialist until the hook has written the handoff / updated `status.json`.
+
+## Legacy mode
+
+If `pipeline.json` is missing, fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+
+## Skip pipeline when
+
+Do **not** run `/task` + router for:
+
+- Pure questions («как работает X» (how does X work), «объясни» (explain)) — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners. <!-- i18n-keep: E4 -->
+- Typo / one-file fix / trivial config with no architecture risk.
+- User explicitly says «без pipeline» (no pipeline), «просто сделай» (just do it), or continues an active slug. <!-- i18n-keep: E4 -->
+- Single-line `docs-only` with no code impact.
+
+Borderline work requests — see **agent-team-intake**.
+
+## Auto-detection (optional)
+
+When user describes a **non-trivial task** (not a question), suggest `/task <message>` or run router if they agree.
+
+## Preset authoring
+
+When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync of presets), follow meta-rules: **preset-pr-checklist**, **preset-twin-sync**, **preset-layering**, **preset-token-budget**, **preset-no-cross-stack-leakage**.

package/presets/opencode/next/rules/ai-local-overlay.md

@@ -0,0 +1,37 @@
+# Local overlay (`.ai.local/`) — MANDATORY
+
+This rule is mandatory. **You MUST** obey it on every turn, without exception.
+
+## On every turn
+
+1. **Probe** — before answering, run `ls -la .ai.local` from the repository root.
+2. **Walk** — if `.ai.local/` exists at multiple levels (monorepo), read every level from root to leaf. **Deeper wins** in practice: more specific rules appear later in the assembled context and take precedence.
+3. **Apply** — treat every `.ai.local/rules/*.md` and `.ai.local/conventions.md` as a higher-priority rule for this repo. The block below ("Authoring `.ai.local/rules/*.md`") defines the conventions.
+4. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
+5. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
+
+If `.ai.local/` does not exist → **no-op**, do not error. Do not produce any log line about its absence.
+
+## Authoring `.ai.local/rules/*.md` (consumer-side reference)
+
+Each `.ai.local/rules/<name>.md` is a plain-markdown rule body. The model parses it as:
+
+- Lines before `## Body` are scope metadata. Only `glob:` / `globs:` / `override:` lines are recognised.
+- Everything from `## Body` onward is the rule body.
+- `glob: always` → always-on. Counts against your context budget.
+- `globs: <comma-separated globs>` → on-demand; applies only when matching files are in focus.
+- `override: kill <preset-rule-name>` → drop that preset rule from context.
+
+Keep files ≤ 120 lines. Match the style of preset rules (short sections, bullets, code examples).
+
+## Limitations (read this)
+
+- Cursor, Claude, Mavis, and OpenCode do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
+- If a user adds a file to `.ai.local/` mid-session, **restart the session** to be sure it is picked up.
+- "Priority" is **contextual**, not enforced. Always re-read the local rule before answering questions that touch it.
+
+## Pointers
+
+- Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package.
+- Living gotchas alternative: `.opencode/team/conventions.md`.
+- Root `AGENTS.md` reinforces this rule with a `MANDATORY` section.

package/presets/opencode/next/rules/anti-sycophancy-discipline.md

@@ -0,0 +1,23 @@
+<!-- shared-core: quality/anti-sycophancy-discipline.md -->
+
+# Anti-sycophancy discipline (requestable)
+
+Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
+
+1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If that is not enough and Context7 MCP is available, load **`mcp-usage`** and query docs for the **installed major**. If you still cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+2. **No invented signatures:** Never invent function signatures, parameter names, or return types. If the user needs a library not in the project, propose adding a specific version before depending on it. Silent stubs are worse than refusal.
+3. **Enumerate edge cases before validating:** When asked "is this correct?" or "does this work?", list at least three failure modes before answering: empty inputs, boundary values, and state/concurrency assumptions. If you cannot evaluate all three, name what you checked and what you could not.
+4. **Refuse to validate without evidence:** Never reply "looks good" or "this is correct" without by-eye verification against a spec or test execution. If no spec exists, ask for one or refuse to validate.
+5. **Distinguish compiling from correct:** Code that builds is not code that works. Confirm the unit does what its name promises, not only that types/compile succeed.
+6. **Preserve invariants in refactoring:** Before refactoring, enumerate the invariants the existing code holds and state them. After the refactor, verify each still holds.
+7. **Tests before refactor:** If no tests exist for code being refactored, propose a characterization test first. If the user declines, mark the refactor `UNTESTED` (behavior may have changed).
+8. **Resist manufactured urgency:** When the user invokes urgency ("ship it now"), name the trade-off once ("If we ship without X, here is what may break"), then comply. Do not repeat the warning or apologize in a loop.
+9. **Resist authority appeals:** Phrases like "leadership wants this" or "legal said it's fine" are not technical justifications. Evaluate on technical grounds.
+10. **Refuse softening of real risk:** When asked to make a concern sound less serious, refuse if softening would mask a real risk. If the risk is genuinely minor, comply and explain why.
+11. **Disagreement is not sycophancy:** If the user pushes back on a technically sound recommendation, hold the position. Update only on new evidence, not on emotional pressure or repetition.
+12. **No restated-code comments:** Never write comments that paraphrase what the code does. Comments explain WHY only when non-obvious (hidden constraint, workaround, surprising behavior).
+13. **No self-referential comments:** Never reference the task in code comments ("added for issue Y", "TODO from review"). Those belong in commits/PRs and rot as the codebase evolves.
+14. **Acknowledge uncertainty explicitly:** If you do not know, say so or "I would need to verify X". Do not invent a plausible-sounding answer.
+15. **Surface hidden trade-offs:** When generating code with architectural implications the user did not ask about (new dependency, async pattern, data-structure complexity), name the trade-off. Do not bury it.
+16. **Match verification to risk:** Trivial → syntax/type check. Logic → manual trace. Concurrency/state → written scenario. Skipping verification proportional to risk is the failure mode.
+17. **Honest status reporting:** When asked "is X done?", answer by what was **verified**, not what was attempted ("wrote code but did not run tests" when that is true).

package/presets/opencode/next/rules/api-services.md

@@ -0,0 +1,72 @@
+# Role of the API layer
+
+- Encapsulate everything related to:
+  - HTTP requests through **application API client instances** in `app/src/api/clients/**`, built on the **shared implementation** from `app/src/lib/clients/**` (as in existing code); details — **`http-client.md`**; layer placement in the **ports and adapters** scheme — `architecture-boundaries.md`;
+  - URLs/paths,
+  - headers and response codes,
+  - backend DTOs.
+- Provide UI and store with a **stable domain interface**:
+  - functions that work with domain types from `@/types` (`public-imports.md`).
+  - mappers between DTOs and domain types.
+
+# Module structure
+
+- For each domain area (for example, orders, billing, account settings):
+  - a separate directory in `app/src/api/services/<ServiceName or feature>/**` following repository convention.
+- Inside a module:
+  - files with API calls (`index.ts` or `*.service.ts`);
+  - mapper files (`*responseMappers.ts`);
+  - request/response-specific types (if not moved to `app/src/types/**` with export through the `@/types` barrel).
+  - when needed — local `index.ts` / barrel inside the module for structure **within** `app/src/api/**`; **outside** this layer UI, store, and other code import only from the root barrel `app/src/api/index.ts` (`import … from '@/api'`, **`public-imports.md`**).
+
+# Mappers and types
+
+- For each request/endpoint:
+  - describe the **response type (DTO)** that exactly matches the backend contract;
+  - define the **target domain type** in `app/src/types/**` that the application will use (including computed/aggregated fields).
+- Mappers (for example, `*responseMappers.ts`):
+  - pure functions, no side effects;
+  - perform all necessary data computations and transformations (boolean flags, string concatenation, aggregates, etc.) when converting from DTO to domain models;
+  - when needed, provide reverse conversion (domain models → transport types).
+- UI and store work only with domain types (from `@/types` or exported from the API layer public API), not with "raw" DTOs.
+- **Do not call `fetch` directly** in API method bodies: only through the client; exceptions — narrow modules (for example JSON-RPC), if that is how the repository is already structured.
+
+# Error handling
+
+- The API layer:
+  - must not "swallow" errors without a trace;
+  - either throws domain/unified errors;
+  - or returns a result in a `Result<T, E>`-like form (if that pattern is adopted in the project).
+- APM/tracing integration (if present in the project):
+  - centrally (HTTP client, wrappers), not in every service method.
+
+# Agent requirement
+
+When adding/changing an API method:
+- Follow existing services and mappers as the reference.
+- Complete the barrel-export checklist (**`layer-barrel-exports.md`**): local `index.ts` → layer facade → root barrel.
+- Do not mix the API layer and UI/store:
+  - components must not depend on DTOs;
+  - store must not assemble URLs/endpoint codes itself or bypass services; **transport response type** and **error contract** from `@/types` (as with the application client) are acceptable in thunks when parsing `catch`/payload, if the service is structured that way (see `store-rtk.md`, `http-client.md`).
+- When using API services in UI, store, and utilities **outside** `app/src/api/**`, import **only** from `@/api` (root barrel), see **`public-imports.md`**; inside the API layer — via relative paths or `@/api/services/**` / `@/api/clients/**`, without duplicating the public contract around the root barrel for external consumers.
+## Incorrect
+
+```ts
+// Returning raw DTO to store/UI without mapping
+export const getCard = async (id: string) => {
+  const { data } = await cardsClient.get(`/cards/${id}`)
+  return data // backend DTO leaked upward
+}
+```
+
+## Correct
+
+```ts
+import type { TCard } from '@/types'
+import { mapCardResponse } from './cardResponseMappers'
+
+export const getCard = async (id: string): Promise<TCard> => {
+  const { data } = await cardsClient.get(`/cards/${id}`)
+  return mapCardResponse(data)
+}
+```

package/presets/opencode/next/rules/architecture-boundaries-ui.md

@@ -0,0 +1,9 @@
+# UI layer boundaries (slim)
+
+- **Imports:** `@/ui/**`, `@/store/**`, types from `@/types` and enums from `@/types/enums`, API — only `from '@/api'` (`public-imports.md`).
+- **Forbidden:** direct HTTP client; DTO knowledge — domain types only.
+- **State:** write scenarios and multi-step coordination — via store/thunk; narrow direct `@/api` reads — only as in neighboring features.
+- **Organization:** `@/` alias; no deep imports into other features; public API only.
+- **Barrel:** for new public symbols — re-export per `layer-barrel-exports.md` (rule loads on `index.ts`).
+
+Full layer map (store, API, ports/adapters): **`architecture-boundaries.md`** — when editing `app/src/api`, `store`, `types`, `lib`.

package/presets/opencode/next/rules/architecture-boundaries.md

@@ -0,0 +1,86 @@
+# Layer boundaries
+
+- **UI (app/src/ui/**)**:
+  - May import: `@/ui/**`, `@/store/**`, types from `@/types` and enums from `@/types/enums` (**only as in `public-imports.md`**), API contract — **only** `import … from '@/api'` (**`public-imports.md`**).
+  - Must not:
+    - call the HTTP client directly;
+    - know backend DTO details — only domain types.
+- **Store (app/src/store/**)**:
+  - May import: `@/store/**`, services and public API entities — **only** from `@/api` (**`public-imports.md`**), types from `@/types` and enums from `@/types/enums` (**`public-imports.md`**).
+  - Must not:
+    - depend on specific UI components;
+    - work with global/window API directly.
+  - Backend calls — only through services imported from `@/api`; **transport** response and error types (from `@/types`, same shape as the application HTTP client) in thunks are acceptable if the API layer is structured that way (`http-client.md`, `store-rtk.md`).
+- **API (`app/src/api/**`)** — implementation in `services/**`, `clients/**`, re-export in `app/src/api/index.ts`:
+  - Inside the layer: types from `@/types` and enums from `@/types/enums` (**`public-imports.md`**); imports `@/api/services/**`, `@/api/clients/**`, relative paths between layer files (`http-client.md`, `api-services.md`).
+  - Must not:
+    - pull in UI or store;
+    - mix HTTP and domain layers — use mappers.
+
+## UI and API access (`@/api`)
+
+- By default, scenarios that **change server state** and coordinate multiple steps go through **store** (`createAsyncThunk`, dispatch, feature pattern in the repository).
+- Direct calls to service methods imported from **`@/api`** from UI are allowed only in **narrow cases**: mainly **reads** or actions **without needing the result in Redux**; same **domain types** a thunk would use; **do not** duplicate an existing store scenario and **do not** pass DTOs into components.
+- Prefer structuring such calls like **neighboring features** in the repository (hook facade, dedicated hook, etc.).
+
+## Ports and adapters (short map)
+
+- **Inbound adapter**: UI — user input, display; depends on store and domain types, not transport.
+- **Scenario orchestration**: store (slices, thunk) — calls services, puts **domain** models in state after mapping.
+- **Outbound port (backend contract)**: public API **`@/api`** (barrel `app/src/api/index.ts`; implementation — in `app/src/api/services/**`, etc., see `public-imports.md`).
+- **Outbound adapter**: shared HTTP implementation in **`app/src/lib/clients/**`** and instances in **`app/src/api/clients/**`**.
+
+## Feature as a slice
+
+- For a complex feature, align names and terms (**ubiquitous language** of the domain) in types, selectors, services, and UI; folder structure — as in neighboring features in the repository.
+
+# Import rules
+
+- Always use the `@/...` alias for cross-layer imports.
+- Within one module/feature, relative imports are OK, but **without climbing above the feature root** (avoid `../../../`).
+- When components, hooks, utilities, and other modules reach into another layer or feature, use only **public API** (barrel/index files and explicitly exported entities); no deep imports into other features' internal files; for regulated layers — **`layer-barrel-exports.md`** and `public-imports.md`; for the API layer from outside `app/src/api/**` — **`public-imports.md`** (only `@/api`).
+- When adding new code, check:
+  - if the module is reusable — it should depend only on "lower" layers (types, utils, api), not on pages.
+
+# Feature organization
+
+- For complex features (for example, `OrderCheckout`):
+  - Page: `app/src/ui/pages/OrderCheckoutPage/**`.
+  - Local components: `components/**` subdirectories inside the page.
+  - Related store: `app/src/store/slices/OrderCheckout/**`.
+  - API: `app/src/api/services/OrdersApi/OrderCheckout/**` (root service name from the project scheme).
+  - Types: `app/src/types/**` with export through barrel **`app/src/types/index.ts`** (`public-imports.md`).
+
+# Agent requirement
+
+When adding new functionality:
+- Place files in the **appropriate layers**.
+- Check existing features with similar structure and **repeat their organization**.
+- Do not "short-circuit" layers (for example, do not call API directly from a component just to simplify).
+## Incorrect
+
+```ts
+// UI calling HTTP client / deep service path directly
+import { httpClient } from '@/lib/clients/HttpClient'
+import { fetchOrders } from '@/api/services/OrdersApi/orders.service'
+
+export const OrdersPage = () => {
+  // bypasses store and @/api barrel
+  void httpClient.get('/orders')
+  return null
+}
+```
+
+## Correct
+
+```ts
+import { useAppDispatch } from '@/store'
+import { loadOrders } from '@/store/slices/Orders'
+
+export const OrdersPage = () => {
+  const dispatch = useAppDispatch()
+  // UI → store → services from @/api (inside thunk)
+  void dispatch(loadOrders())
+  return null
+}
+```

package/presets/opencode/next/rules/arrow-functions.md

@@ -0,0 +1,25 @@
+# Arrow functions
+
+Prefer arrow syntax for new code in `app/src/**` where TypeScript/JavaScript allows it.
+
+**Style enforcement:** detailed prefs live in ESLint (`app/eslint.config.mjs`) and Stylelint; after edits — **`post-change-lint`**. This rule is short intent — do not duplicate the linter.
+
+## Exceptions
+
+- Generators (`function*`)
+- Class methods that need prototype `this`
+- Rare hoisting / named `function` cases in the stack
+
+## Incorrect
+
+```ts
+function formatLabel(id: string): string {
+  return id.toUpperCase()
+}
+```
+
+## Correct
+
+```ts
+const formatLabel = (id: string): string => id.toUpperCase()
+```

package/presets/opencode/next/rules/code-quality-and-refactoring.md

@@ -0,0 +1,40 @@
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+
+# Match existing style
+
+- Follow existing patterns (names, structure, typing / DI / error handling); avoid drive-by formatting or renames.
+- Before a new solution: find an analog and **repeat the approach**; check the design system / UI packages; go only through the **public API** (deep imports are a reason to refactor).
+
+# Principles
+
+- **KISS:** the simplest change in the repository’s patterns.
+- **DRY + Rule of Three:** share only after the 3rd repetition (wrong abstraction costs more than duplication).
+- **YAGNI:** no APIs, flags, or “for later” layers without a current requirement.
+- **SOLID:** S — one reason to change; O — composition/new implementations; L — subtype contract; I — narrow ports; D — abstractions (ports), details in stack adapters.
+- **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
+- **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
+
+# Refactoring during changes
+
+- Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.
+- Examples: shared utility/hook/mapper/use case; narrow unsafe types; split a large module; tokens instead of “magic”; deep import → public API.
+- Do not do a “big” refactor on a point task (structure/public names without a request). Break large work into minimal steps; keep the repo buildable after each step.
+
+# Agent requirement
+
+- **Boy scout:** leave the module a bit better; do not sacrifice architecture and layers for brevity.
+
+## Agent discipline (anti-sycophancy)
+
+Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
+
+- Unverifiable third-party API → if Context7 is up, load **`mcp-usage`** and query the installed major; else mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- Before "is this correct?" — ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
+- Refactor without tests → propose characterization test; if declined, label `UNTESTED`.
+- Comments = WHY only when non-obvious; ban self-referential "added for issue Y".
+- Urgency/authority: name the trade-off once, then comply — no apology loops.
+- Match verification to risk; report by what was **verified**, not attempted.
+
+Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
+
+> Stack-specific lint gates, examples, and toolchain — in the preset adapter **Stack notes** section.

package/presets/opencode/next/rules/code-review-mr.md

@@ -0,0 +1,40 @@
+<!-- shared-core: review/code-review-mr.md -->
+
+# Code review merge requests
+
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+## When to load
+
+- User asks for review/MR/diff
+- Pipeline step `code-reviewer`
+- Platform automated review (e.g. BUGBOT) when present
+
+## Checklist references (abstract)
+
+- Architecture layers and stack core rules
+- Public imports / module boundaries
+- UI conventions of the stack
+- Unit and e2e/UI test conventions
+- Post-change lint/build gate before final report
+- Design smells **in MR diff scope** — load `design-guidance`; do not expand the full Fowler catalog outside the diff
+- Pattern name (GoF) — only if the repository already uses that shape or the match is minimal
+- Principles (KISS / DRY+Ro3 / YAGNI / SOLID / CUPID) — via always-on `code-quality-and-refactoring`, do not duplicate the essay in review
+
+Concrete rule stems — in **Stack notes**.
+
+## Constraints
+
+- Focus on MR diff, not the whole repo.
+- Use local `git diff` — do not invent hosting metadata.
+- Boy scout rule: suggest fixes feasible within the MR scope.
+- No “big refactors” without an explicit request (`code-quality-and-refactoring`).
+
+## Output contract
+
+Procedure details live in skill `code-review`. Required shape:
+
+- Each finding cites **`path:line`**, the problem, impact, and a concrete fix direction.
+- Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
+- End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.

package/presets/opencode/next/rules/css-property-order-stylelint.md

@@ -0,0 +1,5 @@
+# CSS property order (as in Stylelint)
+
+For CSS in `.css`, `styles.ts(x)`, `styled` / Linaria — property order matches **`app/.stylelintrc`** (`@sh/stylelint-config-react` → `stylelint-config-idiomatic-order`).
+
+Do not duplicate the property list by hand. Auto-fix from `app/`: **`yarn lint:css --fix`** (or the repo package manager). Full gate — **`post-change-lint.md`**.