@bonesofspring/ai-rules 0.2.11 → 0.2.13

package/presets/claude/php-hexagonal/rules/architecture/feature-delivery.md

@@ -0,0 +1,53 @@
+---
+description: End-to-end delivery checklist for PHP hexagonal features
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - "**/*.php"
+  - src/**/*
+  - tests/**/*
+  - "**/Composition/**"
+---
+
+<!-- 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/claude/php-hexagonal/rules/architecture/module-public-api.md

@@ -0,0 +1,31 @@
+---
+description: Public module API and package boundaries for PHP services
+paths:
+  - "**/composer.json"
+  - "**/src/**/*.php"
+---
+
+# 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/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,208 @@
+---
+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`; schema SoT: **agent-artifact-contracts**.
+
+## 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.
+
+New pipelines retain top-level `profile` and include `routingDecision` with `complexity`, `riskFlags`, non-empty `routingReasons`, `estimatedWorkPackages`, and `openDecisionCount`. The stack `task-router` owns heuristics; this metadata is auditable evidence and does not change hook semantics.
+
+## Metrics lifecycle
+
+Use the local `metrics.json` ledger described by **agent-task-metrics**: the orchestration runtime initializes attempts before invocation, hooks record host-clock ends, and agents never guess a parallel completion from `currentAgent`.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json`: `.cursor/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. Schema SoT: **agent-artifact-contracts**.
+
+- Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
+- Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
+- Agents upsert only entries they own and preserve foreign entries. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
+- Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
+
+## status.json (pipeline mode)
+
+```json
+{
+  "slug": "...",
+  "intent": "feature",
+  "pipelineIndex": 0,
+  "currentAgent": "task-analyst",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
+  "parallelCompleted": [],
+  "parallelOutcomes": {}
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `activeAttempts` | Transient timing bridge keyed by `attemptId` |
+| `lastCompletedAttempt` | Diagnostic pointer to the latest finished attempt |
+| `parallelCompleted` | Agents that have stopped in the current parallel step |
+| `parallelOutcomes` | Per-agent `{ outcome, attemptId, confidence }` for the current parallel join; cleared when the step advances or retries |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt when agents left lifecycle fields untouched. Wait for that handoff before invoking the next step.
+
+| 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 and update the producer-owned terminal receipt in `artifact-manifest.json`; Markdown remains detailed evidence.
+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, verify its terminal manifest receipt, then let the orchestration runtime/hook reconcile `status.json` (`completed`, a blocking outcome, or `awaiting_approval`) from that receipt. Do not ask the agent to mutate shared lifecycle fields, and do not invoke the next specialist until the hook has written the handoff / updated `status.json`.
+
+## 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`.