@bonesofspring/ai-rules 0.2.11 → 0.2.13

package/presets/claude/php-hexagonal/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/php-hexagonal/hooks/examples/format-edited.example.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Optional: project formatter on edited PHP sources.
+# NOT in default hooks.json. Discover formatter from repo/CI — do not invent one.
+set -euo pipefail
+changed=$(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.php$' || true)
+if [[ -n "${changed:-}" ]]; then
+  # Prefer repo tool already configured — placeholders only:
+  # vendor/bin/php-cs-fixer fix $changed  OR  vendor/bin/pint $changed
+  true
+fi
+exit 0

package/presets/claude/php-hexagonal/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/php-hexagonal/hooks/examples/test-on-save.example.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Optional: Composer/PHPUnit (or Pest) after PHP edits.
+# NOT in default hooks.json. Prefer Composer scripts when present.
+set -euo pipefail
+changed=$(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.php$' || true)
+if [[ -z "${changed:-}" ]]; then
+  exit 0
+fi
+if [[ ! -f composer.json ]]; then
+  exit 0
+fi
+if composer test -q >/dev/null 2>&1; then
+  composer test -q 2>/dev/null || true
+elif [[ -x vendor/bin/pest ]]; then
+  vendor/bin/pest 2>/dev/null || true
+elif [[ -x vendor/bin/phpunit ]]; then
+  vendor/bin/phpunit 2>/dev/null || true
+fi
+exit 0

package/presets/claude/php-hexagonal/hooks/guard-shell-command.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Lightweight shell guard for Claude Code projects using this preset.
+# PHP: do NOT blanket-block composer test / vendor/bin/phpunit / 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
+# PHP_PRESET_GUARD: allow composer/composer 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/php-hexagonal/mcp.json

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

package/presets/claude/php-hexagonal/rules/README.md

@@ -0,0 +1,67 @@
+# `.claude/rules` (preset php-hexagonal)
+
+Claude topic `.md` files are **derived** from Cursor SoT `presets/cursor/php-hexagonal/rules/*.mdc`.
+
+## SoT sync
+
+| Principle | Detail |
+|-----------|--------|
+| **SoT** | `presets/cursor/php-hexagonal/rules/*.mdc` |
+| **Derive** | Claude topic `.md` + `paths:` (drop `alwaysApply`) |
+| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — next, ios-swift, go, java, mcp-ts, and php-hexagonal; see `preset-twin-sync` / build-verifier) |
+
+## Loading budget
+
+- **Session-start (no `paths:`):** exactly **3** — `php-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 stub** (v1): `api-grpc`; `messaging-adapters` is full — see Cursor `presets/cursor/php-hexagonal/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` |
+| `anti-sycophancy-discipline.mdc` | `tooling-and-review/anti-sycophancy-discipline.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` |
+| `php-app-core.mdc` | `stack/php-app-core.md` |
+| `php-conventions.mdc` | `stack/php-conventions.md` |
+| `php-tooling.mdc` | `tooling-and-review/php-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-php.mdc` | `tooling-and-review/security-php.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).
+
+## Metrics policy mapping
+
+| Shared core | Runtime integration | Loading |
+|-------------|---------------------|---------|
+| `agent-team/agent-task-metrics.md` | `agent-team-orchestrator` + `hooks/chain-team-phases.sh` | requestable/on-demand; never session-start |

package/presets/claude/php-hexagonal/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/php-hexagonal/rules/api-and-data/adapters-driven.md

