@bonesofspring/ai-rules 0.2.5 → 0.2.7

package/presets/claude/next/agents/README.md

@@ -12,6 +12,12 @@
 | Migration planner | `migration-specialist.md` | no |
 | API contract reviewer | `api-contract-reviewer.md` | no |
 
+## Analysis (on-demand)
+
+| Agent | Файл | Production-код |
+|-------|------|----------------|
+| Codebase analyzer | `codebase-analyzer.md` | no (explain-as-is only) |
+
 ## Implementation and CI
 
 | Agent | Файл | Production-код |
@@ -56,7 +62,7 @@ SoT по умолчанию — YAML `model` в каждом agent-файле.
 
 | Tier | Default frontmatter | Agents |
 |------|---------------------|--------|
-| **cheap** | `fast` | `task-router`, `task-analyst`, `build-verifier`, `code-reviewer`, `tech-writer` |
+| **cheap** | `fast` | `task-router`, `task-analyst`, `build-verifier`, `code-reviewer`, `tech-writer`, `codebase-analyzer` |
 | **standard** | `inherit` or `sonnet` | `feature-developer`, `debugger`, `ci-investigator`, `api-contract-reviewer`, `accessibility-reviewer`, `qa-tester`, `unit-test-*`, `playwright-test-*` (`sonnet` where already pinned) |
 | **strong** | `opus` | `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor` |
 

package/presets/claude/next/agents/build-verifier.md

@@ -25,6 +25,35 @@ Use **`rules/tooling-and-review/package-manager.md`** for the repo package manag
 
 Prefer **`lint`** (= js + css + type-check) before handoff on large changes.
 
