@bonesofspring/ai-rules 0.2.25 → 0.2.26

package/presets/opencode/php-hexagonal/opencode.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@upstash/context7-mcp@4.0.2"
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,20 @@
+# OpenCode PHP hexagonal rules
+
+Plain Markdown. OpenCode does **not** auto-load these files. Root `AGENTS.md`
+and `.opencode/AGENTS.md` list four essential paths to Read immediately; the
+rest are lazy-loaded when the task matches.
+
+Do not put this catalog into `opencode.json` `instructions` as the only
+always-on path (V2 may ignore that field).
+
+## Essential (entry-critical)
+
+`php-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`,
+`ai-local-overlay`.
+
+## Requestable
+
+All other `*.md` files in this directory. Same stems as Cursor
+`rules/README.md`.
+
+Shared-core markers (`<!-- shared-core: … -->`) are preserved from Cursor.

package/presets/opencode/php-hexagonal/rules/adapters-driven.md

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

package/presets/opencode/php-hexagonal/rules/adapters-driving.md

@@ -0,0 +1,30 @@
+
+# Driving adapters
+
+- Translate transport → application calls → transport response.
+- Map request/response DTOs at the edge; do **not** pass framework request/security types into use cases.
+- AuthN/AuthZ and wire-format validation belong here (or middleware); domain validation stays in domain.
+- Errors: map domain/application exceptions to status codes once (central exception listener / middleware preferred).
+- Keep controllers/handlers thin: decode → call use case → encode; no multi-step workflows or SQL in the adapter.
+
+## Layout
+
+Default (layer-first): `Adapters/Inbound/Http/` (and `…/Grpc/`, `…/Cli/` as needed). Flat `adapters/http/` is an accepted variant when the repo already uses it.
+
+## HTTP
+
+- See `api-http.md`. Prefer thin controllers/actions; routing in one place.
+- Bind path/query/body into request DTOs and validate at the edge before calling application.
+- Framework choice (Slim, Symfony, Laravel, plain PHP) is optional — match the repo.
+
+## gRPC / CLI / messaging consumers
+
+- Same mapping rules; see stub `api-grpc.md` for protobuf notes; messaging consumers that trigger use cases are driving adapters (`messaging-adapters` stub).
+- CLI entrypoints may call composition root or inbound ports — **no** SQL in `bin/` scripts.
+- Propagate cancellation/timeouts from the transport into use-case calls when the stack supports it.
+
+## Forbidden
+
+- SQL, DQL, or business invariants inside controllers.
+- Importing persistence packages from HTTP handlers (wire via application ports).
+- Swallowing exceptions without mapping to a transport status / structured log field.

package/presets/opencode/php-hexagonal/rules/agent-team-intake.md

@@ -0,0 +1,11 @@
+<!-- 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 (“how does X work”, “explain”) — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
+
+Exceptions: user explicitly says “no pipeline”, “just do it”, or continues an active slug.

package/presets/opencode/php-hexagonal/rules/agent-team-orchestrator.md

