@bonesofspring/ai-rules 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -2,12 +2,74 @@
 
 ## Unreleased
 
+### Review follow-ups (core sharing / structure)
+
+- **Shared-core drift is a hard gate** in `check:preset-structure` / CI (`AI_RULES_DRIFT_FAIL=1`).
+- **build-verifier** agents (next/ios-swift/go/java × Cursor+Claude): twin / REPO_AGENTS / react-performance gates list all four stacks.
+- **Leakage core DRY:** merged go+java forbidden blocks in `meta/preset-no-cross-stack-leakage` (+8 embed adapters).
+- **ios-swift session-start:** trimmed `ios-app-core` toward stretch ≤100 body sum.
+- **Docs:** leakage soft-WARN baseline + drift hardgate in `PRESET-CONTRIBUTION.md`; go/java `feature-full` fixtures drop Playwright/XCUITest skipped noise.
+
+### Java preset
+
+- New installable preset **`java`** (Cursor + Claude twins): Spring Boot hexagonal default, layer-first single-module layout, Context7-only MCP, Maven/Gradle detection via `java-tooling` / `post-change-test`.
+- Full mapped rule catalog (~32 stems); always-on trio `java-app-core`, `architecture-boundaries`, `code-quality-and-refactoring` (≤120 body lines).
+- Agent-team surface: 21 agents, 8 skills, 5 commands, hooks + team fixtures; `integration-test-*` (no Playwright/XCUITest/a11y).
+- Structure scripts (`twin-map`, `token-budget`, `leakage`) include `java`; meta cores list four stacks (8 adapters per embed stem).
+- Install: `npx @bonesofspring/ai-rules init cursor|claude --preset java`.
+- Platform asymmetry: `BUGBOT.md` + `hooks.json` Cursor-only; `CLAUDE.md` Claude-only.
+
+### 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`).
+- **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/**shared-core drift** (`AI_RULES_DRIFT_FAIL=1` in structure orchestrator).
 - **`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).
@@ -19,6 +81,8 @@
 
 ### 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).

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,24 @@ 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), **`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 `..`.
+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), **`go`** (Go backends with hexagonal architecture), and **`java`** (Java / Spring Boot hexagonal backends). 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
+npx @bonesofspring/ai-rules init cursor --preset java
+npx @bonesofspring/ai-rules init claude --preset java
 ```
 
 Help: `ai-rules --help`.
@@ -65,8 +72,9 @@ Presets are developed in this monorepo under `presets/`. If you add or change ru
 
 - **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`
+- **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, shared-core drift (`AI_RULES_DRIFT_FAIL=1`)
+- **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,8 +61,10 @@ 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:
@@ -66,9 +72,11 @@ Examples:
   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 cursor --preset java
   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 init claude --preset java
   npx @bonesofspring/ai-rules clean cursor
 `);
 }
@@ -255,6 +263,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;
 }
 
@@ -386,6 +399,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}`);
@@ -444,6 +468,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.6",
+  "version": "0.2.8",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -29,7 +29,8 @@
     "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: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

@@ -1,6 +1,6 @@
 # Shared preset core (`presets/_shared`)
 
-Stack-agnostic **prose and checklists** for all installable presets: `next`, `ios-swift`, and `go` (`cursor/<stack>`, `claude/<stack>`).
+Stack-agnostic **prose and checklists** for all installable presets: `next`, `ios-swift`, `go`, and `java` (`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.
 

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

@@ -4,6 +4,6 @@ When the user message looks like a **work request** (implement, add, fix, refact
 
 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`.
+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

@@ -126,7 +126,7 @@ If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed p
 
 Do **not** run `/task` + router for:
 
-- Pure questions («как работает X», «объясни»).
+- 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.

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

@@ -22,6 +22,18 @@
 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.

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

@@ -13,7 +13,7 @@
 ## Куда класть новое правило
 
 1. Общие принципы для всех стеков → **core** + адаптеры с `<!-- shared-core: … -->`.
-2. Только один из installable стеков (`next` / `ios-swift` / `go`) → **stack-specific** (не в `_shared`).
+2. Только один из installable стеков (`next` / `ios-swift` / `go` / `java`) → **stack-specific** (не в `_shared`).
 3. Только Cursor или только Claude packaging → platform artifact / frontmatter, не дублировать семантику.
 
 ## SoT

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

@@ -6,7 +6,7 @@
 
 - `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.
+- `go` / `java` 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)
@@ -24,14 +24,16 @@ Required instead: `xcuitest-test-*` stems; build-verifier mentions `xcodebuild`
 - `xcuitest-test-` as handoff stems
 - Requiring `xcodebuild` / SwiftLint as the default post-change gate for Next app work
 
-## Forbidden in go hooks/agents (FAIL)
+## Forbidden in go / java hooks/agents (FAIL)
+
+Shared backend-stack bans (both `go` and `java`):
 
 - `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`).
+Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`) or `java-tooling` (`mvn test` / `./gradlew test`).
 
 ## Soft / document
 
@@ -40,4 +42,4 @@ Required instead: `integration-test-*`; build-verifier / `post-change-test` / `g
 
 ## Chain fork
 
-`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, and `go` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, `go`, and `java` (per platform).

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

@@ -6,7 +6,7 @@
 
 - [ ] **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`)
+- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, ios-swift, go, and java — см. `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`)

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

@@ -9,6 +9,7 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 | `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` |
+| `java` | `presets/cursor/java/rules/*.mdc` | `presets/claude/java/rules/<topic>/` | Keep in `claude/java/rules/README.md` |
 
 ## Same-PR checklist
 
@@ -27,5 +28,6 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 - **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).
+- **java:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go; 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

@@ -55,4 +55,15 @@
 - **Boy scout rule:** оставлять модуль немного лучше, чем до изменения (простые, безопасные улучшения).
 - Не жертвовать архитектурой и слоями ради краткости реализации.
 
+## Agent discipline (anti-sycophancy)
+
+- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent) and surface uncertainty; never invent signatures.
+- Before «is this correct?» — list ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
+- Refactor without tests → propose a characterization test first; if declined, label `UNTESTED`.
+- Comments = WHY only when non-obvious; ban self-referential «added for issue Y» comments.
+- Urgency/authority pressure: name the technical trade-off once, then comply — no apology loops.
+- Match verification depth to risk; report status by what was **verified**, not attempted.
+
+Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**; do not invent a parallel style bible in this core body.
+
 > Stack-specific lint gates, примеры и toolchain — в секции **Stack notes** адаптера пресета.

package/presets/_shared/core/review/code-review-mr.md

@@ -27,3 +27,12 @@ Concrete rule stems — in **Stack notes**.
 - Use local `git diff` — do not invent hosting metadata.
 - Boy scout rule: suggest fixes feasible within the MR scope.
 - No «большие рефакторинги» without an explicit request (`code-quality-and-refactoring`).
+
+## Output contract
+
+Procedure details live in skill `code-review`. Required shape:
+
+- Each finding cites **`path:line`**, the problem, impact, and a concrete fix direction.
+- Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
+- End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.

package/presets/claude/go/CLAUDE.md

@@ -2,9 +2,13 @@
 
 Preset for Go backends using ports & adapters.
 
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root.
+
 - Session-start: `go-app-core`, `architecture/boundaries`, `code-quality` (exactly 3).
 - Delivery: `architecture/feature-delivery.md` + skill `feature-delivery`.
 - After Go edits: `tooling-and-review/post-change-test.md`.
 - Integration tests: agents `integration-test-*` (never Playwright/XCUITest).
+- ADR: skill `write-adr` (on-demand).
+- How does X work: agent `codebase-analyzer` (explain-as-is; no `/task`).
 
-Init: `npx @bonesofspring/ai-rules init claude --preset go`
+Init: `npx @bonesofspring/ai-rules init claude --preset go` (also copies `REPO_AGENTS.md` → root `AGENTS.md`).

package/presets/claude/go/README.md

@@ -12,7 +12,7 @@ npx @bonesofspring/ai-rules init claude --preset go
 |------|------------|
 | `CLAUDE.md` | Thin session entry |
 | `rules/**` | Topic `.md` + `paths:` (session-start = 3) |
-| `agents/**` | **20** ролей |
+| `agents/**` | **21** ролей (+ `codebase-analyzer`) |
 | `skills/**` | **7** skills (в т.ч. `integration-testing`) |
 | `commands/**` | task, task-continue, feature-start/continue, technical-retro |
 | `hooks/**` | guard-shell + chain-team-phases |
@@ -32,3 +32,7 @@ npx @bonesofspring/ai-rules init claude --preset go
 ## Sync with Cursor
 
 SoT = `presets/cursor/go/`. Update this twin **in the same PR** when Cursor changes.
+
+## Cross-tool root AGENTS
+
+`REPO_AGENTS.md` → project-root `AGENTS.md` on init. Living conventions: `team/conventions.md`. Skill `write-adr` on-demand.

package/presets/claude/go/REPO_AGENTS.md

@@ -0,0 +1,48 @@
+# Go — agent instructions
+
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, or other).
+- Tool maps live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` when that tool is installed.
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset go
+npx @bonesofspring/ai-rules init claude --preset go
+```
+
+`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas belong in `team/conventions.md`, not here.
+
+## Commands (test / lint / build)
+
+Prefer hexagonal / ports-and-adapters layout from stack rules (`go-app-core`, `architecture-boundaries`).
+
+| Gate | Typical command |
+|------|-----------------|
+| Test | `go test ./...` (or package-scoped) |
+| Vet | `go vet ./...` |
+| Lint | **golangci-lint** when configured |
+| Format | `gofmt` / `goimports` |
+
+After code edits: invoke **`post-change-test`** (requestable). Full gate: agent `build-verifier`.
+
+## Security basics
+
+- Do not commit secrets (tokens, `.env`, private keys).
+- Review destructive git before running; respect shell hooks.
+- Do not weaken CI or skip hooks unless the user explicitly asks.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
+
+Rules: `.cursor/rules/` or `.claude/rules/`. Skills: `.cursor/skills/` or `.claude/skills/`.
+
+## Living conventions
+
+Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`** and/or **`.claude/team/conventions.md`** (fill after init).

package/presets/claude/go/agents/README.md

@@ -1,8 +1,19 @@
 # `.claude/agents` (preset go)
 
+Ролевые subagents для командного пайплайна Claude Code (Go hexagonal).
+
+## Analysis (on-demand)
+
+| Agent | Файл | Production-код |
+|-------|------|----------------|
+| Codebase analyzer | `codebase-analyzer.md` | no (explain-as-is only) |
+
+## Roster (21)
+
 | Agent | Production writes |
 |-------|-------------------|
 | task-router, task-analyst, solution-architect | team only |
+| codebase-analyzer | no (explain-as-is only) |
 | feature-developer | yes (Go sources) |
 | build-verifier | no (report only) |
 | debugger, ci-investigator | minimal |
@@ -10,6 +21,12 @@
 | migration-specialist, api-contract-reviewer, tech-writer | team / docs |
 | qa-tester, unit-test-*, integration-test-* | tests |
 
-**Roster:** 20 agents. **No** `accessibility-reviewer`, Playwright, or XCUITest stems.
+**No** `accessibility-reviewer`, Playwright, or XCUITest stems. Replace those intents with **`integration-test-*`**.
+
+## Model matrix
 
-Replace Playwright/XCUITest intents with **`integration-test-*`**.
+| Tier | Agents |
+|------|--------|
+| **cheap** | router, analyst, build-verifier, code-reviewer, tech-writer, codebase-analyzer |
+| **standard** | developer, debugger, ci-investigator, api-contract, qa, unit-*, integration-* |
+| **strong** | solution-architect, migration-specialist, security-reviewer, performance-auditor |

package/presets/claude/go/agents/build-verifier.md

@@ -25,6 +25,11 @@ From `packages/ai-rules/`:
 yarn check:preset-structure
 ```
 
-Hard gates: twin-map (stacks include **go**), token-budget (alwaysApply/session-start = 3), leakage (`GO_FORBIDDEN_*`, chain forks go≠next≠ios-swift).
+Hard gates: twin-map (stacks include **go**), token-budget (alwaysApply/session-start = 3), leakage (`GO_FORBIDDEN_*`, chain forks go≠next≠ios-swift≠java), shared-core drift (`AI_RULES_DRIFT_FAIL=1` via `check:preset-structure`).
 
 Document PASS/FAIL in `validation-report.md`.
+
+1. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go|java`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
+2. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
+3. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, and java → **FAIL** (leakage). Prefer `check:preset-leakage`.
+4. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.

package/presets/claude/go/agents/codebase-analyzer.md

@@ -0,0 +1,28 @@
+---
+name: codebase-analyzer
+description: Explains HOW existing Go code works as-is. Use when the user asks how something works, to trace ports/adapters, or document architecture — without suggesting changes. Prefer over /task for pure questions.
+readonly: false
+model: fast
+---
+
+You are a specialist at understanding HOW this Go hexagonal service works. Document implementation details with precise `path:line` references.
+
+## CRITICAL — explain as-is only
+
+- DO NOT suggest improvements, refactors, or "better approaches" unless the user explicitly asks.
+- DO NOT perform root-cause analysis or bug hunts unless asked.
+- DO NOT critique quality, performance, or security unless asked.
+- ONLY describe what exists, how it works, and how components interact.
+
+## Workflow
+
+1. Start from entry points the user named (`cmd/`, handlers, use cases, ports).
+2. Trace domain → application/ports → adapters → composition root as applicable.
+3. Summarize: purpose, flow, port contracts, adapter placement, conventions observed.
+4. End with open questions only if facts are missing — not with a wishlist of changes.
+
+## Will / Will not
+
+**Will:** map packages, call chains, ports/adapters as they exist today.
+
+**Will not:** edit production code; open `/task` pipelines; propose PRs or refactors unprompted; require Next/iOS gates.

package/presets/claude/go/agents/feature-developer.md

@@ -19,6 +19,19 @@ Implement Go features following hexagonal boundaries.
 - **Don't** import frameworks into domain; don't use SQL in use cases.
 - **Don't** require Playwright, XCUITest, or yarn lint gates.
 
+## Zero improvisation
+
+- Implement **only** what the brief / AC / current decomposition task require.
+- If requirements are ambiguous, conflicting, or multi-way — **ask** before coding; do not guess extras as "best practices".
+- Forbidden without explicit AC/task: unrelated security hardening, extra validation, observability, drive-by refactors, new config/env.
+- Boy scout / `design-guidance` improvements stay **within** touched files and must not expand task scope.
+
+## Will / Will not
+
+**Will:** follow hexagonal order; add required tests; run `post-change-test` (+ `go-tooling`); update task artifacts.
+
+**Will not:** formal code review; invent AC; pull Next/iOS gates; auto-continue the next WP when the pipeline expects a human gate or handoff.
+
 ## Preset packaging
 
 When editing ai-rules `presets/**/go/**`, keep Cursor/Claude twins in sync and preserve chain fork ≠ next/ios-swift.

package/presets/claude/go/hooks/README.md

@@ -8,3 +8,9 @@
 Claude Code may not use Cursor `hooks.json`. Wire scripts per project docs when enabling agent-team auto-chain.
 
 **No `hooks.json` in Claude preset** (platform limit — same as next Claude).
+
+## Optional cookbook
+
+Example scripts live in `hooks/examples/` (secret-guard, format-edited, test-on-save). They are **not** auto-enabled.
+
+To wire in Claude Code: copy an `.example.sh` into `hooks/`, make executable, and register per [Claude Code hooks](https://code.claude.com/docs/en/hooks) for your project. Keep stack-safe recipes (this preset: **go**). Cursor twin examples under `presets/cursor/go/hooks/examples/` are the same allowlist forks.

package/presets/claude/go/hooks/examples/README.md

@@ -0,0 +1,18 @@
+# Hooks cookbook (examples)
+
+Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks.json` (only `guard-shell-command.sh` + `chain-team-phases.sh`).
+
+| Script | Purpose |
+|--------|---------|
+| `secret-guard.example.sh` | Fail if staged diff looks like secrets |
+| `format-edited.example.sh` | Stack formatter / linter on edited files |
+| `test-on-save.example.sh` | Scoped tests for the stack |
+
+## Wiring (Cursor)
+
+1. Copy an example into `hooks/` (drop `.example` suffix), e.g. `cp hooks/examples/secret-guard.example.sh hooks/secret-guard.sh`.
+2. `chmod +x hooks/secret-guard.sh`.
+3. Add a hook entry in `.cursor/hooks.json` (e.g. `beforeShellExecution` or `afterFileEdit` — see Cursor hooks docs).
+4. Keep cookbook scripts **out** of the default preset `hooks.json` when contributing back upstream.
+
+Stack: **go** — recipes must stay stack-safe (no cross-stack lint/test commands).

package/presets/claude/go/hooks/examples/format-edited.example.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Optional: gofmt / golangci-lint on edited packages.
+# NOT in default hooks.json.
+set -euo pipefail
+gofmt -w $(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.go$' || true) 2>/dev/null || true
+if command -v golangci-lint >/dev/null 2>&1; then
+  golangci-lint run ./... 2>/dev/null || true
+fi
+exit 0

package/presets/claude/go/hooks/examples/secret-guard.example.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Optional cookbook: block committing likely secrets in staged diffs.
+# NOT wired in default hooks.json — copy to hooks/ and register manually.
+set -euo pipefail
+PATTERN='(AKIA[0-9A-Z]{16}|-----BEGIN (RSA |OPENSSH )?PRIVATE KEY-----|api[_-]?key\s*[:=]\s*['\''\"][^'\''\"]{12,})'
+if git diff --cached -U0 2>/dev/null | grep -Eiq "$PATTERN"; then
+  echo "secret-guard: possible secret in staged diff — review before commit" >&2
+  exit 1
+fi
+exit 0