@bonesofspring/ai-rules 0.2.24 → 0.2.26

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

@@ -1,56 +1,77 @@
-# Agent team artifacts (preset php-hexagonal)
+# Agent team artifacts
 
-Artifact directory for the agent-team pipeline on PHP backends (hexagonal / ports & adapters).
+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
 
 ```
-.claude/team/
-  active-task.json
-  fixtures/
+.ai.local/team/
+  README.md
+  active-task.json           # current slug pointer (runtime)
+  fixtures/                  # pipeline profile examples
   tasks/<slug>/
-    pipeline.json
-    status.json
-    brief.md
-    decomposition.md
-    .memlog.md
-    …
+    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)
 ```
 
-## Fixtures
-
-| Fixture | Notes |
-|---------|-------|
-| `feature-full.json` | Full profile; QA scope `e2e-only` = **adapter/integration tests** (not UI e2e); Playwright/XCUITest stems in `skipped` |
-| `feature-light.json` | developer → build-verifier (`composer test` / `vendor/bin/phpunit` / configured static analysis) |
-| `bugfix-standard.json` | debugger → developer (skipIf) → verifier → reviewer |
-
-**Never** schedule Playwright/XCUITest-only steps for this preset. Use `integration-test-*` (or QA with `e2e-only` = integration) for adapter-level coverage.
-
-`playwright-test-*`, `xcuitest-test-*`, and `accessibility-reviewer` appear in fixture `skipped[]` **on purpose** — documented anti-patterns for backend presets (same as go/java). Leakage checker allows those stems only under `skipped[]`; scheduling them in `steps[]` is a **FAIL**.
-
+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": []
+}
+```
 
-## specMode, applyReadiness, memlog
+| 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 |
 
-- **`specMode`:** `consume` | `generate` | `none` — primary in `brief.md` `## Spec mode`; optional top-level `pipeline.json` `specMode`. `none` skips INDEX/author mode (spike/research).
-- **`applyReadiness`:** YAML frontmatter on developer `implementation.md`; JSON-shaped `{ "state": "blocked"|"ready"|"all_done", "contextFiles": [] }` on the analyst receipt (analyst may emit `blocked` pre-gate). See `agent-artifact-contracts`.
-- **Memlog:** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/team/tasks/<slug>/.memlog.md`) — append-only, agent-written; `/task-continue` may read. Hook does not parse it. Example: `fixtures/memlog.example.md`.
+## status.json
 
-## Artifact manifest and receipts
+Prefer `phase: executing`. States: `in_progress`, `completed`, `awaiting_approval` (`/task-continue`), `changes_requested`, `validation_failed`.
 
-Each slug stores one context index at `.claude/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.
+## Commands
 
-Producer/consumer rules:
+```bash
+/task <description>
+/task-continue <slug>
+/technical-retro <slug>
+```
 
-- Read the manifest first and use only the authoritative inputs needed by the current step; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` when it is missing or stale, and report that gap.
-- Producers upsert only their stable entry IDs, preserve foreign entries, and finish with `completed`, `blocked`, `changes_requested`, or `validation_failed` receipt evidence.
-- The router owns `pipeline.json` and its routing entry; analyst, developer, verifier, and reviewer own their named outputs and receipts. Consumers do not edit another producer's receipt.
-- Agents do not mutate `status.json` or `metrics.json`. The orchestration runtime/hook is their single writer. Parallel receipt merges are serialized by the parent/orchestrator.
+After a human gate, close wait via the **installed** hook (do not hand-edit `pipelineIndex`):
 
-## Local metrics ledger
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .claude/hooks/chain-team-phases.sh
+```
 
-`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. The orchestration runtime writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
+Same JSON on Claude, Mavis, or OpenCode: `bash .<tool>/hooks/chain-team-phases.sh`.
 
-`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic; `parallelOutcomes` holds per-agent outcomes for the current parallel join until the step advances. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
+## Contracts
 
-Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .claude/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts.
+- 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/claude/php-laravel/README.md

@@ -1,30 +1,9 @@
-# Preset `php-laravel` (Claude)
+# Laravel preset (Claude Code)
 
-Installable Claude Code preset for **Laravel** backend/API projects (Eloquent, Form Requests, Policies, Actions/Services, Jobs/Queues).
+Twin of `presets/cursor/php-laravel/`. For framework-agnostic PHP use `--preset php-hexagonal`.
 
 ```bash
 npx @bonesofspring/ai-rules init claude --preset php-laravel
 ```
 
