@bonesofspring/ai-rules 0.2.6 → 0.2.8

package/presets/claude/java/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

package/presets/claude/java/hooks/examples/test-on-save.example.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Optional: scoped Maven/Gradle test after Java edits.
+# NOT in default hooks.json. Prefer wrappers when present.
+set -euo pipefail
+changed=$(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.java$' || true)
+if [[ -z "${changed:-}" ]]; then
+  exit 0
+fi
+if [[ -x ./mvnw ]]; then
+  ./mvnw -q test 2>/dev/null || true
+elif [[ -x ./gradlew ]]; then
+  ./gradlew -q test 2>/dev/null || true
+elif [[ -f pom.xml ]]; then
+  mvn -q test 2>/dev/null || true
+elif [[ -f build.gradle || -f build.gradle.kts ]]; then
+  gradle -q test 2>/dev/null || true
+fi
+exit 0

package/presets/claude/java/hooks/guard-shell-command.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Lightweight shell guard for Claude Code projects using this preset.
+# Java: do NOT blanket-block mvn test / ./gradlew test / compiler/IDE inspections / configured static analysis / repo static analysis.
+# Package-manager mismatch checks apply only when a JS lockfile/package.json exists.
+
+set -euo pipefail
+# JAVA_PRESET_GUARD: allow mvn/gradlew test; no Playwright/XCUITest assumptions
+
+input=$(cat)
+
+INPUT="$input" node <<'NODE'
+const fs = require('fs');
+
+const raw = process.env.INPUT || '';
+let event;
+try {
+  event = JSON.parse(raw);
+} catch {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const command = String(event.command || event.input?.command || '');
+if (!command.trim()) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+function out(permission, userMessage, agentMessage) {
+  process.stdout.write(JSON.stringify({
+    permission,
+    user_message: userMessage,
+    agent_message: agentMessage || userMessage,
+  }));
+}
+
+const dangerousGit = /\bgit\s+(reset\s+--hard|clean\s+-[^\n]*f|push\s+--force|push\s+-f|checkout\s+--\s+)/;
+if (dangerousGit.test(command)) {
+  out(
+    'ask',
+    'This command looks destructive for git state. Review it before continuing.',
+    'A project hook flagged a destructive git command. Ask the user before running it.',
+  );
+  process.exit(0);
+}
+
+const managerByFile = [
+  ['yarn.lock', 'yarn'],
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['package-lock.json', 'npm'],
+].find(([file]) => fs.existsSync(file));
+
+let expected = managerByFile?.[1];
+if (!expected && fs.existsSync('package.json')) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    const pm = typeof pkg.packageManager === 'string' ? pkg.packageManager : '';
+    expected = pm.split('@')[0] || undefined;
+  } catch {
+    // Ignore invalid package.json in the hook; the agent can diagnose it later.
+  }
+}
+
+if (!expected) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const used = command.match(/(^|[;&|]\s*)(npm|yarn|pnpm)\s+/)?.[2];
+if (used && used !== expected) {
+  out(
+    'ask',
+    `This repository appears to use ${expected}, but the command uses ${used}. Confirm before continuing.`,
+    `Use ${expected} for package scripts and installs unless the user explicitly approves ${used}.`,
+  );
+  process.exit(0);
+}
+
+process.stdout.write('{ "permission": "allow" }');
+NODE

