@bonesofspring/ai-rules 0.2.6 → 0.2.8

package/presets/claude/java/rules/architecture/ports-interfaces.md

@@ -0,0 +1,34 @@
+---
+description: Inbound and outbound port interfaces for Java hexagonal services
+paths:
+  - "**/ports/**/*"
+  - "application/**/*port*"
+  - "**/application/**/*port*"
+---
+
+# Ports (interfaces)
+
+## Outbound (driven)
+
+- Repository, cache, publisher, clock, ID generator, external client — defined by **application** (owner of the need).
+- Signatures use **domain** types (or small application DTOs), never JPA `@Entity`, JDBC `ResultSet`, or broker message types.
+- Keep interfaces small (ISP); prefer role interfaces over god-repos (`OrderRepository` vs `EverythingRepository`).
+- Do not put Spring Data / JPA repository interfaces in domain; if Spring Data is used, it stays in the outbound adapter and implements (or is wrapped by) the application port.
+
+## Inbound (driving)
+
+- Optional interface wrapping use cases for multiple drivers (HTTP + gRPC + CLI + messaging consumer).
+- Drivers depend on inbound ports / use-case APIs — not on each other.
+- Prefer a concrete use-case class when only one driver exists; extract an interface when a second driver appears (Rule of Three / YAGNI).
+
+## Naming
+
+- `saveOrder`, `findOrderById`, `publishOrderPlaced` — verb-oriented; match neighboring package style.
+- Implementation types live in adapters (`JpaOrderRepository`, `JdbcOrderRepository`), not beside the interface in domain.
+
+## Anti-patterns
+
+- Ports returning untyped `Map<String, Object>`, raw `JsonNode`, or framework entities.
+- Putting port interfaces inside adapter packages (wrong owner — adapters implement, application defines).
+- Leakage of `EntityManager`, `@Entity`, `JdbcTemplate`, or Redis types through port method signatures.
+- One mega-port “for convenience” that every use case depends on.

package/presets/claude/java/rules/architecture/reference-features.md