-## When to use
-
-| Preset | Use when |
-|--------|----------|
-| **`php-laravel`** | App is (or will be) a Laravel backend/API |
-| **`php-hexagonal`** | Framework-agnostic / multi-framework PHP with strict ports & adapters |
-
-## Layout
-
-| Path | Role |
-|------|------|
-| `rules/<topic>/*.md` | Claude twins (34 stems); session-start trio without `paths:` |
-| `agents/` | 21 agents + README |
-| `skills/` | 8 skills + README |
-| `commands/` | 5 slash commands |
-| `team/` | conventions + fixtures |
-| `hooks/` | Shell guard + team chain (byte-forked) — hook scripts only; no `hooks.json` |
-| `REPO_AGENTS.md` | → consumer root `AGENTS.md` |
-| `CLAUDE.md` | Claude quick-start map — **Claude-only** |
-| `MCP.md` / `.mcp.json` | Context7 only (installed to project root) |
-
-Cursor SoT: `presets/cursor/php-laravel/`. Mapping: `rules/README.md`. Dogfood: `dogfood/php-laravel`. Contribution: `docs/PRESET-CONTRIBUTION.md`.
+`team/` seeds **`.ai.local/team/`**. Dogfood: `dogfood/php-laravel`. Catalog: [`rules/README.md`](./rules/README.md).

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

@@ -1,18 +1,34 @@
 # Laravel — agent instructions
 
