@bonesofspring/ai-rules 0.1.37 → 0.1.40

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

@@ -0,0 +1,105 @@
+---
+name: task-router
+description: Task routing specialist. Analyzes user prompt, detects intent (feature, bugfix, review-only, test-only, refactor, spike, retro), and writes pipeline.json with ordered agent steps. Use first for /task or when determining which subagents to run and in what order. Writes only team artifacts; never writes production code.
+model: inherit
+---
+
+You are a task router for a Next.js frontend agent team. You **do not** implement tasks — you classify intent and plan the agent pipeline.
+
+## Inputs
+
+- User task description (from `/task` or orchestrator).
+- Optional: existing files under `.claude/team/tasks/<slug>/`.
+
+## Intent detection
+
+| intent | Signals in prompt | Default steps |
+|--------|-------------------|---------------|
+| `feature` | «добавь», «новая», «реализуй», «сделай», new UI/API/store | task-analyst → feature-developer → code-reviewer → qa-tester |
+| `bugfix` | «баг», «fix», «не работает», «падает», «ошибка», regression | debugger → feature-developer → code-reviewer → qa-tester (scope regression) |
+| `review-only` | «ревью», «review MR», «проверь diff», «code review» | code-reviewer |
+| `test-only` | «e2e», «покрой тестами», «напиши тесты» (no impl) | task-analyst → qa-tester |
+| `refactor` | «рефакторинг», «без изменения поведения», «почисти» | task-analyst → feature-developer → code-reviewer |
+| `spike` | «исследуй», «оцени», «можно ли», «spike», proof of concept | task-analyst → solution-architect |
+| `retro` | «ретро», «разбор», «postmortem» | no pipeline — orchestrator runs `/technical-retro` |
+
+Adjust steps when context is clear:
+
+- **Skip task-analyst** if AC and scope are fully specified in the prompt (document reason in `skipped`).
+- **Add solution-architect** for cross-layer features (API + store + UI), new public APIs, or architecture uncertainty.
+- **Skip qa-tester** for review-only, spike (no code), or trivial one-line fixes (document risk).
+- **Skip feature-developer** for review-only, test-only (tests only), retro.
+
+## Output: pipeline.json
+
+Write to `.claude/team/tasks/<slug>/pipeline.json`:
+
+```json
+{
+  "slug": "<slug>",
+  "intent": "feature",
+  "summary": "One-line task summary",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "code-reviewer", "label": "Code review" },
+    { "agent": "qa-tester", "label": "Unit and e2e tests", "scope": "full" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}
+```
+
+### Step fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `agent` | yes | Subagent name (kebab-case) |
+| `label` | yes | Short human-readable step name |
+| `scope` | no | e.g. `full`, `regression`, `e2e-only` — passed to qa-tester |
+
+### humanGates
+
+Values: `after:<agent-name>` — orchestrator stops after that agent; user runs `/task-continue <slug>` or `/feature-continue <slug>`.
+
+- Default for `feature`, `refactor`, `test-only`: `["after:task-analyst"]`
+- Default for `bugfix`, `review-only`: `[]` (unless analyst added)
+- `spike`: `["after:solution-architect"]`
+
+### skipped (optional)
+
+```json
+"skipped": [{ "agent": "task-analyst", "reason": "AC provided in ticket" }]
+```
+
+## Initial status.json
+
+After writing pipeline.json, write:
+
+```json
+{
+  "slug": "<slug>",
+  "intent": "<intent>",
+  "pipelineIndex": 0,
+  "currentAgent": "<steps[0].agent>",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false,
+  "updatedAt": "<ISO8601>"
+}
+```
+
+Also write `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
+
+## Handoff to orchestrator
+
+Respond with:
+
+1. **Intent** and one-line summary.
+2. **Planned steps** (table: #, agent, label).
+3. **Skipped roles** and why.
+4. **Human gates** (if any).
+5. Tell orchestrator to invoke `steps[0].agent` now (unless intent is `retro` — then run `/technical-retro`).
+
+Do not invoke implementation agents yourself.

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

@@ -1,5 +1,13 @@
 # `.claude/commands` (preset next)
 
-Определения slash-команд для проекта. Копируются в `.claude/commands/` при `ai-rules init claude --preset next`.
+Определения slash-команд и on-demand сценариев. Копируются в `.claude/commands/` при `ai-rules init claude --preset next`.
 
-См. также корневой `README.md` пресета — у Claude Code помимо `rules/` и `commands/` часто используются `skills/`, `agents/`, `hooks/`.
+| Файл | Назначение |
+|------|------------|
+| `task.md` | Единая точка входа: router → dynamic pipeline → первый agent |
+| `task-continue.md` | Продолжение после human gate / паузы по `pipeline.json` |
+| `feature-start.md` | Legacy analyst-only старт без router |
+| `feature-continue.md` | Legacy продолжение; для `pipeline.json` делегирует смысл `/task-continue` |
+| `technical-retro.md` | Фасилитация технического ретро, включая блок «Работа агентов» |
+
+См. также корневой `README.md` пресета — у Claude Code помимо `rules/` и `commands/` часто используются `skills/`, `agents/`, `hooks/`, `team/`.

package/presets/claude/next/commands/feature-continue.md

@@ -0,0 +1,46 @@
+# Feature continue — продолжение после утверждения brief
+
+Legacy-команда для продолжения после human gate. Для новых пайплайнов с `pipeline.json` используй те же правила, что в `/task-continue`.
+
+## Аргументы
+
+`<slug>` — идентификатор задачи из `.claude/team/tasks/<slug>/`.
+
+## Preconditions
+
+1. Прочитай `.claude/team/tasks/<slug>/brief.md` и `decomposition.md`.
+2. Если есть `pipeline.json`, делегируй поведение `/task-continue <slug>`.
+3. Если `pipeline.json` нет, прочитай `status.json`. Продолжай только если:
+   - `phase` is `analysis` and `state` is `awaiting_approval` (user explicitly approved via this command), **or**
+   - `phase` is `development`/`review`/`testing` and work should resume.
+
+## Legacy алгоритм без `pipeline.json`
+
+1. Обнови `status.json`:
+   ```json
+   {
+     "slug": "<slug>",
+     "phase": "development",
+     "state": "approved",
+     "updatedAt": "<ISO8601>"
+   }
+   ```
+   Затем сразу установи `"state": "in_progress"` перед вызовом developer.
+
+2. Запиши `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
+
+3. Вызови subagent **feature-developer** с контекстом:
+   - пути к `brief.md`, `decomposition.md`, `status.json`;
+   - указание следовать `rules/architecture/feature-delivery-workflow.md`.
+
+4. После завершения developer продолжи review → QA по `rules/tooling-and-review/agent-team-orchestrator.md`.
+
+## Если review вернул changes_requested
+
+- Верни `phase` в `development`, `state` в `in_progress`.
+- Снова вызови **feature-developer** с списком правок от reviewer.
+
+## Не делать
+
+- Не пропускать human gate без явного `/feature-continue`.
+- Не совмещать роли developer и reviewer в одном subagent-вызове.