@@ -0,0 +1,34 @@
+---
+description: Reference paths for Java hexagonal layout (fill after init)
+paths:
+  - "src/main/java/**/*"
+  - "**/configuration/**"
+  - "**/*Application.java"
+---
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features (Java)
+
+Fill concrete paths after adopting this preset in a real service repo. Defaults below match layer-first single-module; adjust for feature-first / multi-module variants.
+
+| Area | Example path | Glob hint |
+|------|--------------|-----------|
+| Domain | `src/main/java/<base>/domain/` | `**/domain/**` |
+| Application / ports | `src/main/java/<base>/application/` | `**/application/**` |
+| HTTP adapter | `src/main/java/<base>/adapters/inbound/http/` | `**/adapters/inbound/http/**`, `**/adapters/http/**` |
+| Persistence | `src/main/java/<base>/adapters/outbound/persistence/` | `**/adapters/outbound/persistence/**`, `**/adapters/persistence/**` |
+| Composition root | `…/configuration/`, `*Application.java` | `**/configuration/**`, `**/*Application.java` |
+| Unit tests | `src/test/java/**/*Test.java` | `**/*Test.java`, `**/src/test/java/**` |
+| Integration | `*IT.java` / `*IntegrationTest.java` | `**/*IT.java`, `**/integration/**` |
+
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.cursor/team/conventions.md`** (and the twin tool path if both Cursor and Claude are installed). Consumer-owned; not always-on. See root `AGENTS.md` § Living conventions.
+
+## Dogfood scenarios
+
+1. `/task` new use case — domain → ports → adapters → wire → `post-change-test`.
+2. Bug in handler mapping — debugger + MockMvc / controller unit.
+3. Repository contract — integration-test trio + Testcontainers.
+4. OpenAPI/proto drift — api-contract-reviewer.
+5. Secrets in logs — security-reviewer + `security-java`.

package/presets/claude/java/rules/stack/README.md

@@ -0,0 +1,10 @@
+# Stack
+
+Язык, платформа и базовый каркас сервиса. Index only — тела в topic `.md`.
+
+| File | Cursor SoT |
+|------|------------|
+| [`java-app-core.md`](./java-app-core.md) | `java-app-core.mdc` |
+| [`java-conventions.md`](./java-conventions.md) | `java-conventions.mdc` |
+
+Sync: change Cursor → update Claude twin same PR. Full map: [`../README.md`](../README.md).

package/presets/claude/java/rules/stack/java-app-core.md

@@ -0,0 +1,32 @@
+---
+description: Java/Spring Boot hexagonal stack, module layout, and agent entry points
+---
+
+
+# Стек и окружение
+
+Версии JDK, Spring Boot и зависимостей — **из `pom.xml` / `build.gradle(.kts)` целевого репозитория**. Рамка preset:
+
+- **Язык / платформа:** Java (Maven или Gradle; wrappers `./mvnw` / `./gradlew` предпочтительны).
+- **Default:** Spring Boot **hexagonal** (ports & adapters); domain не знает Spring/JPA/HTTP.
+- **Variants (documented):** plain Java, Quarkus, Micronaut, Jakarta EE — те же границы пакетов.
+- **Layout default:** layer-first single-module; multi-module — documented variant.
+- **Тесты:** JUnit 5 + AssertJ; integration — Testcontainers; REST Assured — optional smoke.
+- **HTTP:** Spring MVC / Jakarta at the edge (примеры, не жёсткий мандат framework).
+- **Static analysis:** discover from repo/CI — do not mandate Checkstyle/SpotBugs/Error Prone.
+
+# Структура (default: layer-first)
+
+```text
+src/main/java/<base>/
+  domain/
+  application/                 # use cases + ports
+  adapters/inbound/http/
+  adapters/outbound/persistence|messaging|external/
+  configuration/               # Spring @Configuration / plain composition
+src/test/java/<base>/
+```
+
+**Feature-first variant:** `<feature>/{domain,application,adapters}` — same dependency direction.
+
+Границы — **`architecture/boundaries.md`**. Tooling — requestable **`tooling-and-review/java-tooling.md`**. После правок Java — **`tooling-and-review/post-change-test.md`**.

package/presets/claude/java/rules/stack/java-conventions.md

@@ -0,0 +1,52 @@
+---
+description: Idiomatic Java conventions for this hexagonal preset
+paths:
+  - "**/*.java"
+---
+
+# Java conventions
+
+- Follow Effective Java and the repository's formatter / static-analysis config when present.
+- Prefer `record` / immutable value types for DTOs and domain VOs when the repo already uses them.
+- Naming: `PascalCase` types, `camelCase` methods/fields, lowercase package segments; match neighboring packages.
+- Prefer package-private by default; expose only what other modules need via public types.
+- Prefer parameterized JUnit 5 tests (`@ParameterizedTest`) when covering multiple cases.
+- Do not invent library APIs — verify symbols against `pom.xml` / `build.gradle(.kts)` and existing imports (`// VERIFY:` when unsure).
+
+## Errors / exceptions
+
+- Prefer unchecked exceptions (`RuntimeException` subtypes) for domain/application failures unless the repo's public API requires checked exceptions.
+- Chain causes (`new X(msg, cause)`); never empty-catch without logging or rethrowing.
+- Prefer domain-specific exception types for structured cases; avoid broad `catch (Exception)`.
+- Map to HTTP/gRPC statuses only in adapters — do not throw `ResponseStatusException` from domain.
+
+## Interfaces / ports
+
+- Depend on interfaces (ports) at the call site; return concrete types from factories when simple.
+- Keep interfaces small (ISP); define ports in application, not on every adapter class «just in case».
+
+## Packages
+
+- Avoid `util`/`common` dumping grounds — name by domain capability.
+- Keep `@SpringBootApplication` / configuration / `main` thin (see `composition-root`).
+- No static mutable request state; no business logic in static initializers.
+
+## Concurrency
+
+- Prefer executor / structured patterns already used in the repo; document cancellation (interrupt, reactive cancel, request-scoped cancel).
+- Do not start unbounded threads/executors from handlers without a shutdown/supervision story.
+- Match existing package patterns for locks / concurrent collections — do not invent frameworks.
+
+## Anti-hallucination
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Empty `catch` / ignored failures | Handle, wrap with cause, or declare |
+| Interfaces on every class «just in case» | Ports at consumer / call site |
+| Invented modules not in `pom.xml` / `build.gradle` | Add dependency explicitly or copy existing import |
+| Raw `Object` / untyped `Map` where a typed type fits | Generics / records / domain types used by the repo |
+| Business logic in static initializers | Wire in composition root / Spring config |
+
+## Agent requirement
+
+New Java code must stay idiomatic and verifiable against `pom.xml` / `build.gradle` and neighboring packages. Less guessed code is better than more.

