@bonesofspring/ai-rules 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -2,13 +2,61 @@
 
 ## 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.
+### Claude Code handbook agent discipline
+
+Borrowed workflow patterns from [claude-code-rules](https://github.com/nikiforovall/claude-code-rules) (methodology marketplace — not coding standards). Additive on top of structure-change / preset-rules-improvements work.
+
+- **`feature-developer` ×6:** Zero improvisation + Will / Will not (scope discipline; clarify before guessing).
+- **`feature-delivery` skill ×6:** short Scope discipline pointer.
+- **`codebase-analyzer` agent ×6:** explain-as-is only; AGENTS/CLAUDE + agents README pointers; roster next/ios **22**, go **21**.
+- **`code-review` skill ×6:** Reuse + Efficiency lenses.
+- **`technical-retro` skill ×6:** wrong-turn taxonomy + conventions.md feedback (Rule of Three); full skill body on next/go/ios (not alias-only); no auto-apply.
+- **`agent-team-intake` / `agent-team-orchestrator`:** pure questions → prefer **`codebase-analyzer`** (aligned with AGENTS/CLAUDE maps).
+- **`docs/PRESET-CONTRIBUTION.md`:** Building blocks matrix (rule / command / skill / agent / conventions / hook).
+
+### Awesome-cursorrules borrow backlog
+
+- **`security-next`** (cursor + claude next): coding-time secrets/auth/XSS/Server Actions rule; wired into `security-reviewer`, catalogs, AGENTS/CLAUDE quick start.
+- **Anti-hallucination banlists:** `next-app-router`, `go-conventions`, `swift-conventions` (❌/✅ tables).
+- **Review output contract** in shared `review/code-review-mr` (+6 adapters) and all 6 `code-review` skills: `path:line`, severity `blocker|important|nit`, verdict line.
+- **Go:** expanded `go-conventions` (errors/interfaces/concurrency); `api-http` resilience (idempotency, bulkheads, thin handlers) — catalog depth stub→full.
+- **iOS:** `swiftui-ui` lifecycle/ownership (`.task`, DI vs `@StateObject`, hit testing).
+- **Shared quality:** Agent discipline (anti-sycophancy) section in `quality/code-quality-and-refactoring` (+6 adapters).
+
+### Preset rules improvements (9 items)
+
+Cross-cutting preset packaging work (all six presets unless noted **next-only**). Hard gates unchanged: twin sync, ≤3 always-on, no cross-stack leakage.
+
+| # | Item | Unreleased note |
+|---|------|-----------------|
+| 1 | Root `AGENTS.md` + **CLI** | `repoRootFiles`: `REPO_AGENTS.md` → `<cwd>/AGENTS.md` on cursor **and** claude `init` (overwrite policy A); removed on `clean` either tool |
+| 2 | Incorrect/Correct samples | **next only** — 9 domain rules with emedcard-grounded pairs |
+| 3 | Impact tags | `impact: CRITICAL\|HIGH\|MEDIUM\|LOW` frontmatter; documented in PRESET-CONTRIBUTION |
+| 4 | Eval harness (opt-in) | `eval/next/manifest.json`, `check-rule-eval.mjs`, `yarn check:rule-eval`, workflow `rule-eval.yml` |
+| 5 | Living conventions | `reference-features` lineage + `team/conventions.md` ×6 |
+| 6 | Hooks cookbook | `hooks/examples/` (secret-guard, format-edited, test-on-save); default `hooks.json` unchanged |
+| 7 | Skill `write-adr` | ×6 presets (on-demand) |
+| 8 | Skill `react-performance` | **next only** (cursor + claude) |
+| 9 | Linter-delegated style | Stack notes in code-quality adapters; `arrow-functions` trimmed → ESLint/Stylelint + `post-change-lint` |
 
 ### Added
 
+- **CLI `repoRootFiles` + root `AGENTS.md` (all stacks):** preset source `REPO_AGENTS.md` → `<cwd>/AGENTS.md` on cursor **and** claude `init` (overwrite); removed on `clean`. Lean cross-tool sections + pointer to `team/conventions.md`.
+- **Impact frontmatter:** `impact: CRITICAL|HIGH|MEDIUM|LOW` documented in `docs/PRESET-CONTRIBUTION.md`; applied on next golden domain rules with Incorrect/Correct samples.
+- **Next Incorrect/Correct samples** on 9 domain rules (architecture-boundaries, public-imports, api-services, store-rtk, react-ui, tests-unit, http-client, layer-barrel-exports, arrow-functions) + Claude twins.
+- **Opt-in eval:** `eval/next/manifest.json`, `scripts/check-rule-eval.mjs`, `yarn check:rule-eval`, workflow `.github/workflows/rule-eval.yml` (not in `check:preset-structure`).
+- **Living conventions:** lineage section in `reference-features.template.md` + 6 adapters; `team/conventions.md` template ×6.
+- **Skills:** `write-adr` ×6; `react-performance` ×2 (next cursor+claude only).
+- **Hooks cookbook:** `hooks/examples/` (secret-guard, format-edited, test-on-save) ×3 stacks ×2 platforms; default `hooks.json` unchanged.
+- **Dogfood:** `sync-dogfood-cursor.sh` copies root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent.
+- **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 +64,28 @@
 
 ### Changed
 
+- **Style delegate:** next `arrow-functions` trimmed → ESLint/Stylelint + `post-change-lint`; ios/go Stack notes point to SwiftLint / golangci; abstract style sentence in shared code-quality core (no tool names in core body).
+- **Leakage scan:** `hooks/**/*.sh` recursive (includes cookbook examples).
+- **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

@@ -32,6 +32,7 @@ If `.cursor` does not appear, check the command output for errors and confirm yo
 - optional dirs when present: `agents/`, `hooks/`, `skills/`, `team/`
 - Cursor root files: `hooks.json`, `BUGBOT.md`, `AGENTS.md`, `MCP.md`, `mcp.json`
 - Claude: `CLAUDE.md`, `MCP.md` under `.claude/`; project `.mcp.json` at repo root
+- **Both tools:** repo-root `AGENTS.md` (from preset `REPO_AGENTS.md`)
 
 Any other files you added under `.cursor/` or `.claude/` (notes, local overrides, IDE state) are **left intact**. Older releases that deleted the whole tool directory are no longer the behavior.
 
@@ -43,18 +44,35 @@ Where things go on `init`:
 | commands | `.cursor/commands` | `.claude/commands` |
 | agents | `.cursor/agents` | `.claude/agents` |
 | hooks | `.cursor/hooks`, `.cursor/hooks.json` | `.claude/hooks` |
+| hooks cookbook | `.cursor/hooks/examples/` (not in default `hooks.json`) | `.claude/hooks/examples/` |
 | skills | `.cursor/skills` | `.claude/skills` |
-| team artifacts template | `.cursor/team` | `.claude/team` |
+| team artifacts template | `.cursor/team` (incl. `conventions.md`) | `.claude/team` |
 | 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` |
+| tool map | `AGENTS.md` → `.cursor/AGENTS.md`, `BUGBOT.md` | `CLAUDE.md` → `.claude/CLAUDE.md` |
+| **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
 
-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 `..`.
+Skills of note: `write-adr` (all stacks); `react-performance` (**next only**). Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`).
+
+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) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`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`
+- **Opt-in rule eval:** `yarn check:rule-eval` + `.github/workflows/rule-eval.yml` (`workflow_dispatch` + paths-scoped PR) — **not** wired into `check:preset-structure`
+- **CLI note:** `_shared` is not an installable `--preset`; `init` copies only `presets/cursor/<name>/` or `presets/claude/<name>/`
+
 MIT.

