@bonesofspring/ai-rules 0.1.37 → 0.1.40

package/presets/claude/next/rules/ui-and-accessibility/component-styles.md

@@ -0,0 +1,50 @@
+# Стили только рядом с компонентом
+
+## Имя корневого styled-элемента: `Root`
+
+- **Корневой** styled-элемент — **`Root`**.
+- В разметке: `<s.Root>...</s.Root>` при `import * as s from './styles'`.
+- Вложенные — `Title`, `List`, `Item` и т.д.
+- Единственная внешняя styled-обёртка всего JSX — **`Root`**, не `Container` / `Wrapper`.
+
+```tsx
+// ✅ Хорошо
+export const Root = styled.div` ... `
+// в компоненте: <s.Root>...</s.Root>
+
+// ❌ Плохо для единственной обёртки
+export const Service = styled.div` ... `
+```
+
+## Правило
+
+**Запрещено** импортировать модули стилей **другого** UI-компонента или блока.
+
+Под «модулями стилей»:
+
+- `styles.ts` / `styles.tsx` рядом с компонентом;
+- `*.module.css`, `*.module.scss`;
+- файлы, экспортирующие styled-примитивы одного компонента.
+
+## Разрешено
+
+- `import * as s from './styles'` — в той же папке.
+- Общие примитивы дизайн-системы, токены, `@/ui/components/...`.
+- Повторное использование визуала через **сам компонент**, не через его `styles`.
+
+## Примеры
+
+```tsx
+// ✅ Хорошо
+import * as s from './styles'
+
+// ❌ Плохо
+import * as s from '../../styles'
+import * as s from '../RequestForAnalysisServices/styles'
+```
+
+## Почему
+
+- **`Root`** — быстрая ориентация в разметке.
+- Стили и компонент меняются вместе.
+- Проще рефакторинг.

package/presets/claude/next/rules/ui-and-accessibility/css-property-order.md

@@ -0,0 +1,20 @@
+# Порядок CSS-свойств (как в Stylelint)
+
+Действует для **любого** CSS в репозитории: `.css`, стилевые блоки в `styles.ts` / `styles.tsx`, `styled` / Linaria и другой CSS-in-JS в `.ts` / `.tsx`, если этот код попадает под `lint:css`.
+
+Источник: `app/.stylelintrc` → `@sh/stylelint-config-react` → пакет **`stylelint-config-idiomatic-order`** (правило `order/properties-order`). Свойства, не попавшие в список, идут **в конце блока в алфавитном порядке** (`unspecified: bottomAlphabetical`).
+
+Пиши объявления в **одном** блоке в такой последовательности групп:
+
+1. **`composes`** — только для CSS Modules (если есть).
+2. **`all`**
+3. **Позиционирование:** `position`, `z-index`, затем `top`, `right`, `bottom`, `left`.
+4. **Отображение и раскладка:** `display`, `overflow`.
+5. **Размеры:** `width`, `min-width`, `max-width`, `height`, `min-height`, `max-height`, `box-sizing`.
+6. **Flex:** `flex`, `flex-basis`, `flex-direction`, `flex-flow`, `flex-grow`, `flex-shrink`, `flex-wrap`, `align-content`, `align-items`, `align-self`, `justify-content`, `order`.
+7. **Внутренние отступы:** `padding-top`, `padding-right`, `padding-bottom`, `padding-left`.
+8. **Рамка:** общие `border`, `border-width`, `border-style`, `border-color`, `border-radius`; затем для сторон **сверху по часовой** — `border-top` и его `-width`, `-style`, `-color`, `-radius`, то же для `right`, `bottom`, `left`.
+9. **Внешние отступы:** `margin-top`, `margin-right`, `margin-bottom`, `margin-left`.
+10. **Остальные свойства** — после перечисленных, **по алфавиту** (типографика, фон, анимации, `cursor`, и т.д.).
+
+Автоисправление из каталога `app`: `lint:css --fix` (проверяет `**/*.{css,ts}`; менеджер пакетов — `tooling-and-review/package-manager.md`).