+## Preset-structure validation (when scope is preset / packages/ai-rules)
+
+When validating **preset packaging** changes (paths under `packages/ai-rules/presets/**`, or `scope: preset-structure-validation` / `preset-artifacts-only`), run these checks. Skip app lint if there are **no** app source changes.
+
+### FAIL (all stacks)
+
+1. **Token budget:** Cursor `alwaysApply: true` count ≤ **3**; Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be session-start (must have `paths:`).
+2. **Leakage (next):** hooks/agents must not require `xcuitest-test-*` handoffs or `xcodebuild` as the default Next post-change gate. See `tooling-and-review/preset-no-cross-stack-leakage.md`.
+3. **Mapping / README:** `rules/README.md` must include a Cursor→Claude mapping table; document core→stack mapping when `_shared` consumers exist.
+4. **shared-core consumers:** if `_shared/core/**` changed, every file with matching `<!-- shared-core: … -->` in this PR must be updated (or intentional fork documented).
+5. **Twin presence:** Cursor rule change without Claude twin same PR → **FAIL** (next, ios-swift, and go). Domain twin body ≥15 lines; thin aliases may be shorter.
+6. **Session-start body budget:** sum body lines of the **3** intended session-start rules ≤ **120** (stretch ≤100); do **not** include `**/README.md` — record in validation-report; FAIL if grossly over.
+7. **Embed drift (soft by default):** run `packages/ai-rules/scripts/check-shared-core-drift.sh`. Document DRIFT; `AI_RULES_DRIFT_FAIL=1` to enforce. Lineage stems excluded from body equality.
+8. **Dogfood (monorepo soft):** prefer `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass dogfood deletion without migration doc → risk / FAIL for maintainers.
+
+9. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
+10. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
+11. **No react-performance on ios/go:** skill directory / required handoff must be absent under ios-swift and go → **FAIL** (leakage). Prefer `check:preset-leakage`.
+12. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.
+
+### Soft notes
+
+- Thin aliases may be &lt;15 body lines.
+- Embed vs lineage: `docs/PRESET-CONTRIBUTION.md`, `_shared/README.md`.
+
+### ios-swift-only checks
+
+When ios-swift paths are also in the PR, apply ios-swift verifier checks (chain fork, Playwright leakage) — **FAIL**.
+
 ## Output
 
 Write `.claude/team/tasks/<slug>/validation-report.md`:

package/presets/claude/next/agents/code-reviewer.md

@@ -61,3 +61,7 @@ Update `status.json`:
 If **REQUEST_CHANGES**, set `"state": "changes_requested"` (hook will re-invoke feature-developer).
 
 Do not mix this output with retrospective facilitation — keep review and retro separate.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/codebase-analyzer.md

@@ -0,0 +1,28 @@
+---
+name: codebase-analyzer
+description: Explains HOW existing code works as-is. Use when the user asks how something works, to trace data flow, or document architecture — without suggesting changes. Prefer over /task for pure questions.
+readonly: false
+model: fast
+---
+
+You are a specialist at understanding HOW this Next.js codebase works. Document implementation details with precise `path:line` references.
+
+## CRITICAL — explain as-is only
+
+- DO NOT suggest improvements, refactors, or "better approaches" unless the user explicitly asks.
+- DO NOT perform root-cause analysis or bug hunts unless asked.
+- DO NOT critique quality, performance, or security unless asked.
+- ONLY describe what exists, how it works, and how components interact.
+
+## Workflow
+
+1. Start from entry points the user named (routes, public barrels `@/api` / `@/types`, feature folders).
+2. Trace calls and data flow across UI → store → API → HTTP as applicable; read each file involved.
+3. Summarize: purpose, flow, contracts between modules, layer placement, conventions observed.
+4. End with open questions only if facts are missing — not with a wishlist of changes.
+
+## Will / Will not
+
+**Will:** map files, call chains, types/mappers, layer boundaries as they exist today.
+
+**Will not:** edit production code; open `/task` pipelines; propose PRs or refactors unprompted.

package/presets/claude/next/agents/debugger.md

@@ -61,3 +61,7 @@ Update `status.json`:
 Handoff summary: root cause, recommended fix, files touched (if any).
 
 Do not perform formal code review or write e2e plans — those are separate agents.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/feature-developer.md

@@ -20,8 +20,25 @@ You are a senior frontend developer working in a Next.js monorepo with strict la
 - Mark completed tasks in `decomposition.md`.
 - Validation: **`rules/tooling-and-review/post-change-lint.md`**. If pipeline next step is **`build-verifier`**, scoped lint/type-check on **changed files** is enough; full project lint is build-verifier's job.
 
+## Zero improvisation
+
+- Implement **only** what the brief / AC / current decomposition task require.
+- If requirements are ambiguous, conflicting, or multi-way — **ask** before coding; do not guess extras as "best practices".
+- Forbidden without explicit AC/task: unrelated security hardening, extra validation, UI polish, logging/monitoring, drive-by refactors, new config/env.
+- Boy scout / `design-guidance` improvements stay **within** touched files and must not expand task scope.
+
+## Will / Will not
+
+**Will:** follow layer order and reference features; add required unit tests; run the post-change gate; update task artifacts.
+
+**Will not:** formal code review; start blocked/dependent tasks; invent AC; auto-continue the next WP when the pipeline expects a human gate or handoff.
+
 ## On completion
 
 Update `status.json` (`currentAgent`: `feature-developer`, `state`: `completed`). Handoff: tasks done, files by layer, unit specs, validation result, gaps for build-verifier/reviewer.
 
 Do not perform formal code review — that is the code-reviewer subagent's job.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/migration-specialist.md

@@ -67,3 +67,7 @@ Update `status.json`:
 ```
 
 Hand off: orchestrator runs human gate (if configured), then `feature-developer` executes phases from the plan.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/performance-auditor.md

@@ -66,3 +66,7 @@ Update `status.json`:
 For standalone `perf-audit` intent, suggest `/technical-retro` or a follow-up `/task` to implement fixes.
 
 Do not modify production code.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/qa-tester.md

@@ -54,3 +54,7 @@ Provide summary:
 - Test run results
 - Gaps vs acceptance criteria
 - Suggest `/technical-retro` with the slug when done
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/security-reviewer.md

@@ -14,9 +14,11 @@ You are a frontend security reviewer for a Next.js TypeScript application.
 
 ## Review scope
 
-- Secrets, tokens, API keys in source or committed env files.
+Load `tooling-and-review/security-next.md` for coding-time invariants. Focus on:
+
+- Secrets, tokens, API keys in source or committed env files; never in `NEXT_PUBLIC_*`.
 - `dangerouslySetInnerHTML`, unsanitized HTML, URL injection.
