@bonesofspring/ai-rules 0.2.13 → 0.2.15

package/presets/cursor/next/rules/tests-unit.mdc

@@ -1,5 +1,5 @@
 ---
-description: Unit и интеграционные тесты (Testing Library и runner проекта)
+description: Unit and integration tests (Testing Library and project runner)
 globs:
   - app/src/**/*.spec.{ts,tsx}
   - app/src/**/*.test.{ts,tsx}
@@ -7,72 +7,71 @@ alwaysApply: false
 impact: MEDIUM
 ---
 
-# Общие правила тестирования
-
-- **Имена файлов:** для **новых** тестов использовать суффикс **`*.spec.ts` / `*.spec.tsx`**. Существующие **`*.test.ts` / `*.test.tsx`** не переименовывать без отдельной задачи (легаси).
-- **Runner и матчеры** — как в проекте (часто Jest или Vitest); для компонентов — **@testing-library/react**.
-- Основная цель тестов:
-  - проверять **поведение и бизнес‑правила**, а не реализацию или внутренние детали.
-- **Именование unit‑тестов** (строки в `describe` / `it` / `test`):
-  - формулировки **только на русском языке** — понятные бизнес‑фразы (что проверяется и какой ожидается результат);
-  - **каждое предложение** в названии **начинается с заглавной буквы** (в том числе после `.`, `!`, `?` и при нескольких предложениях в одной строке); первая буква всей строки — тоже заглавная.
-  - **Проверка в CI:** ESLint (`jest/valid-title` в `app/eslint.config.mjs`) требует, чтобы строка начиналась с русской заглавной (А–Я, Ё), и запрещает пробел после точки, за которым сразу идёт строчная буква (типичный случай нарушения «с заглавной после точки»).
-
-```typescript
-// ✅ Хорошо
-it('Возвращает пустой список. Пользователь не авторизован', () => {})
-it('При ошибке сети показывается сообщение об ошибке', () => {})
-
-// ❌ Плохо (не с заглавной после точки; или не русский)
-it('Возвращает пустой список. пользователь не авторизован', () => {})
-it('Returns empty list when user is guest', () => {})
-```
+# General testing rules
+
+- **File names:** for **new** tests use the **`*.spec.ts` / `*.spec.tsx`** suffix. Do not rename existing **`*.test.ts` / `*.test.tsx`** without a separate task (legacy).
+- **Runner and matchers** — as in the project (often Jest or Vitest); for components — **@testing-library/react**.
+- Primary goal of tests:
+  - verify **behavior and business rules**, not implementation or internal details.
+- **Unit test naming** (strings in `describe` / `it` / `test`):
+  - consumer apps **may use Russian locale** for titles — clear business phrases (what is checked and expected outcome);
+  - when ESLint enforces Russian (see below), each sentence in the title **must start with a capital letter** (including after `.`, `!`, `?` and with multiple sentences on one line); the first letter of the whole string is capitalized too.
+  - **CI check (when configured):** ESLint (`jest/valid-title` in `app/eslint.config.mjs`) may require titles to start with a Russian capital letter and forbid a space after `.` followed immediately by a lowercase letter (typical "capital after period" violation).
+
+Good (Russian locale in consumer app):
+
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
+- `it('При ошибке сети показывается сообщение об ошибке', () => {})` <!-- i18n-keep: E5 --> (On network error, an error message is shown)
+
+Bad (no capital after period; or wrong locale for configured ESLint):
 
-# Тесты компонентов
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `it('Returns empty list when user is guest', () => {})`
 
-- Использовать `render` из `@testing-library/react`.
-- Ассерты:
-  - матчеры DOM для Testing Library, как подключены в проекте (`toBeInTheDocument`, `toHaveTextContent` и т.п.).
-- Взаимодействия:
-  - `userEvent` из `@testing-library/user-event`.
+# Component tests
 
-# Изоляция и моки
+- Use `render` from `@testing-library/react`.
+- Assertions:
+  - DOM matchers for Testing Library as wired in the project (`toBeInTheDocument`, `toHaveTextContent`, etc.).
+- Interactions:
+  - `userEvent` from `@testing-library/user-event`.
 
-- Для работы с API/store:
-  - мокать store (через test‑store) или использовать принятый в проекте способ моков HTTP/API.
-- Не мокать то, что является частью публичного контракта фичи, если это ломает смысл теста.
+# Isolation and mocks
 