package/presets/claude/next/commands/feature-start.md

@@ -0,0 +1,25 @@
+# Feature start — legacy команда агентов
+
+Запуск **фазы анализа** для новой задачи. Для новых задач предпочтительнее `/task`, потому что он сначала строит dynamic pipeline через `task-router`.
+
+## Что делать
+
+1. Извлеки описание задачи из аргументов команды (всё после `/feature-start`).
+2. Сгенерируй **slug** (kebab-case, до 48 символов) из заголовка задачи.
+3. Создай каталог `.claude/team/tasks/<slug>/` если его ещё нет.
+4. Запиши `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
+5. Вызови subagent **task-analyst** с полным описанием задачи и путём к артефактам.
+6. Дождись завершения аналитика. **Не вызывай developer** на этом этапе.
+
+## Human gate
+
+После аналитика:
+
+- Покажи пользователю ссылки на `brief.md` и `decomposition.md`.
+- Попроси проверить и утвердить или прислать правки.
+- Для продолжения: `/feature-continue <slug>` или `/task-continue <slug>`.
+
+## Если slug уже существует
+
+- Если `status.json` в `awaiting_approval` — предложи ревью или `/feature-continue`.
+- Если задача в работе — спроси, продолжать или начать новый slug.

package/presets/claude/next/commands/task-continue.md

@@ -0,0 +1,43 @@
+# Task continue — после human gate или паузы
+
+Продолжение пайплайна из `pipeline.json`. Алиас по смыслу: `/feature-continue`.
+
+## Аргументы
+
+`<slug>` — идентификатор задачи.
+
+## Preconditions
+
+1. Прочитай `.claude/team/tasks/<slug>/pipeline.json` и `status.json`.
+2. Продолжай если:
+   - `awaitingHumanGate: true` или `state: awaiting_approval`, **или**
+   - `state: changes_requested` (после review), **или**
+   - задача прервана и нужно возобновить с `pipelineIndex`.
+
+## Алгоритм
+
+1. Запиши `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
+2. Сбрось gate: `awaitingHumanGate: false`.
+3. Определи **следующий шаг**:
+   - После approval analyst/architect: `pipelineIndex + 1` → следующий agent в `steps`.
+   - После `changes_requested`: снова **feature-developer** (тот же index или найди developer в steps).
+4. Обнови `status.json`:
+   ```json
+   {
+     "pipelineIndex": <n>,
+     "currentAgent": "<steps[n].agent>",
+     "phase": "executing",
+     "state": "in_progress",
+     "awaitingHumanGate": false
+   }
+   ```
+5. Вызови subagent для `currentAgent` с контекстом slug и артефактов.
+6. Если hook `chain-team-phases.sh` включён в проекте и `autoChain: true`, он продолжит цепочку по `pipeline.json`; иначе продолжай следующий шаг вручную.
+
+## Артефакты для handoff
+
+| Agent | Прочитать |
+|-------|-----------|
+| feature-developer | brief.md, decomposition.md, architecture.md (if exists), debug-report.md (if exists) |
+| code-reviewer | brief.md, git diff |
+| qa-tester | brief.md, decomposition.md, scope from pipeline step |

