@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/docs/PRESET-CONTRIBUTION.md

@@ -0,0 +1,431 @@
+# Preset contribution guide
+
+How to develop and evolve installable presets in `@bonesofspring/ai-rules` (`packages/ai-rules/presets/**`).
+
+**Audience:** maintainers editing preset rules, agents, skills, hooks, or platform artifacts — not consumer app developers using `ai-rules init` in their projects.
+
+Related docs:
+
+- Package install surface: [`../README.md`](../README.md)
+- Shared core taxonomy: [`../presets/_shared/README.md`](../presets/_shared/README.md)
+- Regression audit / ADRs: repo `.ai.local/team/tasks/preset-regression-audit/` (`architecture.md`, `documentation.md`)
+
+---
+
+## Rule taxonomy (three layers)
+
+Every preset artifact belongs to one of these layers. Do not mix semantics across layers.
+
+| Layer | Path | What belongs here |
+|-------|------|-------------------|
+| **Core** | `presets/_shared/core/**` | Stack-agnostic prose and checklists. No Cursor/Claude frontmatter. No stack paths (`app/src/**`, `Features/**`, Playwright, `xcodebuild`). |
+| **Stack** | `presets/{cursor\|claude}/<stack>/` | Domain rules, stack always-on trio, stack tooling, stack examples in a delimited `## Stack notes` section. |
+| **Platform** | Same stack tree | Adapter packaging: Cursor `.mdc` (`alwaysApply` / `globs`) vs Claude `.md` (`paths:`). Platform-only files (`BUGBOT.md`, `AGENTS.md`, `CLAUDE.md`, `hooks.json`). |
+
+```text
+Core (_shared/core)          → shared principles
+    ↓ embed / copy + marker
+Stack (cursor|claude/<stack>) → domain + stack deltas
+    ↓ frontmatter / layout
+Platform adapter             → .mdc | .md + platform-only artifacts
+```
+
+**Classification quick check:**
+
+- Applies to all stacks with only example differences → **core** + stack adapters.
+- Only one installable stack (`next` / `nuxt` / `svelte` / `ios-swift` / `android-kotlin` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (never in `_shared`).
+- Only Cursor or only Claude file shape → **platform** (do not duplicate semantics in the other platform).
+
+Meta-rules for **preset authors** live in `core/meta/` and are packaged into each stack with globs limited to `packages/ai-rules/presets/**` (never `alwaysApply` / session-start in consumer installs).
+
+---
+
+## Source of truth (SoT)
+
+| Concern | SoT | Notes |
+|---------|-----|-------|
+| Preset content | `packages/ai-rules/presets/**` | **Not** repo root `.cursor/` — dogfood is a synced working copy. |
+| Per stack | `presets/cursor/<stack>/` | Cursor `.mdc` is SoT for that stack. |
+| Claude twins | `presets/claude/<stack>/` | Derived in the **same PR** as Cursor changes. |
+| Shared core | `presets/_shared/core/**` | Edit core first; update all `<!-- shared-core: … -->` consumers in the same PR. |
+| Monorepo dogfood | Root `.cursor/` | Sync **from** packages on release / dogfood PR (typically `cursor/next` + author meta globs). |
+
+Twin-sync 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` |
+| `nuxt` | `presets/cursor/nuxt/rules/*.mdc` | `presets/claude/nuxt/rules/<topic>/` | Required in `claude/nuxt/rules/README.md` |
+| `svelte` | `presets/cursor/svelte/rules/*.mdc` | `presets/claude/svelte/rules/<topic>/` | Required in `claude/svelte/rules/README.md` |
+| `ios-swift` | `presets/cursor/ios-swift/rules/*.mdc` | `presets/claude/ios-swift/rules/<topic>/` | Required in `claude/ios-swift/rules/README.md` |
+| `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Required in `claude/go/rules/README.md` |
+| `java` | `presets/cursor/java/rules/*.mdc` | `presets/claude/java/rules/<topic>/` | Required in `claude/java/rules/README.md` |
+| `mcp-ts` | `presets/cursor/mcp-ts/rules/*.mdc` | `presets/claude/mcp-ts/rules/<topic>/` | Required in `claude/mcp-ts/rules/README.md` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/rules/*.mdc` | `presets/claude/php-hexagonal/rules/<topic>/` | Required in `claude/php-hexagonal/rules/README.md` |
+| `php-laravel` | `presets/cursor/php-laravel/rules/*.mdc` | `presets/claude/php-laravel/rules/<topic>/` | Required in `claude/php-laravel/rules/README.md` |
+| `android-kotlin` | `presets/cursor/android-kotlin/rules/*.mdc` | `presets/claude/android-kotlin/rules/<topic>/` | Required in `claude/android-kotlin/rules/README.md` |
+
+Claude topic folders (all stacks): `architecture/`, `stack/`, `api-and-data/`, `ui-and-accessibility/`, `testing/`, `tooling-and-review/`.
+
+---
+
+## Shared core sync workflow
+
+1. Change prose under `presets/_shared/core/<area>/<stem>.md`.
+2. Find consumers: `rg 'shared-core: <path>' packages/ai-rules/presets`.
+3. Update every adapter (**all adapters**: stacks × 2 platforms, when the rule is shared) in the **same PR** — see **sync modes** below.
+4. Keep stack-specific content only in adapters (embed: `## Stack notes`; lineage: full stack body).
+5. Update stack `rules/README.md` core→stack mapping if stems or paths changed.
+6. Sync dogfood: `packages/ai-rules/scripts/sync-dogfood-cursor.sh` when maintaining this monorepo.
+
+Sync marker (after frontmatter in platform files):
+
+```html
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+```
+
+### Sync modes
+
+| Mode | When to use | Adapter shape | Drift check |
+|------|-------------|---------------|-------------|
+| **Embed (A)** | Shared principles with small stack examples | Core prose copied into adapter + `## Stack notes` for deltas only | `check-shared-core-drift.sh` compares body (minus frontmatter / Stack notes) to core |
+| **Lineage (B)** | Stack checklist / paths dominate; core stays abstract | Marker present; body is stack-specific (Next `app/**`, iOS `Features/**`, etc.) | Script lists consumers only — **no** body equality |
+
+**Embed stems (reference):** `quality/code-quality-and-refactoring`, `quality/design-guidance`, `quality/mcp-usage`, all `meta/preset-*`, `review/code-review-mr`, `review/technical-retro`, `agent-team/agent-team-intake`, `architecture/product-specs`, `architecture/product-specs-authoring`.
+
+**Lineage stems (reference):** `architecture/feature-delivery-workflow`, `architecture/reference-features.template`, `agent-team/agent-team-orchestrator`.
+
+Intentional fork / mode change: document in PR (and optionally in validation-report).
+
+---
+
+## Token budget (consumer installs)
+
+Hard caps for **installed** presets (not author meta-rules):
+
+| Platform | Always-on mechanism | Cap |
+|----------|---------------------|-----|
+| Cursor | `alwaysApply: true` | **3–5** (extra slots include `ai-local-overlay.mdc`) |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` `loadMode: root-entry` | **3–5** |
+
+Caps are **aligned** across platforms (min **3**, max **5**); slots beyond the base invariants are reserved for `ai-local-overlay`.
+
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
+
+Session-start body budget (where documented): ≤200 lines total (stretch ≤170).
+
+**Author meta-rules** (`preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`):
+
+- **Never** `alwaysApply: true` / never among the Claude session-start rules.
+- Cursor: `globs` → `packages/ai-rules/presets/**` (+ dogfood `.cursor/**` where useful).
+- Claude: `paths:` → `packages/ai-rules/presets/**/*` **plus** dogfood `.claude/**/*` (and optionally `.cursor/rules/**/*`, `.ai.local/team/tasks/**/*` for parity with Cursor meta globs).
+
+`build-verifier` in each stack documents preset-structure **FAIL** checks for budget and meta loading.
+
+---
+
+## PR checklist
+
+Before merging any PR touching `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync):
+
+Use the packaged rule **`preset-pr-checklist`** (Cursor: `preset-pr-checklist.mdc`; Claude: `tooling-and-review/preset-pr-checklist.md`) or the checklist in `presets/_shared/core/meta/preset-pr-checklist.md`.
+
+Summary:
+
+- [ ] SoT: edits in `packages/…`, not only root `.cursor/`
+- [ ] Core: if `_shared/core/**` changed → all `shared-core` consumers updated (or fork documented)
+- [ ] Twin: Cursor change → Claude twin in **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel)
+- [ ] Mapping: `claude/<stack>/rules/README.md` table current
+- [ ] Token budget: Cursor/Claude always-on **3–5** (extra slots = `ai-local-overlay`); body sum ≤200 (stretch ≤170); meta rules not always-on
+- [ ] Leakage: no cross-stack agent stems (`preset-no-cross-stack-leakage`)
+- [ ] Twin depth: domain rules ≥15 body lines; thin aliases documented
+- [ ] README / catalog updated when stems added
+- [ ] CHANGELOG / package README if public install surface changes
+- [ ] Dogfood: `scripts/sync-dogfood-cursor.sh` (or intentional skip documented)
+- [ ] Embed drift: `scripts/check-shared-core-drift.sh` after core/embed edits
+- [ ] Structure gates: `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) passes
+
+Validation: stack `agents/build-verifier.md` → **preset-structure validation** section; CI workflow `preset-structure.yml`.
+
+---
+
+## CLI: `_shared` is not a preset
+
+`ai-rules init` copies only under:
+
+- `presets/cursor/<name>/`
+- `presets/claude/<name>/`
+- `presets/mavis/<name>/` (generated; see the Mavis sibling adapter below)
+- `presets/opencode/<name>/` (generated; see the OpenCode sibling adapter below)
+
+`presets/_shared/` is a **sibling** of the four platform trees — it is **never** copied wholesale to consumer projects.
+
+- Do **not** pass `_shared` as `--preset`.
+- Do **not** nest `_shared` under `cursor/` or `claude/` (would break ignore semantics).
+
+**Exception — docs/specs seed:** when consumer `docs/specs/` is **absent**, `init` copies `presets/_shared/assets/docs-specs/INDEX.md` + `_templates/*` into `<cwd>/docs/specs/` (idempotent; **never overwrite** an existing INDEX). When the tree already exists, skip seed entirely.
+
+List installable presets: directories directly under `presets/cursor/` and `presets/claude/` (e.g. `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, `php-laravel`).
+
+### Mavis sibling adapter
+
+`presets/mavis/` is a third platform sibling (id **`mavis`**, runtime **`mcode`**). Consumer files land under **`.mavis/`** (ai-rules-owned; not a MiniMax-native discovery path). Machine-readable declaration: `presets/mavis/platform-contract.json` (architecture §3.4). Validate with `node scripts/check-mavis-platform-contract.mjs` (add `--self-test` for fixtures).
+
+**Released:** all 10 installable stacks — `npx @bonesofspring/ai-rules init mavis --preset <stack>` (and `init multi --preset <stack>`). Do not add `mcode` / `minimax` CLI aliases. Do not derive Mavis sources from Claude. Capability statuses must link to `docs/MAVIS-COMPATIBILITY.md`; `unknown` / `no-equivalent` capabilities must not declare a native path. Do not pin desktop or CLI patch versions in the contract.
+
+Consumer guide: [`MAVIS.md`](./MAVIS.md). Compatibility evidence: [`MAVIS-COMPATIBILITY.md`](./MAVIS-COMPATIBILITY.md). Adapter authoring: [`presets/mavis/README.md`](../presets/mavis/README.md).
+
+### OpenCode sibling adapter
+
+`presets/opencode/` is a fourth platform sibling (id **`opencode`**, runtime **`opencode`**). Consumer files land under **`.opencode/`** (native agents / skills / commands) plus root `AGENTS.md` and `opencode.json`. Machine-readable declaration: `presets/opencode/platform-contract.json`. Validate with `node scripts/check-opencode-platform-contract.mjs` (add `--self-test` for fixtures).
+
+**Released:** all 10 installable stacks — `npx @bonesofspring/ai-rules init opencode --preset <stack>` (and `init multi --preset <stack>`). Do not derive OpenCode sources from Claude. Capability statuses must link to `docs/OPENCODE-COMPATIBILITY.md`; `unknown` / `no-equivalent` capabilities must not declare a native path. Do not pin OpenCode CLI versions in the contract. Do not write `~/.config/opencode/**`.
+
+Consumer guide: [`OPENCODE.md`](./OPENCODE.md). Compatibility evidence: [`OPENCODE-COMPATIBILITY.md`](./OPENCODE-COMPATIBILITY.md). Adapter authoring: [`presets/opencode/README.md`](../presets/opencode/README.md).
+
+### Product specs authoring surface
+
+| Piece | Path / note |
+|-------|-------------|
+| Discovery stem | `_shared/core/architecture/product-specs.md` — **Consume** mode; requestable (`alwaysApply: false` / Claude `paths: docs/specs/**/*`) |
+| Authoring stem | `_shared/core/architecture/product-specs-authoring.md` — **Generate / Bootstrap**; same requestability; split keeps discovery lean |
+| Assets SoT | `_shared/assets/docs-specs/` — INDEX stub, `_templates/{page,feature}.md`, optional `schemas/frontmatter-v1.schema.json` |
+| CLI seed | `init` copies assets when consumer `docs/specs/` **absent**; never overwrite existing INDEX; skip if directory exists (even empty) |
+| Skill | `skills/spec-authoring/` (stacks with `feature-delivery`) — template ensure, frontmatter/body fill, INDEX same-changeset |
+| Discovery skill | `skills/spec-discovery/` — requestable; 11 methods + claim ledger; author-mode research-before-spec only (not default `/task`) |
+| Command | `/spec-start` → task-analyst author mode → human gate (no dedicated `spec-author` agent) |
+| Agents | **task-analyst** primary author; **tech-writer** post-sync (9 stacks; **mcp-ts analyst-only**); **feature-developer** consumes approved specs as SoT |
+| Validation | code-reviewer **WARN** drift / **FAIL** broken INDEX or missing required FM on touched specs; build-verifier **FAIL** missing assets/twins/requestable; optional `scripts/check-product-specs.sh` (**WARN** default, **`--strict`** FAIL; ships in the npm `files` tarball). Checker is bash INDEX/keys/headings — it does **not** evaluate `frontmatter-v1.schema.json` |
+| Dogfood | `dogfood/mcp-ts-sample/docs/specs/` — mcp-ts field semantics (`routes` = tool names) |
+
+When adding or changing either stem: update **both** ×20 adapters, README mapping rows, and run `check:shared-core-drift` + `check:preset-structure`.
+
+---
+
+## How to add a new stack preset
+
+**Reference implementation:** `go` / `java` / `php-hexagonal` / **`php-laravel`** — backend twins under [`presets/cursor/`](../presets/cursor/) + Claude. Closest template for layered backends is **`java`** (dual tooling discovery + framework variants) or **`go`**; do not copy `next` UI/store surface wholesale. For **frontend** stacks, scaffold from **`next`**, **`nuxt`**, or **`svelte`** (React/RTK vs Vue/Pinia vs SvelteKit/`store-svelte`); recent additions **`nuxt`** (Nuxt 3 root layout, `vue-performance`) and **`svelte`** (SvelteKit `src/` layout, `svelte-performance`, script gate **`check`**) mirror `next` agent-team depth.
+
+**PHP stacks (coexistence):**
+
+| Install id | When to use |
+|------------|-------------|
+| **`php-laravel`** | Laravel backend/API — Eloquent, Form Requests, Policies, `routes/api.php`, `php artisan test`. Agents follow Laravel-first conventions (thin controllers, Actions/Services). |
+| **`php-hexagonal`** | Framework-agnostic or multi-framework PHP — strict ports & adapters (`Domain` / `Application` / `Adapters` / `Composition`); Slim/Symfony/plain PHP edge. |
+
+Distinct CLI ids; neither renames nor replaces the other. Comparison prose in stack READMEs is OK; do not mix hexagonal path invariants into Laravel always-on bodies.
+
+Recent additions: **`android-kotlin`** (scaffolded from `ios-swift` agent-team + `java` CA/Gradle patterns; instrumentation-test trio; vendor-neutral placeholders); **`php-hexagonal`** (scaffolded from `java`, Composer/PHPUnit gates; dogfood `dogfood/php-hexagonal`); **`php-laravel`** (scaffolded from `php-hexagonal`, Laravel-first rules; dogfood `dogfood/php-laravel` — full `laravel/framework`).
+
+1. **Copy structure** from the closest existing stack (flat Cursor `rules/*.mdc`, Claude topic folders). For PHP/Go backends, start from `java` or `go` skeleton and rewrite Stack notes / tooling.
+2. **Define always-on set** (Cursor/Claude 3–5 — extra slots reserved for `ai-local-overlay`) — stack-specific cores plus `ai-local-overlay` on Cursor. Embed shared quality from `_shared/core` where applicable. `go` uses `go-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`, `ai-local-overlay`.
+3. **Stack-specific rules** — domain, tooling, post-change gate, agents/skills with stack-appropriate names (no Playwright stems on iOS/go, no XCUITest stems on Next/go, no xcodebuild/ESLint as required handoffs on go, etc.).
+4. **Embed core** — add `<!-- shared-core: … -->` adapters for shared stems; fill `## Stack notes` with stack examples only in adapters (Go: hexagonal layers; Android: Activity/Compose paths).
+5. **Claude twin** — create topic `.md` files + **Cursor→Claude mapping table** in `claude/<stack>/rules/README.md`. `go` ships `ui-and-accessibility/README.md` as N/A stub only.
+6. **Meta-rules** — add five `preset-*.mdc` / `preset-*.md` wrappers with preset-path globs (same as existing stacks).
+7. **build-verifier** — include preset-structure checks + stack leakage list.
+8. **Platform artifacts** — see next section.
+9. **Structure scripts** — add stack name to `STACKS` in `check-preset-twin-map.sh`, `check-preset-token-budget.sh`, `check-preset-leakage.sh`; fork `chain-team-phases.sh` byte-wise from other stacks.
+10. **Platform registration** — add the stack to `STACK_PROFILES` in `scripts/lib/stack-platform-profiles.mjs`, to `releasedStacks` in both `presets/mavis/platform-contract.json` and `presets/opencode/platform-contract.json`, then generate the derived trees: `node scripts/generate-mavis.mjs --stack <name>` and `node scripts/generate-opencode.mjs --stack <name>`. Verify with `node scripts/check-generated-drift.mjs`.
+11. **Document** — stack `README.md`, `rules/README.md` core→stack table, twin row in this guide, link `_shared/README.md`.
+12. **Package README** — list new preset name under install examples for all four platforms (`init cursor|claude|mavis|opencode --preset <name>`).
+
+Twin policy: Cursor SoT per stack; Claude derived same PR from day one.
+
+---
+
+## Impact tags (domain rules)
+
+Optional YAML frontmatter key for teachable / high-stakes domain rules (especially next rules with Incorrect/Correct samples):
+
+```yaml
+impact: HIGH   # CRITICAL | HIGH | MEDIUM | LOW
+```
+
+| Level | When to use |
+|-------|-------------|
+| `CRITICAL` | Correctness, security, or hard layer boundaries — violations break the product or leak data |
+| `HIGH` | Architecture / imports / public API contracts agents must not invent around |
+| `MEDIUM` | Team conventions that matter for consistency but are not boundary-critical |
+| `LOW` | Style / nit preferences (prefer linters when possible) |
+
+**Rules:**
+
+- Key is exactly `impact` (lowercase); values uppercase enum only.
+- Cursor: same frontmatter as `description` / `globs` / `alwaysApply`.
+- Claude twins: **mirror the same `impact:` key/value** in YAML frontmatter (with `paths:`).
+- **Do not** use a body `## Impact` block — frontmatter only.
+- **Forbidden** in `_shared/core/**` (core has no frontmatter).
+- Structure scripts ignore unknown YAML keys; `check:preset-structure` does **not** require `impact`. Opt-in `yarn check:rule-eval` may require it for golden stems.
+
+---
+
+## How to add a platform-only artifact
+
+Artifacts that do not have a semantic twin on the other platform:
+
+| Artifact | Platform | Location in preset | Installed to |
+|----------|----------|----------------------|--------------|
+| `REPO_AGENTS.md` | Both | `presets/{cursor\|claude}/<stack>/REPO_AGENTS.md` | `<cwd>/AGENTS.md` |
+| `BUGBOT.md` | Cursor only | `presets/cursor/<stack>/BUGBOT.md` | `.cursor/BUGBOT.md` |
+| `AGENTS.md` | Cursor only | `presets/cursor/<stack>/AGENTS.md` | `.cursor/AGENTS.md` |
+| `hooks.json` | Cursor only | `presets/cursor/<stack>/hooks.json` | `.cursor/hooks.json` |
+| `CLAUDE.md` | Claude only | `presets/claude/<stack>/CLAUDE.md` | `.claude/CLAUDE.md` |
+
+**`REPO_AGENTS.md` authoring skeleton** (required section order; bodies per-stack):
+
+```markdown
+# <Stack display name> — agent instructions
+## Cross-tool setup
+## Presence-based load   (next: if `.cursor/` / `.claude/` / `.mavis/` / `.opencode/` exists)
+## Pipelines are shared  (slug lives under `.ai.local/team/tasks/<slug>/`)
+## Commands (test / lint / build)
+## Security basics
+## Tool entry points
+## Living conventions
+## Local overlay (`.ai.local/`) — MANDATORY
+```
+
+Living gotchas go in **`.ai.local/conventions.md`** (pointer only in root `AGENTS.md`). Do not load `.ai.local/team/**` as overlay rules. Keep root file lean (≤ ~80 lines). For **next**, Cursor/Claude/Mavis/OpenCode `REPO_AGENTS.md` must be byte-identical. CLI: `repoRootFiles` maps `REPO_AGENTS.md` → `AGENTS.md` (overwrite on init; `clean` removes it only when no other tool install remains). Do **not** put `REPO_AGENTS.md` in `toolRootFiles`.
+
+**Do not** duplicate Bugbot review prose into Claude — use skill `code-review` + `tooling-and-review/code-review.md` on Claude.
+
+When adding a platform-only file:
+
+1. Place it at the preset root (same level as `rules/`, `agents/`).
+2. Mention in stack `README.md` that there is no cross-platform twin.
+3. Ensure `ai-rules clean` documents the path if it becomes CLI-managed (see package README).
+4. No `shared-core` marker — platform packaging only.
+
+Hooks scripts may fork per stack (e.g. ios-swift `chain-team-phases.sh` must not be byte-identical to next’s).
+
+---
+
+## Where to put a new rule
+
+1. **Shared principle for all stacks?** → `_shared/core/` → adapters in each stack with marker + Stack notes.
+2. **One stack only?** → `presets/cursor/<stack>/rules/<stem>.mdc` + Claude twin under the correct topic folder.
+3. **Preset author workflow?** → `_shared/core/meta/` + `preset-*.mdc` / `tooling-and-review/preset-*.md` with preset globs only.
+4. **Heavy workflow (orchestrator, feature-delivery, code-review)?** → requestable / `paths:` / globs — **not** always-on.
+
+See packaged **`preset-layering`** and **`preset-no-cross-stack-leakage`** for details.
+
+---
+
+## Layout asymmetry (intentional P1)
+
+- **Cursor:** flat `rules/*.mdc` (topic folders optional P2).
+- **Claude:** topic subfolders under `rules/`.
+
+Parity is by **stem and mapping table**, not identical directory shape. Use `claude/<stack>/rules/README.md` as the Cursor→Claude index.
+
+---
+
+## Meta-rules reference (authors)
+
+| Stem | Core source | Purpose |
+|------|-------------|---------|
+| `preset-layering` | `core/meta/preset-layering.md` | Core → Stack → Platform |
+| `preset-twin-sync` | `core/meta/preset-twin-sync.md` | SoT, same-PR twins, mapping |
+| `preset-token-budget` | `core/meta/preset-token-budget.md` | ≤3 always-on, meta loading |
+| `preset-pr-checklist` | `core/meta/preset-pr-checklist.md` | Merge checklist |
+| `preset-no-cross-stack-leakage` | `core/meta/preset-no-cross-stack-leakage.md` | Forbidden cross-stack strings |
+
+Load these when editing files under `packages/ai-rules/presets/**`, `.cursor/**` dogfood, or `.claude/**` dogfood.
+
+---
+
+## Dogfood & structure scripts (this monorepo)
+
+| Script / npm | Purpose |
+|--------------|---------|
+| `scripts/sync-dogfood-cursor.sh` | Copy `presets/cursor/<preset>/` → root `.cursor/` (`AI_RULES_DOGFOOD_PRESET`, default `next`). Also copies `REPO_AGENTS.md` → repo-root `AGENTS.md`. Seeds `.ai.local/team` templates; preserves `.ai.local/team/tasks/`. |
+| `scripts/check-shared-core-drift.sh` / `yarn check:shared-core-drift` | Check embed-mode adapters vs core; lists lineage consumers. Soft by default; set `AI_RULES_DRIFT_FAIL=1` (or use `check:preset-structure`) to exit non-zero on drift. |
+| `scripts/check-preset-twin-map.sh` / `yarn check:preset-twin-map` | **FAIL** if Cursor `.mdc` missing from Claude mapping table, twin file missing, or orphan topic `.md` (excl. `**/README.md`). Stacks: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, `php-laravel`. |
+| `scripts/check-preset-token-budget.sh` / `yarn check:preset-token-budget` | **FAIL** if Cursor `alwaysApply: true` or Claude no-`paths:` (excl. README) count is outside **3–5**, `preset-*` always-on, or intended body sum > **200**. Stacks include `nuxt`, `svelte`. |
+| `scripts/check-preset-leakage.sh` / `yarn check:preset-leakage` | **FAIL** on forbidden stems in `hooks/**/*.sh` (recursive), wrong-stack agent filenames, or **positive** (non-negation) agent body mentions; **FAIL** if chain scripts are byte-identical across stacks. Explicit **negation** of forbidden stems in agent bodies is **suppressed** (INFO summary count only — not a merge blocker). Non-negation mentions in `build-verifier` → **WARN only**. |
+| `scripts/check-preset-structure.sh` / `yarn check:preset-structure` | Orchestrator: twin-map + token-budget + leakage + shared-core drift (**all hard**; drift via `AI_RULES_DRIFT_FAIL=1`). Does **not** run rule-eval. |
+| `scripts/check-product-specs.sh` / `yarn check:product-specs` | Opt-in consumer tree check: frontmatter v1 keys + required body headings on `docs/specs/**` (bash; does **not** run JSON Schema). Ships in the npm package `files` (`scripts/`). **WARN** by default; **`--strict`** exits non-zero. |
+| `yarn check:product-specs:dogfood` | Same script against monorepo `dogfood/mcp-ts-sample`. Soft WARN inside `check:preset-structure` + CI step (`continue-on-error`); not a hard consumer CI gate. |
+| `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` | Opt-in: validates Incorrect/Correct pairs + `impact:` on **next-only** golden stems (`eval/next/manifest.json`). Backend / ios / php-hexagonal / php-laravel stems are out of scope until a stack adds `eval/<stack>/`. Not part of `check:preset-structure`. |
+
+Run from `packages/ai-rules/`:
+
+```bash
+yarn check:preset-structure
+# or
+bash scripts/check-preset-structure.sh
+```
+
+CI: [`.github/workflows/preset-structure.yml`](../../../.github/workflows/preset-structure.yml) runs the orchestrator on PRs touching `packages/ai-rules/**`.
+
+---
+
+## Building blocks — what to add where
+
+When packaging a new habit for agents, pick **one** primary artifact. Prefer the lightest option that fits.
+
+| Artifact | Invocation | Purpose | Context impact |
+|----------|------------|---------|----------------|
+| **Always-on / session-start rule** | Auto | Persistent standards every session | Always in context — **budget 3–5** |
+| **Requestable / globs / `paths:` rule** | On match or demand | Domain/tooling for relevant files | Loaded when paths match |
+| **Slash command** | Manual (or orchestrated) | Reusable prompt template with parameters | One interaction |
+| **Skill (`SKILL.md`)** | Auto or agent-followed | Multi-step procedure / checklist | Loaded into current agent context |
+| **Subagent (`agents/*.md`)** | Auto/Manual | Separate persona + (often) fresh context | Separate system prompt / context |
+| **`.ai.local/conventions.md`** | Pointer from AGENTS | Living gotchas after init (consumer-owned) | Not always-on; fill post-init |
+| **Hook** | Tool lifecycle | Mechanical enforce (format, secret guard) | Outside model prose |
+
+## Skill authoring craft (SDO)
+
+Skills are behavior-shaping, not essays. When adding or editing `skills/**/SKILL.md`:
+
+1. **SDO (`description` = WHEN, not WHAT).** Frontmatter `description` must start with trigger/symptoms (`Use when…`). Do **not** summarize the workflow there — agents skip reading `SKILL.md` and follow the truncated blurb.
+2. **Positive recipes over composition bans.** Write the required output shape (`Your dispatch must contain 1…5`). Bare “don’t restate / don’t narrate” often backfires. Keep **discrete** prohibitions (don’t run tests; don’t edit `status.json`) and **recognition tables** (Red Flags / rationalizations).
+3. **No nuance clauses on hard gates.** `unless it matters` re-opens negotiation. If a rule is strict, keep it strict.
+4. **Size.** Prefer `SKILL.md` under **~500 lines**. Move 100+ line references and scripts beside the skill. If a skill exceeds 500, split — do not grow it.
+5. **Test the failure, then the wording.** Pressure-test with a subagent *without* the skill, capture the excuse, then write the minimal counter. One skill at a time.
+
+Author-only: this section is **not** copied by `init`.
+
+### B1–B5 stems (all stacks)
+
+| Stem | Drift mode | Why | Consumers |
+|------|------------|-----|-----------|
+| `quality/debug-investigation.md` | **embed** | Skill file is core prose + `## Stack notes` only | `skills/debug-investigation/SKILL.md` (10 stacks × 2) |
+| `quality/verification-before-completion.md` | **lineage** | Section snippet inside fat `build-verifier` / `feature-developer` | those agents (debugger 3-fix is inline, not this stem) |
+| `review/receiving-code-review.md` | **lineage** | Section snippet inside fat `code-review` skill | skill + implementer line on `feature-developer`, `debugger`, `ci-investigator` |
+| `agent-team/task-classification.md` | **lineage** | Section snippet inside fat `task-analyst` / `task-router` | those agents |
+
+`check-shared-core-drift.sh` embed mode compares the **entire** adapter (minus frontmatter, marker, `## Stack notes`) to the core file. Fat agents cannot be embed consumers. Do **not** put `<!-- shared-core: quality/debug-investigation.md -->` on `debugger.md`. Every `debugger.md` (including backend `go` / `java` / `php-*`) must still **point at** skill `debug-investigation` at the top of the agent body so the 4-phase embed loads.
+
+Do **not** edit `quality/anti-sycophancy-discipline.md` for receiving-CR until a dedicated ×10 embed PR.
+
+**Decision hints**
+
+- Persistent coding standard for all work → always-on **only** if it fits the budget (Cursor/Claude 3–5); else requestable/globs.
+- Repeated multi-step workflow → **skill** (or command that points at a skill).
+- Needs unbiased fresh eyes / role isolation → **subagent** (e.g. `code-reviewer`, `codebase-analyzer`).
+- Project-specific gotcha after a wrong turn → **`.ai.local/conventions.md`** first; graduate to rule/skill after **3+** repetitions (Rule of Three).
+- Mechanical style/safety → **hook example**, not a prose style bible.
+
+Do **not** put heavy workflows (orchestrator, feature-delivery, code-review) in always-on rules.
+
+---
+
+## Router fixtures vs classifier tests
+
+UI stacks ship `team/fixtures/` documenting expected pipelines (`feature-with-figma-url.json`, `feature-with-ux-no-figma.json`, `mockup-review-standalone.json`, `ux-design-standalone.json`, `mockup-review-fail-embedded-status.json`). These files are **shape examples**; they do **not** execute `task-router` heuristics.
+
+When changing intent detection — especially `figma.com` + UX-review wording → `mockup-review` **before** `ux-design` **before** `review-only` — update those fixtures and replay the classifier by hand. v1 has no automated prompt→intent test.
+
+---
+
+## Optional follow-ups
+
+- CLI codegen / auto twin sync
+- Physical Cursor topic folders mirroring Claude
+- Mass rewrite of stack domain rule bodies
+- Dedicated `preset-verifier` agent (today: `build-verifier` preset-structure section + structure scripts)
+- ~~Tighten leakage WARN heuristics~~ — done: negation mentions suppressed; fixture `skipped` must list Phase-1 roster agents only (`mcp-ts` policy)