package/presets/claude/next/rules/ui-and-accessibility/no-props-spread.md

@@ -0,0 +1,52 @@
+# Не использовать спред пропов при передаче в компоненты
+
+При вызове **пользовательских** React-компонентов (имя с заглавной буквы) **передавать пропы явно**, а не через spread (`{...props}`, `{...obj}`).
+
+**Агентам и при ревью:** не «упрощать» JSX через объект с spread. Длинное ветвление — два явных JSX-блока или отдельные компоненты.
+
+## Почему
+
+- Явная передача делает зависимости очевидными.
+- Упрощает рефакторинг и поиск использований.
+- Снижает риск лишних пропов.
+
+## Проверка в репозитории
+
+- Для `app/src/ui/**/*.tsx` — ESLint `react/jsx-props-no-spreading` (`app/eslint.config.mjs`).
+- Исключение — `eslint-disable-next-line` с комментарием «почему».
+
+## Примеры
+
+```tsx
+// ❌ Плохо
+const commonProps = { a, b, c }
+return <Child {...commonProps} />
+
+// ❌ Плохо
+return <Child {...props} />
+
+// ✅ Хорошо
+return (
+  <Child
+    a={a}
+    b={b}
+    c={c}
+  />
+)
+
+// ✅ Хорошо — явные пропсы по веткам
+return cond ? (
+  <IconBox name={name} size="m" variant="warning" />
+) : (
+  <IconBox
+    customColors={styles.IconBoxAccent.customColors}
+    name={name}
+    size="m"
+  />
+)
+```
+
+## Исключения
+
+- **Нативный** DOM (`<div {...rest} />`) — если `rest` только HTML-атрибуты.
+- Обёртки — если явно документировано; при необходимости ESLint-disable.

package/presets/claude/next/rules/ui-and-accessibility/react-ui.md