package/presets/claude/java/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,60 @@
+# `.claude/rules` (preset java)
+
+Claude topic `.md` files are **derived** from Cursor SoT `presets/cursor/java/rules/*.mdc`.
+
+## SoT sync
+
+| Principle | Detail |
+|-----------|--------|
+| **SoT** | `presets/cursor/java/rules/*.mdc` |
+| **Derive** | Claude topic `.md` + `paths:` (drop `alwaysApply`) |
+| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — next, ios-swift, go, and java; see `preset-twin-sync` / build-verifier) |
+
+## Loading budget
+
+- **Session-start (no `paths:`):** exactly **3** — `java-app-core`, `boundaries`, `code-quality`
+- All others — with `paths:`
+- **Twin depth:** domain rules target ≥15 body lines; thin aliases: `agent-team-intake`, `technical-retro`; **documented stubs** (v1): `api-grpc`, `messaging-adapters` — see Cursor `presets/cursor/java/rules/README.md` Catalog (Depth column)
+
+## Cursor → Claude mapping
+
+| Cursor `.mdc` (SoT) | Claude topic |
+|---------------------|--------------|
+| `adapters-driven.mdc` | `api-and-data/adapters-driven.md` |
+| `adapters-driving.mdc` | `api-and-data/adapters-driving.md` |
+| `agent-team-intake.mdc` | `tooling-and-review/agent-team-intake.md` |
+| `agent-team-orchestrator.mdc` | `tooling-and-review/agent-team-orchestrator.md` |
+| `api-grpc.mdc` | `api-and-data/api-grpc.md` |
+| `api-http.mdc` | `api-and-data/api-http.md` |
+| `application-usecases.mdc` | `architecture/application-usecases.md` |
+| `architecture-boundaries.mdc` | `architecture/boundaries.md` |
+| `code-quality-and-refactoring.mdc` | `tooling-and-review/code-quality.md` |
+| `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |
+| `code-review-mr.mdc` | `tooling-and-review/code-review.md` |
+| `composition-root.mdc` | `architecture/composition-root.md` |
+| `domain-layer.mdc` | `architecture/domain-layer.md` |
+| `feature-delivery-workflow.mdc` | `architecture/feature-delivery.md` |
+| `java-app-core.mdc` | `stack/java-app-core.md` |
+| `java-conventions.mdc` | `stack/java-conventions.md` |
+| `java-tooling.mdc` | `tooling-and-review/java-tooling.md` |
+| `messaging-adapters.mdc` | `api-and-data/messaging-adapters.md` |
+| `module-public-api.mdc` | `architecture/module-public-api.md` |
+| `persistence-adapters.mdc` | `api-and-data/persistence-adapters.md` |
+| `ports-interfaces.mdc` | `architecture/ports-interfaces.md` |
+| `post-change-test.mdc` | `tooling-and-review/post-change-test.md` |
+| `preset-layering.mdc` | `tooling-and-review/preset-layering.md` |
+| `preset-no-cross-stack-leakage.mdc` | `tooling-and-review/preset-no-cross-stack-leakage.md` |
+| `preset-pr-checklist.mdc` | `tooling-and-review/preset-pr-checklist.md` |
+| `preset-token-budget.mdc` | `tooling-and-review/preset-token-budget.md` |
+| `preset-twin-sync.mdc` | `tooling-and-review/preset-twin-sync.md` |
+| `reference-features.mdc` | `architecture/reference-features.md` |
+| `security-java.mdc` | `tooling-and-review/security-java.md` |
+| `technical-retro.mdc` | `tooling-and-review/technical-retro.md` |
+| `tests-e2e.mdc` | `testing/e2e.md` |
+| `tests-integration.mdc` | `testing/integration.md` |
+| `tests-unit.mdc` | `testing/unit.md` |
+
+## Topics
+
+`architecture/`, `stack/`, `api-and-data/`, `testing/`, `tooling-and-review/`.  
+`ui-and-accessibility/` — README stub only (N/A backend).

package/presets/claude/java/rules/api-and-data/README.md

@@ -0,0 +1,14 @@
+# API and data
+
+Driving/driven adapters. Index only.
+
+| File | Cursor SoT |
+|------|------------|
+| [`adapters-driving.md`](./adapters-driving.md) | `adapters-driving.mdc` |
+| [`adapters-driven.md`](./adapters-driven.md) | `adapters-driven.mdc` |
+| [`api-http.md`](./api-http.md) | `api-http.mdc` |
+| [`api-grpc.md`](./api-grpc.md) | `api-grpc.mdc` |
+| [`persistence-adapters.md`](./persistence-adapters.md) | `persistence-adapters.mdc` |
+| [`messaging-adapters.md`](./messaging-adapters.md) | `messaging-adapters.mdc` |
+
+Full map: [`../README.md`](../README.md).

package/presets/claude/java/rules/api-and-data/adapters-driven.md

@@ -0,0 +1,38 @@
+---
+description: Driven adapters (persistence, cache, messaging) for Java hexagonal services
+paths:
+  - "**/adapters/outbound/**/*"
+  - "**/adapters/persistence/**/*"
+  - "**/adapters/cache/**/*"
+  - "**/adapters/messaging/**/*"
+---
+
+# Driven adapters
+
+- Implement application **outbound ports**.
+- Map storage/broker models → domain at the boundary; never return JPA entities or JDBC rows to application.
+- Handle retries/timeouts/idempotency here when infrastructure-specific.
+- Wrap driver/ORM exceptions with context; translate to domain/application errors when meaningful.
+- Honor timeouts/cancellation from the application call when the client API supports them.
+
+## Layout
+
+Default: `adapters/outbound/persistence|messaging|external|cache/`. Flat `adapters/persistence/` etc. remains valid when already used.
+
+## Persistence
+
+- See `persistence-adapters.mdc` for JPA/JDBC/transactions.
+- Keep SQL/JPQL/query builders inside the adapter package; application sees only port methods.
+
+## Cache / messaging / external HTTP
+
+- Cache keys and serialization are adapter concerns.
+- Publishers implement port `publishX`; consumers that trigger use cases are **driving** adapters.
+- Prefer idempotent publish/consume when brokers may redeliver (see stub `messaging-adapters`).
+- Outbound HTTP clients: per-provider timeouts/pools — do not share one god-client for every vendor.
+
+## Forbidden
+
+- Calling other driven adapters bypassing application (hidden coupling).
+- Leaking `Entity`, `ResultSet`, Redis/Jedis, or Kafka client types through port signatures.
+- Embedding business invariants that belong in domain (e.g. discount rules only in SQL).

package/presets/claude/java/rules/api-and-data/adapters-driving.md

@@ -0,0 +1,38 @@
+---
+description: Driving adapters (HTTP, gRPC, CLI) for Java hexagonal services
+paths:
+  - "**/adapters/inbound/**/*"
+  - "**/adapters/http/**/*"
+  - "**/adapters/grpc/**/*"
+  - "**/*Controller*.java"
+---
+
+# Driving adapters
+
+- Translate transport → application calls → transport response.
+- Map request/response DTOs at the edge; do **not** pass framework types (`HttpServletRequest`, Spring Security internals) into use cases.
+- AuthN/AuthZ and wire-format validation belong here (or filters/interceptors); domain validation stays in domain.
+- Errors: map domain/application exceptions to status codes once (central `@ControllerAdvice` / exception mapper preferred).
+- Keep controllers/handlers thin: decode → call use case → encode; no multi-step workflows or SQL in the adapter.
+
+## Layout
+
+Default (layer-first): `adapters/inbound/http/` (and `…/grpc/`, `…/cli/` as needed). Flat `adapters/http/` is an accepted variant when the repo already uses it.
+
+## HTTP
+
+- See `api-http.mdc`. Prefer thin Spring MVC / Jakarta controllers; routing in one place.
+- Bind path/query/body into request DTOs (`@Valid` / Bean Validation at the edge) before calling application.
+- Framework choice (Spring MVC, JAX-RS, Quarkus REST) is optional — match the repo.
+
+## gRPC / CLI / messaging consumers
+
+- Same mapping rules; see stub `api-grpc.mdc` for protobuf notes; messaging consumers that trigger use cases are driving adapters (`messaging-adapters` stub).
+- CLI `main` / CommandLineRunner may call composition root or inbound ports — **no** SQL in `main`.
+- Propagate cancellation/timeouts from the transport into use-case calls when the stack supports it.
+
+## Forbidden
+
+- SQL, JPQL, or business invariants inside controllers.
+- Importing persistence packages from HTTP handlers (wire via application ports).
+- Swallowing exceptions without mapping to a transport status / structured log field.

package/presets/claude/java/rules/api-and-data/api-grpc.md

@@ -0,0 +1,29 @@
+---
+description: Thin gRPC/protobuf extension notes for Java hexagonal services (HTTP-first v1)
+paths:
+  - "**/*.proto"
+  - "**/adapters/inbound/grpc/**/*"
+  - "**/adapters/grpc/**/*"
+---
+
+# gRPC adapters (documented stub)
+
+> **Stub (v1):** HTTP is the preset SoT (`api-http`). This rule is a light placeholder — do not pretend full protobuf/streaming depth. **When to use:** editing `*.proto` or `adapters/**/grpc/**` in a repo that already (or newly) adopts gRPC.
+
+HTTP remains the **v1 SoT**. gRPC is an optional driving adapter with the same hexagonal rules.
+
+## Requirements when adding gRPC
+
+1. Keep protobuf messages in the adapter (or `api/proto`); map to domain/application at the edge.
+2. Implement the same inbound ports / use cases as HTTP — do not fork business logic.
+3. Map gRPC status codes from domain/application errors (parity with HTTP mapper).
+4. Generate code via repo-standard `buf` / `protoc` / protobuf-maven / Gradle protobuf plugins — do not hand-edit generated `*.java` stubs unless the repo requires it.
+
+## Non-goals (v1)
+
+- Full protobuf style guide and streaming patterns — expand this rule when the consumer repo adopts gRPC widely.
+- Mandating gRPC over HTTP.
+
+## Ports
+
+- Prefer shared application use cases; gRPC service class is a driving adapter only.

package/presets/claude/java/rules/api-and-data/api-http.md

@@ -0,0 +1,36 @@
+---
+description: HTTP API adapter conventions for Java hexagonal services
+paths:
+  - "**/adapters/inbound/http/**/*"
+  - "**/adapters/http/**/*"
+  - "**/*Controller*.java"
+  - "**/*handler*.java"
+---
+
+# HTTP API adapters
+
+- Controllers/handlers are **thin**: parse input, call one inbound port / use case, map status + body.
+- Use a consistent error envelope; map **domain exceptions** centrally (`@ControllerAdvice` / `ExceptionMapper`) — do not leak transport types into use cases.
+- Version routes if the repo already versions (`/v1/...`).
+- Spring MVC / Jakarta at the edge by default; plain Java may use JDK `HttpServer` or another framework — same mapping rules.
+- DTO validation: Bean Validation (`@Valid`, constraints) on request DTOs at the adapter; do not put `@NotNull` on domain entities “for HTTP”.
+- Map DTO ↔ domain/application at the edge (dedicated mapper or small private methods).
+
+## Resilience
+
+- Side-effect endpoints (charge, create, enqueue): accept/propagate an **idempotency key** when the domain already uses one; document if intentionally omitted.
+- Outbound HTTP to third parties: prefer **per-provider clients** (separate timeouts/pools) — bulkhead isolation.
+- Provider/ACL adapters return typed results or errors — never raw `Map<String, Object>` / untyped JSON into the domain.
+- Soft file-size hint: split when a controller grows past ~400 LOC.
+
+## Testing
+
+- Prefer `MockMvc` / WebTestClient / JAX-RS test client against the controller with a mocked use case (unit of adapter).
+- Integration: Spring slice or full context + Testcontainers behind driven ports when needed.
+
+## Forbidden
+
+- Business rules or SQL/JPQL in controllers.
+- Ignoring request timeouts / async cancel when the framework exposes them.
+- Raising transport-only errors from use cases (keep HTTP mapping at the adapter edge).
+- Returning JPA entities directly as JSON response bodies.

