@bonesofspring/ai-rules 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -2,13 +2,16 @@
 
 ## Unreleased
 
-### Breaking
-
-- **Deprecated rule stubs removed** (Cursor + Claude `next`): `types-public-imports`, `api-public-imports`, `no-cross-component-styles-import` / `component-styles`. Use `public-imports` and `react-ui` instead.
-- **`next` preset — post-change-lint no longer always-on:** Cursor `post-change-lint.mdc` and Claude twin are **requestable** (not session-start / `alwaysApply`). Load explicitly after code edits via skill `feature-delivery` or agent `build-verifier`. Session-start / alwaysApply is now **3** rules: `next-app-core`, `package-manager`, `code-quality-and-refactoring`. Workspace dogfood `.cursor/rules/post-change-lint.mdc` synced.
-
 ### Added
 
+- **Always-on Principles** in shared `quality/code-quality-and-refactoring` (+6 adapters): compact § **Принципы** — KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition over inheritance, Law of Demeter hint. No smell/GoF catalogs in always-on.
+- **Requestable `quality/design-guidance`** (+6 adapters, Cursor/Claude × next/ios-swift/go): curated Fowler smells (≤12) + GoF (≤8) + skip/avoid; globs `app/src/**/*.{ts,tsx}` / `**/*.swift` / `**/*.go`. Cross-refs in `feature-delivery-workflow` (ubiquitous language) and `code-review-mr` checklist. One-liner wiring in feature-developer / code-review / debugger (+ recommended roles).
+- **Go hexagonal preset (`go`):** Cursor + Claude twins — 32 rules (always-on: `go-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`), 20 agents (`integration-test-*`, no a11y/Playwright/XCUITest), 7 skills (+ `integration-testing`), hooks/commands/team/MCP. Structure scripts `STACKS` include `go`; leakage `GO_FORBIDDEN_*` + pairwise chain forks. Install: `init cursor|claude --preset go`. Lineage markers on go `feature-delivery-workflow` / `reference-features`; go team fixtures / commands READMEs use Go gates (not xcodebuild/XCUITest copy-paste).
+- **Preset structure CI gates:** `scripts/check-preset-{twin-map,token-budget,leakage,structure}.sh` + npm scripts `check:preset-*`; GitHub Actions workflow `.github/workflows/preset-structure.yml` on `packages/ai-rules/**` PRs. Hard FAIL on twin/budget/leakage; soft shared-core drift only (no `AI_RULES_DRIFT_FAIL`).
+- **`presets/_shared/core/**`:** stack-agnostic shared prose (quality, agent-team, architecture templates, review, author meta-rules) with `<!-- shared-core: … -->` adapters in Cursor + Claude `next` and `ios-swift`.
+- **Author meta-rules:** `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage` (never always-on / session-start).
+- **Contributor docs:** `docs/PRESET-CONTRIBUTION.md` (layers, SoT, embed vs lineage sync modes, new-stack checklist).
+- **Monorepo scripts:** `scripts/sync-dogfood-cursor.sh`, `scripts/check-shared-core-drift.sh`.
 - **MCP configs in presets** (`next` + `ios-swift`, Cursor + Claude): `mcp.json` + `MCP.md`. Cursor → `.cursor/mcp.json`; Claude → project-root `.mcp.json`. **next:** Context7, Playwright, Chrome DevTools, Figma (remote). **ios-swift:** Context7 + Figma. CLI `init`/`clean` manage these paths.
 - **Cursor + Claude `ios-swift` — full agent-team parity with `next`:** **21** agents (Playwright trio → `xcuitest-test-{planner,generator,healer}`), **7** skills (`xcuitest-e2e`), **5** slash commands, `hooks.json` + iOS-adapted `chain-team-phases.sh` (Cursor) / hook scripts + README (Claude), `team/fixtures/` ×3, `AGENTS.md` (Cursor) / thin `CLAUDE.md` (≤35 lines).
 - **ios-swift rules:** agent-team intake/orchestrator, `xcode-tooling`, `reference-features`, domain rules (`navigation-coordinators`, `persistence-data`, `security-ios`, `module-public-api`), `technical-retro` alias; **21** rule topics (+ README). CLI init copies agents, hooks, skills, team, `AGENTS.md`.
@@ -16,12 +19,26 @@
 
 ### Changed
 
