@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/opencode/php-hexagonal/skills/feature-delivery/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: feature-delivery
+description: "Delivers PHP hexagonal backend features end-to-end across domain, application/ports, adapters, composition root, tests, and post-change-test validation. Use when implementing or extending a feature, especially through /task or feature-developer."
+---
+
+# Feature Delivery (PHP hexagonal)
+
+1. Read brief, AC, and decomposition.
+2. If `docs/specs/INDEX.md` exists **or** brief/handoff lists approved generated specs, resolve via **`product-specs`** and treat approved specs as behavior SoT before layer work (soft-fail on miss — do not invent behavior). If generation was requested but not yet approved, stop for human gate — do not implement against draft-only gaps.
+3. Follow `feature-delivery-workflow.md` + `reference-features.md`: domain → application/ports → driven adapters → driving adapters → composition root → tests.
+4. Wire DI only in `Composition/` / `Composition/*`.
+5. Add unit tests for domain/use cases; integration tests for risky adapters.
+6. After PHP edits: **invoke** `post-change-test.md` (+ `php-tooling.md`).
+
+## Do / Don't
+
+- **Do** keep ports owned by application; map wire types at adapters.
+- **Don't** put SQL/business rules in HTTP handlers or frameworks in domain.
+- **Don't** use Playwright, XCUITest, or yarn lint as this stack's gate.
+
+## Scope discipline
+
+Implement only the current AC / decomposition task. Clarify ambiguity before coding; do not add unrelated hardening or drive-by refactors. See `feature-developer` → **Zero improvisation**.
+
+## Handoff
+
+Summarize by layer + validation. Agent team: upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/opencode/php-hexagonal/skills/integration-testing/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: integration-testing
+description: "Plans, generates, and heals PHP integration and adapter contract tests (HTTP controller tests, integration DB fixtures). Use for integration-test-* agents or adapter/e2e coverage."
+---
+
+# Integration testing (PHP)
+
+1. Read `tests-integration` / `tests-e2e` rules and task brief.
+2. Prefer testing driven adapters behind ports; HTTP adapters with `HTTP controller tests` + fakes.
+3. Use build tags / CI job split if the repo already does.
+4. Do not introduce Playwright or XCUITest.
+
+## Agents
+
+`integration-test-planner` → `integration-test-generator` → `integration-test-healer` as needed.

package/presets/opencode/php-hexagonal/skills/spec-authoring/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: spec-authoring
+description: "Author or bootstrap consumer docs/specs (INDEX, page/feature templates, frontmatter v1). Use with task-analyst author mode, /spec-start, or when brief AC requests Generate/Bootstrap."
+---
+
+# Spec authoring
+
+Requestable — not always-on. Load **`product-specs`** + **`product-specs-authoring`** first.
+
+## Steps
+
+1. **Resolve mode** — Generate (tree exists) vs Bootstrap (create INDEX + templates + first spec). Refuse inventing INDEX without explicit intent/AC/`/spec-start`.
+2. **Ensure templates** — if consumer `docs/specs/_templates/` missing, copy from package SoT `presets/_shared/assets/docs-specs/_templates/` (or seeded init assets).
+3. **Fill frontmatter v1** — all array keys present (may be `[]`); prefer `type: feature` on backend/MCP; default `status: draft`.
+4. **Fill required body headings** — page: Overview, Entry/actors, Primary flows, States, Acceptance criteria; feature: Overview, Shared behavior/constraints, Related pages. Use `N/A` explicitly when needed.
+5. **Update INDEX** in the **same change set** (columns: id, type, domain, title, path, optional routes/aliases/status).
+6. **Self-check** against `product-specs-authoring` checklist; put blockers in `open_questions`.
+7. **Handoff** — list created/updated paths + INDEX diff for human gate (`after:task-analyst`). Approve before feature-developer.
+
+## Sources
+
+Cite AC / user / Figma / labeled code inference. Do not invent product behavior.
+
+## mcp-ts
+
+Analyst-only path (no tech-writer). `routes` = tool names; `ui`/`store` = `[]`.