package/presets/claude/java/rules/api-and-data/messaging-adapters.md

@@ -0,0 +1,24 @@
+---
+description: Messaging driven/driving adapters for Java hexagonal services (stub)
+paths:
+  - "**/adapters/outbound/messaging/**/*"
+  - "**/adapters/inbound/messaging/**/*"
+  - "**/adapters/messaging/**/*"
+---
+
+# Messaging adapters (documented stub)
+
+> **Stub (v1):** Light guidance only — not a full Kafka/Rabbit/JMS cookbook. **When to use:** editing `adapters/**/messaging/**` or adding broker publishers/consumers. Prefer expanding this rule when the consumer repo standardizes on a broker.
+
+- **Publisher** (driven): implements outbound port; serializes domain events / integration events.
+- **Consumer** (driving): deserializes → calls use case / inbound port; ack/nack policy here.
+- Idempotency keys and retry/DLQ are adapter concerns; document at-least-once assumptions.
+- Do not put broker client types (`KafkaTemplate`, JMS sessions, etc.) in domain or application signatures.
+
+## Event shapes
+
+- Prefer explicit event types in application or a small `events` package used by ports — map to wire format in the adapter.
+
+## Tests
+
+- Unit-test mapping with fakes; integration against embedded/broker Testcontainers when the repo has them.