package/presets/claude/next/commands/task.md

@@ -0,0 +1,40 @@
+# Task — единая точка входа
+
+Главная команда для постановки задачи в Claude Code. Родительский агент = оркестратор, правила — `rules/tooling-and-review/agent-team-orchestrator.md`.
+
+## Аргументы
+
+Всё после `/task` — описание задачи на естественном языке.
+
+Примеры:
+
+- `/task Добавить фильтр по дате в Order History`
+- `/task Order History падает при пустом списке — пофикси`
+- `/task Сделай ревью моих изменений в store/orders`
+- `/task Напиши e2e для сценария оплаты`
+
+## Алгоритм
+
+1. **Slug** — kebab-case из описания (≤48 символов). Создай `.claude/team/tasks/<slug>/`.
+2. **Router** — вызови subagent **task-router** с описанием задачи и путём к slug.
+3. **План** — покажи пользователю таблицу из `pipeline.json`: intent, steps, skipped, humanGates.
+4. **Intent retro** — если `intent === "retro"`, выполни `/technical-retro` и **остановись**.
+5. **Старт** — вызови subagent для `pipeline.steps[0].agent`:
+   - передай slug, пути к артефактам, scope из step (если есть);
+   - обнови `status.json`: `pipelineIndex: 0`, `currentAgent`, `state: in_progress`.
+6. **Human gate** — если после текущего шага есть gate в `humanGates` (`after:<agent>`), после завершения агента **остановись** и попроси `/task-continue <slug>` (или `/feature-continue <slug>`).
+
+## Не делать
+
+- Не вызывать developer до router и (если в pipeline) analyst/architect.
+- Не hardcode порядок ролей — только `pipeline.json`.
+- Не пропускать human gate без явного continue.
+
+## Если slug занят
+
+- `awaitingHumanGate` / `state: awaiting_approval` → предложи ревью артефактов или `/task-continue <slug>`.
+- `in_progress` → спроси: продолжить или новый slug.
+
+## Legacy
+
+`/feature-start` и `/feature-continue` остаются совместимыми; для новых задач предпочитай `/task`.

package/presets/claude/next/commands/technical-retro.md