-- Auth token storage (cookies vs localStorage), refresh flows, 401 handling.
+- Auth token storage (cookies vs localStorage), server-side session verify, refresh flows, 401 handling.
 - CSRF considerations for state-changing requests (as applicable to frontend).
 - Open redirects in navigation/router usage.
 - Sensitive data in client-side logs or error messages.

package/presets/claude/next/agents/solution-architect.md

@@ -68,3 +68,7 @@ Update `status.json`:
 For `spike` intent with human gate after architect: set `"state": "awaiting_approval"` if design needs user sign-off.
 
 Handoff: summary of design decisions and recommended next steps for developer.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/task-analyst.md

@@ -109,3 +109,7 @@ When DoR is reached and artifacts are saved:
 3. **Stop** and ask the user to review artifacts. Tell them to run `/task-continue <slug>` after approval or reply with corrections.
 
 Do not invoke the developer or any implementation subagent.
+
+## Design guidance (optional)
+
+- Optional: Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit — only when decomposing refactor/architecture tasks (not default).

package/presets/claude/next/agents/unit-test-generator.md

@@ -35,3 +35,7 @@ Update `status.json`:
   "updatedAt": "<ISO8601>"
 }
 ```
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/unit-test-healer.md

@@ -36,3 +36,7 @@ Update `status.json`:
   "updatedAt": "<ISO8601>"
 }
 ```
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/unit-test-planner.md

@@ -60,3 +60,7 @@ Update `status.json`:
 ```
 
 Do not write `*.spec.ts` files — that is `unit-test-generator`'s job.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/hooks/README.md

@@ -6,3 +6,9 @@
 | `guard-shell-command.sh` | Destructive git / package-manager guard |
 
 Wire into Claude Code hooks per project documentation when enabling agent team auto-chain.
+
+## Optional cookbook
+
+Example scripts live in `hooks/examples/` (secret-guard, format-edited, test-on-save). They are **not** auto-enabled.
+
+To wire in Claude Code: copy an `.example.sh` into `hooks/`, make executable, and register per [Claude Code hooks](https://code.claude.com/docs/en/hooks) for your project. Keep stack-safe recipes (this preset: **next**). Cursor twin examples under `presets/cursor/next/hooks/examples/` are the same allowlist forks.

package/presets/claude/next/hooks/examples/README.md

@@ -0,0 +1,18 @@
+# Hooks cookbook (examples)
+
+Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks.json` (only `guard-shell-command.sh` + `chain-team-phases.sh`).
+
+| Script | Purpose |
+|--------|---------|
+| `secret-guard.example.sh` | Fail if staged diff looks like secrets |
+| `format-edited.example.sh` | Stack formatter / linter on edited files |
+| `test-on-save.example.sh` | Scoped tests for the stack |
+
+## Wiring (Cursor)
+
+1. Copy an example into `hooks/` (drop `.example` suffix), e.g. `cp hooks/examples/secret-guard.example.sh hooks/secret-guard.sh`.
+2. `chmod +x hooks/secret-guard.sh`.
+3. Add a hook entry in `.cursor/hooks.json` (e.g. `beforeShellExecution` or `afterFileEdit` — see Cursor hooks docs).
+4. Keep cookbook scripts **out** of the default preset `hooks.json` when contributing back upstream.
+
+Stack: **next** — recipes must stay stack-safe (no cross-stack lint/test commands).

package/presets/claude/next/hooks/examples/format-edited.example.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Optional: format/lint edited JS/TS under app/ after save.
+# NOT in default hooks.json. Requires yarn scripts in app/.
+set -euo pipefail
+ROOT="${CURSOR_PROJECT_DIR:-.}"
+cd "$ROOT/app" 2>/dev/null || cd "$ROOT"
+# Prefer project scripts; adjust names to match package.json
+if command -v yarn >/dev/null 2>&1; then
+  yarn lint:js --fix 2>/dev/null || yarn eslint --fix . 2>/dev/null || true
+fi
+exit 0