package/presets/claude/java/rules/testing/README.md

@@ -0,0 +1,11 @@
+# Testing
+
+Unit, integration, e2e smoke. Index only.
+
+| File | Cursor SoT |
+|------|------------|
+| [`unit.md`](./unit.md) | `tests-unit.mdc` |
+| [`integration.md`](./integration.md) | `tests-integration.mdc` |
+| [`e2e.md`](./e2e.md) | `tests-e2e.mdc` |
+
+Full map: [`../README.md`](../README.md).

package/presets/claude/java/rules/testing/e2e.md

@@ -0,0 +1,22 @@
+---
+description: End-to-end HTTP smoke tests for Java services (optional)
+paths:
+  - "**/e2e/**/*.java"
+  - "**/*E2ETest.java"
+  - "**/*SmokeTest.java"
+---
+
+# E2E / HTTP smoke (optional)
+
+> Prefer **`tests-integration`** + `integration-test-*` for adapter contracts. E2E smoke is optional breadth — do not build a browser suite.
+
+- Black-box against a running server (`@SpringBootTest` + Testcontainers with full composition root, or localhost in CI).
+- Cover critical paths only; prefer integration + unit for breadth.
+- REST Assured / WebTestClient are optional HTTP smoke tools when already in the repo — not a mandated framework.
+- Stable test data; avoid depending on wall-clock flakiness.
+- Do **not** use browser/Playwright/XCUITest tooling in this preset.
+
+## Placement
+
+- `e2e/` package or `*E2ETest.java` / `*SmokeTest.java` under `src/test/java` if the repo separates smoke jobs.
+- Keep Failsafe/Gradle smoke tags honest — do not mark unit tests as e2e.

package/presets/claude/java/rules/testing/integration.md

@@ -0,0 +1,27 @@
+---
+description: Integration / adapter contract tests for Java hexagonal services
+paths:
+  - "**/*IT.java"
+  - "**/*IntegrationTest.java"
+  - "**/integration/**"
+  - "**/src/test/java/**/*IT.java"
+---
+
+# Integration tests
+
+- Exercise driven adapters against real infra doubles (**Testcontainers**, docker compose test DB, WireMock, etc.).
+- Or exercise HTTP adapter with `MockMvc` / WebTestClient / Spring Boot **test slices** + wired use case + fake/real ports — still no full prod cluster required.
+- Use Surefire/Failsafe (or Gradle test filters) if the repo separates CI unit vs integration jobs.
+- Keep fixtures deterministic; clean up data between tests.
+- Prefer testing through the **port implementation** (save/load roundtrip) over asserting on private JPA internals.
+
+## Scope
+
+- Contract of a port implementation (repo save/load, outbound client mapping).
+- Not a substitute for domain unit tests.
+- Full `@SpringBootTest` only when slices cannot prove the contract.
+
+## Agents
+
+- Planning/generation: `integration-test-{planner,generator,healer}` + skill `integration-testing` (Phase C surface).
+- Prefer integration-test agents over inventing browser e2e for backend contracts.

package/presets/claude/java/rules/testing/unit.md