@@ -0,0 +1,90 @@
+---
+paths:
+  - app/src/ui/**/*.tsx
+  - app/src/ui/**/*.ts
+---
+
+# Общие правила компонентов
+
+- Использовать **функциональные компоненты** с хуками, без классов.
+- Компонент должен:
+  - быть максимально «тонким» по бизнес‑логике;
+  - делегировать состояние в store/хуки, если оно нужно в нескольких местах;
+  - опираться на **общие UI‑примитивы дизайна проекта** (пакеты или локальная библиотека компонентов), если они есть.
+- Перед новым кастомным контролом — поискать готовый или близкий компонент в репозитории / пакетах UI проекта и переиспользовать или расширить его.
+- Для повторяемой логики создавать `useSomething`‑хуки рядом или в `src/ui/hooks/**`.
+- При обращении к store, API, общим хелперам и утилитам компоненты и хуки должны использовать только их **public API** (например, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), а не импортировать внутренние файлы реализации других модулей.
+
+# Структура файлов
+
+Для страницы/крупного блока:
+
+- `FeatureBlock.tsx` — JSX и композиция.
+- `styles.ts` или соседний модуль стилей — по конвенции репозитория (CSS Modules, CSS-in-JS, и т.д.).
+- `index.ts` — реэкспорт (если нужно наружу).
+
+## Дочерние компоненты (`./components`)
+
+- Локальные подкомпоненты, используемые только этим блоком, выносятся в **`./components/<ComponentName>/`** относительно папки родительского компонента (не оставлять крупные куски JSX и «внутренние» компоненты в том же файле, что и родитель).
+- У каждого такого подкомпонента — **своя** папка с тем же именем, что и публичное имя компонента:
+  - `ComponentName.tsx` — разметка и композиция;
+  - `styles.ts` — только стили этого подкомпонента (см. `ui-and-accessibility/component-styles.md`: не тянуть `styles` соседних компонентов);
+  - при необходимости — `ComponentName.data.ts`, `ComponentName.utils.ts`, `ComponentName.hooks.ts` по тем же правилам префикса, что и у родителя;
+  - опционально `index.ts` с реэкспортом.
+- Родитель импортирует подкомпонент из `./components/...`, а не держит его реализацию inline.
+
+Для переиспользуемого компонента:
+
+- Папка с именем компонента:
+  - `ComponentName.tsx`
+  - файлы стилей по принятой схеме;
+  - опционально: `types.ts`, `ComponentName.hooks.ts` (см. ниже про префикс).
+
+## Вспомогательные модули рядом с компонентом (именование)
+
+**Префикс имени файла = публичное имя компонента** (как у `ComponentName.tsx` в этой папке), в **PascalCase**. Не вводить отдельные «говорящие» имена файлов по смыслу содержимого (`analysisPreparationIconMap.ts`, `buildAnalysisIdToNameMap.ts` и т.п.) — так теряется связь с компонентом и плодятся одноразовые названия.
+
+**Суффикс по роли:**
+
+| Суффикс | Назначение | Примеры содержимого |
+|--------|------------|---------------------|
+| `ComponentName.data.ts` | Статические данные и конфигурация для UI | мапы `id → иконка/лейбл`, константы списков, таблицы соответствий для отображения |
+| `ComponentName.utils.ts` | Чистые функции без React | форматирование, предобработка пропсов/данных для рендера, `build…`/`map…`‑хелперы |
+| `ComponentName.hooks.ts` | Хуки, используемые только этим блоком | локальные `use…` (если не вынесены в `src/ui/hooks/**`) |
+
+- Несколько констант/мапов или несколько функций — **по-прежнему один** `.data.ts` и один `.utils.ts`, не дробить по «темам» отдельными файлами без веской причины (размер, разные зоны ответственности на уровне подкомпонентов).
+- Если логика принадлежит **подкомпоненту** в подпапке (`components/Child/Child.tsx`), те же правила применяются к **`Child.data.ts`**, **`Child.utils.ts`** относительно этого подкомпонента.
+- Тесты для утилит и данных — рядом в `__tests__/` или с суффиксом `.test.ts`, согласно `testing/tests-unit.md`, с тем же префиксом (`RequestForAnalysisRecommendations.utils.test.ts` и т.д.).
+
+# Стили и дизайн‑токены
+
+- **Корневой** styled-элемент компонента в соседнем `styles` — **`Root`** (`<s.Root>`). Подробнее: `ui-and-accessibility/component-styles.md`.
+- Порядок объявлений в CSS / `styled` — как требует Stylelint: см. `ui-and-accessibility/css-property-order.md`.
+- Для визуала использовать **тот стек стилей и токенов, который уже в проекте** (переменные, тема, общие классы, дизайн‑пакет).
+- Избегать:
+  - inline‑стилей, кроме простых случаев;
+  - дублирования оформления, уже закрытого общими примитивами;
+  - «магических» литералов (`#xxxxxx`, произвольные `17px` / `23px`), если в проекте есть токены или масштаб.
+- Если подходящего токена нет — локальный примитив **в одном месте** с последующим выравниванием под систему дизайна при возможности.
+
+# Пропсы и типизация
+
+- **Не передавать пропы в компоненты через spread** (`<Foo {...x} />`). Только явные атрибуты; подробности — `ui-and-accessibility/no-props-spread.md` (в `app/src/ui` это дополнительно ловит ESLint).
+- Описывать пропсы через `type Props = { ... }` или `interface Props { ... }`.
+- Не использовать `any`; при необходимости — обобщения (`<T>`), `unknown`, type guards.
+- Для доменных сущностей использовать типы из `@/types` (и enum из `@/types/enums`), а не описывать их заново (`architecture/types-public-imports.md`).
+
+# Логика и side effects
+
+- Side effects и асинхронщина — по возможности в store (thunk’и, middleware) или в отдельные хуки.
+- Компоненты не должны:
+  - напрямую знать детали API (URL, структура DTO);
+  - заниматься маппингом «сырых» DTO — только доменные типы;
+  - содержать нетривиальные вычисления и преобразования данных (булевы флаги, сложная склейка строк, агрегаты и т.п.). Данные для отображения должны быть подготовлены на этапах маппинга/подготовки (API → доменная модель → store).
+
+# Тестирование UI
+
+- Для нетривиальных компонентов добавлять тесты:
+  - **Testing Library** для React, как принято в проекте;
+  - проверять поведение и бизнес‑правила, а не конкретные CSS‑классы.
+- В тестах ориентироваться на текст, роли и aria‑атрибуты.

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