package/presets/opencode/php-hexagonal/skills/spec-discovery/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: spec-discovery
+description: "Opt-in research-before-spec for task-analyst author mode. 11 named methods plus a mandatory claim ledger. Use when the user or AC asks discovery before generating docs/specs — not default /task consume."
+---
+
+# Spec discovery
+
+Requestable — **not** always-on. Load **only** in **task-analyst author mode** when the user or AC asks research-before-spec (including `/spec-start` with that intent). Never default consume `/task`. Not a pipeline step.
+
+Load **`product-specs`** (and **`product-specs-authoring`** after this skill if authoring follows). Do **not** invent product behavior. Do **not** create a second spec-file tree.
+
+## Load policy
+
+1. Pick a **subset** of methods that fit the task — not all 11 every time.
+2. **`claim-ledger` is mandatory** whenever this skill runs.
+3. Write chronological notes to `.ai.local/team/tasks/<slug>/.memlog.md` (append-only). Do **not** mutate `status.json` / `metrics.json`.
+4. Discovery output lives in memlog + `brief.md` sections. Then hand off to skill **`spec-authoring`** (or stop if `specMode: none`).
+
+Backend / MCP stacks: skip UI-only examples; prefer `analog-scan`, `code-archaeology`, `problem-define`, `assumption-audit`, `claim-ledger`.
+
+## Methods
+
+| Method | Produces | Skip when |
+|--------|----------|-----------|
+| **intake-capture** | Raw idea, origin, first unknowns → memlog + brief Research inputs | User prompt + AC already complete |
+| **index-locator** | Related INDEX rows + linked spec paths + gaps | `specMode: none` or INDEX absent without consume intent |
+| **code-archaeology** | Observed behavior labeled `inferred`/`draft` with path citations | Greenfield with no relevant code |
+| **research-pack-scan** | Claims from `team/tasks/<slug>/research/**` or user-supplied paths | No research paths cited |
+| **evidence-against** | Reasons the idea may fail | Internal spike with no product/external risk |
+| **problem-define** | Who hurts, goals, non-goals, cost of inaction → brief | Brief Goal + Out of scope already exhaustive |
+| **concept-shape** | 2–3 approach options + appetite (small/medium/large); no API design | `architecture.md` exists or one obvious path |
+| **working-backwards-check** | Headline + 5 customer objections + verdict `forged` / `needs-heat` / `cracked` | Consume mode with approved specs |
+| **assumption-audit** | Assumption register → brief Assumptions + `open_questions` | Never skip in author mode (keep lightweight) |
+| **analog-scan** | 2–3 repo analogs via `reference-features` / code search | No plausible analog |
+| **claim-ledger** | Markdown table `source → claim` for every product-behavior claim | **Never skip** when this skill is loaded |
+
+## Claim ledger (required)
+
+Block spec authoring until every product-behavior claim has a source:
+
+```markdown
+| Source | Claim |
+|--------|-------|
+| brief AC-3 | Checkout shows empty cart copy |
+| code-archaeology inferred | Empty state uses an illustration |
+```
+
+Sources: AC / user / UI copy / labeled code inference / research path. Unsourced claims → `open_questions`.
+
+## Memlog
+
+Path: `.ai.local/team/tasks/<slug>/.memlog.md`. Chronological `## YYYY-MM-DD` headings. Optional tags: `decision`, `assumption`, `override`, `event`, `claim`.
+
+## Forbidden
+
+- 108-technique catalogs, HTML composers, party-mode, five `assess.*` slash commands, Python memlog runtime.
+- Dummy INDEX rows when `specMode: none`.
+- Dumping the whole `docs/specs/**` tree — locator is INDEX → linked page + optional `feature.md`.

