@bonesofspring/ai-rules 0.2.11 → 0.2.13

package/presets/cursor/php-hexagonal/rules/api-http.mdc

@@ -0,0 +1,40 @@
+---
+description: HTTP API adapter conventions for PHP hexagonal services
+globs:
+  - "**/Adapters/Inbound/Http/**/*"
+  - "**/adapters/inbound/http/**/*"
+  - "**/adapters/http/**/*"
+  - "**/*Controller*.php"
+  - "**/*Handler*.php"
+  - "**/*Action*.php"
+alwaysApply: false
+---
+
+
+# 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/cursor/php-hexagonal/rules/application-usecases.mdc

@@ -0,0 +1,33 @@
+---
+description: Application use cases and orchestration in PHP hexagonal services
+globs:
+  - "**/Application/**/*"
+  - "**/application/**/*"
+alwaysApply: false
+---
+
+
+# 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/cursor/php-hexagonal/rules/architecture-boundaries.mdc

@@ -0,0 +1,36 @@
+---
+description: Hexagonal layer boundaries for PHP backends (domain, application, ports, adapters)
+alwaysApply: true
+---
+
+
+# Границы слоёв (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/cursor/php-hexagonal/rules/code-quality-and-refactoring.mdc

@@ -0,0 +1,54 @@
+---
+description: Code quality and light refactoring for PHP hexagonal services
+alwaysApply: true
+---
+
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+
+# Поддержка существующего стиля
+
+- Следовать существующим паттернам (имена, структура, типизация / DI / error handling); минимизировать стилистический шум (лишний format/rename).
+- Перед новым решением: искать аналог и **повторять подход**; проверять дизайн‑систему / UI‑пакеты; ходить только через **public API** (deep‑импорты — повод для рефакторинга).
+
+# Принципы
+
+- **KISS:** самое простое изменение в паттернах репозитория.
+- **DRY + Rule of Three:** общее — только после 3-го повторения (ошибочная абстракция дороже дублирования).
+- **YAGNI:** без API, флагов, слоёв «на будущее» без текущего требования.
+- **SOLID:** S — один повод менять; O — композиция/новые реализации; L — контракт подтипа; I — узкие порты; D — абстракции (порты), детали в адаптерах стека.
+- **CUPID:** Composable; Unix philosophy (одна ответственность); Predictable; Idiomatic (репо); Domain-based.
+- **Composition over inheritance;** Law of Demeter — без цепочек `a.b.c.d`; через public API / facade.
+
+# Рефакторинг при изменениях
+
+- Лёгкий refactor OK, если меньше дублирования, выше читаемость, без ломки публичных контрактов.
+- Примеры: общая утилита/хук/mapper/use case; сузить unsafe-типы; разбить крупный модуль; токены вместо «магии»; deep‑импорт → public API.
+- Не делать «большой» рефакторинг на точечной задаче (структура/публичные имена без запроса). Крупное — минимальными шагами; код остаётся собираемым.
+
+# Требование к агенту
+
+- **Boy scout:** оставлять модуль немного лучше; не жертвовать архитектурой и слоями ради краткости.
+
+## Agent discipline (anti-sycophancy)
+
+Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
+
+- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- Before «is this correct?» — ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
+- Refactor without tests → propose characterization test; if declined, label `UNTESTED`.
+- Comments = WHY only when non-obvious; ban self-referential «added for issue Y».
+- Urgency/authority: name the trade-off once, then comply — no apology loops.
+- Match verification to risk; report by what was **verified**, not attempted.
+
+Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
+
+> 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 PHP 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`** + **`php-tooling.mdc`** (not yarn lint / xcodebuild / Playwright).
+- Style/static analysis: use **repository/CI** formatter and checks — do not invent a parallel PHP-CS-Fixer/PHPStan bible in rules.

package/presets/cursor/php-hexagonal/rules/code-review-mr.mdc

@@ -0,0 +1,54 @@
+---
+description: Code review checklist for PHP hexagonal merge requests
+alwaysApply: false
+---
+
+<!-- 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; framework/ORM only at edges.
+- HTTP DTO validation/mapping and persistence entity isolation: `api-http`, `persistence-adapters`.
+- Composition root (`Composition/`, `Composition/*`) has no business logic.
+- Tests: `tests-unit` (PHPUnit), `tests-integration` (integration DB fixtures); post-change: `post-change-test` / `php-tooling`.
+- Security: secrets/PII/`security-php`; framework Security config stays out of domain.
+- Never require Playwright, XCUITest, `lint:js`, or `xcodebuild` for PHP MRs.

package/presets/cursor/php-hexagonal/rules/composition-root.mdc

@@ -0,0 +1,37 @@
+---
+description: Composition root and DI wiring for PHP hexagonal services
+globs:
+  - "**/Composition/**/*"
+  - "**/composition/**/*"
+  - "**/bootstrap/**/*"
+  - "**/public/index.php"
+alwaysApply: false
+---
+
+
+# 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/cursor/php-hexagonal/rules/design-guidance.mdc