+- **Meta twin policy (three stacks):** `preset-twin-sync` / `preset-pr-checklist` / `preset-layering` core + embeds name **next, ios-swift, and go**; twin FAIL applies to all three (`check-preset-twin-map.sh`).
+- **PRESET-CONTRIBUTION:** shared-core sync step says **all six adapters** (3 stacks × 2 platforms), not «four presets».
+- **Claude session-start count (Option A):** when counting rules without `paths:`, **exclude `**/README.md`**; intended trio remains **exactly 3**; body budget sums only those 3 (`preset-token-budget`, PRESET-CONTRIBUTION, build-verifier ×4).
+- **Twin policy doc sync:** `claude/next/rules/README.md` — missing twin is **FAIL** (next, ios-swift, and go); no soft FAIL for next.
+- **next agent roster docs:** READMEs/commands say **21** agents (was stale 20).
+- **PRESET-CONTRIBUTION:** cross-link → `.cursor/team/tasks/preset-regression-audit/` (was `preset-arch-quality-rules`).
+- **Twin policy:** missing Claude twin for a changed Cursor rule is **FAIL** on **next**, **ios-swift**, and **go**.
+- **build-verifier** preset-structure section: twin FAIL on next, session-start line budget, embed-drift + dogfood script hooks.
+- Claude meta-rule `paths:` include dogfood `.claude/**/*` (+ `.cursor/rules` / `team/tasks` for parity).
 - **Agent team slug bootstrap:** `/task` and `/feature-start` (Cursor + Claude, `next` + `ios-swift`) create `.cursor|claude/team/tasks/<slug>/` via **Write**, not Shell `mkdir` — avoids Cursor sandbox `Operation not permitted` (esp. macOS Desktop/Documents). Orchestrator + `team/README` + `task-router` document the rule.
 - **Token model (ios-swift + next):** both presets use **3** alwaysApply / session-start rules (~77 / ~59 body lines). Post-change verification is **requestable** — ios: `post-change-build`; next: `post-change-lint`. Orchestrator, intake, code-review, feature-delivery, tooling rules load on-demand (`paths:` / description).
 - Claude `next`: `agent-team-orchestrator` and `code-review-mr` use `paths:` (on-demand) — session-start matches the 3-rule budget above.
 - Cursor `next` agents: all pipeline agents set **`readonly: false`** so they can write `.cursor/team/**`. Production/app restrictions remain in prompt bodies (Cursor `readonly: true` blocks all file writes, including team artifacts).
 - **ios-swift:** `networking-services` HTTP-only (persistence split out); soft AC-19 for thin aliases (`agent-team-intake`, `technical-retro`); `feature-developer` requires stack-specific hook handoff forks.
 
+### Breaking
+
+- **Deprecated rule stubs removed** (Cursor + Claude `next`): `types-public-imports`, `api-public-imports`, `no-cross-component-styles-import` / `component-styles`. Use `public-imports` and `react-ui` instead.
+- **`next` preset — post-change-lint no longer always-on:** Cursor `post-change-lint.mdc` and Claude twin are **requestable** (not session-start / `alwaysApply`). Load explicitly after code edits via skill `feature-delivery` or agent `build-verifier`. Session-start / alwaysApply is now **3** rules: `next-app-core`, `package-manager`, `code-quality-and-refactoring`. Workspace dogfood `.cursor/rules/post-change-lint.mdc` synced.
+
 ### Notes
 
 - **P2 optional (ios-swift):** Remaining polish: feature-delivery matrix enrichment, swift-conventions body cap. (`BUGBOT.md` shipped.)

package/README.md

@@ -48,13 +48,25 @@ Where things go on `init`:
 | MCP | `mcp.json` → `.cursor/mcp.json`, `MCP.md` → `.cursor/` | `mcp.json` → **`.mcp.json`** (project root), `MCP.md` → `.claude/` |
 | other | `BUGBOT.md`, `AGENTS.md` → `.cursor/` | `CLAUDE.md` → `.claude/CLAUDE.md` |
 