-# HTTP‑клиент
+- For API/store work:
+  - mock the store (via test-store) or use the project's accepted HTTP/API mock approach.
+- Do not mock what is part of the feature's public contract if that breaks the test's meaning.
 
-- При изменении **реализации общего HTTP‑клиента** (разбор тел, заголовки, ветки ошибок, 401/refresh, `FormData`, `blob` и т.п.) — **обновить или добавить behavior‑тесты** рядом с модулем клиента в `app/src/lib/clients/**` (предпочтительно `*.spec.ts`; легаси `*.test.ts` — не трогать без задачи).
-- Проверять смысловые ветки: успешный JSON, HTTP‑ошибка, сеть, релевантные для проекта сценарии авторизации.
+# HTTP client
 
-# Мапперы и преобразование данных
+- When changing the **shared HTTP client implementation** (body parsing, headers, error branches, 401/refresh, `FormData`, `blob`, etc.) — **update or add behavior tests** next to the client module in `app/src/lib/clients/**` (prefer `*.spec.ts`; legacy `*.test.ts` — do not touch without a task).
+- Cover meaningful branches: successful JSON, HTTP error, network, auth scenarios relevant to the project.
 
-- Функции маппинга данных (DTO -> доменная модель и обратно), особенно содержащие вычисляемые поля и ветвления, должны быть покрыты unit‑тестами.
-- В тестах мапперов особое внимание уделять edge‑кейсам и регрессии бизнес‑правил (например, граничные значения, отсутствие полей, неожиданные комбинации значений).
+# Mappers and data transformation
 
-# Требование к агенту
+- Data mapping functions (DTO → domain model and back), especially with computed fields and branches, must have unit tests.
+- In mapper tests, pay special attention to edge cases and business-rule regression (for example, boundary values, missing fields, unexpected value combinations).
 
-При добавлении тестов:
-- Следовать существующей структуре и паттернам тестов в репозитории: файл `*.spec.ts(x)` рядом с модулем или в общем каталоге тестов — как в соседних фичах.
-- Добавлять тесты для критичных веток логики и edge‑кейсов.
- - При работе с данными:
-   - использовать **типы респонса** из API (DTO‑типы), а также **целевые доменные типы** из `@/types`, не дублировать интерфейсы в тестах;
-   - по возможности опираться на данные и обработчики из `app/src/mocks/**` (или аналог в репо), а не плодить случайные тестовые данные "с нуля".
- - Размещение:
-   - для **компонентов UI** — **не создавать** поддиректорию `__tests__` внутри папки компонента; тест — соседний `*.spec.tsx`.
-   - в **других модулях** (например `api/services`) допустима уже существующая схема с `__tests__` — не ломать ради единообразия с UI.
-   - **новые** файлы — `*.spec.ts` / `*.spec.tsx` (см. блок «Имена файлов» выше).
+# Agent requirement
+
+When adding tests:
+- Follow existing test structure and patterns in the repository: `*.spec.ts(x)` next to the module or in a shared test directory — as in neighboring features.
+- Add tests for critical logic branches and edge cases.
+ - When working with data:
+   - use **response types** from the API (DTO types) and **target domain types** from `@/types`; do not duplicate interfaces in tests;
+   - when possible, rely on data and handlers from `app/src/mocks/**` (or repo equivalent), not ad-hoc random test data.
+ - Placement:
+   - for **UI components** — **do not create** a `__tests__` subdirectory inside the component folder; the test is a sibling `*.spec.tsx`.
+   - in **other modules** (for example `api/services`) an existing `__tests__` layout is acceptable — do not break it for UI uniformity.
+   - **new** files — `*.spec.ts` / `*.spec.tsx` (see "File names" above).
 ## Incorrect
 
 ```ts
 it('returns empty list when guest', () => {})
-it('Возвращает пустой список. пользователь не авторизован', () => {})
 ```
 
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+
 ## Correct
 
-```ts
-it('Возвращает пустой список. Пользователь не авторизован', () => {})
-```
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->

package/presets/cursor/next/rules/types-jsdoc.mdc

@@ -1,42 +1,49 @@
 ---
