@bonesofspring/ai-rules 0.2.10 → 0.2.12

package/presets/claude/php-hexagonal/rules/architecture/ports-interfaces.md

@@ -0,0 +1,34 @@
+---
+description: Inbound and outbound port interfaces for PHP 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 Eloquent/Doctrine entities, PDO statement types, or broker message types.
+- Keep interfaces small (ISP); prefer role interfaces over god-repos (`OrderRepository` vs `EverythingRepository`).
+- Do not put ORM repository base classes in domain; if Eloquent/Doctrine 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 (`DoctrineOrderRepository`, `PdoOrderRepository`), not beside the interface in domain.
+
+## Anti-patterns
+
+- Ports returning untyped `array` bags or framework entities.
+- Putting port interfaces inside adapter packages (wrong owner — adapters implement, application defines).
+- Leakage of `EntityManager`, Eloquent models, or Redis types through port method signatures.
+- One mega-port “for convenience” that every use case depends on.

package/presets/claude/php-hexagonal/rules/architecture/reference-features.md

@@ -0,0 +1,39 @@
+---
+description: Reference paths for PHP hexagonal layout (dogfood/php-hexagonal)
+paths:
+  - "**/Domain/**/*"
+  - "**/Application/**/*"
+  - "**/Adapters/**/*"
+  - "**/Composition/**/*"
+---
+
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features (PHP)
+
+Canonical layout matches `dogfood/php-hexagonal/` (consumer repos may rename; prefer the same shapes). Defaults match layer-first single-module; adjust for feature-first / multi-module variants.
+
+| Area | Example path | Glob hint |
+|------|--------------|-----------|
+| Domain | `src/Domain/` | `**/Domain/**`, `**/domain/**` |
+| Application / ports | `src/Application/` | `**/Application/**`, `**/application/**` |
+| HTTP adapter | `src/Adapters/Inbound/Http/` | `**/Adapters/Inbound/Http/**`, `**/adapters/http/**` |
+| Persistence | `src/Adapters/Outbound/Persistence/` | `**/Adapters/Outbound/Persistence/**` |
+| Messaging | `src/Adapters/Outbound/Messaging/` | `**/Adapters/Outbound/Messaging/**` |
+| Composition root | `src/Composition/` | `**/Composition/**`, `**/bootstrap/**` |
+| Unit tests | `tests/Unit/` | `**/tests/Unit/**`, `**/*Test.php` |
+| Integration | `tests/Integration/` | `**/tests/Integration/**`, `**/*IT.php` |
+
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.claude/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` (`dogfood/php-hexagonal`).
+2. Bug in handler mapping — debugger + controller unit with mocked use case.
+3. Repository contract — integration-test trio + DB fixtures (sample uses in-memory persistence).
+4. OpenAPI/proto drift — api-contract-reviewer.
+5. Secrets in logs — security-reviewer + `security-php`.
+
+Init (maintainer): `node packages/ai-rules/bin/cli.js init cursor --preset php-hexagonal --cwd dogfood/php-hexagonal` — do not commit generated `.cursor/` into the sample unless the team decides otherwise.

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

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

package/presets/claude/php-hexagonal/rules/stack/php-app-core.md

@@ -0,0 +1,35 @@
+---
+description: PHP/Composer hexagonal stack, module layout, and agent entry points
+---
+
+# Стек и окружение
+
+Версии 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`**.

package/presets/claude/php-hexagonal/rules/stack/php-conventions.md