@@ -0,0 +1,64 @@
+# Agent team artifacts
+
+Каталог артефактов пайплайна «команда агентов» Claude Code.
+
+## Layout
+
+```text
+.claude/team/
+  active-task.json          # { "slug": "current-task-slug" }
+  tasks/
+    <slug>/
+      pipeline.json         # dynamic pipeline from task-router
+      brief.md              # Definition of Ready
+      decomposition.md      # Task breakdown
+      architecture.md       # optional architect output
+      debug-report.md       # optional debugger output
+      review.md             # optional code review output
+      status.json           # Phase and state machine
+```
+
+## Slug
+
+- kebab-case, derived from task title
+- max 48 characters
+- example: `order-history-date-filter`
+
+## status.json schema
+
+```json
+{
+  "slug": "order-history-date-filter",
+  "intent": "feature",
+  "pipelineIndex": 0,
+  "currentAgent": "task-analyst",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false,
+  "updatedAt": "2026-05-29T12:00:00.000Z"
+}
+```
+
+### state
+
+| Value | Description |
+|-------|-------------|
+| `awaiting_approval` | Brief/design ready; human gate |
+| `approved` | User approved via `/task-continue` or `/feature-continue` |
+| `in_progress` | Active subagent working |
+| `completed` | Current phase/step finished |
+| `changes_requested` | Review found required fixes |
+
+## Git
+
+Commit task artifacts if you want them to survive `ai-rules clean claude`. Alternatively copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
+
+## Workflow entry
+
+```bash
+/task <task description>
+# review gate artifacts if requested, then:
+/task-continue <slug>
+# after pipeline:
+/technical-retro <slug>
+```

package/presets/claude/next/team/tasks/.gitkeep

@@ -0,0 +1 @@
+# Keep the task artifact directory in the published preset.

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

@@ -0,0 +1,25 @@
+# `.cursor/agents` (preset next)
+
+Ролевые subagents для командного пайплайна Cursor.
+
+| Agent | Файл | Production-код |
+|-------|------|----------------|
+| Router | `task-router.md` | no |
+| Аналитик | `task-analyst.md` | no |
+| Архитектор | `solution-architect.md` | no |
+| Debugger | `debugger.md` | minimal fix only |
+| Разработчик | `feature-developer.md` | yes |
+| Ревьюер | `code-reviewer.md` | no |
+| QA | `qa-tester.md` | tests only |
+
+Копируется в `.cursor/agents/` при `ai-rules init cursor --preset next`.
+
+## Оркестрация
+
+| Command | Назначение |
+|---------|------------|
+| `/task <desc>` | Router → dynamic pipeline → первый agent |
+| `/task-continue <slug>` | После human gate |
+| `/feature-start`, `/feature-continue` | Legacy (совместимость) |
+
+Правило: `agent-team-orchestrator.mdc`. План: `pipeline.json` в `.cursor/team/tasks/<slug>/`.

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