-description: Стиль JSDoc для доменных и транспортных типов в app/src/types
+description: JSDoc style for domain and transport types in app/src/types
 globs: app/src/types/**/*.ts
 alwaysApply: false
 ---
 
-# Документация типов в `app/src/types`
+# Type documentation in `app/src/types`
 
-При добавлении или существенном изменении типов в этом слое **следовать уже принятому в репозитории стилю JSDoc** (см. примеры: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
+When adding or substantially changing types in this layer, **follow the JSDoc style already adopted in the repo** (see examples: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
 
-## Язык и форма
+## Language and form
 
-- Текст комментариев — **на русском**, кратко и по делу: что означает тип или поле в предметной области или в контракте с API.
-- **Не опираться** на теги в духе `@param`, `@returns`, `@see`, `@deprecated` для описания типов — в этом слое они **не используются**; достаточно обычного текста в `/** … */`.
+- Comment text — **in Russian** (repo locale convention for domain/API field descriptions), brief and to the point: what the type or field means in the domain or API contract.
+- **Do not rely** on tags like `@param`, `@returns`, `@see`, `@deprecated` for type descriptions — they are **not used** in this layer; plain text in `/** … */` is enough.
 
-## Экспортируемый `type` / `interface`
+## Exported `type` / `interface`
 
-- Сразу **перед объявлением** — блок `/** … */`.
-- Если нужно пояснить источник данных, ограничения или неочевидности — **второй абзац** в том же блоке (в JSDoc для абзаца — пустая строка между строками текста).
-- Для **вложенных** объектов в том же файле каждый такой тип документируется отдельным блоком над своим объявлением.
+- Immediately **before the declaration** — a `/** … */` block.
+- If you need to explain data source, constraints, or non-obvious details — a **second paragraph** in the same block (in JSDoc, separate paragraphs with a blank line between text lines).
+- For **nested** objects in the same file, document each type with its own block above its declaration.
 
-## Поля
+## Fields
 
-- У **каждого** публичного свойства — **однострочный** `/** … */` на строке непосредственно **над** полем.
-- Если поле **не приходит с бэкенда «как есть»**, а вычисляется или дополняется на фронте (маппер, селектор, UI) — начать описание с префикса **`[computed]`** (как в `TUserProfile`, типах плана лечения).
-- Для форматов данных указывать это **в тексте**: например дата `YYYY-MM-DD`, пример отображаемой строки в кавычках.
+- For **every** public property — a **single-line** `/** … */` on the line directly **above** the field.
+- If a field **does not come from the backend as-is** but is computed or enriched on the frontend (mapper, selector, UI) — start the description with the **`[computed]`** prefix (as in `TUserProfile`, treatment plan types).
+- For data formats, state this **in the text**: e.g. date `YYYY-MM-DD`, a display string example in quotes.
 
-## Классы и прочие объявления
+Example field comment (Russian locale — keep Cyrillic in type docs): <!-- i18n-keep: E5 -->
 
-- Для **классов** (например ошибки транспорта) при изменении публичного API — краткий блок над классом и **комментарии к публичным полям** по тем же правилам, что у свойств интерфейса.
+```ts
+/** Дата рождения в формате YYYY-MM-DD */ <!-- i18n-keep: E5 -->
+birthDate: string
+```
+
+## Classes and other declarations
+
+- For **classes** (e.g. transport errors), when changing public API — a brief block above the class and **comments on public fields** using the same rules as interface properties.
 
 ## `enum`
 
-- В `enums.ts` исторически часто **без JSDoc** на каждом члене; для новых enum допустимо короткое описание **над самим enum**, если назначение неочевидно из имени. Подписи для UI — как принято, через объекты `*Names` рядом с enum.
+- In `enums.ts`, members are often **without JSDoc** historically; for new enums a short description **above the enum** is acceptable if purpose is not obvious from the name. UI labels — as established, via `*Names` objects next to the enum.
 
-## Практика для агента
+## Agent practice
 
-- Добавляя новый тип или поле, **не оставлять** новые публичные поля без пояснения, если смысл не равен имени на 100%.
-- Правя файл, где уже есть такие комментарии, **поддерживать тот же стиль**, а не смешивать с англоязычными или «теговыми» блоками.
-- Не раздувать комментарии: одна-две фразы на тип, одна строка на поле — норма; исключение — действительно сложная доменная оговорка.
+- When adding a new type or field, **do not leave** new public fields unexplained if meaning is not 100% clear from the name.
+- When editing a file that already has such comments, **maintain the same style**, not mixed with English-only or tag-heavy blocks.
+- Do not bloat comments: one or two sentences per type, one line per field is normal; exception — a genuinely complex domain caveat.
 
-См. также импорты и barrel: `public-imports.mdc`.
+See also imports and barrel: `public-imports.mdc`.

package/presets/cursor/next/skills/feature-delivery/SKILL.md

@@ -8,7 +8,7 @@ description: Delivers Next.js frontend features end-to-end across domain types,
 1. Read task brief, acceptance criteria, and decomposition if present.
 2. Read **`feature-delivery-workflow.mdc`** and **`reference-features.mdc`** — follow layer order and mirror closest reference feature.
 3. Add or update focused tests for changed behavior.
-4. Validation from `app/`: **invoke** **`post-change-lint.mdc`** after code edits (requestable, not always-on — but mandatory when code changed). Pipeline: scoped lint OK if next step is `build-verifier`.
+4. Validation from `app/`: **invoke** **`post-change-lint.mdc`** after code edits (requestable, not always-on — but **must** when code changed). Pipeline: scoped lint OK if next step is `build-verifier`.
 
 ## Scope discipline
 

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

@@ -1,6 +1,6 @@
 # Agent team artifacts
 
-Каталог артефактов пайплайна «команда агентов» Cursor.
+Artifact directory for the Cursor “agent team” pipeline.
 
 ## Layout
 
@@ -97,7 +97,7 @@ Prefer **`executing`** for pipeline mode. Legacy: `analysis`, `development`, `re
 ## Workflow entry
 
 ```bash
-/task <описание задачи>
+/task <task description>
 /task-continue <slug>
 /technical-retro <slug>
 ```

package/presets/cursor/nuxt/AGENTS.md

@@ -0,0 +1,39 @@
+# Nuxt 3 stack — Cursor agent team
+
+Short Cursor entry point. Detailed rules — `.cursor/rules/*.mdc`; scenarios — `.cursor/skills/**`.
+
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root (cross-tool setup, commands, security, living conventions pointers).
+
+See `.cursor/rules/README.md` for the full catalog and loading strategy.
+
+## Quick start
+
+| Task | Where to look |
+|------|----------------|
+| Any new work task | `/task` → `commands/task.md` + `agent-team-orchestrator.mdc` (+ `agent-team-intake.mdc` on-demand) |
+| New end-to-end feature | skill `feature-delivery` + `feature-delivery-workflow.mdc` |
+| Stack and layers | `nuxt-app-core.mdc` |
+| Reference features | `reference-features.mdc` (fill in repo paths) |
+| After code edits | `post-change-lint.mdc` (**requestable**, but required after edits; full gate — `build-verifier`) |
+| Code review MR | skill `code-review` + `code-review-mr.mdc` |
+| Security (auth/forms/env) | `security-nuxt.mdc` + agent `security-reviewer` |
+| Validation before review | agent `build-verifier` |
+| Technical retro | `/technical-retro` + skill `technical-retro` |
+
+## When to use `/task`
+
+- Implementation, bugfix, migration, tests, MR review, CI-fix — **prefer `/task`**.
+- Simple one-liner with no architecture risk — may skip the pipeline if the user explicitly asks.
+- “How does X work?” questions — agent `codebase-analyzer` (explain-as-is) or answer without `/task`.
+
+## Pipeline routing
+
+Intent detection, profiles (`full` / `standard` / `light`), and default steps — **only** in `agents/task-router.md`. Schema and examples — `agents/README.md`.
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset nuxt
+```
+
+Copies rules, commands, agents, hooks, skills, team, `hooks.json`, `BUGBOT.md`, `AGENTS.md` → `.cursor/AGENTS.md`, `MCP.md`, `mcp.json` → `.cursor/mcp.json`, plus `REPO_AGENTS.md` → root `AGENTS.md`. Skills: `write-adr`, `vue-performance` (on-demand).

package/presets/cursor/nuxt/BUGBOT.md

@@ -0,0 +1,14 @@
+# Cursor Bugbot Review Guidelines
+
+Follow the **`code-review` skill** and **`code-review-mr.mdc`** for the full checklist.
+
+## Priorities
+
+1. Correctness regressions and runtime bugs.
+2. Architecture boundary violations (`architecture-boundaries.mdc`).
+3. Missing unit tests for mapper/domain/store logic; e2e updates for user flows.
+4. Type safety, `@/types` / `@/api` imports, barrel exports.
+
+## Review style
+
+Lead with concrete findings: file, impact, fix direction. Skip style-only nits unless they violate lint rules or project conventions.

package/presets/cursor/nuxt/MCP.md

@@ -0,0 +1,16 @@
+# MCP (preset `nuxt`, Cursor)
+
+Copied to `.cursor/mcp.json` on `ai-rules init cursor --preset nuxt`.
+
+## Servers
+
+| Name | Package | Why |
+|------|---------|-----|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Vue/Nuxt/TS and library docs (fewer stale APIs in agent replies) |
+| `playwright` | `@playwright/mcp` | Browser automation for e2e agents (`playwright-test-*`) and selector checks |
+| `chrome-devtools` | `chrome-devtools-mcp` | Live DOM/network/performance when debugging UI |
+| `figma` | remote `https://mcp.figma.com/mcp` | Design context → code (layouts, tokens, Code Connect); OAuth in Cursor |
+
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment — higher Context7 rate limits. Figma — OAuth on first connect (do not write the token into the config).
+
+After init: Settings → MCP → enable servers (or restart Cursor). Locally you may extend/override; `init` overwrites the same-named `mcp.json`.

package/presets/cursor/nuxt/README.md

@@ -0,0 +1,47 @@
+# Nuxt 3 preset (Cursor)
+
+Rules and agent-team surface for Nuxt 3 / Vue / TypeScript.
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset nuxt
+```
+
+Copies:
+
+| Path | Contents |
+|------|----------|
+| `REPO_AGENTS.md` | → repo-root `AGENTS.md` (cross-tool) |
+| `AGENTS.md` | → `.cursor/AGENTS.md` quick-start |
+| `BUGBOT.md` | Cursor Bugbot review priorities |
+| `rules/**` | `.mdc` + README (alwaysApply ≤3); golden rules with Incorrect/Correct + `impact:` |
+| `agents/**` | **22** roles (+ README; includes on-demand `codebase-analyzer`) |
+| `skills/**` | 9 skills (incl. `playwright-e2e`, `write-adr`, `vue-performance`) |
+| `commands/**` | task, task-continue, feature-start/continue, technical-retro |
+| `hooks.json` + `hooks/**` | guard-shell + chain-team-phases; optional `hooks/examples/` cookbook |
+| `team/**` | fixtures + `conventions.md` + README |
+| `mcp.json` + `MCP.md` | Context7 + Figma MCP → `.cursor/mcp.json` |
+
+## alwaysApply (≤3)
+
+`nuxt-app-core`, `package-manager`, `code-quality-and-refactoring`.
+
+Requestable (not always-on): `post-change-lint`, `agent-team-*`, `code-review-mr`, `feature-delivery-workflow`, `reference-features`, domain globs.
+
+## Preset taxonomy & contributing
+
+- **Layers:** Core → Stack → Platform — [`../../_shared/README.md`](../../_shared/README.md)
+- **Contribution guide:** [`../../docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md) (SoT, twins, token budget, PR checklist)
+- **Author meta-rules:** `preset-*.mdc` (globs `packages/ai-rules/presets/**`, never alwaysApply)
+- **Core→stack mapping:** [`rules/README.md`](./rules/README.md) § Shared core
+
+## Sync with Claude
+
+SoT = this Cursor preset. After edits to `.mdc` / agents / skills — update the twin in `presets/claude/nuxt/` **in the same PR**.
+
+`BUGBOT.md` — **Cursor-only** (no Claude twin); for Claude Code — skill `code-review` + `tooling-and-review/code-review.md`.
+
+Claude→Cursor map: `presets/claude/nuxt/rules/README.md`.
+
+See also `AGENTS.md`.

package/presets/cursor/nuxt/REPO_AGENTS.md

@@ -0,0 +1,49 @@
+# Nuxt 3 — agent instructions
+
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, or other).
+- Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` — use them when that tool is installed.
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset nuxt
+npx @bonesofspring/ai-rules init claude --preset nuxt
+```
+
+`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas belong in `team/conventions.md`, not here.
+
+## Commands (test / lint / build)
+
+Working directory for package scripts: **repository root** (directory with `nuxt.config.*`). Detect the package manager from lockfile / `packageManager` (`package-manager` rule).
+
+| Gate | Typical command |
+|------|-----------------|
+| Lint JS | `yarn lint:js` (or project equivalent) from repo root |
+| Lint CSS | `yarn lint:css` from repo root |
+| Typecheck | `yarn typecheck` (`nuxt typecheck`) from repo root |
+| Unit tests | project unit script (often Vitest) at repo root |
+| Build | project `build` / `nuxt build` at repo root |
+
+After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent `build-verifier`.
+
+## Security basics
+
+- Do not commit secrets (`.env`, tokens, credentials).
+- Review destructive git (`reset --hard`, force-push) before running; respect shell hooks.
+- Do not weaken CI or skip hooks unless the user explicitly asks.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
+
+Rules: `.cursor/rules/` or `.claude/rules/`. Skills: `.cursor/skills/` or `.claude/skills/`.
+
+## Living conventions
+
+Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`** and/or **`.claude/team/conventions.md`** (fill after init; not overwritten on every dogfood sync when already present).

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

@@ -0,0 +1,206 @@
+# `.cursor/agents` (preset nuxt)
+
+Role subagents for the Cursor team pipeline.
+
+## Planning and routing
+
+| Agent | File | Production code |
+|-------|------|-----------------|
+| Router | `task-router.md` | no |
+| Analyst | `task-analyst.md` | no |
+| Architect | `solution-architect.md` | no |
+| Migration planner | `migration-specialist.md` | no |
+| API contract reviewer | `api-contract-reviewer.md` | no |
+
+## Analysis (on-demand)
+
+| Agent | File | Production code |
+|-------|------|-----------------|
+| Codebase analyzer | `codebase-analyzer.md` | no (explain-as-is only) |
+
+## Implementation and CI
+
+| Agent | File | Production code |
+|-------|------|-----------------|
+| Debugger | `debugger.md` | minimal fix only |
+| CI investigator | `ci-investigator.md` | minimal CI fix only |
+| Build verifier | `build-verifier.md` | no |
+| Developer | `feature-developer.md` | yes |
+
+## Review specialists
+
+| Agent | File | Production code |
+|-------|------|-----------------|
+| Reviewer | `code-reviewer.md` | no |
+| A11y reviewer | `accessibility-reviewer.md` | no |
+| Security reviewer | `security-reviewer.md` | no |
+| Performance auditor | `performance-auditor.md` | no |
+
+## Testing
+
+| Agent | File | Production code |
+|-------|------|-----------------|
+| QA | `qa-tester.md` | tests only |
+| Unit planner | `unit-test-planner.md` | no |
+| Unit generator | `unit-test-generator.md` | tests only |
+| Unit healer | `unit-test-healer.md` | tests only |
+| Playwright planner | `playwright-test-planner.md` | e2e plans only |
+| Playwright generator | `playwright-test-generator.md` | e2e tests only |
+| Playwright healer | `playwright-test-healer.md` | e2e fixes only |
+
+## Documentation
+
+| Agent | File | Production code |
+|-------|------|-----------------|
+| Tech writer | `tech-writer.md` | docs only |
+
+Copied to `.cursor/agents/` on `ai-rules init cursor --preset nuxt`.
+
+## Frontmatter `readonly`
+
+All pipeline agents are **`readonly: false`**. They need write access under `.cursor/team/**` (`pipeline.json`, `brief.md`, `review.md`, `status.json`, …).
+
+The “do not touch production / `app/**`” limit is set **in the prompt body**, not via the `readonly` flag. In Cursor `readonly: true` blocks *any* file edits (including team) — that breaks the pipeline for team agents.
+
+## Model matrix (frontmatter `model`)
+
+Default SoT — YAML `model` in each agent file. Optional `steps[].model` (`cheap` \| `standard` \| `strong`) overrides the tier for a pipeline step (see `task-router.md`, `agent-team-orchestrator.mdc`).
+
+| Tier | Default frontmatter | Agents |
+|------|---------------------|--------|
+| **cheap** | `fast` | `task-router`, `task-analyst`, `build-verifier`, `code-reviewer`, `tech-writer`, `codebase-analyzer` |
+| **standard** | `inherit` | `feature-developer`, `debugger`, `ci-investigator`, `api-contract-reviewer`, `accessibility-reviewer`, `qa-tester`, `unit-test-*`, `playwright-test-*` |
+| **strong** | `claude-opus-4-8[effort=high]` | `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor` |
+
+**Notes**
+
+- `inherit` = parent-chat model (usually stronger than `fast`).
+- Strong pin uses Cursor bracket options (`[effort=high]`). If the ID is blocked by plan/admin, Cursor falls back to a compatible model.
+- Alternate strong pin when Opus unavailable: `composer-2.5[fast=false]` (edit frontmatter locally).
+- Never put `strong` on `build-verifier` / `tech-writer` / `task-router`.
+
+## Orchestration
+
+| Command | Purpose |
+|---------|---------|
+| `/task <desc>` | Router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After a human gate |
+| `/feature-start`, `/feature-continue` | Legacy (compatibility) |
+
+Rule: `agent-team-orchestrator.mdc`. Plan: `pipeline.json` under `.cursor/team/tasks/<slug>/`.
+
+## Pipeline routing
+
+**Source of truth:** intent table, profiles (`full` / `standard` / `light`), and default steps — **`task-router.md`** only. Do not duplicate intent→pipeline tables in entry docs.
+
+## pipeline.json reference
+
+### Top-level fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `slug` | yes | Task identifier |
+| `intent` | yes | From router intent detection |
+| `profile` | no | `full` \| `standard` \| `light` — see `task-router.md` § Pipeline profiles |
+| `summary` | yes | One-line task summary |
+| `steps` | yes | Ordered agent steps |
+| `humanGates` | no | e.g. `["after:task-analyst"]` |
+| `autoChain` | no | Default `true` |
+| `skipped` | no | Roles skipped with reason |
+
+### Step fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `agent` | yes | Subagent name (kebab-case) or array for `parallel: true` |
+| `label` | yes | Short human-readable step name |
+| `scope` | no | e.g. `unit-in-dev`, `e2e-only`, `regression`, `full` |
+| `skipIf` | no | `debugger.fixed` \| `ci-investigator.resolved` |
+| `parallel` | no | When `true` and `agent` is array — invoke all in one turn |
+| `model` | no | `cheap` \| `standard` \| `strong` — pipeline tier override; omit → agent frontmatter |
+
+### Minimal template
+
+```json
+{
+  "slug": "<slug>",
+  "intent": "feature",
+  "summary": "One-line task summary",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
+    { "agent": "build-verifier", "label": "Lint, check, unit smoke" },
+    { "agent": "code-reviewer", "label": "Code review" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}
+```
+
+### Example: parallel reviewers + model tiers
+
+```json
+{
+  "intent": "feature",
+  "profile": "full",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify" },
+    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
+    { "agent": "feature-developer", "label": "Implement", "scope": "unit-in-dev" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    {
+      "agent": ["accessibility-reviewer", "security-reviewer"],
+      "parallel": true,
+      "label": "A11y and security",
+      "model": "strong"
+    },
+    { "agent": "code-reviewer", "label": "Review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"]
+}
+```
+
+### Example: light profile with cheap models
+
+```json
+{
+  "intent": "feature",
+  "profile": "light",
+  "steps": [
+    { "agent": "feature-developer", "label": "Implement", "model": "cheap" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" }
+  ],
+  "humanGates": []
+}
+```
+
+### Example: bugfix skipIf
+
+```json
+{
+  "intent": "bugfix",
+  "steps": [
+    { "agent": "debugger", "label": "Root cause" },
+    { "agent": "feature-developer", "label": "Fix if needed", "skipIf": "debugger.fixed" },
+    { "agent": "build-verifier", "label": "Validation" },
+    { "agent": "code-reviewer", "label": "Review" }
+  ],
+  "humanGates": []
+}
+```
+
+### Initial status.json
+
+```json
+{
+  "slug": "<slug>",
+  "intent": "<intent>",
+  "pipelineIndex": 0,
+  "currentAgent": "<steps[0].agent>",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false,
+  "updatedAt": "<ISO8601>"
+}
+```