package/presets/opencode/php-hexagonal/skills/technical-retro/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: technical-retro
+description: "Facilitates technical retrospectives for tasks, sprints, incidents, releases, and agent-team pipelines. Use when the user asks for retro, postmortem, process review, or action items after delivery."
+---
+
+# Technical Retro
+
+## Inputs
+
+Ask for missing period, focus, task slug, participants, or format constraints. If a slug is provided, read `.ai.local/team/tasks/<slug>/` artifacts and local git status/diff. Do not invent facts not present in artifacts or the user's message.
+
+## Facilitation Principles
+
+- Focus on process and system behavior, not blame.
+- Separate facts, interpretations, and proposed actions.
+- Balance what worked with what slowed delivery.
+- Keep action items concrete, owned, and measurable.
+
+## Default Structure
+
+1. Goal and scope.
+2. Timeline or factual observations.
+3. What worked.
+4. What hurt quality, speed, or confidence.
+5. Root causes for the top one or two issues.
+6. Experiments and action items.
+
+## Agent Team Block
+
+For `/task` pipelines, include router, analyst, developer, **build-verifier** (composer test / vendor/bin/phpunit), reviewer, QA/integration tests, hooks, and rules.
+
+## Wrong-turn taxonomy (optional)
+
+When artifacts or the user mention agent mistakes, tag incidents:
+
+| Kind | Signal |
+|------|--------|
+| `correction` | User pushback («no», «don't», «actually») |
+| `retry` | Same tool/approach 2+ times before success |
+| `waste` | Many searches before the right file |
+| `reversal` | Edit then revert / delete |
+| `dead-end` | Env/tool failure (missing binary, wrong path) |
+
+Severity: **high** (explicit correction / large waste) · **med** · **low**. Confidence 0–100 — be honest; low-confidence items are optional.
+
+## Preset feedback loop
+
+If the same issue appeared in **2+** tasks (or **3+** for packaging a new rule/skill — Rule of Three), add section **Preset updates**:
+
+- Proposed change to `.opencode/rules/`, `.opencode/agents/`, `.opencode/skills/`, or **`.ai.local/conventions.md`** (prefer conventions for project gotchas)
+- One concrete snippet or file path
+- Whether it belongs in always-on vs globs vs skill vs conventions (see `PRESET-CONTRIBUTION` → Building blocks)
+
+Do not apply preset or conventions changes without user approval.

package/presets/opencode/php-hexagonal/skills/unit-testing/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: unit-testing
+description: "Plans, generates, and heals parameterized PHPUnit unit tests for domain, use cases, and mappers using *Test.php and tests-unit rules. Use for unit-test planning, generation, or healing."
+---
+
+# Unit testing (PHP)
+
+1. Prefer PHPUnit `@ParameterizedTest` (and PHPUnit assertions assertions) beside code under test (`*Test.php`).
+2. Fake outbound ports for use cases with PHPUnit mocks; no real DB/network.
+3. Follow `tests-unit.md`; heal with `unit-test-healer` when red.
+
+## Agents
+
+`unit-test-planner` → `unit-test-generator` → `unit-test-healer`.

package/presets/opencode/php-hexagonal/skills/write-adr/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: write-adr
+description: "Author an Architecture Decision Record (ADR) with Context, Decision, Consequences, and Links. Use when capturing a durable technical choice for the team."
+---
+
+# Write ADR
+
+On-demand skill for durable architecture decisions. Stack-agnostic sections — fill with project-specific paths and links.
+
+## When to use
+
+- Choosing between non-trivial alternatives (storage, layering, library, API shape).
+- Recording a decision that future agents/humans should not silently reverse.
+- User asks for an ADR, decision log, or “why did we pick X”.
+
+## Template
+
+Create (or append) a short markdown ADR in the repo’s agreed location (e.g. `docs/adr/`, `.ai.local/team/`, wiki). Suggested filename: `NNNN-short-title.md`.
+
+```markdown
+# ADR NNNN: <Title>
+
+## Context
+What problem / constraint / force requires a decision?
+
+## Decision
+What we chose (one clear option). Include rejected alternatives briefly if useful.
+
+## Consequences
+Positive and negative outcomes; follow-up work; what becomes harder.
+
+## Links
+Related PRs, issues, rules, prior ADRs, diagrams.
+```
+
+## Guidelines
+
+- Prefer one decision per ADR.
+- Keep Context factual; Decision imperative and short.
+- Link living gotchas to `.ai.local/conventions.md` when the decision becomes a recurring local pattern.
+- Do not put ADR bodies only in root `AGENTS.md` (overwrite on init).

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

@@ -0,0 +1,77 @@
+# Agent team artifacts
+
+Shared `/task` runtime for Cursor, Claude, Mavis, and OpenCode. Seeded at **`.ai.local/team/`**. Overlay must not load this tree as rules.
+
+`init` refreshes README + fixtures. It never overwrites `tasks/<slug>/`. `clean <tool>` never deletes `.ai.local/`.
+
+## Layout
+
+```
+.ai.local/team/
+  README.md
+  active-task.json           # current slug pointer (runtime)
+  fixtures/                  # pipeline profile examples
+  tasks/<slug>/
+    pipeline.json            # router-owned plan
+    status.json              # hook-owned lifecycle
+    metrics.json             # hook-owned append-only ledger
+    artifact-manifest.json   # producer receipts
+    brief.md, decomposition.md, implementation.md, review.md, …
+    .memlog.md               # optional agent notes (hook does not parse)
+```
+
+Bootstrap a slug by **writing** `pipeline.json` (editor Write tool). Do not `mkdir -p` from a sandboxed Shell. The hook owns `status.json` / `metrics.json`; agents must not patch lifecycle fields.
+
+## pipeline.json
+
+```json
+{
+  "slug": "order-history-date-filter",
+  "intent": "feature",
+  "specMode": "consume",
+  "summary": "Add date filter to Order History",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
+    { "agent": "build-verifier", "label": "Validation gate" },
+    { "agent": "code-reviewer", "label": "Code review" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}
+```
+
+| Field | Notes |
+|-------|--------|
+| `agent` | kebab-case, or an array when `parallel: true` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only` |
+| `skipIf` | `debugger.fixed` \| `ci-investigator.resolved` |
+| `model` | optional `cheap` \| `standard` \| `strong` |
+| `specMode` | `consume` \| `generate` \| `none` — `brief.md` `## Spec mode` wins |
+
+## status.json
+
+Prefer `phase: executing`. States: `in_progress`, `completed`, `awaiting_approval` (`/task-continue`), `changes_requested`, `validation_failed`.
+
+## Commands
+
+```bash
+/task <description>
+/task-continue <slug>
+/technical-retro <slug>
+```
+
+After a human gate, close wait via the **installed** hook (do not hand-edit `pipelineIndex`):
+
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .opencode/hooks/chain-team-phases.sh
+```
+
+Same JSON on Claude, Mavis, or OpenCode: `bash .<tool>/hooks/chain-team-phases.sh`.
+
+## Contracts
+
+- Manifest schema: shared core `agent-team/agent-artifact-contracts.md`. Read it first; producers upsert only their IDs.
+- Metrics: append-only allowlisted events — `agent-team/agent-task-metrics.md`. Aggregate: `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .ai.local/team`.
+- Commit `.ai.local/team/` templates (and slugs if you want them in clones).

package/presets/opencode/php-hexagonal/team/fixtures/bugfix-standard.json

@@ -0,0 +1,37 @@
+{
+  "slug": "example-bugfix-standard",
+  "intent": "bugfix",
+  "profile": "standard",
+  "summary": "Regression fix with review",
+  "steps": [
+    {
+      "agent": "debugger",
+      "label": "Root cause"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Fix if needed",
+      "skipIf": "debugger.fixed"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "composer test / vendor/bin/phpunit / static analysis"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "playwright-test-planner",
+      "reason": "PHP backend uses integration-test-* — not in this bugfix path"
+    },
+    {
+      "agent": "xcuitest-test-planner",
+      "reason": "PHP backend uses integration-test-* — not in this bugfix path"
+    }
+  ]
+}

package/presets/opencode/php-hexagonal/team/fixtures/feature-full.json

@@ -0,0 +1,61 @@
+{
+  "slug": "example-feature-full",
+  "intent": "feature",
+  "specMode": "consume",
+  "profile": "full",
+  "summary": "Multi-layer PHP use case with integration-test coverage",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Clarify and decompose"
+    },
+    {
+      "agent": "solution-architect",
+      "label": "Design boundaries",
+      "model": "strong"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Implement + unit tests",
+      "scope": "unit-in-dev"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "composer test / vendor/bin/phpunit / static analysis",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "Integration tests",
+      "scope": "e2e-only"
+    },
+    {
+      "agent": "integration-test-planner",
+      "label": "Plan integration coverage"
+    },
+    {
+      "agent": "integration-test-generator",
+      "label": "Generate integration tests"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
+  ],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "accessibility-reviewer",
+      "reason": "PHP backend has no UI surface"
+    }
+  ]
+}

package/presets/opencode/php-hexagonal/team/fixtures/feature-light.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-light",
+  "intent": "feature",
+  "profile": "light",
+  "summary": "Trivial single-package change with explicit AC",
+  "steps": [
+    { "agent": "feature-developer", "label": "Implement", "model": "cheap" },
+    { "agent": "build-verifier", "label": "composer test / vendor/bin/phpunit / static analysis", "model": "cheap" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "task-analyst", "reason": "Explicit AC and single-package scope" },
+    { "agent": "code-reviewer", "reason": "Light profile — non-trivial module/service changes should use standard" },
+    { "agent": "qa-tester", "reason": "No integration-test AC" }
+  ]
+}

package/presets/opencode/php-hexagonal/team/fixtures/memlog.example.md

@@ -0,0 +1,9 @@
+# Memlog example
+
+Append-only. Agents write; `/task-continue` may read. The hook does not parse this file.
+
+## 2026-08-13
+
+- `decision`: specMode=generate; research-before-spec requested
+- `claim`: empty-cart copy lives in the empty-state handler (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/opencode/php-laravel/MCP.md

@@ -0,0 +1,26 @@
+# MCP (php-laravel)
+
+Default MCP surface for this preset: **Context7** only (library docs).
+
+See `mcp.json`. Do not require Playwright or browser MCP servers for Laravel API delivery.
+
+
+## Agent usage
+
+Load requestable rule `mcp-usage`. The **session MCP catalog** is source of truth (this file and `mcp.json` are hints). Discover tool schemas before calling; never invent them.
+
+**Context7 (shipped):** query docs when a third-party API is not confirmed by lockfile + sibling files. Use the installed major. Cap ≤3 doc queries per question. If Context7 is down, mark `// VERIFY` and continue — do not block.
+
+## Local overlay (not shipped)
+
+`init` **merges** `mcpServers`: preset keys are updated; extra local servers are kept. User-level MCP is never touched. Prefer user-level MCP if you do not want overlay servers in the project file.
+
+Use an overlay only when it is **ready** (`serverStatus` not `error` / `needsAuth` / `loading`) **and** the task fits. Absence is not a blocker unless the user required that MCP as source of truth.
+
+| Kind | Typical aliases | When |
+|------|-----------------|------|
+| Observability | `sentry`, `datadog`, `plugin-datadog-*` | production error, event/trace id, APM |
+| Tickets | `linear`, `jira`, `notion`, `plugin-notion-*` | ticket/page URL; read-only; task-folder artifacts remain SoT |
+| GitHub MCP | `github` | optional; native `gh` remains SoT for PRs and checks |
+
+Do **not** require Storybook, Playwright, or Chrome DevTools MCP as delivery gates on this preset.

package/presets/opencode/php-laravel/OPENCODE.md

@@ -0,0 +1,53 @@
+# Laravel stack — OpenCode agent team
+
+Short OpenCode entry. Native discovery: `.opencode/agents/`,
+`.opencode/skills/`, `.opencode/commands/`. Rule files under
+`.opencode/rules/*.md` are **not** auto-loaded.
+
+Root `AGENTS.md` is native always-on. Read it first, then this file.
+
+## How to load
+
+- Essential rules: Read immediately (paths below). Do not preload the catalog.
+- Other rules: lazy `Read` `.opencode/rules/<stem>.md` when the task matches.
+- Agents: native `@name` / Task from `.opencode/agents/`.
+- Commands: native `/task` from `.opencode/commands/`.
+- After a producer receipt, run `bash .opencode/hooks/chain-team-phases.sh`.
+  Agents must not write lifecycle fields in `status.json` / `metrics.json`.
+
+## Essential rules (read every turn)
+
+- `.opencode/rules/laravel-app-core.md`
+- `.opencode/rules/architecture-boundaries.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+
+See `.opencode/rules/README.md` for the full catalog and loading strategy.
+
+**Platform docs:** published with the `@bonesofspring/ai-rules` package
+(`docs/OPENCODE.md`, `docs/OPENCODE-COMPATIBILITY.md`) — **not** copied into
+the consumer repo. Source: https://github.com/bonesofspring/ai-rules
+
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root (cross-tool setup, commands, security, living conventions pointers).
+
+| Task | Where to look |
+|------|----------------|
+| New work task | `/task` → `commands/task.md` + `agent-team-orchestrator.md` |
+| End-to-end feature | skill `feature-delivery` + `feature-delivery-workflow.md` |
+| Stack and layers | `laravel-app-core.md`, `architecture-boundaries.md` |
+| After PHP edits | `post-change-test.md` (+ `php-tooling.md`) → `php artisan test` |
+| Feature / integration tests | `integration-test-*` + skill `integration-testing` |
+| Unit tests | `unit-test-*` + skill `unit-testing` |
+| Code review | skill `code-review` + `code-review-mr.md` |
+| ADR | skill `write-adr` (on-demand) |
+| How does X work | agent `codebase-analyzer` (explain-as-is; without `/task`) |
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init opencode --preset php-laravel
+```
+
+Copies rules, commands, agents, hooks, skills, `OPENCODE.md` →
+`.opencode/AGENTS.md`, `MCP.md`, `opencode.json` → project `opencode.json`
+(`mcp` merge), plus `REPO_AGENTS.md` → root `AGENTS.md`. Seeds `.ai.local/team/`.

package/presets/opencode/php-laravel/README.md

@@ -0,0 +1,17 @@
+# Laravel preset (OpenCode)
+
+Sibling adapter derived from `presets/cursor/php-laravel`. Platform id `opencode`;
+runtime `opencode`. Consumer install root is `.opencode/` (native agents,
+skills, commands) plus root `AGENTS.md` and `opencode.json`.
+
+Mapping: `adapter-map.json`. Do not derive this tree from Claude.
+
+```bash
+npx @bonesofspring/ai-rules init opencode --preset php-laravel
+```
+
+Install id: `php-laravel`. Listed in `platform-contract.json` `releasedStacks`.
+
+`init` writes `.opencode/**`, root `AGENTS.md`, `opencode.json`, and seeds `.ai.local/team/`.
+No `hooks.json` / Bugbot; chain with `bash .opencode/hooks/chain-team-phases.sh`.
+`clean opencode` does not delete `.ai.local/`.

package/presets/opencode/php-laravel/REPO_AGENTS.md

@@ -0,0 +1,74 @@
+# Laravel — agent instructions
+
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`, `.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, Mavis, OpenCode, or other).
+- All four platforms ship **the same** root file. `init` overwrites it; content does not depend on which tool ran last.
+- Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md` — use them when that tool is installed.
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init multi --preset php-laravel
+```
+
+Per-tool: `init cursor|claude|mavis|opencode --preset php-laravel`. `init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). `clean` of one tool leaves this file if another tool install remains. Living gotchas belong in `.ai.local/conventions.md`, not here.
+
+## Presence-based load
+
+When the tree exists, read the tool map, then the essential rules. Do not preload the full catalog.
+
+- If `.cursor/` exists: read `.cursor/AGENTS.md`.
+- If `.claude/` exists: read `.claude/CLAUDE.md`.
+- If `.mavis/` exists: read `.mavis/AGENTS.md`, then `.mavis/rules/laravel-app-core.md`, `.mavis/rules/architecture-boundaries.md`, `.mavis/rules/code-quality-and-refactoring.md`, `.mavis/rules/ai-local-overlay.md`.
+- If `.opencode/` exists: read `.opencode/AGENTS.md`, then `.opencode/rules/laravel-app-core.md`, `.opencode/rules/architecture-boundaries.md`, `.opencode/rules/code-quality-and-refactoring.md`, `.opencode/rules/ai-local-overlay.md`.
+
+Mavis has no native rule discovery without those root paths. OpenCode has no `alwaysApply` engine — the four `.opencode/rules/*.md` files above are the always-on set.
+
+## Pipelines are shared
+
+`/task` slug, `status.json`, and `metrics.json` live under `.ai.local/team/tasks/<slug>/`. Cursor, Claude, Mavis, and OpenCode share this folder (including `init multi`).
+
+## Commands (test / verify)
+
+Detect Composer from the repo (`composer.json` / `composer.lock`). Prefer `php artisan test` when `artisan` exists.
+
+| Gate | Typical command |
+|------|-----------------|
+| Tests | `php artisan test` or `composer test` (Pest if that is the repo default) |
+| Static analysis (if configured) | `vendor/bin/phpstan` / `vendor/bin/psalm` |
+| Format (if configured) | `vendor/bin/pint` / `php-cs-fixer` |
+| Post-change | requestable `post-change-test` + `php-tooling` |
+
+Static analysis / format — only tools already configured in the repo/CI.
+
+## Security basics
+
+- Do not commit secrets (`.env`, tokens, credentials).
+- Review destructive git before running; respect shell hooks.
+- Prefer Form Requests + Policies; keep mass-assignment protection tight.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
+| Mavis | `.mavis/AGENTS.md` (optional if Mavis not installed) |
+| OpenCode | `.opencode/AGENTS.md` (optional if OpenCode not installed) |
+
+Rules: `.cursor/rules/`, `.claude/rules/`, `.mavis/rules/`, or `.opencode/rules/`.
+Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/skills/`.
+
+## Living conventions
+
+Gotchas, local patterns, and team decisions: **`.ai.local/conventions.md`** (fill after init; `init` does not overwrite it).
+
+## Local overlay (`.ai.local/`) — MANDATORY
+
+A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
+
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
+
+Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.