-The package ships presets including **`next`** (Next.js stack) and **`ios-swift`** (iOS apps on Swift / SwiftUI). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Name is a single path segment, no `/` or `..`.
+The package ships presets including **`next`** (Next.js stack), **`ios-swift`** (iOS apps on Swift / SwiftUI), and **`go`** (Go backends with hexagonal architecture). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Name is a single path segment, no `/` or `..`.
 
 ```bash
 npx @bonesofspring/ai-rules init cursor --preset ios-swift
 npx @bonesofspring/ai-rules init claude --preset ios-swift
+npx @bonesofspring/ai-rules init cursor --preset go
+npx @bonesofspring/ai-rules init claude --preset go
 ```
 
 Help: `ai-rules --help`.
 
+## Contributing to presets
+
+Presets are developed in this monorepo under `presets/`. If you add or change rules, agents, or platform artifacts:
+
+- **Taxonomy & layers:** [`presets/_shared/README.md`](presets/_shared/README.md) — shared core (`_shared/core`), stack adapters, platform packaging
+- **Contribution guide:** [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md) — SoT, twin sync, embed vs lineage, token budget (≤3 always-on), PR checklist, new stack preset, platform-only files (`BUGBOT.md`, `CLAUDE.md`)
+- **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh)
+- **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage; soft drift included without `AI_RULES_DRIFT_FAIL`
+- **CLI note:** `_shared` is not an installable `--preset`; `init` copies only `presets/cursor/<name>/` or `presets/claude/<name>/`
+
 MIT.

package/bin/cli.js

@@ -65,8 +65,10 @@ Examples:
   npx @bonesofspring/ai-rules init cursor --preset next
   npx @bonesofspring/ai-rules init cursor next
   npx @bonesofspring/ai-rules init cursor --preset ios-swift
+  npx @bonesofspring/ai-rules init cursor --preset go
   npx @bonesofspring/ai-rules init claude
   npx @bonesofspring/ai-rules init claude --preset ios-swift
+  npx @bonesofspring/ai-rules init claude --preset go
   npx @bonesofspring/ai-rules clean cursor
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -24,6 +24,13 @@
     "bin",
     "presets"
   ],
+  "scripts": {
+    "check:preset-structure": "bash scripts/check-preset-structure.sh",
+    "check:preset-twin-map": "bash scripts/check-preset-twin-map.sh",
+    "check:preset-token-budget": "bash scripts/check-preset-token-budget.sh",
+    "check:preset-leakage": "bash scripts/check-preset-leakage.sh",
+    "check:shared-core-drift": "bash scripts/check-shared-core-drift.sh"
+  },
   "engines": {
     "node": ">=18"
   },

package/presets/_shared/README.md