package/presets/claude/next/hooks/examples/secret-guard.example.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Optional cookbook: block committing likely secrets in staged diffs.
+# NOT wired in default hooks.json — copy to hooks/ and register manually.
+set -euo pipefail
+PATTERN='(AKIA[0-9A-Z]{16}|-----BEGIN (RSA |OPENSSH )?PRIVATE KEY-----|api[_-]?key\s*[:=]\s*['\''\"][^'\''\"]{12,})'
+if git diff --cached -U0 2>/dev/null | grep -Eiq "$PATTERN"; then
+  echo "secret-guard: possible secret in staged diff — review before commit" >&2
+  exit 1
+fi
+exit 0

package/presets/claude/next/hooks/examples/test-on-save.example.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Optional: scoped unit tests for changed files under app/src.
+# NOT in default hooks.json. No Playwright here.
+set -euo pipefail
+ROOT="${CURSOR_PROJECT_DIR:-.}"
+cd "$ROOT/app" 2>/dev/null || exit 0
+yarn test --findRelatedTests --passWithNoTests 2>/dev/null || yarn test --passWithNoTests 2>/dev/null || true
+exit 0

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

@@ -1,11 +1,21 @@
 # `.claude/rules` (preset next)
 
-В Claude Code все `.md` под `rules/` **обнаруживаются рекурсивно**. Правила без YAML frontmatter загружаются **в начале сессии**; с `paths:` — **только при работе** с matching-файлами.
+В Claude Code все `.md` под `rules/` **обнаруживаются рекурсивно**. Тела **derived** из Cursor SoT; индексы — не второй SoT.
+
+## SoT sync
+
+| Principle | Detail |
+|-----------|--------|
+| **SoT** | `presets/cursor/next/rules/*.mdc` — edit here first |
+| **Derive** | Claude topic `.md` = body + `paths:` (from Cursor `globs:` / requestable triggers) |
+| **Drop** | Cursor-only keys (`alwaysApply`); keep short `description` |
+| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — next, ios-swift, and go; see `preset-twin-sync` / build-verifier) |
+| **Shared core** | `presets/_shared/core/**` — see `<!-- shared-core: … -->` markers; taxonomy in `_shared/README.md` |
 
 ## Loading strategy
 
 - **Session start (no `paths:`):** ровно **3** — `next-app-core`, `package-manager`, `code-quality`
-- **On-demand (`paths:` or via commands):** `post-change-lint` (**обязателен после правок кода**), `agent-team-intake`, `agent-team-orchestrator`, `code-review-mr`, architecture, imports, UI, tests, feature-delivery-workflow, reference-features, next-app-router, react-a11y-coding
+- **On-demand (`paths:` or via commands):** `post-change-lint` (**обязателен после правок кода**), `agent-team-intake`, `agent-team-orchestrator`, `code-review-mr`, `security-next`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, reference-features, next-app-router, react-a11y-coding, `technical-retro`, **preset-*** meta (paths on `packages/ai-rules/presets/**`)
 - **Skills:** long workflows (`feature-delivery`, `code-review`, …)
 
 ### UI edit bundle (consolidated paths)
@@ -21,27 +31,71 @@
 
 **Не грузятся на типичный UI edit:** `architecture/architecture-boundaries.md` (api/store/types/lib), `architecture/layer-barrel-exports.md` (только `index.ts`), `stack/navigation-router.md` (только `app/src/app/**`). Стили колокации — в `react-ui.md` (не отдельный stub).
 
-## С чего начать
+## Cursor → Claude mapping
 