package/docs/PRESET-ENGLISH-STYLE.md

@@ -0,0 +1,91 @@
+# Preset English style guide (B0)
+
+## Goal
+
+All installable preset prose is **English**: shared core, stack adapters (Cursor SoT + Claude twins), agents, skills, commands, hooks comments, and package-facing docs under `packages/ai-rules/presets/**`.
+
+Prose-only change: do not rename stems, paths, frontmatter keys, or CLI surfaces for translation.
+
+## Exception taxonomy (E1–E8)
+
+| ID | Kind | Policy | Example |
+|----|------|--------|---------|
+| **E1** | Technical identifiers | Always keep | Rule stems, agent names, npm scripts, env vars |
+| **E2** | Paths, globs, frontmatter keys | Always keep | `alwaysApply: true`, `globs:`, `paths:` |
+| **E3** | Embed markers & schema tokens | Always keep | `<!-- shared-core: … -->`, JSON field names |
+| **E4** | Quoted product/UI / user-phrasing | Keep original + EN gloss | `«Сохранить» (Save)` <!-- i18n-keep: E4 --> |
+| **E5** | Locale demo fixtures | Keep target locale | Cyrillic in a hypothetical i18n fixture |
+| **E6** | Proper nouns / trademarks | Always keep | Next.js, Pinia, SwiftLint |
+| **E7** | Stack CLI output (verbatim) | Keep if cited as evidence | Untranslated linter message quote |
+| **E8** | Author RU in runtime team tasks | Out of scope | Existing `.ai.local/team/tasks/**` — no retroactive translation |
+
+E1–E3 and E6 never need a marker (they are not “other-language prose”). E8 is scoped out of audits that target presets.
+
+## Keep marker
+
+When retaining non-English under **E4**, **E5**, or **E7**, place within ±3 lines of the match:
+
+```html
+<!-- i18n-keep: E4|E5|E7 -->
+```
+
+Use the matching ID only (e.g. `<!-- i18n-keep: E4 -->`).
+
+**Audit:** `npm run check:preset-i18n` (hard) or soft `bash scripts/check-preset-i18n.sh` — unmarked Cyrillic in scoped trees is a FAIL in hard mode. Markers may sit within ±3 lines of the match.
+
+## E4 gloss template (canonical)
+
+When citing non-English user/product phrasing, use **original first, English gloss in parentheses**:
+
+```text
+«оригинал» (English gloss)
+```
+
+Examples:
+
+- Intent signals: `«добавь» (add), «новая» (new)`
+- Skip phrases: `«без pipeline» (no pipeline), «просто сделай» (just do it)`
+- Inline pairs: `«как работает X» / "how does X work"` (guillemets for the original; ASCII quotes for English)
+
+Do **not** use EN-first “also RU: …” or `«RU» / "EN"` as the default in new prose. Prefer the forms above for Cursor SoT and Claude twins.
+
+English-only reason strings (no locale copy) use ASCII quotes: `"iOS uses XCUITest"`, not guillemets.
+
+## Stack-class bilingual policy
+
+| Class | Stacks | User-signal tables / `/task` examples |
+|-------|--------|----------------------------------------|
+| **Bilingual (RU+EN)** | `next`, `nuxt`, `php-hexagonal`, `php-laravel`, `go`, `java` | Include RU user phrasing with E4 glosses (canonical template) |
+| **EN-primary** | `svelte`, `ios-swift`, `mcp-ts` | EN signals/examples are enough; add E4 RU glosses only when the consuming product expects RU prompts |
+
+E5 fixtures (test titles, JSDoc locale demos) follow the **repo product locale**. Prefer tagging fixtures **E5** (not E4). When showing a Cyrillic fixture, an EN gloss on the same line is optional but recommended for bilingual stacks.
+
+## Glossary
+
+| Term | Meaning |
+|------|---------|
+| **SoT** | Source of truth. Packages path `packages/ai-rules/presets/**`; per stack, Cursor `.mdc` before Claude twin. Prefer **SoT** after first expansion in a doc; “source of truth” is fine in running prose. |
+| **always-on** | Loaded every session: Cursor `alwaysApply: true`; Claude rules without `paths:` (3–5 — see `preset-token-budget`). |
+| **requestable** | Loaded on demand (globs / paths / agent wiring), not session-start. |
+| **FAIL / PASS** | Verifier outcomes (`build-verifier`, drift scripts). Preserve casing in checklists. |
+| **must** | Hard requirement; violation is FAIL or blocking. Prefer this word for normative gates. |
+| **should** | Strong default; document intentional deviation. |
+| **may / can** | Optional / allowed. |
+| **required** | Prefer for **loading** behavior (“required after edits” = agent must load/run the rule). Prefer **must** for checklist obligations (“Errors — must fix”). Avoid **mandatory** in new prose. |
+
+Modality mapping when translating: должен → **must**; следует → **should**; можно → **may** / **can** as context fits. <!-- i18n-keep: E5 -->
+
+## Translation order
+
+1. **Core** — `presets/_shared/core/**` (no `<!-- shared-core -->` markers in core files).
+2. **Embeds** — update all `<!-- shared-core: … -->` consumers to match EN core bodies (same PR as core when possible); `scripts/sync-shared-core-embeds.sh` for EMBED-mode stems.
+3. **Cursor SoT** — `presets/cursor/<stack>/` rule/agent/skill/command bodies.
+4. **Claude twin** — `presets/claude/<stack>/` equivalent semantics **same PR** (`preset-twin-sync`).
+5. **Dogfood sync** — `packages/ai-rules/scripts/sync-dogfood-cursor.sh` after Cursor SoT changes in this monorepo.
+
+Also: `check-shared-core-drift.sh` for embed-mode stems; stack README mapping tables when stems move; `check-preset-i18n` via `check-preset-structure` / CI.
+
+## Related
+
+- Contribution workflow: [`PRESET-CONTRIBUTION.md`](./PRESET-CONTRIBUTION.md)
+- Meta rules: `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`