@@ -0,0 +1,53 @@
+# Техническое ретро — роль агента
+
+Агент выступает как **нейтральный фасилитатор технической ретроспективы**, а не как ревьюер кода или оценщик людей. Цель — вынести уроки, согласовать действия и улучшить процесс разработки.
+
+## Когда включать
+
+- Пользователь просит: «ретро», «техническое ретро», «разбор спринта/итерации», «что пошло хорошо / плохо», «action items после релиза».
+- Есть контекст: период (спринт, квартал), тема (релиз, инцидент, миграция), или приложены заметки/линки.
+
+## Входные данные (запросить при нехватке)
+
+- **Период и фокус** (например: две недели, релиз X, постмортем).
+- **Участники/роли** (если важно для формулировок): только разработка или весь кросс‑функциональный поток.
+- **Ограничения**: время (15 / 30 / 60 мин), формат (async в чате vs синхронная повестка).
+- По желанию: список deliverables, метрики, ссылки на тикеты/MR — **без выдумывания** фактов, которых нет в сообщении или репозитории.
+
+Если контекста мало — задать **1–3 коротких уточняющих вопроса**, затем продолжить с явными допущениями в шапке вывода.
+
+## Принципы фасилитации
+
+- **Безопасность и нейтральность**: формулировки про процесс и систему, не про «виноватых»; избегать ярлыков к людям.
+- **Конкретика**: от абстрактного «надо лучше общаться» — к наблюдаемым событиям и договорённостям.
+- **Баланс**: зафиксировать и позитив (что усилить), и зоны роста.
+- **Один владелец и срок** у каждого action item; избегать списка «сделает команда» без имени/роли.
+- **Не смешивать с code review**: ретро не заменяет построчный разбор диффа; при запросе «и ретро, и ревью» — развести два блока в ответе.
+
+## Рекомендуемая структура сессии (по умолчанию)
+
+Подстроить под указанное время. Для короткого async‑формата — сжать до шагов 2–4.
+
+1. **Цель и рамки** (1–2 предложения): зачем встреча, что в фокусе / что вне скоупа.
+2. **Сбор фактов** (молча в чате — списком от пользователя; агент структурирует):
+   - что шло хорошо,
+   - что мешало / вызывало риски,
+   - сюрпризы (технический долг, узкие места, зависимости).
+3. **Группировка тем**: объединить дубли, выделить 3–7 тем для обсуждения (приоритет — влияние × изменяемость).
+4. **Корневые причины (легко)**: для 1–2 самых болезненных тем — кратко «5 почему» или «что в процессе/артефактах позволило этому случиться», без морализаторства.
+5. **Эксперименты на следующий цикл**: не больше 1–3 изменений процесса/инструментов; каждое — измеримое или с явным критерием «успех/не успех».
+6. **Action items**: таблица или список с **что / владелец / до когда / как поймём, что сработало**.
+
+## Формат ответа агента
+
+- Краткая **шапка**: период, фокус, допущения (если были).
+- **Повестка** или итог по этапам выше.
+- **Темы** — буллеты; по спорным местам — **вопросы команде**, а не окончательные выводы без данных.
+- **Решения и эксперименты** отдельным блоком.
+- **Action items** — в конце, каждый пункт с владельцем и дедлайном (или пометка «нужно назначить на встрече»).
+
+## Ограничения
+
+- Не приписывать команде цитаты или факты, которых не было во входе.
+- Не выдавать юридические/HR‑рекомендации; при явных конфликтах или токсичности — мягко предложить эскалацию человеку, ответственному за команду, без детализации «наказаний».
+- Если пользователь просит только шаблон — выдать **шаблон повестки и доски** (колонки, таймбоксы) без выдуманного контента.

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

@@ -3,3 +3,9 @@
 Событийные хуки автоматизации Claude Code — по документации продукта, если включены в репозитории.
 
 Папка копируется в `.claude/hooks/` при `ai-rules init claude --preset next`, если существует.
+
+| Файл | Назначение |
+|------|------------|
+| `chain-team-phases.sh` | Optional chaining helper для agent team pipeline после завершения subagent |
+
+Hook-скрипт сам по себе не включает автоматизацию: подключайте его в конфигурации Claude Code hooks целевого проекта, если хотите auto-chain. Без hook workflow продолжает родительский агент по `rules/tooling-and-review/agent-team-orchestrator.md`.