-- **`commands/task.md`** — router → `pipeline.json` → agents
-- **`architecture/reference-features.md`** — заполнить TBD после init
-- **`architecture/feature-delivery-workflow.md`** — порядок слоёв
+| Cursor `.mdc` (SoT) | Claude topic |
+|---------------------|--------------|
+| `next-app-core.mdc` | `stack/next-app-core.md` |
+| `package-manager.mdc` | `tooling-and-review/package-manager.md` |
+| `code-quality-and-refactoring.mdc` | `tooling-and-review/code-quality.md` |
+| `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |
+| `next-app-router.mdc` | `stack/next-app-router.md` |
+| `arrow-functions.mdc` | `stack/arrow-functions.md` |
+| `types-jsdoc.mdc` | `stack/types-jsdoc.md` |
+| `no-type-assertion-as-import-export.mdc` | `stack/no-type-assertion.md` |
+| `navigation-router-stack.mdc` | `stack/navigation-router.md` |
+| `navigation-router-ui.mdc` | `stack/navigation-router-ui.md` |
+| `architecture-boundaries.mdc` | `architecture/architecture-boundaries.md` |
+| `architecture-boundaries-ui.mdc` | `architecture/architecture-boundaries-ui.md` |
+| `feature-delivery-workflow.mdc` | `architecture/feature-delivery-workflow.md` |
+| `reference-features.mdc` | `architecture/reference-features.md` |
+| `public-imports.mdc` | `architecture/public-imports.md` |
+| `layer-barrel-exports.mdc` | `architecture/layer-barrel-exports.md` |
+| `api-services.mdc` | `api-and-data/api-services.md` |
+| `http-client.mdc` | `api-and-data/http-client.md` |
+| `store-rtk.mdc` | `api-and-data/store-rtk.md` |
+| `react-ui.mdc` | `ui-and-accessibility/react-ui.md` |
+| `react-a11y-coding.mdc` | `ui-and-accessibility/react-a11y-coding.md` |
+| `no-props-spread.mdc` | `ui-and-accessibility/no-props-spread.md` |
+| `css-property-order-stylelint.mdc` | `ui-and-accessibility/css-property-order.md` |
+| `tests-unit.mdc` | `testing/tests-unit.md` |
+| `tests-e2e-structure.mdc` | `testing/tests-e2e-structure.md` |
+| `playwright-agents.mdc` | `testing/playwright-agents.md` |
+| `post-change-lint.mdc` | `tooling-and-review/post-change-lint.md` |
+| `code-review-mr.mdc` | `tooling-and-review/code-review-mr.md` |
+| `security-next.mdc` | `tooling-and-review/security-next.md` |
+| `agent-team-intake.mdc` | `tooling-and-review/agent-team-intake.md` |
+| `agent-team-orchestrator.mdc` | `tooling-and-review/agent-team-orchestrator.md` |
+| `technical-retro.mdc` | `tooling-and-review/technical-retro.md` |
+| `preset-layering.mdc` | `tooling-and-review/preset-layering.md` |
+| `preset-twin-sync.mdc` | `tooling-and-review/preset-twin-sync.md` |
+| `preset-token-budget.mdc` | `tooling-and-review/preset-token-budget.md` |
+| `preset-pr-checklist.mdc` | `tooling-and-review/preset-pr-checklist.md` |
+| `preset-no-cross-stack-leakage.mdc` | `tooling-and-review/preset-no-cross-stack-leakage.md` |
 
-## Каталог (новые и ключевые)
+## Core → stack mapping
 
-| Файл | Назначение |
-|------|------------|
-| `architecture/reference-features.md` | Эталонные пути UI/store/API |
-| `stack/next-app-router.md` | App Router, RSC |
-| `ui-and-accessibility/react-a11y-coding.md` | A11y при кодинге UI |
-| `architecture/feature-delivery-workflow.md` | Сквозной чеклист (paths) |
-| `architecture/architecture-boundaries-ui.md` | Slim границы UI при правках компонентов |
-| `architecture/architecture-boundaries.md` | Полная карта UI / store / API |
-| `stack/navigation-router-ui.md` | Навигация в UI-компонентах (slim) |
-| `stack/navigation-router.md` | Полный аудит стека навигации |
-| `tooling-and-review/agent-team-orchestrator.md` | Pipeline, build-verifier, parallel |
-| `agents/build-verifier.md` | Validation gate agent |
-
-Полный список — см. подпапки `architecture/`, `stack/`, `api-and-data/`, `ui-and-accessibility/`, `testing/`, `tooling-and-review/`.
+| Shared core | Cursor adapter | Notes |
+|-------------|----------------|-------|
+| `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` / `code-quality.md` | + Stack notes (ESLint/CSS) |
+| `quality/design-guidance.md` | `design-guidance.mdc` / `design-guidance.md` | requestable smells/GoF |
+| `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | Roles in Stack notes |
+| `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | thin alias |
+| `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | Next layer checklist in Stack notes |
+| `architecture/reference-features.template.md` | `reference-features.mdc` | path table in Stack notes |
+| `review/code-review-mr.md` | `code-review-mr.mdc` | Next checklist refs |
+| `review/technical-retro.md` | `technical-retro.mdc` | thin alias |
+| `meta/preset-*.md` | `preset-*.mdc` | author globs only |
+
+## Folders
+
+| Папка | О чём |
+|-------|--------|
+| `stack/` | Next core, router, conventions |
+| `architecture/` | Границы, feature-delivery, reference-features, imports |
+| `api-and-data/` | HTTP, services, store |
+| `testing/` | Unit, e2e, Playwright |
+| `ui-and-accessibility/` | React UI, a11y, props |
+| `tooling-and-review/` | Quality, review, lint, agent-team, retro, **preset meta** |
 
 **Коллизии:** импорт типов и API — **`architecture/public-imports.md`**.