@@ -0,0 +1,214 @@
+<!-- shared-core: agent-team/agent-team-orchestrator.md -->
+
+# Agent team orchestrator
+
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.ai.local/team/tasks/<slug>/`.
+
+Work request without `/task` — see **agent-team-intake** (when to suggest the router instead of coding directly).
+
+## Entry points
+
+| Command | When |
+|---------|------|
+| **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After human gate or pause |
+| `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
+| `/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` (plus skill `ux-design` for behavioral UX **where the stack has a UI surface**), `solution-architect`, `migration-specialist` |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer and `mockup-reviewer` **only when the stack has a UI surface** |
+| Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
+| Docs | `tech-writer` |
+
+**OpenCode frontmatter:** all team pipeline agents use `mode: subagent` and `permission.edit` so they can write team artifacts (`edit: allow` for implementers; deny except `.ai.local/team/**` for reviewers/planners). Production/app restrictions live in the agent prompt body. See `agents/README.md`.
+
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`; schema SoT: **agent-artifact-contracts**.
+
+## Stack notes
+
+Roles, write scopes, and OpenCode `mode` / `permission` packaging — **`agents/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.
+
+## Routing decision contract
+
+Keep top-level `profile` (`light` | `standard` | `full`) and add a top-level `routingDecision` object:
+
+```json
+{
+  "profile": "standard",
+  "routingDecision": {
+    "complexity": "moderate",
+    "riskFlags": ["behavior-regression"],
+    "routingReasons": [
+      "The failure needs root-cause analysis before a bounded fix.",
+      "Behavior changes require validation and independent review."
+    ],
+    "estimatedWorkPackages": 1,
+    "openDecisionCount": 0
+  }
+}
+```
+
+| Field | Contract |
+|-------|----------|
+| `complexity` | `low` \| `moderate` \| `high`; classify scope and coordination, not perceived coding difficulty |
+| `riskFlags` | Array of concrete signals such as `public-contract`, `cross-layer`, `security-sensitive`, `migration`, `destructive`, `concurrency-state`, `external-dependency`, `unclear-acceptance-criteria`, `broad-test-surface`, `behavior-regression` |
+| `routingReasons` | Non-empty, auditable facts from the request; each reason explains a profile, gate, specialist, skip, or checkpoint choice |
+| `estimatedWorkPackages` | Integer ≥1; count meaningful independently verifiable delivery scopes, not files or agents |
+| `openDecisionCount` | Integer ≥0; unresolved product/architecture/contract choices at routing time |
+
+Rubric:
+
+- `low`: one bounded scope, explicit acceptance criteria, reversible change, no risk flags or open decisions. Use `light` only when stack verification policy permits.
+- `moderate`: several files or adjacent concerns, a regression/refactor with known boundaries, or one contained risk flag. Usually `standard`.
+- `high`: cross-layer/public-contract work, migration/destructive/security/concurrency risk, broad test surface, multiple work packages, or unclear acceptance criteria. Usually `full`.
+- Increase the profile when risk, open decisions, or required checkpoints demand it; do not lower complexity merely because the implementation is familiar.
+- Do not write generic reasons such as “standard by default.” Name the observed signal and the routing consequence.
+
+Existing pipelines without `routingDecision` remain valid; routers emit it for new pipelines. The block is documentary routing evidence in P0 and does not change hook behavior.
+
+## Metrics lifecycle
+
+For local metrics policy and the `metrics.json` ledger, see **agent-task-metrics**. The orchestration runtime records `task_started` and one `attempt_started` before each invocation; the hook records host-clock terminal and human-gate events. Keep active attempt identities in `status.json.activeAttempts` so parallel completions can be bound safely.
+
+Do not calculate durations in agents. For parallel steps, never attribute a stop using `currentAgent` alone: use a stable runtime identity, the sole active attempt, or an explicit receipt marked with fallback confidence.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. The full schema and completion conventions live in **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 points to authoritative paths and records producer, status, 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 unrelated 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 |
+
+| 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 |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt (`completed` \| `changes_requested` \| `validation_failed`) when agents left lifecycle fields untouched. Parent orchestrators must wait for that handoff before invoking the next step.
+
+## 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`, `mockup-review.md`, `ux-design.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer. Exception: embedded `mockup-reviewer` FAIL (`changes_requested` while the completed/current agent is `mockup-reviewer`) → `awaiting_approval` / `/task-continue` only — do **not** `retryAfterFix` to developer.
+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
+
+- 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, fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+
+## Skip pipeline when
+
+Do **not** run `/task` + router for:
+
+- Pure questions («как работает X» (how does X work), «объясни» (explain)) — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners. <!-- i18n-keep: E4 -->
+- Typo / one-file fix / trivial config with no architecture risk.
+- User explicitly says «без pipeline» (no pipeline), «просто сделай» (just do it), or continues an active slug. <!-- i18n-keep: E4 -->
+- Single-line `docs-only` with no code impact.
+
+Borderline work requests — see **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**.

package/presets/opencode/php-hexagonal/rules/ai-local-overlay.md

@@ -0,0 +1,37 @@
+# Local overlay (`.ai.local/`) — MANDATORY
+
+This rule is mandatory. **You MUST** obey it on every turn, without exception.
+
+## On every turn
+
+1. **Probe** — before answering, run `ls -la .ai.local` from the repository root.
+2. **Walk** — if `.ai.local/` exists at multiple levels (monorepo), read every level from root to leaf. **Deeper wins** in practice: more specific rules appear later in the assembled context and take precedence.
+3. **Apply** — treat every `.ai.local/rules/*.md` and `.ai.local/conventions.md` as a higher-priority rule for this repo. Do **not** load `.ai.local/team/**` as rules (shared pipeline artifacts). The block below ("Authoring `.ai.local/rules/*.md`") defines the conventions.
+4. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
+5. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
+
+If `.ai.local/` does not exist → **no-op**, do not error. Do not produce any log line about its absence.
+
+## Authoring `.ai.local/rules/*.md` (consumer-side reference)
+
+Each `.ai.local/rules/<name>.md` is a plain-markdown rule body. The model parses it as:
+
+- Lines before `## Body` are scope metadata. Only `glob:` / `globs:` / `override:` lines are recognised.
+- Everything from `## Body` onward is the rule body.
+- `glob: always` → always-on. Counts against your context budget.
+- `globs: <comma-separated globs>` → on-demand; applies only when matching files are in focus.
+- `override: kill <preset-rule-name>` → drop that preset rule from context.
+
+Keep files ≤ 120 lines. Match the style of preset rules (short sections, bullets, code examples).
+
+## Limitations (read this)
+
+- Cursor/Claude do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
+- If a user adds a file to `.ai.local/` mid-session, **restart the session** to be sure it is picked up.
+- "Priority" is **contextual**, not enforced. Always re-read the local rule before answering questions that touch it.
+
+## Pointers
+
+- Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package.
+- Living gotchas: `.ai.local/conventions.md`. Pipeline artifacts: `.ai.local/team/` (do not load as rules).
+- Root `AGENTS.md` reinforces this rule with a `MANDATORY` section.