package/bin/cli.js

@@ -21,6 +21,8 @@ const PRESETS = {
     mcpJsonSrc: 'mcp.json',
     mcpJsonDest: '.cursor/mcp.json',
     toolRootFiles: ['BUGBOT.md', 'AGENTS.md', 'MCP.md'],
+    /** Preset-root basename → path relative to cwd (not under .cursor/). */
+    repoRootFiles: { 'REPO_AGENTS.md': 'AGENTS.md' },
   },
   claude: {
     rulesDir: '.claude/rules',
@@ -32,6 +34,8 @@ const PRESETS = {
     mcpJsonSrc: 'mcp.json',
     mcpJsonDest: '.mcp.json',
     toolRootFiles: ['MCP.md'],
+    /** Same cross-tool root AGENTS.md as cursor (overwrite on init). */
+    repoRootFiles: { 'REPO_AGENTS.md': 'AGENTS.md' },
   },
 };
 
@@ -57,16 +61,20 @@ Options:
 
 Notes:
   init merges into the target directory; same-named files are overwritten.
-  Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
+  Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
   Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
+  Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
+  clean removes tool dirs/files and <cwd>/AGENTS.md (shared across tools — re-init the other tool to restore).
   Command forms: "init cursor --preset next", "init cursor next", "--preset next init cursor", "cursor init --preset next".
 
 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
 `);
 }
@@ -253,6 +261,11 @@ function presetHasAnySource(base, cfg) {
       return true;
     }
   }
+  for (const srcName of Object.keys(cfg.repoRootFiles || {})) {
+    if (fs.existsSync(path.join(base, srcName))) {
+      return true;
+    }
+  }
   return false;
 }
 
@@ -384,6 +397,17 @@ function cmdInit(tool, preset, cwdOption) {
         copiedSteps++;
       }
     }
+
+    for (const [srcName, destRel] of Object.entries(cfg.repoRootFiles || {})) {
+      const from = path.join(base, srcName);
+      if (fs.existsSync(from)) {
+        const destAbs = path.join(cwd, destRel);
+        fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+        fs.copyFileSync(from, destAbs);
+        console.log(`Copied ${srcName} → ${destRel}`);
+        copiedSteps++;
+      }
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`init failed: ${msg}`);
@@ -442,6 +466,11 @@ function cmdClean(tool, cwdOption) {
     removedParts.push(`${toolRoot}/${name}`);
   }
 
+  for (const destRel of Object.values(cfg.repoRootFiles || {})) {
+    removeFileIfExists(path.join(cwd, destRel));
+    removedParts.push(destRel);
+  }
+
   console.log(`Removed ${removedParts.join(', ')} (if present)`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -24,6 +24,14 @@
     "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",
+    "check:rule-eval": "node scripts/check-rule-eval.mjs"
+  },
   "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», «объясни») — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/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», «объясни») — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners.
+- 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,43 @@
+# Эталонные фичи (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.
+
+## Living conventions
+
+После init команда ведёт **локальные** gotchas, patterns и decisions в consumer-owned store (не в shared core и не только в корневом `AGENTS.md`):
+
+| Раздел | Что фиксировать |
+|--------|-----------------|
+| Gotchas | Повторяющиеся ловушки, хрупкие места, «не делай X в этом репо» |
+| Patterns | Локальные паттерны сверх эталонной таблицы |
+| Decisions | Краткие ADR-ссылки / продуктовые решения, влияющие на код |
+
+Указатель пути к файлу и stack-таблицы — в адаптере пресета (`team/conventions.md`). Файл **не** always-on.
+
+## Связанные правила
+
+- `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).