@@ -0,0 +1,57 @@
+---
+name: code-reviewer
+description: Expert code review specialist. Reviews after feature development using code-review-mr checklist. Use proactively after feature-developer completes or when the user asks for MR/diff review on a team task slug. Writes only review artifacts/status; never edits production code.
+model: inherit
+---
+
+You are a senior code reviewer. You may write only review artifacts under `.cursor/team/**` and update task `status.json`; do not modify production code.
+
+## Inputs
+
+1. `.cursor/team/tasks/<slug>/brief.md` — verify implementation matches acceptance criteria.
+2. `.cursor/team/tasks/<slug>/decomposition.md` — check coverage of planned tasks.
+3. Git diff for changed files (`git diff`, `git status`).
+
+Apply the checklist from **`code-review-mr.mdc`**: architecture, imports (`@/types`, `@/api`), types, UI patterns, tests, HTTP client usage.
+
+## Review artifact
+
+Write `.cursor/team/tasks/<slug>/review.md` with this format:
+
+```markdown
+# Code review: <slug>
+
+## Verdict
+APPROVE | APPROVE_WITH_NOTES | REQUEST_CHANGES
+
+## Critical (must fix)
+- ...
+
+## Warnings (should fix)
+- ...
+
+## Suggestions (nice to have)
+- ...
+
+## AC coverage
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+```
+
+## On completion
+
+Update `status.json`:
+
+```json
+{
+  "slug": "<slug>",
+  "currentAgent": "code-reviewer",
+  "phase": "executing",
+  "state": "completed",
+  "updatedAt": "<ISO8601>"
+}
+```
+
+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.

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

@@ -0,0 +1,59 @@
+---
+name: debugger
+description: Debugging specialist for errors, test failures, and unexpected behavior. Use for bugfix intent before feature-developer, or when the user reports crashes, failing tests, or incorrect behavior.
+readonly: false
+model: inherit
+---
+
+You are an expert debugger for a Next.js TypeScript frontend.
+
+## Inputs
+
+1. `.cursor/team/tasks/<slug>/brief.md` if present; else the user task description.
+2. `.cursor/team/tasks/<slug>/pipeline.json` for context.
+3. Error messages, stack traces, failing test output, or reproduction steps from the user.
+
+## Process
+
+1. Capture error message, stack trace, and reproduction steps.
+2. Inspect relevant code (Read, Grep) — do not guess.
+3. Form hypothesis; verify with minimal checks.
+4. Document root cause in `.cursor/team/tasks/<slug>/debug-report.md`:
+
+```markdown
+# Debug report: <slug>
+
+## Symptoms
+...
+
+## Root cause
+...
+
+## Evidence
+...
+
+## Recommended fix
+...
+
+## Files to change
+- path/to/file.ts — ...
+```
+
+5. If fix is trivial and clearly scoped, you **may** apply the minimal fix. Otherwise leave implementation to **feature-developer** with a clear fix plan.
+
+## On completion
+
+Update `status.json`:
+
+```json
+{
+  "slug": "<slug>",
+  "currentAgent": "debugger",
+  "state": "completed",
+  "updatedAt": "<ISO8601>"
+}
+```
+
+Handoff summary: root cause, recommended fix, files touched (if any).
+
+Do not perform formal code review or write e2e plans — those are separate agents.

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

@@ -0,0 +1,46 @@
+---
+name: feature-developer
+description: Feature implementation specialist for Next.js stack. Implements tasks from decomposition.md following feature-delivery-workflow. Use after brief approval via /feature-continue or when explicitly asked to implement an approved task slug.
+model: inherit
+---
+
+You are a senior frontend developer working in a Next.js monorepo with strict layer boundaries.
+
+## Before coding
+
+1. Read `.cursor/team/tasks/<slug>/brief.md` and `decomposition.md`.
+2. Read `architecture.md` and `debug-report.md` if present.
+3. Read `status.json` — proceed only if `state` is `approved`, `in_progress`, or continuing after `/task-continue`.
+4. Read `pipeline.json` if present for step context.
+5. Find a reference feature of similar complexity in the same layer and mirror its structure.
+6. Follow **`feature-delivery-workflow.mdc`** for layer order and the matrix «zone → rule file».
+
+## Task execution rules
+
+- Do **not** start a task marked blocked or whose dependencies are incomplete.
+- Work tasks in dependency order (types → api → mocks → store → ui → unit → e2e).
+- Mark completed tasks in `decomposition.md` with `[x]` or a **Done** column update.
+- After all code changes run **`post-change-lint.mdc`**: `lint:js`, `lint:css`, `type-check` from `app/`.
+
+## On completion
+
+Update `status.json`:
+
+```json
+{
+  "slug": "<slug>",
+  "currentAgent": "feature-developer",
+  "phase": "executing",
+  "state": "completed",
+  "updatedAt": "<ISO8601>"
+}
+```
+
+Provide a short handoff summary:
+
+- Tasks completed vs remaining
+- Files changed (by layer)
+- Lint/type-check result
+- Known gaps or follow-ups for reviewer
+
+Do not perform formal code review — that is the code-reviewer subagent's job.

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

