@bonesofspring/ai-rules 0.2.2 → 0.2.4

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

@@ -0,0 +1,380 @@
+#!/usr/bin/env bash
+# Chains agent team steps from pipeline.json after subagentStop.
+# Falls back to legacy phase-based flow when pipeline.json is absent.
+
+set -euo pipefail
+
+input=$(cat)
+
+INPUT="$input" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+
+const TEAM_ROOT = path.join(process.cwd(), '.claude', 'team');
+
+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 activePath = path.join(TEAM_ROOT, '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 taskDir = path.join(TEAM_ROOT, 'tasks', slug);
+const statusPath = path.join(taskDir, 'status.json');
+const pipelinePath = path.join(taskDir, 'pipeline.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) {
+  status = { ...status, ...next, slug, updatedAt: now };
+  fs.writeFileSync(statusPath, JSON.stringify(status, null, 2) + '\n');
+}
+
+function out(message) {
+  process.stdout.write(JSON.stringify({ followup_message: message }));
+}
+
+function readArtifact(name) {
+  const p = path.join(taskDir, name);
+  if (!fs.existsSync(p)) return '';
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function getStepAgents(step) {
+  if (!step) return [];
+  return Array.isArray(step.agent) ? step.agent : [step.agent];
+}
+
+function skipIfMatches(skipIf, dir) {
+  if (!skipIf) return false;
+  if (skipIf === 'debugger.fixed') {
+    const text = readArtifact('debug-report.md');
+    return /fixApplied:\s*true/i.test(text) || /\*\*Fix applied:\*\*\s*true/i.test(text);
+  }
+  if (skipIf === 'ci-investigator.resolved') {
+    const text = readArtifact('ci-report.md');
+    return /fixApplied:\s*true/i.test(text) || /## Verdict\s*\nPASS/i.test(text);
+  }
+  return false;
+}
+
+function findNextExecutableStep(steps, startIdx, dir) {
+  for (let i = startIdx; i < steps.length; i++) {
+    if (!skipIfMatches(steps[i].skipIf, dir)) {
+      return { step: steps[i], index: i };
+    }
+  }
+  return null;
+}
+
+const AGENT_HANDOFF = {
+  'task-analyst': (s) =>
+    `Invoke task-analyst for slug "${s}". Write brief.md and decomposition.md under .claude/team/tasks/${s}/. ` +
+    `Set status.json: phase executing, state awaiting_approval if human gate applies. Do not use legacy phase analysis.`,
+  debugger: (s) =>
+    `Invoke debugger subagent for slug "${s}". Investigate root cause; write debug-report.md with fixApplied: true/false. ` +
+    `Update status.json when done.`,
+  'solution-architect': (s) =>
+    `Invoke solution-architect for slug "${s}". Read brief.md; write architecture.md. Update status.json when done.`,
+  'migration-specialist': (s) =>
+    `Invoke migration-specialist for slug "${s}". Read brief.md; write migration-plan.md. Update status.json when done.`,
+  'api-contract-reviewer': (s) =>
+    `Invoke api-contract-reviewer (readonly) for slug "${s}". Write api-contract-review.md. Update status.json when done.`,
+  'ci-investigator': (s) =>
+    `Invoke ci-investigator for slug "${s}". Diagnose CI failure; write ci-report.md; apply minimal fix. ` +
+    `Use ci-investigation skill. Update status.json when done.`,
+  'feature-developer': (s) =>
+    `Invoke feature-developer for slug "${s}". Read brief.md, decomposition.md, validation-report.md, review.md, architecture.md, migration-plan.md, api-contract-review.md, debug-report.md if present. ` +
+    `Follow architecture/feature-delivery-workflow.md and architecture/reference-features.md. Include unit tests for mappers/logic before handoff. Update status.json when done.`,
+  'build-verifier': (s) =>
+    `Invoke build-verifier (readonly) for slug "${s}". Run lint:js, lint:css, type-check, and targeted unit tests from app/. ` +
+    `Write validation-report.md. Set state completed or validation_failed. Do not edit production code.`,
+  'accessibility-reviewer': (s) =>
+    `Invoke accessibility-reviewer (readonly) for slug "${s}". Review UI diff; write a11y-review.md. Update status.json when done.`,
+  'performance-auditor': (s) =>
+    `Invoke performance-auditor (readonly) for slug "${s}". Write perf-report.md. Update status.json when done.`,
+  'code-reviewer': (s) =>
+    `Invoke code-reviewer subagent (readonly) for slug "${s}". Review git diff vs brief.md per tooling-and-review/code-review-mr.md. ` +
+    `Update status.json when done.`,
+  'security-reviewer': (s) =>
+    `Invoke security-reviewer (readonly) for slug "${s}". Write security-review.md. Update status.json when done.`,
+  'qa-tester': (s, scope) =>
+    `Invoke qa-tester for slug "${s}"${scope ? ` (scope: ${scope})` : ''}. ` +
+    `Add/update tests per brief. Follow testing/playwright-agents.md. Update status.json when done.`,
+  'unit-test-planner': (s) =>
+    `Invoke unit-test-planner for slug "${s}". Write unit-test-plan.md. Use unit-testing skill. Update status.json when done.`,
+  'unit-test-generator': (s) =>
+    `Invoke unit-test-generator for slug "${s}". Implement specs from unit-test-plan.md. Use unit-testing skill. Update status.json when done.`,
+  'unit-test-healer': (s) =>
+    `Invoke unit-test-healer for slug "${s}". Fix failing unit tests. Use unit-testing and debug-investigation skills. Update status.json when done.`,
+  'playwright-test-planner': (s) =>
+    `Invoke playwright-test-planner for slug "${s}". Create/update app/__tests__/e2e/**/*.cases.md. ` +
+    `Follow testing/playwright-agents.md and the playwright-e2e skill. Update status.json when done.`,
+  'playwright-test-generator': (s) =>
+    `Invoke playwright-test-generator for slug "${s}". Generate/update *.spec.ts from matching *.cases.md. ` +
+    `Use playwright MCP when available. Follow testing/playwright-agents.md and the playwright-e2e skill. Update status.json when done.`,
+  'playwright-test-healer': (s) =>
+    `Invoke playwright-test-healer for slug "${s}". Fix failing/flaky e2e while preserving cases.md assertions. ` +
+    `Use playwright MCP when available. Follow testing/playwright-agents.md and debug-investigation. Update status.json when done.`,
+  'tech-writer': (s) =>
+    `Invoke tech-writer for slug "${s}". Write documentation.md from task artifacts. Update status.json when done.`,
+};
+
+const REVIEW_AGENTS = new Set([
+  'code-reviewer',
+  'accessibility-reviewer',
+  'security-reviewer',
+  'api-contract-reviewer',
+]);
+
+function handoffForAgent(agent, scope) {
+  const fn = AGENT_HANDOFF[agent];
+  return fn ? fn(slug, scope) : `Invoke ${agent} subagent for slug "${slug}". Update status.json when done.`;
+}
+
+function handoffForParallelStep(step) {
+  const agents = getStepAgents(step);
+  return (
+    `Invoke IN PARALLEL (one message, multiple Task calls): ${agents.join(' AND ')} for slug "${slug}". ` +
+    `Each agent writes its artifact and appends itself to status.json parallelCompleted when done.`
+  );
+}
+
+function hasGateAfter(agent, humanGates) {
+  return Array.isArray(humanGates) && humanGates.includes(`after:${agent}`);
+}
+
+function hasGateAfterStep(step, humanGates) {
+  return getStepAgents(step).some((a) => hasGateAfter(a, humanGates));
+}
+
+function legacyFlow() {
+  if (status.phase === 'analysis') {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  if (status.phase === 'development' && (status.state === 'completed' || status.state === 'in_progress')) {
+    writeStatus({ phase: 'executing', state: 'in_progress', currentAgent: 'build-verifier' });
+    out(handoffForAgent('build-verifier'));
+    process.exit(0);
+  }
+  if (status.currentAgent === 'build-verifier' && status.state === 'completed') {
+    writeStatus({ phase: 'executing', state: 'in_progress', currentAgent: 'code-reviewer' });
+    out(handoffForAgent('code-reviewer'));
+    process.exit(0);
+  }
+  if (status.phase === 'review' && status.state === 'completed') {
+    writeStatus({ phase: 'executing', state: 'in_progress', currentAgent: 'qa-tester' });
+    out(handoffForAgent('qa-tester'));
+    process.exit(0);
+  }
+  if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
+    writeStatus({
+      currentAgent: 'feature-developer',
+      state: 'in_progress',
+      phase: 'executing',
+      retryAfterFix: status.currentAgent,
+    });
+    out(
+      handoffForAgent('feature-developer') +
+        ` After fixes, re-run ${status.currentAgent}.`,
+    );
+    process.exit(0);
+  }
+  if (status.state === 'validation_failed' && status.currentAgent === 'build-verifier') {
+    writeStatus({
+      currentAgent: 'feature-developer',
+      state: 'in_progress',
+      phase: 'executing',
+      retryAfterFix: 'build-verifier',
+    });
+    out(
+      handoffForAgent('feature-developer') +
+        ` Read validation-report.md. After fixes, re-run build-verifier.`,
+    );
+    process.exit(0);
+  }
+  if (status.state === 'completed' && status.retryAfterFix) {
+    const retry = status.retryAfterFix;
+    writeStatus({ currentAgent: retry, state: 'in_progress', retryAfterFix: null });
+    out(handoffForAgent(retry));
+    process.exit(0);
+  }
+  if (status.phase === 'testing' && status.state === 'completed') {
+    writeStatus({ phase: 'done', state: 'completed' });
+    out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+    process.exit(0);
+  }
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+if (!fs.existsSync(pipelinePath)) {
+  legacyFlow();
+}
+
+let pipeline;
+try {
+  pipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8'));
+} catch {
+  legacyFlow();
+}
+
+const steps = pipeline.steps || [];
+if (steps.length === 0 || pipeline.autoChain === false) {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+if (status.awaitingHumanGate || status.state === 'awaiting_approval') {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+if (status.state === 'changes_requested' && REVIEW_AGENTS.has(status.currentAgent)) {
+  const reviewer = status.currentAgent;
+  writeStatus({
+    currentAgent: 'feature-developer',
+    state: 'in_progress',
+    phase: 'executing',
+    retryAfterFix: reviewer,
+  });
+  out(
+    handoffForAgent('feature-developer') +
+      ` After fixes, re-run ${reviewer}.`,
+  );
+  process.exit(0);
+}
+
+if (status.state === 'validation_failed' && status.currentAgent === 'build-verifier') {
+  writeStatus({
+    currentAgent: 'feature-developer',
+    state: 'in_progress',
+    phase: 'executing',
+    retryAfterFix: 'build-verifier',
+  });
+  out(
+    handoffForAgent('feature-developer') +
+      ` Read validation-report.md. After fixes, re-run build-verifier.`,
+  );
+  process.exit(0);
+}
+
+if (status.state === 'completed' && status.retryAfterFix) {
+  const retry = status.retryAfterFix;
+  writeStatus({ currentAgent: retry, state: 'in_progress', retryAfterFix: null });
+  out(handoffForAgent(retry));
+  process.exit(0);
+}
+
+const idx = typeof status.pipelineIndex === 'number' ? status.pipelineIndex : 0;
+const currentStep = steps[idx];
+if (!currentStep) {
+  writeStatus({ phase: 'done', state: 'completed', currentAgent: null });
+  out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+  process.exit(0);
+}
+
+const completedAgent = status.currentAgent || getStepAgents(currentStep)[0];
+const stepAgents = getStepAgents(currentStep);
+
+if (currentStep.parallel && stepAgents.length > 1) {
+  const done = [...(status.parallelCompleted || [])];
+  if (completedAgent && !done.includes(completedAgent)) {
+    done.push(completedAgent);
+  }
+  writeStatus({ parallelCompleted: done });
+  const remaining = stepAgents.filter((a) => !done.includes(a));
+  if (remaining.length > 0) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  writeStatus({ parallelCompleted: [] });
+}
+
+if (hasGateAfterStep(currentStep, pipeline.humanGates)) {
+  writeStatus({
+    awaitingHumanGate: true,
+    state: 'awaiting_approval',
+    currentAgent: completedAgent,
+  });
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+const next = findNextExecutableStep(steps, idx + 1, taskDir);
+if (!next) {
+  writeStatus({
+    pipelineIndex: steps.length,
+    phase: 'done',
+    state: 'completed',
+    currentAgent: null,
+    awaitingHumanGate: false,
+  });
+  out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+  process.exit(0);
+}
+
+const { step: nextStep, index: nextIdx } = next;
+const nextAgents = getStepAgents(nextStep);
+
+writeStatus({
+  pipelineIndex: nextIdx,
+  currentAgent: nextAgents[0],
+  phase: 'executing',
+  state: 'in_progress',
+  awaitingHumanGate: false,
+  parallelCompleted: [],
+});
+
+if (nextStep.parallel && nextAgents.length > 1) {
+  out(handoffForParallelStep(nextStep));
+} else {
+  out(handoffForAgent(nextAgents[0], nextStep.scope));
+}
+NODE

package/presets/claude/next/hooks/guard-shell-command.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Lightweight shell guard for Claude projects using this preset.
+
+set -euo pipefail
+
+input=$(cat)
+
+INPUT="$input" node <<'NODE'
+const fs = require('fs');
+
+const raw = process.env.INPUT || '';
+let event;
+try {
+  event = JSON.parse(raw);
+} catch {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const command = String(event.command || event.input?.command || '');
+if (!command.trim()) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+function out(permission, userMessage, agentMessage) {
+  process.stdout.write(JSON.stringify({
+    permission,
+    user_message: userMessage,
+    agent_message: agentMessage || userMessage,
+  }));
+}
+
+const dangerousGit = /\bgit\s+(reset\s+--hard|clean\s+-[^\n]*f|push\s+--force|push\s+-f|checkout\s+--\s+)/;
+if (dangerousGit.test(command)) {
+  out(
+    'ask',
+    'This command looks destructive for git state. Review it before continuing.',
+    'A project hook flagged a destructive git command. Ask the user before running it.',
+  );
+  process.exit(0);
+}
+
+const managerByFile = [
+  ['yarn.lock', 'yarn'],
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['package-lock.json', 'npm'],
+].find(([file]) => fs.existsSync(file));
+
+let expected = managerByFile?.[1];
+if (!expected && fs.existsSync('package.json')) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    const pm = typeof pkg.packageManager === 'string' ? pkg.packageManager : '';
+    expected = pm.split('@')[0] || undefined;
+  } catch {
+    // Ignore invalid package.json in the hook; the agent can diagnose it later.
+  }
+}
+
+if (!expected) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const used = command.match(/(^|[;&|]\s*)(npm|yarn|pnpm)\s+/)?.[2];
+if (used && used !== expected) {
+  out(
+    'ask',
+    `This repository appears to use ${expected}, but the command uses ${used}. Confirm before continuing.`,
+    `Use ${expected} for package scripts and installs unless the user explicitly approves ${used}.`,
+  );
+  process.exit(0);
+}
+
+process.stdout.write('{ "permission": "allow" }');
+NODE

package/presets/claude/next/mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    },
+    "playwright-test": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    },
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    },
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}

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

@@ -1,16 +1,47 @@
 # `.claude/rules` (preset next)
 
-В Claude Code все `.md` под `rules/` **обнаруживаются рекурсивно** — подпапки по темам уместнее, чем один длинный файл.
+В Claude Code все `.md` под `rules/` **обнаруживаются рекурсивно**. Правила без YAML frontmatter загружаются **в начале сессии**; с `paths:` — **только при работе** с matching-файлами.
 
-Соответствие темам из пресета Cursor (для переноса смысла из `.mdc`):
+## Loading strategy
 
-| Папка | О чём |
-|-------|--------|
-| `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 |
+- **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
+- **Skills:** long workflows (`feature-delivery`, `code-review`, …)
 
-Добавляйте сюда `.md` файлы с осмысленными именами (`testing.md`, `api-design.md`, …).
+### UI edit bundle (consolidated paths)
+
+При правке `app/src/ui/**/*.tsx` подгружается **уменьшенный** набор:
+
+| Rule | Назначение |
+|------|------------|
+| `ui-and-accessibility/react-ui.md` | Структура, стили, пропсы |
+| `architecture/architecture-boundaries-ui.md` | Slim границы UI-слоя |
+| `ui-and-accessibility/react-a11y-coding.md` | A11y |
+| `stack/navigation-router-ui.md` | Краткий ориентир навигации |
+
+**Не грузятся на типичный 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).
+
+## С чего начать
+
+- **`commands/task.md`** — router → `pipeline.json` → agents
+- **`architecture/reference-features.md`** — заполнить TBD после init
+- **`architecture/feature-delivery-workflow.md`** — порядок слоёв
+
+## Каталог (новые и ключевые)
+
+| Файл | Назначение |
+|------|------------|
+| `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/`.
+
+**Коллизии:** импорт типов и API — **`architecture/public-imports.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/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/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/public-imports.md`**; внутри слоя API — по относительным путям или `@/api/services/**` / `@/api/clients/**`, не дублируя публичный контракт мимо корневого barrel для внешних потребителей.

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

@@ -0,0 +1,40 @@
+---
+paths:
+  - app/src/lib/clients/**/*.ts
+  - app/src/api/clients/**/*.ts
+---
+
+# HTTP-транспорт
+
+**Имена** фабрик, классов ошибок, типов ответа и конфига — **как в текущем коде репозитория** и в barrel `app/src/types/index.ts`. Ниже — **архитектурные правила**, а не спецификация переименований.
+
+## Роль слоя
+
+- Обычные REST‑вызовы к backend идут через **одну реализацию** в `app/src/lib/clients/**` (модуль общего клиента) и **преднастроенные экземпляры** в `app/src/api/clients/**`, по тому же паттерну, что уже принят в проекте.
+- Место транспорта в общей картине **порты и адаптеры** — в `architecture/architecture-boundaries.md` (раздел **«Порты и адаптеры»**).
+- **Не** вызывать `fetch` напрямую из `app/src/api/services/**`, store и UI (см. `architecture/architecture-boundaries.md`, `api-and-data/api-services.md`); из store/UI — только вызовы через сервисы из `@/api` (`architecture/public-imports.md`).
+- **Исключения** (узкие протоколы, отдельный транспорт) — только там, где в репозитории уже есть образец; повторять его, не плодить произвольные обходы общего клиента.
+
+## Типы
+
+- Всё, что относится к **контракту запроса/ответа/ошибки** приложения и реэкспортируется для HTTP‑слоя, импортировать **только** из barrel `@/types`, без deep‑импортов из внутренних файлов `app/src/types/**` (см. `architecture/public-imports.md`).
+- Не поднимать в новом коде **типы и зависимости от внешнего HTTP‑клиента**, от которого проект ушёл; ориентир — **`package.json`** и существующие вызовы.
+
+## Контракт ошибок
+
+- Ошибки сети и HTTP должны приходить в **едином виде**, который задаёт общий клиент (обычно класс/обёртка с полем вроде `response` для тела и статуса).
+- В **`catch`** ориентироваться на **фактическую форму** ошибки в этом репозитории (как в соседних слайсах/сервисах): доступ к телу ошибки, статусу, диагностическому коду — **по полям текущей реализации**, без выдумывания второго формата.
+
+## Поведение, которое остаётся в клиенте
+
+- Общие заголовки, `credentials`, загрузка файлов (**FormData** / снятие лишних заголовков), бинарные ответы (**blob** и аналоги), единообразный разбор JSON и прочих тел.
+- Перехват **401 / refresh**, обработка **404** и т.п. — **централизованно**, если так уже сделано в клиенте; не дублировать ту же логику в каждом сервисе.
+
+## Связь со store
+
+- Thunk может возвращать **тип обёртки успешного ответа**, если сервис так устроен; в **state** по возможности класть **доменные** типы после маппинга. Подробнее — `api-and-data/store-rtk.md`.
+
+## Требование к агенту
+
+- Меняя реализацию общего клиента — **обновить или добавить behavior‑тесты** рядом с модулем клиента (`testing/tests-unit.md`).
+- Не вводить **второй полноценный HTTP‑стек** без явной задачи и согласования с архитектурой репозитория.