package/presets/claude/next/rules/api-and-data/api-services.md

@@ -1,6 +1,7 @@
 ---
 paths:
   - app/src/api/services/**/*.ts
+impact: HIGH
 ---
 
 # Роль API слоя
@@ -55,3 +56,24 @@ paths:
   - компоненты не должны зависеть от DTO;
   - store не должен сам собирать URL/коды эндпоинтов и не обходить сервисы; **транспортный тип ответа** и **контракт ошибки** из `@/types` (как у прикладного клиента) допустимы во thunk при разборе `catch`/payload, если так выстроен сервис (см. `api-and-data/store-rtk.md`, `api-and-data/http-client.md`).
 - При использовании API‑сервисов в UI, store и утилитах **вне** `app/src/api/**` импортировать **только** из `@/api` (корневой barrel), см. **`architecture/public-imports.md`**; внутри слоя API — по относительным путям или `@/api/services/**` / `@/api/clients/**`, не дублируя публичный контракт мимо корневого barrel для внешних потребителей.
+## 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/claude/next/rules/api-and-data/http-client.md

@@ -2,6 +2,7 @@
 paths:
   - app/src/lib/clients/**/*.ts
   - app/src/api/clients/**/*.ts
+impact: HIGH
 ---
 
 # HTTP-транспорт
@@ -38,3 +39,23 @@ paths:
 
 - Меняя реализацию общего клиента — **обновить или добавить behavior‑тесты** рядом с модулем клиента (`testing/tests-unit.md`).
 - Не вводить **второй полноценный HTTP‑стек** без явной задачи и согласования с архитектурой репозитория.
+## Incorrect
+
+```ts
+// Inside api/services — ad-hoc fetch bypasses shared client
+export const getSettings = async () => {
+  const res = await fetch('/api/settings')
+  return res.json()
+}
+```
+
+## Correct
+
+```ts
+import { appHttpClient } from '@/api/clients/appHttpClient'
+
+export const getSettings = async () => {
+  const { data } = await appHttpClient.get('/settings')
+  return mapSettingsResponse(data)
+}
+```

package/presets/claude/next/rules/api-and-data/store-rtk.md

@@ -1,6 +1,7 @@
 ---
 paths:
   - app/src/store/**/*.ts
+impact: HIGH
 ---
 
 # Общие принципы
@@ -63,3 +64,22 @@ paths:
 - Строго типизировать state и actions.
 - Использовать **единый стиль именования actions и селекторов**, как в существующих слайсах.
 - При работе с ошибками и ответами HTTP опираться на **`api-and-data/http-client.md`** и контракты из `@/types`, а не на типы внешних HTTP‑библиотек вне зависимостей проекта.
+## Incorrect
+
+```ts
+export const loadProfile = createAsyncThunk('profile/load', async () => {
+  const res = await fetch('/api/profile')
+  return res.json() // raw DTO into slice
+})
+```
+
+## Correct
+
+```ts
+import { profileApi } from '@/api'
+
+export const loadProfile = createAsyncThunk('profile/load', async () => {
+  // service returns domain model already mapped
+  return profileApi.getProfile()
+})
+```

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

@@ -4,6 +4,7 @@ paths:
   - app/src/store/**/*
   - app/src/types/**/*
   - app/src/lib/**/*