@@ -0,0 +1,112 @@
+---
+description: Design smells (Fowler) and curated GoF patterns for agents. Load when assessing structure, smells, or pattern fit.
+globs:
+  - "**/*.php"
+alwaysApply: false
+---
+
+<!-- shared-core: quality/design-guidance.md -->
+
+# Design guidance (smells & patterns)
+
+Словарь **code smells** (Fowler) и **design patterns** (GoF) для агентов при implement / review / debug.
+
+Применять только в scope задачи или MR. Лёгкий refactor — да; «большой» rewrite без явного запроса — нет.
+
+Называть паттерн **только если** репозиторий уже так делает или это минимальный match. Иначе — extract/split/move без ярлыка GoF.
+
+Не заменяет always-on Principles в `code-quality-and-refactoring` (KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition, Demeter).
+
+## When to load
+
+- **Feature delivery / implement** — оценка структуры модулей, границ и дублирования.
+- **Code review** — smells и pattern fit **в диффе MR**, не по всему репо.
+- **Debug** — root-cause похож на wrong abstraction, Feature Envy, Message Chains, Shotgun Surgery.
+- **Light refactor only** — улучшения в рамках boy-scout / MR scope; не расширять задачу ради каталога.
+
+Агенты и skills подгружают stem по one-liner wiring — не копировать этот каталог в промпт агента.
+
+## How to use (agent rules of thumb)
+
+1. Сначала сверить с Principles (always-on): проще ли решение, нет ли ранней абстракции, соблюдён ли public API.
+2. Затем отметить smells **в изменённых файлах** задачи/MR; предложить fix только если он укладывается в light refactor.
+3. Паттерн GoF — опциональный ярлык после того, как структура уже ясна; не начинать дизайн с выбора паттерна.
+4. Если smell и паттерн конфликтуют с границами слоёв стека — побеждают stack boundaries и existing repo patterns.
+5. Не требовать переименования «под GoF», если поведение уже корректно и читаемо.
+
+## Code smells (Fowler, curated ≤12)
+
+Таблица: smell → detect hint → fix hint (одна линия каждый). Без механических меню рефакторинга.
+
+| # | Smell | Detect | Fix hint |
+|---|-------|--------|----------|
+| 1 | Duplicate Code | одинаковая логика в ≥2 местах | dedupe после Rule of Three |
+| 2 | Long Method / Long Module | единица делает слишком много | extract в рамках scope; без big rewrite |
+| 3 | Feature Envy | метод чаще трогает чужие данные, чем свои | сдвинуть логику к данным / public API |
+| 4 | Data Clumps | одни и те же группы аргументов кочуют вместе | сгруппировать в type / value object |
+| 5 | Primitive Obsession | сырые string/int вместо доменных понятий | typed ids / value objects при нужде домена |
+| 6 | Speculative Generality | неиспользуемые хуки, флаги, абстракции «на будущее» | удалить (YAGNI) |
+| 7 | Message Chains | цепочки `a.b.c.d` | Demeter; facade / public API модуля |
+| 8 | Middle Man | класс почти только прокидывает вызовы | убрать pass-through **или** оставить как boundary |
+| 9 | Divergent Change | один модуль меняется по разным причинам | split по поводам изменения |
+| 10 | Shotgun Surgery | одно смысловое изменение разъезжается по многим файлам | consolidate ответственность |
+| 11 | Inappropriate Intimacy | доступ к чужим internals / private деталям | только public API / ports / facades |
+| 12 | Refused Bequest / Parallel Inheritance | подтип игнорирует базу; зеркальные иерархии классов | composition; не плодить параллельные деревья |
+
+**Skip Fowler (не в core):** Lazy Class, Incomplete Library Class, Comments-as-smell dogma, полный каталог 70+, пошаговые recipe-меню.
+
+Приоритет при конфликте smells: Inappropriate Intimacy и Message Chains (границы модулей) > Duplicate Code (после Rule of Three) > Long Method внутри уже правильного модуля.
+
+## Design patterns (GoF, curated ≤8)
+
+Suggest only when repo already uses the shape or the match is minimal. Prefer extract-function over naming Strategy ради ярлыка.
+
+Паттерны ниже — **разрешённый минимум** для агентов; остальной GoF по умолчанию в Skip.
+
+| Pattern | When to suggest | Anti-trigger |
+|---------|-----------------|--------------|
+| Strategy | взаимозаменяемые алгоритмы уже (или явно скоро) выбираются политикой | один алгоритм без ветвления политики |
+| Adapter | обернуть внешний / чужой API под локальный port | лишняя обёртка вокруг своего же API |
+| Facade | упростить multi-step subsystem за public API | facade превращается в god-object |
+| Factory Method | полиморфное создание уже принято в стиле репо | factory на каждый тривиальный `new` |
+| Decorator | аддитивное поведение без взрыва subclass-иерархий | decorator «для слоёв» без реальной нужды |
+| Observer | events / subscriptions уже есть в архитектуре | самодельный pub/sub без прецедента в репо |
+| Template Method | общий algorithm skeleton + вариативные hooks | наследование ради пары отличающихся строк |
+| Composite | дерево однородных узлов (UI/domain), как уже в репо | Composite на плоский список без иерархии |
+
+Если сомневаешься между двумя паттернами — выбери более простой extract/compose без имени; ярлык можно добавить на review, если репо уже так говорит.
+
+## Skip / avoid by default
+
+| Catalog | Skip |
+|---------|------|
+| GoF | Singleton, Abstract Factory, Flyweight, Memento, Interpreter, Visitor, Bridge, Prototype |
+| GoF (conditional) | Command, Chain of Responsibility, State — упоминать **только если** репо уже использует |
+| Fowler | всё сверх 12 smells выше |
+| DDD | Aggregates, bounded-context maps, event sourcing, CQRS — **не в core** |
+| DDD (pointer) | ubiquitous language anti-pattern — расширять в `feature-delivery-workflow`, не здесь |
+| GRASP | список Larman как отдельные правила — skip (перекрывается SOLID/CUPID) |
+| Clean Code dogma | жёсткие caps на строки функции / «ровно один assert» — skip |
+
+Не вводить второй stem (`refactoring-smells` / `design-patterns-for-agents`) — один каталог: `design-guidance`.
+
+## Out of scope for this stem
+
+- Полный GoF (23) и полный Fowler catalog.
+- Stack-specific рецепты (пути модулей, lint-команды) — только в **Stack notes** адаптера.
+- Security, a11y, perf — отдельные review-правила; здесь только структурные smells/patterns.
+- Четвёртое always-on правило — запрещено; этот stem только requestable / agent-load.
+
+## Cross-refs
+
+- Always-on Principles: `code-quality-and-refactoring`.
+- DIP / ports vs adapters: stack `architecture-boundaries` (детали стека — в Stack notes адаптеров).
+- Ubiquitous language: `feature-delivery-workflow` (lineage).
+- MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
+- Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).
+
+## Stack notes
+
+- Strategy via small interfaces at **ports**; adapters (framework/ORM/HTTP) implement, domain stays free of frameworks.
+- Suggest Facade at package public API; avoid Singleton in favor of composition root / `@Configuration` wiring.
+- Prefer records / immutable VOs for Strategy inputs when the repo already uses them — do not invent patterns mid-module.