package/presets/claude/java/rules/api-and-data/persistence-adapters.md

@@ -0,0 +1,33 @@
+---
+description: Persistence driven adapters (JPA/JDBC/repos) for Java hexagonal services
+paths:
+  - "**/adapters/outbound/persistence/**/*"
+  - "**/adapters/persistence/**/*"
+  - "**/*Repository*.java"
+  - "**/*repository*.java"
+---
+
+# Persistence adapters
+
+- Implement outbound repository ports from application.
+- Use parameterized queries / JPA Criteria / Spring Data methods — **never** string-concatenated SQL with untrusted input.
+- Map rows / JPA entities → **domain** inside the adapter; entities stay private to the adapter package when possible.
+- Transactions: use cases own the boundary (`@Transactional` on application services, or a `UnitOfWork` port). Adapters must not start ad-hoc transactions that hide business atomicity.
+- Migrations live with infra (`db/migration`, Flyway/Liquibase dirs) — **not** in domain.
+
+## Mapping
+
+- JPA `@Entity` / JDBC row mappers are adapter-local; do not pass them through port signatures or up into application/domain.
+- Nullability and DB defaults convert to domain values explicitly (no silent nulls into invariants).
+- Spring Data repositories may be used **inside** the adapter as helpers; the application still depends on the port interface, not on `JpaRepository`.
+
+## Forbidden
+
+- Importing persistence from domain, or leaking `EntityManager` / `@Entity` / `JdbcTemplate` through port APIs.
+- Building SQL/JPQL strings in use cases.
+- Returning JPA entities from REST controllers “because lazy loading”.
+
+## Tests
+
+- Integration tests with Testcontainers / test DB preferred for repos; unit-test mappers with fixtures.
+- Spring `@DataJpaTest` / JDBC slices only when needed — prefer testing through the port implementation.

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