@@ -0,0 +1,47 @@
+# Shared preset core (`presets/_shared`)
+
+Stack-agnostic **prose and checklists** for all installable presets: `next`, `ios-swift`, and `go` (`cursor/<stack>`, `claude/<stack>`).
+
+**Not an installable preset.** CLI `init` copies only under `presets/cursor/<name>/` or `presets/claude/<name>/` — this sibling is never shipped to consumer apps.
+
+## Layers
+
+```text
+Core (_shared/core)     → stack-agnostic prose
+Stack (cursor|claude/<stack>) → domain / tooling deltas
+Platform adapter        → .mdc frontmatter | .md + paths:
+```
+
+See meta-rules: `core/meta/preset-layering.md`, `preset-twin-sync.md`, `preset-token-budget.md`, `preset-pr-checklist.md`, `preset-no-cross-stack-leakage.md`.
+
+**Contributing:** [`../../docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md) (full guide: layers, SoT, new stack, platform artifacts, PR checklist).
+
+## Sync model
+
+1. Edit core under `core/**` when changing shared principles.
+2. Update every consumer that carries `<!-- shared-core: <path> -->` in the **same PR**.
+3. Cursor `presets/cursor/<stack>/` is SoT per stack; Claude twins are derived in the same PR.
+4. Dogfood: `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (packages → root `.cursor/`).
+
+### Sync modes (marker semantics)
+
+| Mode | Marker | Adapter body | Typical stems |
+|------|--------|--------------|---------------|
+| **Embed** | `<!-- shared-core: … -->` | Core prose + optional `## Stack notes` only for deltas | `quality/*`, `meta/preset-*`, thin review/intake aliases |
+| **Lineage** | same marker | **Stack-specific** body; core is abstract SoT / checklist reference | `architecture/feature-delivery-workflow`, `architecture/reference-features.template`, `agent-team/agent-team-orchestrator` |
+
+Do **not** expect lineage adapters to byte-match core. Embed adapters should match core after stripping frontmatter and `## Stack notes` — verify with `scripts/check-shared-core-drift.sh`.
+
+## Folder map
+
+| Dir | Contents |
+|-----|----------|
+| `core/quality/` | Boy-scout + Principles (always-on); requestable `design-guidance` (smells ≤12 + GoF ≤8) |
+| `core/agent-team/` | Orchestrator + intake (pipeline language) |
+| `core/architecture/` | Feature-delivery abstract + reference-features template |
+| `core/review/` | Code-review MR + technical-retro alias |
+| `core/meta/` | Author-facing preset meta-rules |
+
+## CLI note
+
+Do **not** nest `_shared` under `cursor/` or `claude/`. Do not pass `_shared` as `--preset`.

package/presets/_shared/core/agent-team/agent-team-intake.md

@@ -0,0 +1,9 @@
+# Agent team intake
+
+When the user message looks like a **work request** (implement, add, fix, refactor, review MR, write tests, spike) — not a question about how code works:
+
+1. Prefer **`/task <their request>`** or invoke **task-router** first.
+2. Do not jump straight to coding without router + pipeline when scope is non-trivial.
+3. Pure questions («как работает X», «объясни») — answer normally, no `/task`.
+
+Exceptions: user explicitly says «без pipeline», «просто сделай», or continues an active slug.

package/presets/_shared/core/agent-team/agent-team-orchestrator.md

@@ -0,0 +1,142 @@
+# Agent team orchestrator
+
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.cursor/team/tasks/<slug>/` (Claude: `.claude/team/tasks/<slug>/`).
+
+Work request без `/task` — см. **agent-team-intake** (когда предлагать router вместо прямого кодинга).
+
+## Entry points
+
+| Command | When |
+|---------|------|
+| **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After human gate or pause |
+| `/feature-start <desc>` | Legacy: analyst-only start (no router) |
+| `/feature-continue <slug>` | Alias of task-continue |
+| `/technical-retro [slug]` | Retro with agent team block |
+
+## Roles (shared catalog)
+
+Roster of specialists is **stack-specific** (agent names and write scopes differ). See **Stack notes** in the stack adapter for the live Roles table. Common patterns:
+
+| Kind | Examples (names vary by stack) |
+|------|--------------------------------|
+| Planning | `task-router`, `task-analyst`, `solution-architect`, `migration-specialist` |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer **only when the stack has a UI surface** |
+| Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
+| Docs | `tech-writer` |
+
+**Cursor frontmatter:** all team pipeline agents use `readonly: false` so they can write team artifacts. Production/app restrictions live in the agent prompt body — do **not** set `readonly: true`.
+
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`.
+
+## Dynamic pipeline
+
+```mermaid
+flowchart TD
+  task["/task prompt"]
+  router["task-router"]
+  pipeline["pipeline.json"]
+  step0["steps 0..N"]
+  gate{"humanGates?"}
+  hook["subagentStop hook"]
+  retro["/technical-retro"]
+
+  task --> router
+  router --> pipeline
+  pipeline --> step0
+  step0 --> gate
+  gate -->|"/task-continue"| step0
+  step0 --> hook
+  hook --> step0
+  step0 --> retro
+```
+
+**Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
+
+## status.json (pipeline mode)
+
+```json
+{
+  "slug": "...",
+  "intent": "feature",
+  "pipelineIndex": 0,
+  "currentAgent": "task-analyst",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false
+}
+```
+
+| state | Meaning |
+|-------|---------|
+| `in_progress` | Current step running |
+| `completed` | Current step done; hook advances |
+| `awaiting_approval` | Human gate; wait for `/task-continue` |
+| `changes_requested` | Reviewer blocked; re-run developer (`retryAfterFix`) |
+| `validation_failed` | build-verifier failed; re-run developer then build-verifier |
+
+## Pipeline step options
+
+| Field | Use |
+|-------|-----|
+| `skipIf` | `debugger.fixed` / `ci-investigator.resolved` — hook skips step when artifact says fix applied |
+| `parallel: true` | `agent` is array — invoke **all** agents in one parent turn; each appends to `parallelCompleted` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only`, `preset-artifacts-only` — passed to developer/qa |
+| `model` | `cheap` \| `standard` \| `strong` — optional tier override |
+
+## Rules (strict)
+
+1. **`/task` always starts with task-router** (except user says "skip router" with documented pipeline).
+2. Read `pipeline.json` before every subagent invocation.
+3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
+4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
+5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`).
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
+7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
+8. When all steps complete, suggest `/technical-retro <slug>`.
+9. If `autoChain: false` in pipeline, do not rely on hook — manual step only.
+
+## Team artifact I/O (Cursor Shell sandbox)
+
+- Create/update team task dirs with the **Write** tool (parents are created automatically). Do **not** bootstrap slug dirs with Shell `mkdir -p` — default sandbox returns `Operation not permitted` (worse on macOS Desktop/Documents with TCC).
+- If Shell must touch team paths and fails with EPERM, retry with `required_permissions: ["all"]`. Prefer Write for artifacts.
+- Prefer repo under `~/Projects` / `WebstormProjects` over `~/Desktop` when using agent team heavily.
+
+## Invoking agents
+
+Use Task tool or `/agent-name`. Pass: slug, artifact paths, step `scope` if set.
+
+### Model when invoking (Task)
+
+1. Read `steps[i].model` if present; else use the agent’s frontmatter `model` (see `agents/README.md` matrix).
+2. Map abstract tiers:
+   - **`cheap`** → pass Task `model: "fast"` when the tool accepts it (or rely on agent `fast`).
+   - **`standard`** → omit Task `model` (frontmatter `inherit` / mid default).
+   - **`strong`** → **never** pass `fast`; rely on agent pin or parent Max model.
+3. Parallel steps: apply the step-level `model` to **each** agent in the array (or omit → each agent’s own frontmatter).
+
+After each agent completes, ensure `status.json` has `state: completed` (or `awaiting_approval` if gate applies).
+
+## Legacy mode
+
+If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+
+## Skip pipeline when
+
+Do **not** run `/task` + router for:
+
+- Pure questions («как работает X», «объясни»).
+- Typo / one-file fix / trivial config with no architecture risk.
+- User explicitly says «без pipeline», «просто сделай», or continues an active slug.
+- Single-line `docs-only` with no code impact.
+
+Borderline work requests — см. **agent-team-intake**.
+
+## Auto-detection (optional)
+
+When user describes a **non-trivial task** (not a question), suggest `/task <message>` or run router if they agree.
+
+## Preset authoring
+
+When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync of presets), follow meta-rules: **preset-pr-checklist**, **preset-twin-sync**, **preset-layering**, **preset-token-budget**, **preset-no-cross-stack-leakage**.

package/presets/_shared/core/architecture/feature-delivery-workflow.md

@@ -0,0 +1,46 @@
+# Доставка фичи (сквозной порядок)
+
+Типичная фича с данными и UI. Конкретные каталоги и rule stems — в **Stack notes** адаптера.
+
+## Чеклист (абстрактный порядок)
+
+1. **Домен / типы** — сущности и контракты слоя Domain/types; public API слоя.
+2. **Транспорт / DTO** — DTO и мапперы Domain ↔ transport (не протекают в UI).
+3. **Сервисы / Data** — реализации репозиториев / API-сервисов через public клиенты стека.
+4. **Состояние** — store / ViewModel / use cases; без прямого HTTP и без DTO в UI.
+5. **UI** — тонкие views/components; данные через состояние; design-system.
+6. **Тесты** — unit на mappers / нетривиальную логику; e2e/UI по конвенции стека.
+7. **Завершение** — post-change gate стека (lint/build) + package/toolchain rules.
+
+## Поток данных (ориентир)
+
+```mermaid
+flowchart LR
+  DTO[DTO] --> Mappers[Mappers]
+  Mappers --> Domain[Domain]
+  Domain --> Service[Service / Repo]
+  Service --> State[Store / VM]
+  State --> UI[UI]
+```
+
+## Частичные сценарии
+
+| Задача | Минимум |
+|--------|---------|
+| Только API / модель | Domain + DTO + mapper + service/repo; unit на mapper |
+| Только состояние | Протоколы/сервисы; без HTTP в UI |
+| Только UI | Существующее состояние; без DTO |
+| Только тесты | Specs по конвенции; не менять production без нужды |
+
+## Антипаттерны (общие)
+
+- DTO / transport-типы в UI или presentation state.
+- Низкоуровневый HTTP / конкретный клиент из UI в обход сервиса.
+- Deep-import внутренних файлов другого модуля/фичи.
+- Нарушение границ слоёв ради краткости.
+- **Ubiquitous language:** имена и границы Domain/типов отражают предметную область фичи — не смешивать транспорт/фреймворк-термины в домен без нужды; presentation не диктует словарь модели.
+- При оценке структуры, smells или выбора паттерна — подгружать requestable **`design-guidance`** (не always-on); не копировать каталог в чеклист фичи.
+
+## Матрица зона → правила
+
+Заполняется в stack adapter: конкретные globs/пути и имена `.mdc` / topic `.md`.

package/presets/_shared/core/architecture/reference-features.template.md

@@ -0,0 +1,31 @@
+# Эталонные фичи (reference features)
+
+Перед реализацией найди фичу того же типа и **повтори её структуру**, не изобретая новую организацию файлов.
+
+## Таблица эталонов
+
+Замени placeholders на **реальные** пути после `ai-rules init` / договорённости команды:
+
+| Слой | Эталон | Что копировать |
+|------|--------|----------------|
+| UI / Presentation | **TBD** | компоненты, styles/data helpers, barrel |
+| State / ViewModel | **TBD** | slice/VM, selectors, types |
+| API / Data | **TBD** | service/repo, mappers, barrel |
+| Domain / Types | **TBD** | domain types, public export |
+| Unit tests | **TBD** | `*.spec` / XCTest naming |
+| E2E / UI tests | **TBD** | cases/plans, page objects / accessibility IDs |
+
+## Как использовать
+
+1. Определи затронутые слои из `decomposition.md` или задачи.
+2. Открой эталон из таблицы (после заполнения путей).
+3. Зеркаль именование, порядок файлов, паттерны импортов и тестов.
+4. Если эталона нет — выбери **самую близкую** существующую фичу того же слоя и зафиксируй выбор в handoff.
+
+## Связанные правила
+
+- `code-quality-and-refactoring` — повторять паттерны, не deep-import.
+- `feature-delivery-workflow` — порядок слоёв.
+- skill `feature-delivery` — end-to-end сценарий.
+
+> Concrete path tables, globs, and dogfood checklists live in the stack adapter **Stack notes**.

package/presets/_shared/core/meta/preset-layering.md

@@ -0,0 +1,25 @@
+# Preset layering
+
+Правила для **авторов пресетов** (`packages/ai-rules/presets/**`). Не always-on в consumer apps.
+
+## Слои
+
+| Слой | Где | Что класть |
+|------|-----|------------|
+| **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; без frontmatter; без путей `app/**`, `Features/**`, Playwright, xcodebuild |
+| **Stack** | `presets/{cursor\|claude}/<stack>/` | Domain/tooling, always-on trio стека, stack examples в **Stack notes** |
+| **Platform** | Cursor `.mdc` / Claude `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
+
+## Куда класть новое правило
+
+1. Общие принципы для всех стеков → **core** + адаптеры с `<!-- shared-core: … -->`.
+2. Только один из installable стеков (`next` / `ios-swift` / `go`) → **stack-specific** (не в `_shared`).
+3. Только Cursor или только Claude packaging → platform artifact / frontmatter, не дублировать семантику.
+
+## SoT
+
+- Packages path — SoT; root `.cursor/` — dogfood sync.
+- Per stack: **Cursor** `presets/cursor/<stack>/` → Claude twin same PR.
+- `_shared` **не** `--preset` и не копируется CLI `init`.
+
+См. также: `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`.

package/presets/_shared/core/meta/preset-no-cross-stack-leakage.md

@@ -0,0 +1,43 @@
+# Preset no cross-stack leakage
+
+Запрет протекания stack-specific имён, путей и handoff stems между пресетами.
+
+## Principles
+
+- `next` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `ios-swift` must not ship Playwright handoffs or Next lint recipes as required commands.
+- `go` must not ship Playwright, XCUITest, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
+- Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
+
+## Forbidden in ios-swift hooks/agents (FAIL)
+
+In ios-swift `chain-team-phases.sh` / agent handoffs (Cursor + Claude):
+
+- `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`
+- `app/__tests__/e2e` as a required path
+- Positive yarn recipes `lint:js` / `lint:css` as commands to run (negation prose alone is weak — prefer zero occurrences)
+
+Required instead: `xcuitest-test-*` stems; build-verifier mentions `xcodebuild` or `post-change-build` / `xcode-tooling`.
+
+## Forbidden in next hooks/agents (FAIL when present as required)
+
+- `xcuitest-test-` as handoff stems
+- Requiring `xcodebuild` / SwiftLint as the default post-change gate for Next app work
+
+## Forbidden in go hooks/agents (FAIL)
+
+- `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
+- Positive yarn recipes `lint:js` / `lint:css`
+- `xcuitest-test-`, `xcodebuild`, `SwiftLint` as required handoffs
+- Agent file `accessibility-reviewer` (no UI surface)
+
+Required instead: `integration-test-*`; build-verifier / `post-change-test` / `go-tooling` (`go test`, `go vet`).
+
+## Soft / document
+
+- Mentioning the other stack in **docs** comparing presets is OK.
+- `build-verifier` may reference other stacks when validating **preset packaging** (`scope: preset-structure-validation`).
+
+## Chain fork
+
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, and `go` (per platform).

package/presets/_shared/core/meta/preset-pr-checklist.md

@@ -0,0 +1,28 @@
+# Preset PR checklist
+
+Чеклист для PR, затрагивающих `packages/ai-rules/presets/**` (и dogfood `.cursor/` sync).
+
+## Before merge
+
+- [ ] **SoT:** правки в `packages/…` (не только root `.cursor/`)
+- [ ] **Core:** если менялся `_shared/core/**` — обновлены все `<!-- shared-core: … -->` consumers (или documented intentional fork)
+- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, ios-swift, and go — см. `preset-twin-sync`)
+- [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table актуален
+- [ ] **Token budget:** alwaysApply / session-start ≤ 3; meta rules not always-on
+- [ ] **Leakage:** нет чужих stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
+- [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
+- [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
+- [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (or document intentional skip) when maintaining this monorepo
+- [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
+
+## Pointers
+
+- Layering: `preset-layering`
+- Sync: `preset-twin-sync`
+- Budget: `preset-token-budget`
+- Leakage: `preset-no-cross-stack-leakage`
+- Validation: stack `agents/build-verifier.md` → preset-structure section
+- Dogfood script: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`
+- Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
+- Orchestrator: when editing presets, load this checklist + twin-sync

package/presets/_shared/core/meta/preset-token-budget.md

@@ -0,0 +1,30 @@
+# Preset token budget
+
+Инварианты загрузки правил в **установленном** пресете (consumer app).
+
+## Hard caps
+
+| Platform | Always-on | Cap |
+|----------|-----------|-----|
+| Cursor | `alwaysApply: true` | **≤ 3** |
+| Claude | rules **without** `paths:` | **ровно 3** |
+
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+
+Session-start body budget (где задокументировано): ≤120 строк суммарно (stretch ≤100).
+
+## Meta / author rules
+
+Rules for preset authors (`preset-layering`, `preset-twin-sync`, …):
+
+- **Never** `alwaysApply: true` on consumer installs.
+- Cursor: `globs` limited to `packages/ai-rules/presets/**` (and dogfood `.cursor/**` where useful).
+- Claude: `paths:` limited to `packages/ai-rules/presets/**` (and `.claude/**` dogfood if present).
+
+## Heavy workflows
+
+Orchestrator, feature-delivery, code-review, post-change gates, domain globs — **requestable / paths**, not always-on.
+
+## Verifier
+
+build-verifier **FAIL** if alwaysApply / session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/_shared/core/meta/preset-twin-sync.md

@@ -0,0 +1,31 @@
+# Preset twin sync
+
+Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
+
+## Matrix
+
+| Stack | Cursor SoT | Claude derive | Mapping table |
+|-------|------------|---------------|---------------|
+| `next` | `presets/cursor/next/rules/*.mdc` | `presets/claude/next/rules/<topic>/` | **Required** in `claude/next/rules/README.md` |
+| `ios-swift` | `presets/cursor/ios-swift/rules/*.mdc` | `presets/claude/ios-swift/rules/<topic>/` | Keep in `claude/ios-swift/rules/README.md` |
+| `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Keep in `claude/go/rules/README.md` |
+
+## Same-PR checklist
+
+1. Edit Cursor rule first (body + frontmatter).
+2. Update Claude twin: body + `paths:` (from Cursor `globs:` / requestable triggers); drop `alwaysApply`.
+3. Update mapping table row if stem/path changed.
+4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
+
+## Twin depth
+
+- **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
+- **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
+
+## Severity (build-verifier)
+
+- **next:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **ios-swift:** missing Claude twin for a changed Cursor rule → **FAIL**.
+- **go:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift; mapping table required).
+
+Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/_shared/core/quality/code-quality-and-refactoring.md

@@ -0,0 +1,58 @@
+# Поддержка существующего стиля
+
+- Новые изменения должны:
+  - следовать существующим паттернам (имена, структура, типизация / DI / error handling стека);
+  - минимизировать «стилистический шум» (лишние правки форматирования, rename без нужды).
+- Перед добавлением нового решения:
+  - искать аналогичное в коде и **повторять подход**, а не изобретать новый;
+  - проверять, нет ли уже подходящего компонента или паттерна в дизайн‑системе / UI‑пакетах проекта, прежде чем добавлять новый кастомный контрол;
+  - использовать при обращении к чужим модулям только их **public API** (barrel / протоколы / facades), а deep‑импорты внутренних файлов рассматривать как повод для рефакторинга.
+
+# Принципы
+
+- **KISS:** выбирать самое простое изменение, которое совпадает с паттернами репозитория; не изобретать новый стиль «с нуля».
+- **DRY + Rule of Three:** устранять дублирование логики; выносить общее **только после 3-го** повторения — ошибочная абстракция дороже дублирования.
+- **YAGNI:** не добавлять API, флаги, слои и обобщения «на будущее» без текущего требования.
+- **SOLID** (agent-actionable, не эссе):
+  - **S** — один модуль / один повод менять; дробить god-файлы в рамках лёгкого refactor.
+  - **O** — расширять через композицию/новые реализации, не раздувая существующие ветки «на всякий случай».
+  - **L** — подтип не ломает контракт базового типа/протокола.
+  - **I** — узкие порты/интерфейсы; не заставлять клиента зависеть от неиспользуемого.
+  - **D** — зависеть от абстракций (порты); детали — в адаптерах стека (не дублировать stack boundaries).
+- **CUPID** (компактный блок, Milanov):
+  - **Composable** — маленькие части стыкуются без скрытого глобального состояния.
+  - **Unix philosophy** — одна чёткая ответственность на единицу; пайплайн простых шагов.
+  - **Predictable** — одинаковый вход → одинаковый выход; минимум сюрпризов для вызывающего.
+  - **Idiomatic** — следовать идиомам языка и **существующим** конвенциям репо.
+  - **Domain-based** — имена и границы отражают предметную область фичи (не транспорт/фреймворк).
+- **Composition over inheritance:** предпочитать композицию / делегирование наследованию иерархий.
+- **Law of Demeter (hint):** не строить цепочки `a.b.c.d`; ходить через public API / facade модуля.
+
+# Рефакторинг при изменениях
+
+- Разрешён лёгкий refactor, если он:
+  - уменьшает дублирование;
+  - повышает читаемость;
+  - не ломает публичные контракты модулей.
+- Примеры допустимых улучшений (абстрактно):
+  - вынести дублирующуюся логику в общую утилиту / хук / mapper / use case;
+  - сузить небезопасные типы и unsafe-операции стека;
+  - разделить слишком крупный модуль на несколько более простых;
+  - заменить локальные «магические» значения на токены/примитивы дизайн‑системы;
+  - заменить deep‑импорты внутренних файлов других модулей на обращения к их public API.
+
+# Ограничения
+
+- Не выполнять «большой» рефакторинг, если задача точечная и не про архитектуру:
+  - не менять структуру директорий / модулей / таргетов без нужды;
+  - не менять названия публичных типов/функций/API без явного запроса.
+- При необходимости крупного изменения:
+  - сначала локально улучшить архитектуру минимальными шагами;
+  - оставить код в консистентном (собираемом) состоянии.
+
+# Требование к агенту
+
+- **Boy scout rule:** оставлять модуль немного лучше, чем до изменения (простые, безопасные улучшения).
+- Не жертвовать архитектурой и слоями ради краткости реализации.
+
+> Stack-specific lint gates, примеры и toolchain — в секции **Stack notes** адаптера пресета.