@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/opencode/next/team/README.md

@@ -1,36 +1,28 @@
 # Agent team artifacts
 
-Artifact directory for the Cursor “agent team” pipeline.
+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
 
 ```
-.opencode/team/
-  active-task.json
-  fixtures/                  # pipeline profile examples (feature-full, feature-light, bugfix-standard)
-  tasks/
-    <slug>/
-      pipeline.json
-      status.json
-      metrics.json             # schema-v1 append-only event ledger (see Local metrics ledger)
-      brief.md
-      decomposition.md
-      debug-report.md          # fixApplied: true/false
-      validation-report.md     # build-verifier: PASS | FAIL
-      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
-      .memlog.md             # append-only agent notes (optional)
+.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)
 ```
 
-## pipeline.json schema
+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
 {
@@ -42,8 +34,7 @@ Artifact directory for the Cursor “agent team” pipeline.
     { "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" },
-    { "agent": "qa-tester", "label": "E2E", "scope": "e2e-only" }
+    { "agent": "code-reviewer", "label": "Code review" }
   ],
   "humanGates": ["after:task-analyst"],
   "autoChain": true,
@@ -51,98 +42,36 @@ Artifact directory for the Cursor “agent team” pipeline.
 }
 ```
 
-### Step fields
-
-| Field | Description |
-|-------|-------------|
-| `agent` | kebab-case name or array when `parallel: true` |
-| `label` | Human-readable step name |
-| `scope` | Passed to agents (e.g. `unit-in-dev`, `e2e-only`) |
+| 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` |
-| `parallel` | Invoke all `agent` values in one parent turn |
-
-Optional top-level **`specMode`:** `consume` | `generate` | `none` (router echo; `brief.md` `## Spec mode` wins).
-
-## status.json (pipeline mode)
-
-```json
-{
-  "slug": "order-history-date-filter",
-  "intent": "feature",
-  "pipelineIndex": 0,
-  "currentAgent": "task-analyst",
-  "phase": "executing",
-  "state": "in_progress",
-  "awaitingHumanGate": false,
-  "retryAfterFix": null,
-  "activeAttempts": {},
-  "lastCompletedAttempt": null,
-  "parallelCompleted": [],
-  "parallelOutcomes": {},
-  "updatedAt": "2026-05-29T12:00:00.000Z"
-}
-```
-
-### phase
-
-Prefer **`executing`** for pipeline mode. Legacy: `analysis`, `development`, `review`, `testing`, `done`.
+| `model` | optional `cheap` \| `standard` \| `strong` |
+| `specMode` | `consume` \| `generate` \| `none` — `brief.md` `## Spec mode` wins |
 
-### state
+## status.json
 
-| Value | Description |
-|-------|-------------|
-| `in_progress` | Current step running |
-| `completed` | Current step finished |
-| `awaiting_approval` | Human gate; use `/task-continue` |
-| `changes_requested` | Reviewer requires fixes |
-| `validation_failed` | build-verifier failed |
-| `approved` | Legacy continue |
+Prefer `phase: executing`. States: `in_progress`, `completed`, `awaiting_approval` (`/task-continue`), `changes_requested`, `validation_failed`.
 
-## Workflow entry
+## Commands
 
 ```bash
-/task <task description>
+/task <description>
 /task-continue <slug>
 /technical-retro <slug>
 ```
 
-## Creating task dirs
-
-Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook owns `status.json` lifecycle; parent may only create a minimal bootstrap if missing. Do **not** use Shell `mkdir -p` — Cursor’s default sandbox returns `Operation not permitted` (especially for repos on macOS Desktop/Documents).
-
-## Git
-
-Commit task artifacts if you want them to survive `ai-rules clean cursor`. Or copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
-
-## specMode, applyReadiness, memlog
-
-- **`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:** `.opencode/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`.
-
-## Artifact manifest and receipts
-
-Each slug stores one context index at `.opencode/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.
-
-Producer/consumer rules:
-
-- 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.
-
-## Local metrics ledger
-
-`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. Policy SoT: `presets/_shared/core/agent-team/agent-task-metrics.md`. 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.
-
-`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`.
-
-After a human gate, `/task-continue` closes wait via the installed hook (do not hand-edit `pipelineIndex` first):
+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
 ```
 
-That appends `human_gate_ended` before the next `attempt_started`. Claude twins use the same payload against `.claude/hooks/chain-team-phases.sh`. Other installable stacks ship the same ledger contract in their `team/README.md`.
+Same JSON on Claude, Mavis, or OpenCode: `bash .<tool>/hooks/chain-team-phases.sh`.
+
+## Contracts
 
-Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .opencode/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts. For retros, see `/technical-retro` → **Metrics evidence**.
+- 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/nuxt/MCP.md

@@ -0,0 +1,36 @@
+# MCP (preset `nuxt`, OpenCode)
+
+Merged into project `opencode.json` `mcp` on `ai-rules init opencode --preset nuxt`.
+
+## Servers
+
+| Name | Package | Why |
+|------|---------|-----|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Vue/Nuxt/TS and library docs (fewer stale APIs in agent replies) |
+| `playwright` | `@playwright/mcp` | Browser automation for e2e agents (`playwright-test-*`) and selector checks |
+| `chrome-devtools` | `chrome-devtools-mcp` | Live DOM/network/performance when debugging UI |
+| `figma` | remote `https://mcp.figma.com/mcp` | Design context → code (layouts, tokens, Code Connect); OAuth in OpenCode (operator MCP config) |
+
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment — higher Context7 rate limits. Figma — OAuth on first connect (do not write the token into the config).
+
+
+## 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 |
+| Storybook | `storybook`, `user-storybook`, `plugin-storybook`, `storybook-mcp-addon` | component docs/stories/controls; needs Storybook running; not shipped |
+
+**Browser split (this preset):** Playwright MCP → e2e agents and selectors. Chrome DevTools MCP → `debugger` / `performance-auditor` against a running app. Not interchangeable.

package/presets/opencode/nuxt/OPENCODE.md

@@ -0,0 +1,65 @@
+# Nuxt 3 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/nuxt-app-core.md`
+- `.opencode/rules/package-manager.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).
+
+## Quick start
+
+| Task | Where to look |
+|------|----------------|
+| Any new work task | `/task` → `commands/task.md` + `agent-team-orchestrator.md` (+ `agent-team-intake.md` on-demand) |
+| New end-to-end feature | skill `feature-delivery` + `feature-delivery-workflow.md` |
+| Stack and layers | `nuxt-app-core.md` |
+| Reference features | `reference-features.md` (fill in repo paths) |
+| After code edits | `post-change-lint.md` (**requestable**, but required after edits; full gate — `build-verifier`) |
+| Code review MR | skill `code-review` + `code-review-mr.md` |
+| Security (auth/forms/env) | `security-nuxt.md` + agent `security-reviewer` |
+| Validation before review | agent `build-verifier` |
+| Technical retro | `/technical-retro` + skill `technical-retro` |
+
+## When to use `/task`
+
+- Implementation, bugfix, migration, tests, MR review, CI-fix — **prefer `/task`**.
+- Simple one-liner with no architecture risk — may skip the pipeline if the user explicitly asks.
+- “How does X work?” questions — agent `codebase-analyzer` (explain-as-is) or answer without `/task`.
+
+## Pipeline routing
+
+Intent detection, profiles (`full` / `standard` / `light`), and default steps — **only** in `agents/task-router.md`. Schema and examples — `agents/README.md`.
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init opencode --preset nuxt
+```
+
+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/nuxt/README.md

@@ -0,0 +1,17 @@
+# Nuxt 3 preset (OpenCode)
+
+Sibling adapter derived from `presets/cursor/nuxt`. 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 nuxt
+```
+
+Install id: `nuxt`. 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/nuxt/REPO_AGENTS.md

@@ -0,0 +1,75 @@
+# Nuxt 3 — 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 nuxt
+```
+
+Per-tool: `init cursor|claude|mavis|opencode --preset nuxt`. `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/nuxt-app-core.md`, `.mavis/rules/package-manager.md`, `.mavis/rules/code-quality-and-refactoring.md`, `.mavis/rules/ai-local-overlay.md`.
+- If `.opencode/` exists: read `.opencode/AGENTS.md`, then `.opencode/rules/nuxt-app-core.md`, `.opencode/rules/package-manager.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 / lint / build)
+
+Working directory for package scripts: **repository root** (directory with `nuxt.config.*`). Detect the package manager from lockfile / `packageManager` (`package-manager` rule).
+
+| Gate | Typical command |
+|------|-----------------|
+| Lint JS | `yarn lint:js` (or project equivalent) from repo root |
+| Lint CSS | `yarn lint:css` from repo root |
+| Typecheck | `yarn typecheck` (`nuxt typecheck`) from repo root |
+| Unit tests | project unit script (often Vitest) at repo root |
+| Build | project `build` / `nuxt build` at repo root |
+
+After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent `build-verifier`.
+
+## Security basics
+
+- Do not commit secrets (`.env`, tokens, credentials).
+- Review destructive git (`reset --hard`, force-push) before running; respect shell hooks.
+- Do not weaken CI or skip hooks unless the user explicitly asks.
+
+## 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.