@@ -0,0 +1,33 @@
+---
+description: Unit testing conventions for Java hexagonal services
+paths:
+  - "**/*Test.java"
+  - "**/*Tests.java"
+  - "**/src/test/java/**"
+---
+
+# Unit tests
+
+- Prefer **JUnit 5**; clear arrange/act/assert (or Given/When/Then).
+- Domain and application: mock/fake **ports** only — no real DB/network.
+- Prefer fakes over heavy mocking when simple; **Mockito** is optional when the repo already uses it.
+- Prefer **AssertJ** fluent assertions when already on the classpath; otherwise JUnit assertions are fine.
+- Skip integration/e2e files matching `*IT.java`, `*IntegrationTest.java`, `*E2ETest.java`, `*SmokeTest.java`, or dirs `integration/`, `e2e/` — those use other rules.
+
+## Scope
+
+- Domain factories/invariants; application use cases with port fakes; pure mappers.
+- Adapter unit tests may use `MockMvc` + mocked use case — still no live DB.
+
+## Forbidden smells
+
+- `HttpServletRequest` / `ServerHttpRequest` / Spring MVC types in **domain** tests.
+- SQL or live HTTP in use-case unit tests.
+- Brittle tests on package-private adapter internals without need.
+- Loading a full `@SpringBootTest` for a pure domain/unit case.
+- Structural smells vocabulary (Feature Envy, Message Chains, …): see requestable `design-guidance` — do not duplicate the catalog here.
+
+## Naming
+
+- `UseCaseDoXTest` / `EntityInvariantTest` (or `*Tests` if the repo already uses that suffix).
+- Match Surefire patterns the CI already uses.

package/presets/claude/java/rules/tooling-and-review/README.md

@@ -0,0 +1,21 @@
+# Tooling and review
+
+Качество, review, test gate, security, agent-team, retro, preset meta. Index only.
+
+| File | Cursor SoT |
+|------|------------|
+| [`code-quality.md`](./code-quality.md) | `code-quality-and-refactoring.mdc` |
+| [`code-review.md`](./code-review.md) | `code-review-mr.mdc` |
+| [`post-change-test.md`](./post-change-test.md) | `post-change-test.mdc` |
+| [`java-tooling.md`](./java-tooling.md) | `java-tooling.mdc` |
+| [`security-java.md`](./security-java.md) | `security-java.mdc` |
+| [`agent-team-intake.md`](./agent-team-intake.md) | `agent-team-intake.mdc` |
+| [`agent-team-orchestrator.md`](./agent-team-orchestrator.md) | `agent-team-orchestrator.mdc` |
+| [`technical-retro.md`](./technical-retro.md) | `technical-retro.mdc` |
+| [`preset-layering.md`](./preset-layering.md) | `preset-layering.mdc` |
+| [`preset-twin-sync.md`](./preset-twin-sync.md) | `preset-twin-sync.mdc` |
+| [`preset-token-budget.md`](./preset-token-budget.md) | `preset-token-budget.mdc` |
+| [`preset-pr-checklist.md`](./preset-pr-checklist.md) | `preset-pr-checklist.mdc` |
+| [`preset-no-cross-stack-leakage.md`](./preset-no-cross-stack-leakage.md) | `preset-no-cross-stack-leakage.mdc` |
+
+Sync: change Cursor → update Claude twin same PR. Full map: [`../README.md`](../README.md).

package/presets/claude/java/rules/tooling-and-review/agent-team-intake.md

@@ -0,0 +1,26 @@
+---
+description: Suggest /task for Java backend work requests
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - "**/*.java"
+  - src/main/java/**/*
+  - "**/configuration/**"
+  - "**/*Application.java"
+---
+
+<!-- shared-core: agent-team/agent-team-intake.md -->
+
+# 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.
+
+## Stack notes
+
+- Scope: Java services (`src/main/java/**`, `configuration/`, `*Application.java`) — hexagonal ports/adapters — not Playwright/XCUITest UI flows.

package/presets/claude/java/rules/tooling-and-review/agent-team-orchestrator.md