@@ -0,0 +1,16 @@
+# Architecture
+
+Hexagonal boundaries and delivery. Index only.
+
+| File | Cursor SoT |
+|------|------------|
+| [`boundaries.md`](./boundaries.md) | `architecture-boundaries.mdc` |
+| [`feature-delivery.md`](./feature-delivery.md) | `feature-delivery-workflow.mdc` |
+| [`reference-features.md`](./reference-features.md) | `reference-features.mdc` |
+| [`domain-layer.md`](./domain-layer.md) | `domain-layer.mdc` |
+| [`application-usecases.md`](./application-usecases.md) | `application-usecases.mdc` |
+| [`ports-interfaces.md`](./ports-interfaces.md) | `ports-interfaces.mdc` |
+| [`composition-root.md`](./composition-root.md) | `composition-root.mdc` |
+| [`module-public-api.md`](./module-public-api.md) | `module-public-api.mdc` |
+
+Full map: [`../README.md`](../README.md).

package/presets/claude/java/rules/architecture/application-usecases.md

@@ -0,0 +1,32 @@
+---
+description: Application use cases and orchestration in Java hexagonal services
+paths:
+  - "application/**/*"
+  - "**/application/**/*"
+---
+
+# Application / use cases
+
+- One use case ≈ one application service method (command/query).
+- Depend on **outbound ports** (interfaces), not concrete repos, JPA, or HTTP clients.
+- Orchestrate domain; transaction boundaries via ports (`UnitOfWork` / `@Transactional` **on the application service** when the repo uses Spring) — still **no SQL/JPQL** here.
+- Keep signatures in domain / application types — never `HttpServletRequest`, `EntityManager`, or controller DTOs.
+- Spring `@Service` on use cases is optional wiring sugar; domain remains Spring-free. Plain Java: plain classes constructed in composition root.
+
+## Forbidden
+
+- Importing `adapters.*`, JDBC drivers, Spring Web, JPA entity classes.
+- Embedding `DataSource`, Redis/Kafka clients, or controller types in use-case fields.
+- Business rules that belong on domain entities/VOs (keep use cases thin orchestrators).
+
+## Structure
+
+- Prefer `…/application/<Feature>Service.java` (or `…/<usecase>/`) with ports colocated (`…/application/ports/` or `*Port.java` beside the service).
+- Inbound port = interface the driving adapter calls (optional when a concrete use-case class is the only API).
+- Package layout may be layer-first (`application/`) or feature-first (`<feature>/application/`) — same dependency direction.
+
+## Tests
+
+- Unit-test with fakes/mocks of outbound ports; assert domain outcomes and port interactions — **no** real DB.
+- Mockito is optional when the repo already uses it; prefer simple fakes for narrow ports.
+- JUnit 5; AssertJ when present.

package/presets/claude/java/rules/architecture/boundaries.md