@@ -0,0 +1,51 @@
+---
+description: Idiomatic PHP conventions for this hexagonal preset
+paths:
+  - "**/*.php"
+---
+
+# PHP conventions
+
+- Follow PSR-1 / PSR-12 (or the repo's PHP-CS-Fixer / Pint config) when present.
+- Naming: `PascalCase` classes, `camelCase` methods/properties, namespaces match Composer PSR-4.
+- Prefer `final` classes / `readonly` where the repo already uses them; do not invent a new style mid-module.
+- Prefer typed properties, return types, and `strict_types=1` when neighboring files use them.
+- Prefer PHPUnit data providers / Pest datasets when covering multiple cases.
+- Do not invent library APIs — verify symbols against `composer.json` and existing imports (`// VERIFY:` when unsure).
+
+## Errors / exceptions
+
+- Prefer domain/application exception types extending `\RuntimeException` (or the repo's base) unless public API requires otherwise.
+- Chain causes (`new X($msg, 0, $previous)`); never empty-catch without logging or rethrowing.
+- Prefer domain-specific exception types for structured cases; avoid bare `catch (\Throwable)`.
+- Map to HTTP/gRPC statuses only in adapters — do not throw framework HTTP exceptions 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 / namespaces
+
+- Avoid `Util`/`Common` dumping grounds — name by domain capability.
+- Keep bootstrap / composition / `public/index.php` thin (see `composition-root`).
+- No static mutable request state; no business logic in static initializers.
+
+## Concurrency / async
+
+- Match existing patterns (sync request/response by default; Fibers/async only if the repo already uses them).
+- Do not start unbounded background workers from handlers without a shutdown/supervision story.
+
+## 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 packages not in `composer.json` | Add dependency explicitly or copy existing import |
+| Untyped `array` where a VO/DTO fits | Typed objects / arrayshape used by the repo |
+| Business logic in bootstrap | Wire in composition root |
+
+## Agent requirement
+
+New PHP code must stay idiomatic and verifiable against `composer.json` and neighboring packages. Less guessed code is better than more.

package/presets/claude/php-hexagonal/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/php-hexagonal/rules/testing/e2e.md

@@ -0,0 +1,35 @@
+---
+description: Optional end-to-end / smoke tests for PHP hexagonal services
+paths:
+  - "**/tests/E2E/**/*"
+  - "**/tests/e2e/**/*"
+  - "**/*E2ETest.php"
+  - "**/*SmokeTest.php"
+---
+
+# E2E / smoke tests (optional)
+
+- Prefer **`integration-test-*`** for adapter contracts; treat e2e/smoke as a thin optional layer above PHPUnit integration.
+- Smoke may hit a running service (`php -S` / container) or boot the HTTP kernel end-to-end when the repo already has that harness.
+- Keep scenarios few and stable: health/ready, one happy-path create/read — not a second unit suite.
+- Place under `tests/E2E/` or `*SmokeTest.php` / `*E2ETest.php` when the repo uses those names.
+
+## Boundary vs integration
+
+| Layer | Typical scope |
+|-------|----------------|
+| Integration | Adapter + real/fake infra (DB fixture, in-process HTTP controller) — **default** for delivery |
+| E2E / smoke | Process or network boundary (boot `public/index.php`, hit `/todos`) — optional |
+
+If the repo only has `tests/Unit` + `tests/Integration`, do **not** invent an e2e framework.
+
+## Non-goals
+
+- Playwright browser e2e, XCUITest, or accessibility-reviewer — **out of this preset**.
+- Mandating a separate e2e framework if the repo only has PHPUnit integration tests.
+
+## Related
+
+- Integration depth: `tests-integration` + `integration-test-*`.
+- Sample smoke entry: `dogfood/php-hexagonal/public/index.php` (optional local server).
+- Gates: `post-change-test` / `php-tooling` — never yarn lint or browser stacks.

package/presets/claude/php-hexagonal/rules/testing/integration.md

@@ -0,0 +1,31 @@
+---
+description: Integration / adapter contract tests for PHP hexagonal services
+paths:
+  - "**/*IT.php"
+  - "**/*IntegrationTest.php"
+  - "**/integration/**"
+  - "**/tests/**/*IT.php"
+---
+
+# Integration tests
+
+- Exercise adapters against real collaborators the repo already supports (DB, HTTP kernel, message duals).
+- Prefer repository/CI fixtures (test DB, docker-compose, existing harness) — do not invent a new stack.
+- Keep domain/use-case pure logic in unit tests; integration proves wiring + contracts.
+- Agents: `integration-test-planner` → `generator` → `healer`; skill `integration-testing`.
+
+## Scope
+
+- Persistence adapters against a real schema/migration set.
+- HTTP contract tests through the framework kernel with faked or real outbound ports as the repo does.
+- Messaging consumer/publisher contracts when the repo has broker test duals.
+
+## Forbidden
+
+- Requiring Playwright, XCUITest, or yarn `lint:js`/`lint:css` as PHP integration gates.
+- Turning every use-case test into a full-kernel boot when a unit fake suffices.
+
+## Related
+
+- After edits: `post-change-test` (+ `php-tooling`).
+- Unit: `tests-unit`; optional smoke: `tests-e2e`.

package/presets/claude/php-hexagonal/rules/testing/unit.md

@@ -0,0 +1,32 @@
+---
+description: Unit testing conventions for PHP hexagonal services
+paths:
+  - "**/*Test.php"
+  - "**/*Tests.php"
+  - "**/tests/**"
+---
+
+# Unit tests
+
+- Prefer **PHPUnit** (or **Pest** if already in repo/CI); 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; PHPUnit mocks / Prophecy / Mockery only if the repo already uses them.
+- Prefer data providers / Pest datasets when covering multiple cases.
+- Skip integration/e2e files matching `*IT.php`, `*IntegrationTest.php`, dirs `Integration/`, `E2E/` — those use other rules.
+
+## Scope
+
+- Domain factories/invariants; application use cases with port fakes; pure mappers.
+- Adapter unit tests may exercise controllers with a mocked use case — still no live DB.
+
+## Forbidden smells
+
+- Framework request/response types in **domain** tests.
+- SQL or live HTTP in use-case unit tests.
+- Brittle tests on private adapter internals without need.
+- Booting a full framework kernel for a pure domain/unit case.
+
+## Naming
+
+- `UseCaseDoXTest` / `EntityInvariantTest` (or Pest `describe`/`it` if that is the repo style).
+- Match PHPUnit/Pest patterns CI already uses.

package/presets/claude/php-hexagonal/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` |
+| [`php-tooling.md`](./php-tooling.md) | `php-tooling.mdc` |
+| [`security-php.md`](./security-php.md) | `security-php.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/php-hexagonal/rules/tooling-and-review/agent-team-intake.md

@@ -0,0 +1,26 @@
+---
+description: Suggest /task for PHP backend work requests
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - "**/*.php"
+  - src/**/*
+  - "**/Composition/**"
+  - "**/Composition/*"
+---
+
+<!-- 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: PHP services (`src/**`, `Composition/`, `Composition/*`) — hexagonal ports/adapters — not Playwright/XCUITest UI flows.

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

@@ -0,0 +1,183 @@
+---
+description: Orchestrates the agent team via task-router and pipeline.json for PHP presets
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - "**/*.php"
+  - src/**/*
+  - "**/Composition/**"
+  - "**/Composition/*"
+---
+
+<!-- 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.
+
+## Metrics lifecycle
+
+Use the local `metrics.json` ledger described by **agent-task-metrics**: initialize attempts before invocation, let hooks record host-clock ends, and never guess a parallel completion from `currentAgent`.
+
+## 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 (PHP 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: PHP hexagonal (`src` domain|application|adapters, `Composition/` / `Composition/*`) — not Next `app/src` or iOS `Features/`.
+- After PHP code changes, pipeline includes **build-verifier** with `composer test` / `vendor/bin/phpunit` + `post-change-test` / `php-tooling` (static analysis only if repo/CI already configures it).
+- Chain hook handoffs: `integration-test-*`, `post-change-test`, `php-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/php-hexagonal/rules/tooling-and-review/anti-sycophancy-discipline.md

@@ -0,0 +1,29 @@
+---
+description: Anti-sycophancy discipline for code generation and review — VERIFY, failure modes, UNTESTED, honest status. Load when writing or changing code.
+paths:
+  - "**/*.php"
+---
+
+<!-- shared-core: quality/anti-sycophancy-discipline.md -->
+
+# Anti-sycophancy discipline (requestable)
+
+Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
+
+1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If you cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+2. **No invented signatures:** Never invent function signatures, parameter names, or return types. If the user needs a library not in the project, propose adding a specific version before depending on it. Silent stubs are worse than refusal.
+3. **Enumerate edge cases before validating:** When asked "is this correct?" or "does this work?", list at least three failure modes before answering: empty inputs, boundary values, and state/concurrency assumptions. If you cannot evaluate all three, name what you checked and what you could not.
+4. **Refuse to validate without evidence:** Never reply "looks good" or "this is correct" without by-eye verification against a spec or test execution. If no spec exists, ask for one or refuse to validate.
+5. **Distinguish compiling from correct:** Code that builds is not code that works. Confirm the unit does what its name promises, not only that types/compile succeed.
+6. **Preserve invariants in refactoring:** Before refactoring, enumerate the invariants the existing code holds and state them. After the refactor, verify each still holds.
+7. **Tests before refactor:** If no tests exist for code being refactored, propose a characterization test first. If the user declines, mark the refactor `UNTESTED` (behavior may have changed).
+8. **Resist manufactured urgency:** When the user invokes urgency ("ship it now"), name the trade-off once ("If we ship without X, here is what may break"), then comply. Do not repeat the warning or apologize in a loop.
+9. **Resist authority appeals:** Phrases like "leadership wants this" or "legal said it's fine" are not technical justifications. Evaluate on technical grounds.
+10. **Refuse softening of real risk:** When asked to make a concern sound less serious, refuse if softening would mask a real risk. If the risk is genuinely minor, comply and explain why.
+11. **Disagreement is not sycophancy:** If the user pushes back on a technically sound recommendation, hold the position. Update only on new evidence, not on emotional pressure or repetition.
+12. **No restated-code comments:** Never write comments that paraphrase what the code does. Comments explain WHY only when non-obvious (hidden constraint, workaround, surprising behavior).
+13. **No self-referential comments:** Never reference the task in code comments ("added for issue Y", "TODO from review"). Those belong in commits/PRs and rot as the codebase evolves.
+14. **Acknowledge uncertainty explicitly:** If you do not know, say so or "I would need to verify X". Do not invent a plausible-sounding answer.
+15. **Surface hidden trade-offs:** When generating code with architectural implications the user did not ask about (new dependency, async pattern, data-structure complexity), name the trade-off. Do not bury it.
+16. **Match verification to risk:** Trivial → syntax/type check. Logic → manual trace. Concurrency/state → written scenario. Skipping verification proportional to risk is the failure mode.
+17. **Honest status reporting:** When asked "is X done?", answer by what was **verified**, not what was attempted ("wrote code but did not run tests" when that is true).

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

@@ -0,0 +1,53 @@
+---
+description: Code quality and light refactoring for PHP hexagonal services
+---
+
+<!-- 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.