-Cross-tool repo-root guide for the **php-laravel** preset (Laravel-first). Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+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, or other).
+- 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 cursor --preset php-laravel
-npx @bonesofspring/ai-rules init claude --preset php-laravel
+npx @bonesofspring/ai-rules init multi --preset php-laravel
 ```
 
-`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`).
+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)
 
@@ -37,11 +53,22 @@ Static analysis / format — only tools already configured in the repo/CI.
 
 | Tool | Map |
 |------|-----|
-| Cursor | `.cursor/AGENTS.md` |
-| Claude Code | `.claude/CLAUDE.md` |
+| 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/` or `.claude/rules/`. Feature/integration tests: `integration-test-*` (never Playwright/XCUITest).
+Rules: `.cursor/rules/`, `.claude/rules/`, `.mavis/rules/`, or `.opencode/rules/`.
+Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/skills/`.
 
 ## Living conventions
 
-Gotchas and team decisions: `.cursor/team/conventions.md` and/or `.claude/team/conventions.md` (fill after init; fixtures ship with the preset).
+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.

package/presets/claude/php-laravel/agents/api-contract-reviewer.md

@@ -15,7 +15,7 @@ Review **HTTP/gRPC contract alignment** for Laravel services.
 
 ## Output
 
-`.claude/team/tasks/<slug>/api-contract-review.md` — gaps, severity, suggested fixes (no code edits).
+`.ai.local/team/tasks/<slug>/api-contract-review.md` — gaps, severity, suggested fixes (no code edits).
 
 ## Non-scope
 

package/presets/claude/php-laravel/agents/build-verifier.md

@@ -12,7 +12,7 @@ You are the build verifier for **Laravel** services (and for **ai-rules preset p
 1. Detect Composer from `composer.json` / `composer.lock`; prefer `php artisan test` when `artisan` exists.
 2. Run from module/project root: `php artisan test` or `composer test` or `vendor/bin/phpunit` (or Pest if that is the repo default / CI).
 3. If present in **repo or CI**: formatter + static analysis (Pint, PHPStan, Psalm, PHP-CS-Fixer, or project-equivalent) per `php-tooling` / `post-change-test`. Mirror CI gates locally when configs/scripts exist; do **not** invent a tool the repo does not use.
-4. Write `.claude/team/tasks/<slug>/validation-report.md` with commands + results.
+4. Write `.ai.local/team/tasks/<slug>/validation-report.md` with commands + results.
 5. On failure: emit receipt outcome `validation_failed` — do **not** patch production code (developer retries).
 
 **Never** require Playwright, XCUITest, `lint:js`/`lint:css`, `xcodebuild`/`SwiftLint`, `mvn`, or `gradlew` as the Laravel gate.
@@ -58,7 +58,7 @@ Document PASS/FAIL in `validation-report.md`.
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.
 - **Owned outputs:** `validation-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `validation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `validation_failed`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/php-laravel/agents/code-reviewer.md

@@ -5,14 +5,14 @@ readonly: false
 model: fast
 ---
 
-You are a senior Laravel code reviewer. Write only review artifacts under `.claude/team/**`; do not modify production code.
+You are a senior Laravel code reviewer. Write only review artifacts under `.ai.local/team/**`; do not modify production code.
 
 ## Inputs
 
-1. `.claude/team/tasks/<slug>/brief.md`
-2. `.claude/team/tasks/<slug>/decomposition.md`
+1. `.ai.local/team/tasks/<slug>/brief.md`
+2. `.ai.local/team/tasks/<slug>/decomposition.md`
 3. Git diff (`git diff`, `git status`)
-4. `.claude/team/tasks/<slug>/validation-report.md` if present
+4. `.ai.local/team/tasks/<slug>/validation-report.md` if present
 
 Apply skill `code-review` and `tooling-and-review/code-review.md`. Weigh `architecture/boundaries.md`, `api-and-data/http-layer.md`, `api-and-data/form-requests.md`, `architecture/actions-services.md`, `api-and-data/eloquent-persistence.md`, `architecture/service-providers.md`, `api-and-data/policies-authorization.md`, `api-and-data/routes-api.md`, `stack/laravel-conventions.md`, `testing/unit.md`, `testing/integration.md`, `tooling-and-review/security-php.md`.
 
@@ -37,7 +37,7 @@ You **issue** reviews. Implementers acting on your findings must verify each ite
 
 ## Artifact
 
-Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update the owned terminal receipt accordingly.
+Write `.ai.local/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANGES, findings by severity, AC coverage. Update the owned terminal receipt accordingly.
 
 ## Design guidance
 
@@ -45,7 +45,7 @@ Write `.claude/team/tasks/<slug>/review.md` with verdict APPROVE | REQUEST_CHANG
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation, validation evidence, and the scoped git diff.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation, validation evidence, and the scoped git diff.
 - **Owned outputs:** `review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/php-laravel/agents/debugger.md

@@ -20,7 +20,7 @@ Use the **`debug-investigation` skill** for the investigation loop.
 - Xcode / lldb / Instruments as required path
 - Playwright browser debugging
 
-Write `.claude/team/tasks/<slug>/debug-report.md`.
+Write `.ai.local/team/tasks/<slug>/debug-report.md`.
 
 
 ## 3-fix architecture gate

package/presets/claude/php-laravel/agents/feature-developer.md

@@ -37,7 +37,7 @@ Implement Laravel features following Laravel-first layer boundaries.
 
 When editing ai-rules `presets/**/php-laravel/**`, keep Cursor/Claude twins in sync and preserve chain fork ≠ next/ios-swift/go/java/mcp-ts/php-hexagonal (see `preset-no-cross-stack-leakage`).
 
-Update `.claude/team/tasks/<slug>/implementation.md` and the owned implementation receipt.
+Update `.ai.local/team/tasks/<slug>/implementation.md` and the owned implementation receipt.
 
 ## Design guidance
 
@@ -75,7 +75,7 @@ applyReadiness:
 
 **Code Map + Suggested Review Order:** when this WP spans **>1 layer or module**, add to `implementation.md` a Code Map (3–8 annotated paths) and Suggested Review Order lines `concern | path:line | ≤15 words`. Omit for single-file / single-layer WPs.
 
-**Memlog:** append implementation decisions to `.claude/team/tasks/<slug>/.memlog.md` (append-only).
+**Memlog:** append implementation decisions to `.ai.local/team/tasks/<slug>/.memlog.md` (append-only).
 
 
 
@@ -86,7 +86,7 @@ Load requestable rule `mcp-usage` when verifying third-party library APIs (Conte
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
 - **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/php-laravel/agents/integration-test-generator.md

@@ -19,4 +19,4 @@ You are the **integration-test-generator** for Laravel services.
 
 ## Artifacts
 
-Write plans/results under `.claude/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).
+Write plans/results under `.ai.local/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).

package/presets/claude/php-laravel/agents/integration-test-healer.md

@@ -19,4 +19,4 @@ You are the **integration-test-healer** for Laravel services.
 
 ## Artifacts
 
-Write plans/results under `.claude/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).
+Write plans/results under `.ai.local/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).

package/presets/claude/php-laravel/agents/integration-test-planner.md

@@ -19,4 +19,4 @@ You are the **integration-test-planner** for Laravel services.
 
 ## Artifacts
 
-Write plans/results under `.claude/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).
+Write plans/results under `.ai.local/team/tasks/<slug>/` (e.g. `integration-test-plan.md`).

package/presets/claude/php-laravel/agents/migration-specialist.md

@@ -13,7 +13,7 @@ You plan migrations for **PHP modules** (toolchain, deps, layout refactors). Do
 
 ## Deliverable
 
-Write `.cursor/team/tasks/<slug>/migration-plan.md`:
+Write `.ai.local/team/tasks/<slug>/migration-plan.md`:
 
 1. Current vs target (PHP version, Composer plugins, major deps).
 2. Phased steps with rollback.

package/presets/claude/php-laravel/agents/openspec-author.md

@@ -21,8 +21,8 @@ If `openspec/` is absent in the repo, stop and report `blocked` with the message
 
 ## Inputs
 
-1. `.claude/team/tasks/<slug>/{brief.md, decomposition.md, architecture.md}` (Cursor: `.cursor/team/tasks/<slug>/`).
-2. `.claude/team/tasks/<slug>/artifact-manifest.json` — read first, consume `artifactInputIds`.
+1. `.ai.local/team/tasks/<slug>/{brief.md, decomposition.md, architecture.md}` (Cursor: `.ai.local/team/tasks/<slug>/`).
+2. `.ai.local/team/tasks/<slug>/artifact-manifest.json` — read first, consume `artifactInputIds`.
 3. `openspec/config.yaml` — schema, context block, `rules.proposal | specs | design | tasks`. **Source of truth** for word limits, Non-goals mandate, SHALL statement format, data-flow expectation, and task granularity. Never fork.
 4. `openspec/specs/<capability>/spec.md` — surviving applied specs (the "as-is" target).
 5. `openspec/changes/archive/<YYYY-MM-DD>-<change-id>/` — prior decisions (D-1..) and open questions (OQ-1..) reusable across changes.
@@ -121,14 +121,14 @@ If `scope` carries multiple phases (e.g. `openspec:<change-id>:propose+apply`),
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and available architecture/migration/review artifacts.
-- **Owned outputs:** `openspec/changes/<change-id>/**` (proposal.md, design.md, tasks.md, .openspec.yaml, specs/<capability>/spec.md delta) plus the team slot `openspec-change.md` in `.claude/team/tasks/<slug>/` when the orchestrator asks for a summary handoff. Preserve all foreign entries; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `openspec-change`).
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and available architecture/migration/review artifacts.
+- **Owned outputs:** `openspec/changes/<change-id>/**` (proposal.md, design.md, tasks.md, .openspec.yaml, specs/<capability>/spec.md delta) plus the team slot `openspec-change.md` in `.ai.local/team/tasks/<slug>/` when the orchestrator asks for a summary handoff. Preserve all foreign entries; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `openspec-change`).
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths under `openspec/changes/<change-id>/**`, attach `openspec validate <change-id> --type change --strict` exit code + deltas-only summary, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
 
 ## Output
 
-When invoked directly (no pipeline), write the spec handoff at `.claude/team/tasks/<slug>/openspec-change.md`:
+When invoked directly (no pipeline), write the spec handoff at `.ai.local/team/tasks/<slug>/openspec-change.md`:
 
 ```markdown
 # OpenSpec change: <change-id>

package/presets/claude/php-laravel/agents/performance-auditor.md

@@ -15,7 +15,7 @@ Audit Laravel performance risks on the task scope.
 
 ## Output
 
-`.claude/team/tasks/<slug>/perf-report.md`. No production edits. Not Instruments/Xcode.
+`.ai.local/team/tasks/<slug>/perf-report.md`. No production edits. Not Instruments/Xcode.
 
 
 ## MCP usage

package/presets/claude/php-laravel/agents/qa-tester.md

@@ -23,7 +23,7 @@ Ensure test coverage for the Laravel task scope.
 - Introduce Playwright/XCUITest
 - Put raw SQL into Action/Service unit tests when neighbors mock persistence
 
-Coordinate with existing plans under `.claude/team/tasks/<slug>/`.
+Coordinate with existing plans under `.ai.local/team/tasks/<slug>/`.
 
 ## Design guidance
 

package/presets/claude/php-laravel/agents/security-reviewer.md

@@ -27,6 +27,6 @@ For each item: check when affected paths are in the diff; otherwise record **N/A
 
 ## Output
 
-`.claude/team/tasks/<slug>/security-review.md`. Do not edit production code.
+`.ai.local/team/tasks/<slug>/security-review.md`. Do not edit production code.
 
 Never require Keychain/ATS/iOS-only controls as the primary checklist.

package/presets/claude/php-laravel/agents/solution-architect.md

@@ -8,7 +8,7 @@ Design solutions for **Laravel** services.
 
 ## Deliverable
 
-`.claude/team/tasks/<slug>/architecture.md` covering:
+`.ai.local/team/tasks/<slug>/architecture.md` covering:
 
 - Routes & HTTP surface (Controllers, Form Requests, Resources)
 - Actions / Services and domain invariants

package/presets/claude/php-laravel/agents/task-analyst.md

@@ -45,7 +45,7 @@ Emit an analysis receipt; the runtime applies any configured human gate.
 
 **`none`:** skip INDEX row requirement and author mode; do not invent a dummy INDEX.
 
-**Research-before-spec (opt-in):** load skill **`spec-discovery`** only when the user/AC asks research before authoring (not default consume `/task`). Run a **subset** of methods; **`claim-ledger` is mandatory** whenever the skill loads. Append chronological notes to `.claude/team/tasks/<slug>/.memlog.md` (append-only; do not mutate `status.json`).
+**Research-before-spec (opt-in):** load skill **`spec-discovery`** only when the user/AC asks research before authoring (not default consume `/task`). Run a **subset** of methods; **`claim-ledger` is mandatory** whenever the skill loads. Append chronological notes to `.ai.local/team/tasks/<slug>/.memlog.md` (append-only; do not mutate `status.json`).
 
 **applyReadiness (author blocked):** if specs are drafted but the human gate has not passed, or a required named spec is missing, emit `applyReadiness: { "state": "blocked", "contextFiles": ["…"] }` on the analysis receipt. Do not invoke feature-developer.
 
@@ -72,7 +72,7 @@ If the prompt/brief has a tracker URL (Linear/Jira/Notion/…) and that MCP is r
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
 - **Owned outputs:** `brief.md` and `decomposition.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/php-laravel/agents/task-router.md

@@ -10,7 +10,7 @@ You are a task router for a **Laravel backend** agent team. You **do not** imple
 ## Inputs
 
 - User task description (from `/task` or orchestrator).
-- Optional: existing files under `.claude/team/tasks/<slug>/`.
+- Optional: existing files under `.ai.local/team/tasks/<slug>/`.
 - Pipeline JSON schema — **`agents/README.md`**.
 
 ## Intent detection
@@ -103,7 +103,7 @@ Optional: `"model": "cheap" | "standard" | "strong"`. Same policy as other prese
 - `full` / `spike` / security|perf specialists → `strong` on architect, migration, security, perf steps
 - never `strong` on build-verifier / tech-writer / task-router
 
-Fixtures: `.claude/team/fixtures/` (feature-full, feature-light, bugfix-standard).
+Fixtures: `.ai.local/team/fixtures/` (feature-full, feature-light, bugfix-standard).
 
 ## humanGates (defaults)
 
@@ -120,7 +120,7 @@ Fixtures: `.claude/team/fixtures/` (feature-full, feature-light, bugfix-standard
 
 ## Output
 
-Write `.claude/team/tasks/<slug>/pipeline.json` and initialize the routing entry in `artifact-manifest.json`; set `.claude/team/active-task.json`. The orchestration runtime creates and owns `status.json`.
+Write `.ai.local/team/tasks/<slug>/pipeline.json` and initialize the routing entry in `artifact-manifest.json`; set `.ai.local/team/active-task.json`. The orchestration runtime creates and owns `status.json`.
 
 ## Handoff
 
@@ -150,7 +150,7 @@ Return the routing receipt to the orchestrator. The orchestration runtime/hook e
 
 ## Artifact contract
 
-- **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume the user request and any existing authoritative task/decision entries.
+- **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume the user request and any existing authoritative task/decision entries.
 - **Owned outputs:** `pipeline.json` and the routing manifest entry; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `routing`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/php-laravel/agents/unit-test-planner.md

@@ -14,7 +14,7 @@ Plan **Laravel unit tests** (PHPUnit/Pest `@dataProvider`, PHPUnit assertions).
 
 ## Output
 
-`.claude/team/tasks/<slug>/unit-test-plan.md` — cases, namespaces, edge cases (null, empty, PHP exceptions).
+`.ai.local/team/tasks/<slug>/unit-test-plan.md` — cases, namespaces, edge cases (null, empty, PHP exceptions).
 
 ## Forbidden
 

package/presets/claude/php-laravel/ai-local/conventions.md

@@ -0,0 +1,21 @@
+# Living conventions
+
+Consumer-owned store for post-init gotchas, patterns, and decisions. **Not** always-on. Fill after `ai-rules init`. Root `AGENTS.md` only points here.
+
+## Gotchas
+
+<!-- e.g. fragile flows, “never do X in this repo” -->
+
+-
+
+## Patterns
+
+<!-- local patterns beyond reference-features table -->
+
+-
+
+## Decisions
+
+<!-- short pointers to ADRs / product choices that affect code -->
+
+-

package/presets/claude/php-laravel/commands/README.md

@@ -8,4 +8,4 @@ Slash-command and on-demand scenario definitions. Copied to `.claude/commands/`
 | `task-continue.md` | Resume after human gate / pause via `pipeline.json` |
 | `technical-retro.md` | Technical retro facilitation, including the “Agent work” block |
 
-See also the preset root `README.md` — Claude Code uses `skills/`, `agents/`, `hooks/`, and `team/` in addition to `rules/` and `commands/`.
+See also the preset root `README.md`. Artifacts: `.ai.local/team/README.md`.

package/presets/claude/php-laravel/commands/spec-start.md

@@ -11,8 +11,8 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 
 1. Extract description from arguments after `/spec-start` (domain, page/feature ids, sources).
 2. Generate a **slug** (kebab-case, ≤48 chars), e.g. `spec-<domain>-<id>`.
-3. Ensure `.claude/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
-4. Write `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
+3. Ensure `.ai.local/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
+4. Write `.ai.local/team/active-task.json` → `{ "slug": "<slug>" }`.
 5. Write minimal `pipeline.json`: task-analyst → (optional stop) → feature-developer only if user asked implement-after. **No separate spec-author agent.**
 6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate. Optional: if arguments/AC ask research-before-spec, also load skill **`spec-discovery`** (not default).
 7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.

package/presets/claude/php-laravel/commands/task-continue.md

@@ -13,7 +13,7 @@ Resume the pipeline from `pipeline.json`.
 
 ## Preconditions
 
-1. Read `.claude/team/tasks/<slug>/pipeline.json` and `status.json`.
+1. Read `.ai.local/team/tasks/<slug>/pipeline.json` and `status.json`.
 2. Continue if:
    - `awaitingHumanGate: true` or `state: awaiting_approval`, **or**
    - `state: changes_requested` (after review), **or**
@@ -21,7 +21,7 @@ Resume the pipeline from `pipeline.json`.
 
 ## Algorithm
 
-1. Write `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
+1. Write `.ai.local/team/active-task.json` → `{ "slug": "<slug>" }`.
 2. **Human gate resume** (`awaitingHumanGate` / `awaiting_approval`):
    1. **Do not** manually increment `pipelineIndex` or invent `currentAgent` first.
    2. Close the gate + activate the next attempt via the **installed** hook (single authority for ledger + status):

package/presets/claude/php-laravel/commands/task.md

@@ -24,7 +24,7 @@ Examples:
 
 ## Algorithm
 
-1. **Slug** — kebab-case from description (≤48 characters). Create `.claude/team/tasks/<slug>/` via Write / Edit; runtime/hook owns `status.json` — **do not** rely on Shell `mkdir` as the only way to create the directory.
+1. **Slug** — kebab-case from description (≤48 characters). Create `.ai.local/team/tasks/<slug>/` via Write / Edit; runtime/hook owns `status.json` — **do not** rely on Shell `mkdir` as the only way to create the directory.
 2. **Router** — invoke subagent **task-router** with the task description and slug path.
 3. **Plan** — show the user the table from `pipeline.json`: intent, steps, skipped, humanGates.
 4. **Intent retro** — if `intent === "retro"`, run `/technical-retro` and **stop**.

package/presets/claude/php-laravel/hooks/README.md

@@ -2,7 +2,7 @@
 
 | File | Purpose |
 |------|---------|
-| `chain-team-phases.sh` | Pipeline chaining after subagent stop (`TEAM_ROOT=.claude/team`) |
+| `chain-team-phases.sh` | Pipeline chaining after subagent stop (`TEAM_ROOT=.ai.local/team`) |
 | `guard-shell-command.sh` | Destructive git / JS package-manager guard; **allows** `php artisan test / composer test` / `compiler/IDE inspections` / `configured static analysis` / `repo static analysis` |
 
 Claude Code may not use Cursor `hooks.json`. Wire scripts per project docs when enabling agent-team auto-chain.