@@ -0,0 +1,29 @@
+---
+description: Hexagonal layer boundaries for Java backends (domain, application, ports, adapters)
+---
+
+
+# Границы слоёв (hexagonal)
+
+- **Domain** (`**/domain`):
+  - Может: entities, value objects, domain services, domain errors; JDK / same BC domain.
+  - Не должен: Spring/Jakarta web, JPA/JDBC, brokers, HTTP DTOs, transport serialization annotations.
+- **Application** (`**/application`):
+  - Может: use cases; **define ports** (inbound/outbound interfaces) with domain types in signatures.
+  - Не должен: concrete adapters, SQL/JPQL, controller/framework types as domain input.
+- **Ports**: interfaces only — no adapter implementations in port packages.
+- **Driving adapters** (`adapters/inbound/**`): map DTO ↔ application/domain at the edge; no business rules/SQL in controllers.
+- **Driven adapters** (`adapters/outbound/**`): implement outbound ports; map rows/messages → domain; do not leak persistence models upward.
+- **Composition** (`configuration/`, `*Application.java`): wires the graph; no business logic.
+
+# Зависимости
+
+- Направление: **adapters → application → domain**.
+- Driven adapters implement outbound ports defined by application.
+- Domain never imports adapters or frameworks.
+- Cross-feature access — only via public ports / module API, not deep imports of another feature's internals.
+
+# Требование к агенту
+
+- Класть файлы в правильный слой; не «коротить» слои ради скорости.
+- DI / wiring только в composition / configuration.

package/presets/claude/java/rules/architecture/composition-root.md

@@ -0,0 +1,31 @@
+---
+description: Composition root and DI wiring for Java hexagonal services
+paths:
+  - "**/configuration/**"
+  - "**/*Application.java"
+---
+
+# Composition root
+
+- Construct adapters, use cases, and servers in `configuration/` and/or `*Application.java`.
+- **Spring Boot default:** `@SpringBootApplication` + `@Configuration` / `@Bean` (or component scan limited to adapters + application). Wire ports → implementations explicitly when scan ambiguity exists.
+- **Plain Java:** explicit bootstrap / factory in `main` — same graph, no component scan.
+- Quarkus / Micronaut / Jakarta: CDI/`@ApplicationScoped` equivalents — still **no business logic** here.
+- Load config once; fail fast on missing required settings (Spring `Environment` / typed `@ConfigurationProperties`, or plain config objects).
+- Lifecycle: graceful shutdown via Spring lifecycle beans / JVM shutdown hooks matching the repo.
+
+## Allowed here
+
+- Import all layers for **wiring only**.
+- Process-wide loggers, metrics, health indicators, ObjectMapper beans.
+
+## Forbidden
+
+- Business rules, SQL/JPQL, HTTP routing tables with domain logic.
+- Global mutable singletons for repos without clear init (prefer constructor injection / explicit beans).
+- Putting domain types under Spring stereotype annotations unless the repo already does — prefer adapters + application as Spring components.
+
+## Tests
+
+- Optional smoke that the context loads (`@SpringBootTest` / slice, or construction test for plain Java).
+- Heavy logic stays in unit/integration tests — composition-root tests only prove the graph builds.

package/presets/claude/java/rules/architecture/domain-layer.md

@@ -0,0 +1,38 @@
+---
+description: Domain layer invariants for Java hexagonal services
+paths:
+  - "domain/**/*"
+  - "**/domain/**/*"
+---
+
+# Domain layer
+
+- Pure business types and rules; **no I/O**, no Spring, no JPA, no HTTP.
+- Prefer small value objects with validation factories (`of` / `parse` / package-private constructors) that throw typed **domain** exceptions.
+- Domain errors are typed (`RuntimeException` subtypes or a small sealed hierarchy); map to HTTP/gRPC statuses **only** in adapters.
+- Domain services orchestrate entities/VOs without calling outbound ports (ports live in **application**).
+- Keep invariants close to the type that owns them; avoid anemic bags of fields with all logic in use cases.
+- Prefer `record` / immutable types when the repo already uses them; do not invent a new VO style mid-module.
+
+## Forbidden imports
+
+- Spring (`org.springframework.*`), Jakarta Servlet / JAX-RS resource types, Spring MVC / WebFlux.
+- JPA (`jakarta.persistence.*`, `EntityManager`), Spring Data repositories, JDBC templates as domain deps.
+- Redis/Kafka/HTTP clients, Jackson `@Json*` / OpenAPI annotations that mirror wire contracts.
+- Framework request-scope / security-context plumbing as a substitute for domain deadlines (prefer explicit types).
+
+## Allowed
+
+- JDK: `java.time`, collections, `Optional` sparingly, custom exceptions, pure utilities.
+- Cross-aggregate references by **ID**, not by loading other aggregates via ports.
+- Deadline/time primitives only when the domain API genuinely needs them (prefer application to pass values).
+
+## Plain-Java / alternate frameworks
+
+Same rules: domain stays framework-free whether the edge is Spring Boot, Quarkus, Micronaut, or plain JDK.
+
+## Tests
+
+- JUnit 5 unit tests (parameterized when covering many cases); **no** DB, `MockMvc`, Testcontainers, or Spring contexts.
+- Cover invalid factory inputs and invariant violations explicitly.
+- Prefer AssertJ when the repo already depends on it.