package/presets/opencode/php-hexagonal/rules/anti-sycophancy-discipline.md

@@ -0,0 +1,23 @@
+<!-- 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 that is not enough and Context7 MCP is available, load **`mcp-usage`** and query docs for the **installed major**. If you still 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/opencode/php-hexagonal/rules/api-grpc.md

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

package/presets/opencode/php-hexagonal/rules/api-http.md

@@ -0,0 +1,28 @@
+
+# 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/opencode/php-hexagonal/rules/application-usecases.md

@@ -0,0 +1,25 @@
+
+# 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/opencode/php-hexagonal/rules/architecture-boundaries.md

@@ -0,0 +1,31 @@
+
+# Layer boundaries (hexagonal)
+
+- **Domain** (`**/Domain/**`, `**/domain/**`):
+  - May: entities, value objects, domain services, domain errors; PHP stdlib / same BC domain.
+  - Must not: framework HTTP kernels, Eloquent/Doctrine as domain types, broker SDKs, transport DTOs.
+- **Application** (`**/Application/**`, `**/application/**`):
+  - May: use cases; **define ports** (inbound/outbound interfaces) with domain types in signatures.
+  - Must not: 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.
+
+# Dependencies
+
+- Direction: **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`)
+
+# Agent requirement
+
+- Place files in the correct layer; do not short-circuit layers for speed.
+- DI / wiring only in composition / bootstrap.

package/presets/opencode/php-hexagonal/rules/code-quality-and-refactoring.md

@@ -0,0 +1,40 @@
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+
+# Match existing style
+
+- Follow existing patterns (names, structure, typing / DI / error handling); avoid drive-by formatting or renames.
+- Before a new solution: find an analog and **repeat the approach**; check the design system / UI packages; go only through the **public API** (deep imports are a reason to refactor).
+
+# Principles
+
+- **KISS:** the simplest change in the repository’s patterns.
+- **DRY + Rule of Three:** share only after the 3rd repetition (wrong abstraction costs more than duplication).
+- **YAGNI:** no APIs, flags, or “for later” layers without a current requirement.
+- **SOLID:** S — one reason to change; O — composition/new implementations; L — subtype contract; I — narrow ports; D — abstractions (ports), details in stack adapters.
+- **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
+- **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
+
+# Refactoring during changes
+
+- Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.
+- Examples: shared utility/hook/mapper/use case; narrow unsafe types; split a large module; tokens instead of “magic”; deep import → public API.
+- Do not do a “big” refactor on a point task (structure/public names without a request). Break large work into minimal steps; keep the repo buildable after each step.
+
+# Agent requirement
+
+- **Boy scout:** leave the module a bit better; do not sacrifice architecture and layers for brevity.
+
+## Agent discipline (anti-sycophancy)
+
+Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
+
+- Unverifiable third-party API → if Context7 is up, load **`mcp-usage`** and query the installed major; else 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, examples, and toolchain — in the preset adapter **Stack notes** section.

package/presets/opencode/php-hexagonal/rules/code-review-mr.md

@@ -0,0 +1,40 @@
+<!-- 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`; do not expand the full Fowler catalog outside the diff
+- Pattern name (GoF) — only if the repository already uses that shape or the match is minimal
+- Principles (KISS / DRY+Ro3 / YAGNI / SOLID / CUPID) — via always-on `code-quality-and-refactoring`, do not duplicate the essay in 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 “big refactors” 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`**.

package/presets/opencode/php-hexagonal/rules/composition-root.md

@@ -0,0 +1,27 @@
+
+# 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.