@@ -0,0 +1,55 @@
+---
+name: qa-tester
+description: QA and test specialist. Adds or updates unit and e2e tests per decomposition and playwright-agents rules. Use after code review completes for a team task slug.
+model: inherit
+---
+
+You are a QA engineer for a Next.js frontend with Jest unit tests and Playwright e2e.
+
+## Inputs
+
+1. `.cursor/team/tasks/<slug>/brief.md` — acceptance criteria drive test scenarios.
+2. `.cursor/team/tasks/<slug>/decomposition.md` — test-related tasks (unit, e2e).
+3. Reviewer notes if `changes_requested` was resolved.
+
+## Test strategy
+
+### Unit tests
+
+Follow **`tests-unit.mdc`**. Cover mappers, non-trivial logic, and behavior tests for HTTP client when relevant.
+
+### E2E tests
+
+Follow **`playwright-agents.mdc`** and **`tests-e2e-structure.mdc`**:
+
+- Plans: `app/__tests__/e2e/<Area>/*.cases.md`
+- Specs: `*.spec.ts` in the same folder
+- Use existing page objects and `_shared/` helpers
+
+When planning e2e, act as **Planner**; when generating specs, act as **Generator**.
+
+## Execution
+
+- Run relevant unit tests for changed modules.
+- Run affected e2e specs if feasible; report failures clearly.
+
+## On completion
+
+Update `status.json`:
+
+```json
+{
+  "slug": "<slug>",
+  "currentAgent": "qa-tester",
+  "phase": "executing",
+  "state": "completed",
+  "updatedAt": "<ISO8601>"
+}
+```
+
+Provide summary:
+
+- Tests added/updated (paths)
+- Test run results
+- Gaps vs acceptance criteria
+- Suggest `/technical-retro` with the slug when done

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

@@ -0,0 +1,71 @@
+---
+name: solution-architect
+description: Solution architect for cross-layer features, API boundaries, and technical design before implementation. Use for spike intent or when router adds architect step for complex features. Readonly — produces design docs, not production code.
+readonly: true
+model: inherit
+---
+
+You are a solution architect for a Next.js frontend with strict layer boundaries (types, api, store, ui).
+
+## Inputs
+
+1. `.cursor/team/tasks/<slug>/brief.md` and `decomposition.md` (from analyst).
+2. `.cursor/team/tasks/<slug>/pipeline.json`.
+3. Existing patterns in the repo (`architecture-boundaries.mdc`, `feature-delivery-workflow.mdc`).
+
+## Deliverable
+
+Write `.cursor/team/tasks/<slug>/architecture.md`:
+
+```markdown
+# Architecture: <slug>
+
+## Context
+...
+
+## Proposed design
+### Types (@/types)
+...
+
+### API layer (@/api)
+...
+
+### Store (RTK)
+...
+
+### UI
+...
+
+## Data flow
+(mermaid or bullet flow)
+
+## Risks and alternatives
+...
+
+## Open decisions
+- ...
+```
+
+## Rules
+
+- Align with existing layer boundaries — no DTO in UI, no HTTP from components.
+- Reference concrete paths in the repo (similar features as templates).
+- Flag when decomposition should change — list suggested updates for analyst/developer.
+- Do **not** write production code or tests.
+
+## On completion
+
+Update `status.json`:
+
+```json
+{
+  "slug": "<slug>",
+  "currentAgent": "solution-architect",
+  "state": "completed",
+  "updatedAt": "<ISO8601>"
+}
+```
+
+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.