package/presets/claude/java/rules/architecture/feature-delivery.md

@@ -0,0 +1,52 @@
+---
+description: End-to-end delivery checklist for Java hexagonal features
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - "**/*.java"
+  - src/main/java/**/*
+  - src/test/java/**/*
+  - "**/configuration/**"
+---
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (Java hexagonal)
+
+Order of work:
+
+1. **Domain** — entities/VOs/errors (`domain-layer`).
+2. **Application + ports** — use case + outbound interfaces (`application-usecases`, `ports-interfaces`).
+3. **Driven adapters** — persistence/cache/messaging implementing ports (`adapters-driven`, `persistence-adapters`).
+4. **Driving adapters** — HTTP/gRPC/CLI mapping DTOs (`adapters-driving`, `api-http`; stubs for gRPC/messaging).
+5. **Composition root** — wire in `configuration/` / `*Application.java` (`composition-root`).
+6. **Tests** — unit (domain/app) → integration (adapters) → optional e2e smoke.
+7. **Gate** — `post-change-test` (+ `java-tooling`).
+
+```mermaid
+flowchart LR
+  D[Domain] --> A[Application+Ports]
+  A --> Drv[Driven adapters]
+  Drv --> A
+  HTTP[Driving HTTP] --> A
+  CR[Composition root] --> HTTP
+  CR --> A
+  CR --> Drv
+```
+
+## Matrix
+
+| Path | Rules |
+|------|-------|
+| `**/domain/**` | `domain-layer`, `architecture-boundaries` |
+| `**/application/**` | `application-usecases`, `ports-interfaces` |
+| `**/adapters/inbound/**`, `**/adapters/http/**` | `adapters-driving`, `api-http` / `api-grpc` |
+| `**/adapters/outbound/**`, `**/adapters/persistence/**` | `adapters-driven`, `persistence-adapters` / `messaging-adapters` |
+| `**/configuration/**`, `**/*Application.java` | `composition-root` |
+| After `*.java` edits | `post-change-test` (+ `java-tooling`) |
+
+## Anti-patterns
+
+- Framework types in domain; SQL/JPQL in use cases; DI inside controllers; skipping port interfaces “for speed”; returning JPA entities as HTTP bodies.
+- **Ubiquitous language:** Domain names/boundaries reflect the feature domain — do not mix transport/framework terms into domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- Spring Boot is the default edge; plain Java / Quarkus / Micronaut keep the same layer order with different wiring.

package/presets/claude/java/rules/architecture/module-public-api.md

@@ -0,0 +1,31 @@
+---
+description: Public module API and package boundaries for Java services
+paths:
+  - "**/api/**/*.java"
+  - "**/module-info.java"
+  - pom.xml
+  - "**/build.gradle*"
+---
+
+# Module public API
+
+- Published types under a module's public packages are a compatibility surface — change carefully; prefer additive APIs.
+- Service-private code stays in implementation packages — do not treat every package as public API.
+- Prefer package-private by default; expose only what other modules/features need.
+- Do not deep-import another module's internal packages; depend on its published API / facade only.
+- Document breaking Java API changes in CHANGELOG when the repo publishes libraries.
+
+## Single-module default / multi-module variant
+
+- **Default:** one deployable module with layer-first packages under `src/main/java/<base>/`.
+- **Multi-module (Maven/Gradle):** each module exposes a narrow public API; application ports may live in an `application-api` module; adapters depend inward. Do not invent multi-module scaffolding unless the repo already uses it.
+
+## pom.xml / build.gradle
+
+- Module coordinates and JDK version are SoT for toolchain.
+- Prefer minimal direct deps; pin via BOM / lockfile the repo already uses (`pom.xml`, `build.gradle(.kts)`).
+
+## Cross-feature
+
+- Inside one module, features communicate via application ports or small public facades — not by importing sibling feature adapter packages.
+- JPMS `module-info.java` (when present): export only public packages; keep adapters non-exported when possible.