@@ -0,0 +1,179 @@
+---
+description: Orchestrates the agent team via task-router and pipeline.json for Java presets
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - "**/*.java"
+  - src/main/java/**/*
+  - "**/configuration/**"
+  - "**/*Application.java"
+---
+
+<!-- shared-core: agent-team/agent-team-orchestrator.md -->
+
+# 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` (no `accessibility-reviewer`) |
+| 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**.
+
+## Stack notes
+
+### Roles (Java hexagonal — 21 agents)
+
+| Kind | Agents | Writes |
+|------|--------|--------|
+| Planning | `task-router`, `task-analyst`, `solution-architect` | team only |
+| Analysis | `codebase-analyzer` | explain-as-is only |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` | sources / minimal |
+| Gates | `build-verifier` | `validation-report.md` only |
+| Review | `code-reviewer`, `security-reviewer`, `performance-auditor`, `api-contract-reviewer`, `migration-specialist` | team / plans |
+| Docs | `tech-writer` | docs |
+| Unit tests | `unit-test-{planner,generator,healer}`, `qa-tester` | tests |
+| Integration | `integration-test-{planner,generator,healer}` | adapter/IT tests |
+
+**No** `accessibility-reviewer`, Playwright, or XCUITest. Replace those intents with **`integration-test-*`**.
+
+### Handoffs / gates
+
+- Scope: Java hexagonal (`src/main/java` domain|application|adapters, `configuration/` / `*Application.java`) — not Next `app/src` or iOS `Features/`.
+- After Java code changes, pipeline includes **build-verifier** with `mvn test` / `./gradlew test` + `post-change-test` / `java-tooling` (static analysis only if repo/CI already configures it).
+- Chain hook handoffs: `integration-test-*`, `post-change-test`, `java-tooling` — never `lint:js`, Playwright, XCUITest, or `xcodebuild`.
+- Skills: `feature-delivery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`.

package/presets/claude/java/rules/tooling-and-review/code-quality.md

@@ -0,0 +1,83 @@
+---
+description: Code quality and light refactoring for Java hexagonal services
+---
+
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+
+# Поддержка существующего стиля
+
+- Новые изменения должны:
+  - следовать существующим паттернам (имена, структура, типизация / DI / error handling стека);
+  - минимизировать «стилистический шум» (лишние правки форматирования, rename без нужды).
+- Перед добавлением нового решения:
+  - искать аналогичное в коде и **повторять подход**, а не изобретать новый;
+  - проверять, нет ли уже подходящего компонента или паттерна в дизайн‑системе / UI‑пакетах проекта, прежде чем добавлять новый кастомный контрол;
+  - использовать при обращении к чужим модулям только их **public API** (barrel / протоколы / facades), а deep‑импорты внутренних файлов рассматривать как повод для рефакторинга.
+
+# Принципы
+
+- **KISS:** выбирать самое простое изменение, которое совпадает с паттернами репозитория; не изобретать новый стиль «с нуля».
+- **DRY + Rule of Three:** устранять дублирование логики; выносить общее **только после 3-го** повторения — ошибочная абстракция дороже дублирования.
+- **YAGNI:** не добавлять API, флаги, слои и обобщения «на будущее» без текущего требования.
+- **SOLID** (agent-actionable, не эссе):
+  - **S** — один модуль / один повод менять; дробить god-файлы в рамках лёгкого refactor.
+  - **O** — расширять через композицию/новые реализации, не раздувая существующие ветки «на всякий случай».
+  - **L** — подтип не ломает контракт базового типа/протокола.
+  - **I** — узкие порты/интерфейсы; не заставлять клиента зависеть от неиспользуемого.
+  - **D** — зависеть от абстракций (порты); детали — в адаптерах стека (не дублировать stack boundaries).
+- **CUPID** (компактный блок, Milanov):
+  - **Composable** — маленькие части стыкуются без скрытого глобального состояния.
+  - **Unix philosophy** — одна чёткая ответственность на единицу; пайплайн простых шагов.
+  - **Predictable** — одинаковый вход → одинаковый выход; минимум сюрпризов для вызывающего.
+  - **Idiomatic** — следовать идиомам языка и **существующим** конвенциям репо.
+  - **Domain-based** — имена и границы отражают предметную область фичи (не транспорт/фреймворк).
+- **Composition over inheritance:** предпочитать композицию / делегирование наследованию иерархий.
+- **Law of Demeter (hint):** не строить цепочки `a.b.c.d`; ходить через public API / facade модуля.
+
+# Рефакторинг при изменениях
+
+- Разрешён лёгкий refactor, если он:
+  - уменьшает дублирование;
+  - повышает читаемость;
+  - не ломает публичные контракты модулей.
+- Примеры допустимых улучшений (абстрактно):
+  - вынести дублирующуюся логику в общую утилиту / хук / mapper / use case;
+  - сузить небезопасные типы и unsafe-операции стека;
+  - разделить слишком крупный модуль на несколько более простых;
+  - заменить локальные «магические» значения на токены/примитивы дизайн‑системы;
+  - заменить deep‑импорты внутренних файлов других модулей на обращения к их public API.
+
+# Ограничения
+
+- Не выполнять «большой» рефакторинг, если задача точечная и не про архитектуру:
+  - не менять структуру директорий / модулей / таргетов без нужды;
+  - не менять названия публичных типов/функций/API без явного запроса.
+- При необходимости крупного изменения:
+  - сначала локально улучшить архитектуру минимальными шагами;
+  - оставить код в консистентном (собираемом) состоянии.
+
+# Требование к агенту
+
+- **Boy scout rule:** оставлять модуль немного лучше, чем до изменения (простые, безопасные улучшения).
+- Не жертвовать архитектурой и слоями ради краткости реализации.
+
+## 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** адаптера пресета.
+## Stack notes
+
+- **No UI layer in this preset** — ignore shared-core bullets about дизайн‑система / UI‑пакеты / CSS‑токены; apply public-API and boy-scout rules to Java packages/ports instead.
+- Public API between packages: exported types in module API or explicit ports — avoid deep imports of another feature's internals.
+- Prefer checked/unchecked exceptions with clear translation at adapter edges; do not leak persistence exceptions upward.
+- Interfaces belong at **ports** (consumer side), not on every class; prefer composition over inheritance.
+- Post-change gate: **`post-change-test.mdc`** + **`java-tooling.mdc`** (not yarn lint / xcodebuild / Playwright).
+- Style/static analysis: use **repository/CI** formatter and checks — do not invent a parallel Checkstyle/SpotBugs bible in rules.

package/presets/claude/java/rules/tooling-and-review/code-review.md

@@ -0,0 +1,59 @@
+---
+description: Code review checklist for Java hexagonal merge requests
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - "**/*.java"
+  - src/main/java/**/*
+  - src/test/java/**/*
+  - "**/configuration/**"
+---
+<!-- shared-core: review/code-review-mr.md -->
+
+# Code review merge requests
+
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+## When to load
+
+- User asks for review/MR/diff
+- Pipeline step `code-reviewer`
+- Platform automated review (e.g. BUGBOT) when present
+
+## Checklist references (abstract)
+
+- Architecture layers and stack core rules
+- Public imports / module boundaries
+- UI conventions of the stack
+- Unit and e2e/UI test conventions
+- Post-change lint/build gate before final report
+- Design smells **in MR diff scope** — load `design-guidance`; не разворачивать полный каталог Fowler вне диффа
+- Pattern name (GoF) — только если репозиторий уже использует эту форму или match минимален
+- Principles (KISS / DRY+Ro3 / YAGNI / SOLID / CUPID) — через always-on `code-quality-and-refactoring`, не дублировать эссе в review
+
+Concrete rule stems — in **Stack notes**.
+
+## Constraints
+
+- Focus on MR diff, not the whole repo.
+- 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`**.
+
+## Stack notes
+
+- Hexagonal boundaries: `architecture-boundaries`, `domain-layer`, ports vs adapters; Spring/JPA only at edges.
+- HTTP DTO validation/mapping and persistence entity isolation: `api-http`, `persistence-adapters`.
+- Composition root (`configuration/`, `*Application.java`) has no business logic.
+- Tests: `tests-unit` (JUnit 5), `tests-integration` (Testcontainers); post-change: `post-change-test` / `java-tooling`.
+- Security: secrets/PII/`security-java`; Spring Security config stays out of domain.
+- Never require Playwright, XCUITest, `lint:js`, or `xcodebuild` for Java MRs.