@@ -0,0 +1,38 @@
+---
+description: Driven adapters (persistence, cache, messaging) for PHP 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 ORM entities or raw PDO 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`.
+- Keep SQL/DQL/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 — do not share one god-client for every vendor.
+
+## Forbidden
+
+- Calling other driven adapters bypassing application (hidden coupling).
+- Leaking ORM models, PDO types, Redis, or broker client types through port signatures.
+- Embedding business invariants that belong in domain (e.g. discount rules only in SQL).

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

@@ -0,0 +1,38 @@
+---
+description: Driving adapters (HTTP, gRPC, CLI) for PHP hexagonal services
+paths:
+  - "**/adapters/inbound/**/*"
+  - "**/adapters/http/**/*"
+  - "**/adapters/grpc/**/*"
+  - "**/*Controller*.php"
+---
+
+# Driving adapters
+
+- Translate transport → application calls → transport response.
+- Map request/response DTOs at the edge; do **not** pass framework request/security types into use cases.
+- AuthN/AuthZ and wire-format validation belong here (or middleware); domain validation stays in domain.
+- Errors: map domain/application exceptions to status codes once (central exception listener / middleware 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 controllers/actions; routing in one place.
+- Bind path/query/body into request DTOs and validate at the edge before calling application.
+- Framework choice (Slim, Symfony, Laravel, plain PHP) 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 entrypoints may call composition root or inbound ports — **no** SQL in `bin/` scripts.
+- Propagate cancellation/timeouts from the transport into use-case calls when the stack supports it.
+
+## Forbidden
+
+- SQL, DQL, 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/php-hexagonal/rules/api-and-data/api-grpc.md

@@ -0,0 +1,29 @@
+---
+description: Thin gRPC/protobuf extension notes for PHP 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 `protoc` / protobuf PHP plugins — do not hand-edit generated 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/php-hexagonal/rules/api-and-data/api-http.md

@@ -0,0 +1,36 @@
+---
+description: HTTP API adapter conventions for PHP hexagonal services
+paths:
+  - "**/adapters/inbound/http/**/*"
+  - "**/adapters/http/**/*"
+  - "**/*Controller*.php"
+  - "**/*handler*.php"
+---
+
+# HTTP API adapters
+
+- Controllers/handlers/actions are **thin**: parse input, call one inbound port / use case, map status + body.
+- Use a consistent error envelope; map **domain exceptions** centrally (exception listener / middleware) — do not leak transport types into use cases.
+- Version routes if the repo already versions (`/v1/...`).
+- Framework-agnostic edge by default (Slim / Symfony HttpFoundation / Laravel HTTP / plain PHP) — same mapping rules.
+- DTO validation at the adapter edge; do not put HTTP constraints on domain entities.
+- 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) — bulkhead isolation.
+- Provider/ACL adapters return typed results or errors — never raw untyped arrays into the domain.
+- Soft file-size hint: split when a controller grows past ~400 LOC.
+
+## Testing
+
+- Prefer controller/handler unit tests with a mocked use case.
+- Integration: HTTP kernel + DB fixtures behind driven ports when needed (`integration-test-*`).
+
+## Forbidden
+
+- Business rules or SQL/DQL in controllers.
+- Ignoring request timeouts / cancel when the framework exposes them.
+- Raising transport-only errors from use cases (keep HTTP mapping at the adapter edge).
+- Returning ORM entities directly as JSON response bodies.

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

@@ -0,0 +1,37 @@
+---
+description: Messaging driven/driving adapters for PHP hexagonal services
+paths:
+  - "**/Adapters/Outbound/Messaging/**/*"
+  - "**/Adapters/Inbound/Messaging/**/*"
+  - "**/adapters/**/messaging/**/*"
+---
+
+# Messaging adapters
+
+- **Publisher** (driven): implements an outbound port; serializes application/domain events to wire format inside the adapter.
+- **Consumer** (driving): deserializes → maps to application/domain types → calls inbound port / use case; **ack/nack** (and commit) stays in the adapter.
+- Idempotency keys, retry, and DLQ/parking-lot policy are adapter (or infra) concerns — document at-least-once vs exactly-once assumptions at the port.
+- Use the broker client already present in the repo — do not invent a second stack.
+
+## Event shapes
+
+- Prefer explicit event types in application or a small `Events` namespace used by ports.
+- Map wire DTOs ↔ application events **only** in the adapter; never pass broker payloads (`AMQPMessage`, Kafka records, SQS envelopes) into domain.
+
+## Stack notes (PHP)
+
+- Prefer the transport already wired: **Symfony Messenger**, enqueue/AMQP clients, php-rdkafka / Kafka clients, or AWS SDK for SQS — follow the repo.
+- Framework bus types (`Envelope`, `MessageBusInterface`, raw AMQP channel) stay in adapters / composition — not in domain or application ports.
+- Outbox / inbox and retry schedules are infra; ports expose intent (`publish`, `handle`) without broker APIs.
+
+## Forbidden
+
+- Broker client types (`AMQPStreamConnection`, `RdKafka\Producer`, SQS client classes, Messenger `Envelope`) in domain or application signatures.
+- Business rules inside listeners beyond mapping + calling one use case.
+- Silent catch-and-ack that drops poison messages without DLQ/metrics policy.
+
+## Tests
+
+- Unit-test mapping and idempotency branches with fakes.
+- Integration against embedded broker / Testcontainers **when the repo already has that setup**.
+- After edits: `post-change-test` (+ `php-tooling`); agents `integration-test-*` when adding consumer contracts.

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

@@ -0,0 +1,33 @@
+---
+description: Persistence driven adapters (PDO/ORM/repos) for PHP hexagonal services
+paths:
+  - "**/adapters/outbound/persistence/**/*"
+  - "**/adapters/persistence/**/*"
+  - "**/*Repository*.php"
+  - "**/*repository*.php"
+---
+
+# Persistence adapters
+
+- Implement outbound repository ports from application.
+- Use parameterized queries / query builders / ORM methods — **never** string-concatenated SQL with untrusted input.
+- Map rows / ORM entities → **domain** inside the adapter; entities stay private to the adapter package when possible.
+- Transactions: use cases own the boundary (framework transaction on application services, or a `UnitOfWork` port). Adapters must not start ad-hoc transactions that hide business atomicity.
+- Migrations live with infra (`database/migrations`, Doctrine migrations dirs) — **not** in domain.
+
+## Mapping
+
+- Eloquent/Doctrine entities / PDO 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).
+- ORM repositories may be used **inside** the adapter as helpers; the application still depends on the port interface, not on the ORM base class.
+
+## Forbidden
+
+- Importing persistence from domain, or leaking `EntityManager` / Eloquent models / PDO through port APIs.
+- Building SQL/DQL strings in use cases.
+- Returning ORM entities from HTTP controllers “because lazy loading”.
+
+## Tests
+
+- Integration tests with test DB / fixtures preferred for repos; unit-test mappers with fixtures.
+- Prefer testing through the port implementation (`integration-test-*`).

package/presets/claude/php-hexagonal/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/php-hexagonal/rules/architecture/application-usecases.md

@@ -0,0 +1,31 @@
+---
+description: Application use cases and orchestration in PHP 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, ORM, or HTTP clients.
+- Orchestrate domain; transaction boundaries via ports (`UnitOfWork` / framework transaction on the application service when the repo uses that) — still **no SQL/DQL** here.
+- Keep signatures in domain / application types — never framework request objects, `EntityManager`, or controller DTOs.
+- Framework service attributes on use cases are optional wiring sugar; domain remains framework-free. Plain PHP: plain classes constructed in composition root.
+
+## Forbidden
+
+- Importing `Adapters\*`, PDO/Doctrine drivers, framework HTTP, ORM entity classes as use-case deps.
+- Embedding 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.php` (or `…/<usecase>/`) with ports colocated (`…/Application/Ports/` or `*Port.php` 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.
+- Prefer simple fakes for narrow ports; PHPUnit mocks only if the repo already uses them.

package/presets/claude/php-hexagonal/rules/architecture/boundaries.md

@@ -0,0 +1,34 @@
+---
+description: Hexagonal layer boundaries for PHP backends (domain, application, ports, adapters)
+---
+
+# Границы слоёв (hexagonal)
+
+- **Domain** (`**/Domain/**`, `**/domain/**`):
+  - Может: entities, value objects, domain services, domain errors; PHP stdlib / same BC domain.
+  - Не должен: framework HTTP kernels, Eloquent/Doctrine as domain types, broker SDKs, transport DTOs.
+- **Application** (`**/Application/**`, `**/application/**`):
+  - Может: use cases; **define ports** (inbound/outbound interfaces) with domain types in signatures.
+  - Не должен: concrete adapters, SQL/DQL, controller/framework types as domain input.
+- **Ports**: interfaces only — no adapter implementations in port packages.
+- **Driving adapters** (`Adapters/Inbound/**`, `adapters/inbound/**`): map DTO ↔ application/domain at the edge; no business rules/SQL in controllers.
+- **Driven adapters** (`Adapters/Outbound/**`, `adapters/outbound/**`): implement outbound ports; map rows/messages → domain; do not leak persistence models upward.
+- **Composition** (`Composition/`, `composition/`, bootstrap): 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.
+
+# Edit bundles (load on matching paths)
+
+- `**/Domain/**` → `domain-layer`; `**/Application/**` → `application-usecases` + `ports-interfaces`
+- Inbound HTTP/gRPC → `adapters-driving` + `api-http` / `api-grpc`; outbound persistence/messaging → `adapters-driven` + matching `*-adapters`
+- `**/Composition/**`, bootstrap → `composition-root`; after `*.php` edits → `post-change-test` (+ `php-tooling`)
+
+# Требование к агенту
+
+- Класть файлы в правильный слой; не «коротить» слои ради скорости.
+- DI / wiring только в composition / bootstrap.

package/presets/claude/php-hexagonal/rules/architecture/composition-root.md

@@ -0,0 +1,33 @@
+---
+description: Composition root and DI wiring for PHP hexagonal services
+paths:
+  - "**/Composition/**"
+  - "**/Composition/*"
+---
+
+# Composition root
+
+- Construct adapters, use cases, and servers in `Composition/` (or repo bootstrap / DI container definitions).
+- Wire ports → implementations explicitly (PHP-DI, Symfony DI, Laravel container, or manual factories — match the repo).
+- Load config once; **fail fast** on missing required settings before opening listeners or connections.
+- Lifecycle: graceful shutdown matching the repo (close DB pools / clients in reverse wire order).
+
+## Allowed here
+
+- Import all layers for **wiring only**.
+- Process-wide loggers, metrics, health providers constructed once and injected.
+
+## Forbidden
+
+- Business rules, SQL/DQL, HTTP routing tables with domain logic.
+- Global mutable singletons for repos without clear init (prefer constructor injection / explicit bindings).
+- Putting domain types under framework stereotypes unless the repo already does — prefer adapters + application as framework components.
+
+## Framework variants (pointer)
+
+- Slim / plain PHP: explicit bootstrap in `public/index.php` or `Composition/`.
+- Symfony / Laravel: keep container config / providers thin — no business rules in service providers.
+
+## Tests
+
+- Optional smoke that the container/bootstrap builds; heavy logic stays in unit/integration tests.

package/presets/claude/php-hexagonal/rules/architecture/domain-layer.md

@@ -0,0 +1,37 @@
+---
+description: Domain layer invariants for PHP hexagonal services
+paths:
+  - "domain/**/*"
+  - "**/domain/**/*"
+---
+
+# Domain layer
+
+- Pure business types and rules; **no I/O**, no framework, no ORM, no HTTP.
+- Prefer small value objects with validation factories (`of` / `from` / private constructors) that throw typed **domain** exceptions.
+- Domain errors are typed (`RuntimeException` subtypes or a small 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 `readonly` / immutable types when the repo already uses them; do not invent a new VO style mid-module.
+
+## Forbidden imports
+
+- Framework HTTP kernels, PSR-15 request/response types as domain deps, Laravel/Symfony request classes.
+- Eloquent/Doctrine entities as domain types, `EntityManager`, query builders as domain deps.
+- Redis/Kafka/HTTP clients, OpenAPI/JSON serialization attributes that mirror wire contracts.
+- Framework request-scope / security-context plumbing as a substitute for domain deadlines (prefer explicit types).
+
+## Allowed
+
+- PHP stdlib: `DateTimeImmutable`, arrays/collections used by the repo, 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-PHP / alternate frameworks
+
+Same rules: domain stays framework-free whether the edge is Slim, Symfony HttpFoundation, Laravel HTTP, or plain PHP.
+
+## Tests
+
+- PHPUnit (or Pest) unit tests; **no** DB, HTTP controller harness, or framework kernel.
+- Cover invalid factory inputs and invariant violations explicitly.