package/presets/claude/next/hooks/chain-team-phases.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Chains agent team phases after subagent completion when wired into Claude Code hooks.
+# Reads stdin JSON from a subagent-stop style hook; writes followup_message to stdout.
+
+set -euo pipefail
+
+input=$(cat)
+
+INPUT="$input" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+
+const inputRaw = process.env.INPUT || '';
+let hookInput;
+try {
+  hookInput = JSON.parse(inputRaw);
+} catch {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+if (hookInput.status !== 'completed') {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+const teamRoot = path.join(process.cwd(), '.claude', 'team');
+const activePath = path.join(teamRoot, 'active-task.json');
+
+if (!fs.existsSync(activePath)) {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+let active;
+try {
+  active = JSON.parse(fs.readFileSync(activePath, 'utf8'));
+} catch {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+const slug = active.slug;
+if (!slug) {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+const statusPath = path.join(teamRoot, 'tasks', slug, 'status.json');
+if (!fs.existsSync(statusPath)) {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+let status;
+try {
+  status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+} catch {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+const now = new Date().toISOString();
+
+function writeStatus(next) {
+  fs.writeFileSync(statusPath, JSON.stringify({ ...status, ...next, slug, updatedAt: now }, null, 2) + '\n');
+}
+
+function out(message) {
+  process.stdout.write(JSON.stringify({ followup_message: message }));
+}
+
+// Human gate: do not auto-chain during analysis or explicit approval waits.
+if (status.phase === 'analysis' || status.state === 'awaiting_approval') {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+// Legacy mode without pipeline.json.
+if (status.phase === 'development' && status.state === 'completed') {
+  writeStatus({ phase: 'review', state: 'in_progress' });
+  out(
+    `Subagent development phase finished for slug "${slug}". ` +
+      `Invoke the code-reviewer subagent. ` +
+      `Read .claude/team/tasks/${slug}/brief.md and decomposition.md. ` +
+      `Review git diff against acceptance criteria per rules/tooling-and-review/code-review-mr.md. ` +
+      `Update status.json when done.`,
+  );
+  process.exit(0);
+}
+
+if (status.phase === 'review' && status.state === 'completed') {
+  writeStatus({ phase: 'testing', state: 'in_progress' });
+  out(
+    `Code review completed for slug "${slug}". ` +
+      `Invoke the qa-tester subagent. ` +
+      `Add or update unit and e2e tests per brief acceptance criteria. ` +
+      `Follow rules/testing/playwright-agents.md and rules/testing/tests-e2e-structure.md. ` +
+      `Update status.json when done.`,
+  );
+  process.exit(0);
+}
+
+if (status.phase === 'review' && status.state === 'changes_requested') {
+  out(
+    `Review requested changes for slug "${slug}". ` +
+      `Invoke feature-developer with the review fix list, then re-run code-reviewer.`,
+  );
+  process.exit(0);
+}
+
+if (status.phase === 'testing' && status.state === 'completed') {
+  writeStatus({ phase: 'done', state: 'completed' });
+  out(
+    `QA phase completed for slug "${slug}". ` +
+      `Suggest running /technical-retro with this slug. ` +
+      `Read team artifacts under .claude/team/tasks/${slug}/ and git diff for the retro.`,
+  );
+  process.exit(0);
+}
+
+process.stdout.write('{}');
+NODE

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

@@ -1,16 +1,54 @@
 # `.claude/rules` (preset next)
 
-В Claude Code все `.md` под `rules/` **обнаруживаются рекурсивно** — подпапки по темам уместнее, чем один длинный файл.
+В Claude Code все `.md` под `rules/` **обнаруживаются рекурсивно**. Правила без YAML frontmatter загружаются **в начале сессии**; с `paths:` — **только при работе** с matching-файлами (экономия контекста).
 
-Соответствие темам из пресета Cursor (для переноса смысла из `.mdc`):
+Соответствие пресету Cursor (`.cursor/rules/*.mdc`):
 
-| Папка | О чём |
-|-------|--------|
-| `stack/` | Next.js, React, TypeScript |
-| `architecture/` | границы слоёв, модули |
-| `api-and-data/` | сервисы, API, данные |
-| `testing/` | unit, e2e, Playwright |
-| `ui-and-accessibility/` | UI, a11y, без spread props там, где это правило команды |
-| `tooling-and-review/` | качество кода, ревью MR |
+| Папка | О чём | Загрузка |
+|-------|--------|----------|
+| `architecture/` | границы слоёв, barrel, импорты, доставка фичи | session start |
+| `stack/` | Next.js, TS, навигация, JSDoc типов | core — session; `types-jsdoc.md` — `paths: app/src/types/**` |
+| `api-and-data/` | HTTP, сервисы, store | `paths:` по каталогам слоя |
+| `ui-and-accessibility/` | React UI, стили, a11y, пропсы | core — session; `react-ui.md` — `paths: app/src/ui/**` |
+| `testing/` | unit, e2e, Playwright agents | `tests-unit.md`, `tests-e2e-structure.md` — `paths:`; `playwright-agents.md` — session start |
+| `tooling-and-review/` | lint, package manager, качество, MR review | session start |
 
-Добавляйте сюда `.md` файлы с осмысленными именами (`testing.md`, `api-design.md`, …).
+On-demand сценарии вне постоянного контекста — в `commands/` (например `technical-retro.md`).
+
+## С чего начать новую фичу
+
+Для обычной задачи — **`commands/task.md`**: router → `pipeline.json` → нужные agents. Для ручной реализации без team workflow — **`architecture/feature-delivery-workflow.md`**.
+
+## Каталог правил
+
+| Файл | Назначение |
+|------|------------|
+| `tooling-and-review/package-manager.md` | Менеджер пакетов перед install/run |
+| `tooling-and-review/agent-team-intake.md` | Когда использовать `/task` и task-router |
+| `tooling-and-review/agent-team-orchestrator.md` | Dynamic pipeline, subagents, gates, handoff artifacts |
+| `architecture/feature-delivery-workflow.md` | Сквозной порядок работ по фиче, mermaid, матрица слой → правило |
+| `stack/next-app-core.md` | Стек, слои, порты‑адаптеры, работа агента |
+| `tooling-and-review/post-change-lint.md` | **Обязательный** ESLint + Stylelint после изменений |
+| `architecture/architecture-boundaries.md` | Границы UI / store / API, импорты, фича как срез |
+| `api-and-data/http-client.md` | Единый HTTP‑стек, контракты из `@/types` |
+| `api-and-data/api-services.md` | Сервисы, мапперы, прикладные API‑клиенты |
+| `api-and-data/store-rtk.md` | Redux Toolkit, thunk’и, типизация ошибок |
+| `architecture/types-public-imports.md` | Импорты только через barrel `@/types` |
+| `architecture/api-public-imports.md` | Импорты только через barrel `@/api` |
+| `architecture/layer-barrel-exports.md` | Двухуровневые barrel для слоёв с public API |
+| `stack/types-jsdoc.md` | JSDoc для типов в `app/src/types` |
+| `stack/no-type-assertion.md` | Ограничение `as`, `instanceof` для ошибок транспорта |
+| `tooling-and-review/code-review-mr.md` | Чеклист ревью MR |
+| `testing/tests-unit.md` | Unit‑тесты и behavior‑тесты HTTP‑клиента |
+| `testing/playwright-agents.md`, `testing/tests-e2e-structure.md` | E2e |
+| `ui-and-accessibility/react-ui.md` | React/Next UI: структура, `.data.ts` / `.utils.ts`, стили |
+| `ui-and-accessibility/no-props-spread.md` | Без spread пропов в компонентах |
+| `ui-and-accessibility/component-styles.md` | Колокация стилей, `Root` |
+| `ui-and-accessibility/css-property-order.md` | Порядок CSS (Stylelint) |
+| `stack/arrow-functions.md` | Стрелочные функции |
+| `stack/navigation-router.md` | Навигация по стеку проекта |
+| `tooling-and-review/code-quality.md` | Качество кода и рефакторинг |
+
+**Коллизии:** импорт типов — **`architecture/types-public-imports.md`**; импорт API вне `app/src/api/**` — **`architecture/api-public-imports.md`**.
+
+Задачи на **сеть, HTTP, эндпоинты**: **`api-and-data/http-client.md`** + **`api-and-data/api-services.md`** + **`api-and-data/store-rtk.md`**.

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

@@ -1,3 +1,9 @@
 # API and data
 
-Конвенции сервисов, API-слоя и работы с данными.
+HTTP-транспорт, сервисы, Redux store.
+
+| Файл | Содержание | `paths:` |
+|------|------------|----------|
+| `http-client.md` | Единый HTTP-клиент, ошибки, связь со store | `app/src/lib/clients/**`, `app/src/api/clients/**` |
+| `api-services.md` | Сервисы, мапперы, DTO → домен | `app/src/api/services/**` |
+| `store-rtk.md` | Redux Toolkit, thunk'и, типизация | `app/src/store/**` |

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

@@ -0,0 +1,57 @@
+---
+paths:
+  - app/src/api/services/**/*.ts
+---
+
+# Роль API слоя
+
+- Инкапсулировать всё, что связано с:
+  - HTTP‑запросами через **экземпляры прикладных API‑клиентов** в `app/src/api/clients/**`, собранные на **общей реализации** из `app/src/lib/clients/**` (как в существующем коде); подробности — **`api-and-data/http-client.md`**; положение слоя в схеме **порты и адаптеры** — `architecture/architecture-boundaries.md`;
+  - URL/путями,
+  - заголовками и кодами ответов,
+  - DTO backend.
+- Предоставлять UI и store **стабильный доменный интерфейс**:
+  - функции, работающие с доменными типами из `@/types` (`architecture/types-public-imports.md`).
+  - мапперы между DTO и доменными типами.
+
+# Структура модулей
+
+- Для каждой доменной области (например, заказы, биллинг, настройки аккаунта):
+  - отдельный каталог в `app/src/api/services/<ИмяСервиса или фичи>/**` по конвенции репозитория.
+- Внутри модуля:
+  - файлы с вызовами API (`index.ts` или `*.service.ts`);
+  - файлы мапперов (`*responseMappers.ts`);
+  - специфичные типы запросов/ответов (если не вынесены в `app/src/types/**` с экспортом через barrel `@/types`).
+  - при необходимости — локальные `index.ts` / barrel внутри модуля для структуры **внутри** `app/src/api/**`; **снаружи** этого слоя UI, store и остальной код импортируют только из корневого barrel `app/src/api/index.ts` (`import … from '@/api'`, **`architecture/api-public-imports.md`**).
+
+# Мапперы и типы
+
+- Для каждого запроса/эндпоинта:
+  - описывать **response‑тип (DTO)**, точно соответствующий контракту backend;
+  - определять **целевой доменный тип** в `app/src/types/**`, с которым будет работать приложение (включая вычисляемые/агрегированные поля).
+- Мапперы (например, `*responseMappers.ts`):
+  - чистые функции, без сайд‑эффектов;
+  - выполняют все необходимые вычисления и преобразования данных (булевы флаги, склейка строк, агрегаты и т.п.) при переводе из DTO в доменные модели;
+  - при необходимости обеспечивают обратное преобразование (доменные модели → транспортные типы).
+- UI и store работают только с доменными типами (из `@/types` или экспортируемыми из public API слоя API), а не с «сырыми» DTO.
+- **Не вызывать `fetch` напрямую** в теле API‑методов: только через клиент; исключения — узкие модули (например JSON‑RPC), если так уже устроено в репозитории.
+
+# Обработка ошибок
+
+- API‑слой:
+  - не должен «глотать» ошибки без следа;
+  - либо бросает доменные/унифицированные ошибки;
+  - либо возвращает результат в `Result<T, E>`‑подобной форме (если такой паттерн принят в проекте).
+- Интеграция с APM/трассировкой (если есть в проекте):
+  - централизованно (HTTP‑клиент, обёртки), а не в каждом методе сервиса.
+
+# Требование к агенту
+
+При добавлении/изменении API‑метода:
+
+- Следовать существующим сервисам и мапперам как эталону.
+- Пройти чеклист barrel-экспортов (**`architecture/layer-barrel-exports.md`**): локальный `index.ts` → фасад слоя → корневой barrel.
+- Не смешивать слой API и UI/store:
+  - компоненты не должны зависеть от 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/api-public-imports.md`**; внутри слоя API — по относительным путям или `@/api/services/**` / `@/api/clients/**`, не дублируя публичный контракт мимо корневого barrel для внешних потребителей.