+impact: CRITICAL
 ---
 
 # Границы между слоями
@@ -73,3 +74,30 @@ paths:
 - Разместить файлы в **соответствующих слоях**.
 - Проверить существующие фичи с аналогичной структурой и **повторить их организацию**.
 - Не "коротить" слои (например, не вызывать API прямо из компонента только ради упрощения).
+## 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/claude/next/rules/architecture/feature-delivery-workflow.md

@@ -6,6 +6,9 @@ paths:
   - app/src/types/**/*
 ---
 
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+
 # Доставка фичи (сквозной порядок)
 
 Типичная фича с данными с backend и общим состоянием. Детали слоёв — `architecture/architecture-boundaries.md`, `stack/next-app-core.md`.
@@ -64,6 +67,8 @@ flowchart LR
 - HTTP-клиент из компонента/thunk в обход сервиса.
 - Deep-import `@/api/services/**` из UI/store.
 - `{...props}` — `ui-and-accessibility/no-props-spread.md`.
+- **Ubiquitous language:** имена Domain/типов отражают предметную область фичи — не смешивать транспорт/фреймворк-термины в домен без нужды.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
 
 ## Матрица: зона → правила
 

package/presets/claude/next/rules/architecture/layer-barrel-exports.md

@@ -1,6 +1,7 @@
 ---
 paths:
   - app/src/**/index.ts
+impact: MEDIUM
 ---
 
 # Barrel-экспорты слоёв с public API
@@ -56,3 +57,17 @@ paths:
 | Core | `app/src/core/index.ts` | ESLint: `@/core/index` |
 
 Иллюстрация двух уровней (API): локальный `services/.../<Feature>/index.ts` → фасад `*ApiService.ts` → `app/src/api/index.ts`.
+## Incorrect
+
+```ts
+// app/src/api/index.ts — leaking internals
+export { mapCardResponse } from './services/CardsApi/cardResponseMappers'
+export { rawCardsClient } from './clients/rawCardsClient'
+```
+
+## Correct
+
+```ts
+// app/src/api/index.ts — public facade only
+export { cardsApi } from './services/CardsApi'
+```

package/presets/claude/next/rules/architecture/public-imports.md

@@ -5,6 +5,7 @@ paths:
   - app/src/lib/**/*
   - app/src/types/**/*
   - app/src/api/**/*
+impact: HIGH
 ---
 
 # Публичные импорты (`@/types`, `@/api`)
@@ -44,3 +45,16 @@ import { MedcardApiService } from '@/api/services/MedcardApiService/MedcardApiSe
 ```
 
 Новые публичные символы API — реэкспорт в `app/src/api/index.ts` по **`architecture/layer-barrel-exports.md`**.
+## Incorrect
+
+```ts
+import type { TUserProfile } from '@/types/User.types'
+import { OrdersApi } from '@/api/services/OrdersApi'
+```
+
+## Correct
+
+```ts
+import type { TUserProfile } from '@/types'
+import { ordersApi } from '@/api'
+```

package/presets/claude/next/rules/architecture/reference-features.md

@@ -6,10 +6,15 @@ paths:
   - app/src/types/**/*
 ---
 
+<!-- shared-core: architecture/reference-features.template.md -->
+
+
 # Эталонные фичи (reference features)
 
 Перед реализацией найди фичу того же типа и **повтори её структуру**, не изобретая новую организацию файлов.
 
+Taxonomy / shared core: [`presets/_shared/README.md`](../../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
+
 ## Таблица эталонов
 
 Замени **TBD** на реальные пути после договорённости в команде (или при `ai-rules init` в целевом репо):
@@ -30,6 +35,10 @@ paths:
 3. Зеркаль именование, порядок файлов, паттерны импортов и тестов.
 4. Если эталона нет — выбери **самую близкую** существующую фичу того же слоя и зафиксируй выбор в handoff.
 
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.claude/team/conventions.md`** (and the twin tool path if both Cursor and Claude are installed). Consumer-owned; not always-on. See root `AGENTS.md` § Living conventions.
+
 ## Связанные правила
 
 - `tooling-and-review/code-quality.md` — повторять паттерны, не deep-import.