package/docs/specs/INDEX.md

@@ -0,0 +1,9 @@
+# Product specs INDEX
+
+Discovery table for `docs/specs/**`. Agents start here when the file exists.
+
+| id | type | domain | title | path | routes | aliases | status |
+|----|------|--------|-------|------|--------|---------|--------|
+| <!-- example-row: example-page | page | example | Example page | docs/specs/domains/example/example-page.md | /example | ExamplePage | draft --> |
+
+<!-- Add one row per page/feature spec. Keep `id` and `path` in sync with frontmatter. -->

package/docs/specs/_templates/feature.md

@@ -0,0 +1,32 @@
+---
+id: example-feature
+type: feature
+domain: example
+routes: []
+ui: []
+store: []
+api: []
+aliases: []
+e2e: []
+status: draft
+owners: []
+related: []
+---
+
+# Example feature
+
+## Overview
+
+Cross-page shared behavior for this domain. Prefer `type: feature` on backend/MCP stacks.
+
+## Shared behavior / constraints
+
+- Invariants that apply across related pages/tools.
+
+## Related pages
+
+- Link page specs in this domain (or N/A).
+
+## Cross-cutting states
+
+N/A

package/docs/specs/_templates/page.md

@@ -0,0 +1,47 @@
+---
+id: example-page
+type: page
+domain: example
+routes: []
+ui: []
+store: []
+api: []
+aliases: []
+e2e: []
+status: draft
+owners: []
+related: []
+---
+
+# Example page
+
+## Overview
+
+Short product behavior summary. Replace placeholders from brief AC / user / labeled sources.
+
+## Entry / actors
+
+Who enters this page and from where.
+
+## Primary flows
+
+1. Happy path steps.
+
+## States
+
+- Loading: …
+- Empty: …
+- Error: …
+- Success: …
+
+## Acceptance criteria
+
+- [ ] Link or restated AC from brief / product source.
+
+## Edge cases
+
+N/A
+
+## Related specs
+
+- (optional feature.md or sibling page ids)