package/presets/cursor/php-hexagonal/rules/domain-layer.mdc

@@ -0,0 +1,39 @@
+---
+description: Domain layer invariants for PHP hexagonal services
+globs:
+  - "**/Domain/**/*"
+  - "**/domain/**/*"
+alwaysApply: false
+---
+
+
+# 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.

package/presets/cursor/php-hexagonal/rules/feature-delivery-workflow.mdc

@@ -0,0 +1,47 @@
+---
+description: End-to-end delivery checklist for PHP hexagonal features
+alwaysApply: false
+---
+
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (PHP 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 `Composition/` / `Composition/*` (`composition-root`).
+6. **Tests** — unit (domain/app) → integration (adapters) → optional e2e smoke.
+7. **Gate** — `post-change-test` (+ `php-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` |
+| `**/Composition/**`, `**/Composition/*` | `composition-root` |
+| After `*.php` edits | `post-change-test` (+ `php-tooling`) |
+
+## Anti-patterns
+
+- Framework types in domain; SQL/DQL in use cases; DI inside controllers; skipping port interfaces “for speed”; returning ORM 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.
+- PHP framework edge is the default edge; plain PHP / Slim / Symfony HttpFoundation keep the same layer order with different wiring.

package/presets/cursor/php-hexagonal/rules/messaging-adapters.mdc

@@ -0,0 +1,38 @@
+---
+description: Messaging driven/driving adapters for PHP hexagonal services
+globs:
+  - "**/Adapters/Outbound/Messaging/**/*"
+  - "**/Adapters/Inbound/Messaging/**/*"
+  - "**/adapters/**/messaging/**/*"
+alwaysApply: false
+---
+
+# 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/cursor/php-hexagonal/rules/module-public-api.mdc

@@ -0,0 +1,32 @@
+---
+description: Public module API and package boundaries for PHP services
+globs:
+  - "**/composer.json"
+  - "**/src/**/*.php"
+alwaysApply: false
+---
+
+# Module public API
+
+- Published types under a package's public namespaces are a compatibility surface — change carefully; prefer additive APIs.
+- Service-private code stays in implementation namespaces — do not treat every namespace as public API.
+- Prefer narrow exports; expose only what other modules/features need.
+- Do not deep-import another module's internal namespaces; depend on its published API / facade only.
+- Document breaking PHP API changes in CHANGELOG when the repo publishes libraries.
+
+## Single-package default / multi-package variant
+
+- **Default:** one Composer package with layer-first namespaces under `src/` (see `dogfood/php-hexagonal`).
+- **Multi-package (Composer path repos / monorepo):** each package exposes a narrow public API; application ports may live in an `*-api` / `*-contracts` package; adapters depend inward. Do not invent multi-package scaffolding unless the repo already uses it.
+- Path repositories / `"repositories": [{"type":"path",...}]` — treat each package's `composer.json` `autoload.psr-4` as that package's boundary SoT.
+
+## composer.json
+
+- Package name, PHP version, and PSR-4 map are SoT for toolchain/autoload.
+- Prefer minimal direct deps; pin via `composer.lock` the repo already uses.
+- Dev-only tools (PHPUnit, PHPStan) stay in `require-dev` — not runtime public API.
+
+## Cross-feature
+
+- Inside one package, features communicate via application ports or small public facades — not by importing sibling feature adapter namespaces (`Adapters/Inbound/...` of another feature).
+- Domain and application types may be shared within the package; adapter DTOs stay local to that adapter.

package/presets/cursor/php-hexagonal/rules/persistence-adapters.mdc

@@ -0,0 +1,35 @@
+---
+description: Persistence driven adapters (PDO/ORM/repos) for PHP hexagonal services
+globs:
+  - "**/Adapters/Outbound/Persistence/**/*"
+  - "**/adapters/outbound/persistence/**/*"
+  - "**/adapters/persistence/**/*"
+  - "**/*Repository*.php"
+alwaysApply: false
+---
+
+
+# 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/cursor/php-hexagonal/rules/php-app-core.mdc

@@ -0,0 +1,37 @@
+---
+description: PHP/Composer hexagonal stack, module layout, and agent entry points
+alwaysApply: true
+---
+
+
+# Стек и окружение
+
+Версии PHP и зависимостей — **из `composer.json` / `composer.lock` целевого репозитория**. Рамка preset:
+
+- **Язык / платформа:** PHP **8.x** + **Composer** + **PSR-4** namespaces.
+- **Архитектура:** hexagonal (ports & adapters); domain не знает HTTP/ORM/брокеры.
+- **Framework:** framework-agnostic HTTP edge; Slim / Symfony HttpFoundation / Laravel HTTP — **variants in Stack notes only** (не Laravel-first).
+- **Тесты:** PHPUnit default; Pest — если уже в репо/CI.
+- **Static / format:** PHPStan/Psalm / PHP-CS-Fixer/Pint — только если уже сконфигурированы.
+- **HTTP:** thin controllers at the edge; map DTO ↔ application/domain.
+
+# Структура (default: layer-first)
+
+```text
+src/
+  Domain/
+  Application/              # use cases + port interfaces
+  Adapters/Inbound/Http/
+  Adapters/Outbound/Persistence|Messaging|External/
+  Composition/              # bootstrap / DI wiring (no business logic)
+tests/
+  Unit/
+  Integration/
+composer.json
+```
+
+**Feature-first variant:** `src/<Feature>/{Domain,Application,Adapters}` — same dependency direction.
+
+Namespace base — из Composer PSR-4 map (`App\Domain\…` и т.п.); не изобретать classmap.
+
+Границы — **`architecture-boundaries.mdc`**. Tooling — requestable **`php-tooling.mdc`**. После правок PHP — **`post-change-test.mdc`**.