@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/CHANGELOG.md

@@ -2,17 +2,42 @@
 
 ## Unreleased
 
+### Over-abstraction guardrails + aligned always-on budget
+
+- **Shared core** `quality/code-quality-and-refactoring` gains an **Over-abstraction guardrails** section: no unnecessary constants, no invented one-off utilities (Rule of Three), decompose over conditionals. Propagated to all 10 stacks (Cursor + Claude; Mavis / OpenCode regenerated).
+- **UI rules** add a **Conditional rendering** section (decompose branches into child components, early returns for loading/empty/error, no nested ternaries): `react-ui` (next, with Incorrect/Correct pair), `vue-ui` (nuxt), `svelte-ui` (svelte), `compose-ui` (android-kotlin), `swiftui-ui` (ios-swift). Backend stacks get the stack-agnostic bullet from shared core.
+- **Token budget raised and aligned** across platforms: Cursor / Claude / Mavis / OpenCode always-on count is now **3–5** (was Cursor ≤4, Claude exactly 3, Mavis/OpenCode ≤4); session-start body cap is **200** lines (stretch **170**) and combined Mavis/OpenCode entry cap is **200** nonempty lines (was 140/170). Enforced by `check-preset-token-budget.sh`, `check-{mavis,opencode}-token-budget.mjs`, `test-{mavis,opencode}-context-budget.mjs`; policy in `preset-token-budget` / `preset-pr-checklist`, `docs/PRESET-CONTRIBUTION.md`, and every `build-verifier` / `rules/README.md`.
+- Consumers: re-run `npx @bonesofspring/ai-rules init <tool|multi> --preset <stack>` to pick up the new rule bodies and policy text.
+
+### Shared `.ai.local/team/` pipelines (breaking)
+
+- `/task` artifacts (`pipeline.json`, `status.json`, `metrics.json`, receipts) now live at **`.ai.local/team/tasks/<slug>/`**, shared across Cursor, Claude, Mavis, and OpenCode (including `init multi`).
+- `init` seeds `.ai.local/team/` (README + fixtures; never overwrites `tasks/<slug>/`). Legacy `.{cursor,claude,mavis,opencode}/team/tasks/<slug>` is migrated on first init; leftover dirs become a pointer README. `clean <tool>` does **not** delete `.ai.local/`.
+- **Scope:** because the runtime is shared, **any** single-tool `init` consolidates **all four** legacy `.{cursor,claude,mavis,opencode}/team/` directories, not only the tool being installed. Documented in `ai-rules --help`.
+- **Non-destructive migration:** every non-`README.md` legacy entry (including `conventions.md`, dot-prefixed slugs, and loose files under `tasks/`) is migrated *and* copied into a timestamped `.ai.local/.rollback/legacy-team-<stamp>/` backup before removal; an entry is deleted only after its copy is verified. Colliding task slugs are kept side by side as `<slug>__from-<tool>/` instead of first-wins. Symlinked legacy `team` dirs and entries are skipped with a warning so `rmSync` cannot escape the resolved `--cwd`. `Migrated legacy …` is logged only when something was actually copied. `.ai.local/.rollback/` carries its own `.gitignore`, so backups cannot be committed by accident and your root `.gitignore` is never edited; backups are not pruned automatically (see `docs/LOCAL-OVERLAY.md` § Migration backups).
+- Living gotchas stay in **`.ai.local/conventions.md`**. Overlay does not load `team/**` as rules. `init` seeds that file from the preset template `presets/<platform>/<stack>/ai-local/conventions.md` (moved out of `team/`) and **never** overwrites an existing consumer file.
+- Consumers: re-run `npx @bonesofspring/ai-rules init <tool|multi> --preset <stack>` to seed/migrate. Commit `.ai.local/team/` if you want tasks to survive clones.
+
+### WP-F: Mavis / OpenCode / multi for all 10 stacks
+
+- `init mavis|opencode|multi --preset <stack>` now covers every installable stack: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, `php-laravel`.
+- Shared derive: `scripts/generate-mavis.mjs --stack <s>` and `scripts/generate-opencode.mjs --stack <s>` (Cursor SoT; never Claude). The thin `generate-*-next.mjs` wrappers were removed in favour of the `--stack` drivers. Profiles in `scripts/lib/stack-platform-profiles.mjs`.
+- Review follow-up (WP-F): derived hooks set `const PLATFORM` to `mavis` / `opencode` (installed metrics no longer record `"cursor"`); OpenCode `openspec-author` allows `openspec/**` and `tech-writer` allows `docs/**` after `"*": deny`.
+- `releasedStacks` in both platform contracts lists all 10. `init multi` already skipped unreleased platforms; after this flip it installs four roots on every stack.
+- OpenCode `permission.edit: allow` follows family (Playwright / XCUITest / instrumentation / integration healers; mcp-ts is `feature-developer` only).
+- Consumers: `npx @bonesofspring/ai-rules init multi --preset <stack>` after publish. Dogfood of this repo stays `next`.
+
 ### Quad-install Next: shared root `AGENTS.md`
 
 - Cursor, Claude, Mavis, and OpenCode **next** presets now ship the **same** `REPO_AGENTS.md` (presence-based load + per-tool pipeline caveat + local overlay). Last `init` still overwrites the file; content no longer depends on which tool ran last.
 - `clean <tool>` leaves root `AGENTS.md` when another tool install is still present.
-- `init multi --preset next` installs all four platforms in one command (Mavis/OpenCode skipped on stacks they have not released).
+- `init multi --preset <stack>` installs all four platforms when the stack is in that platform's `releasedStacks`.
 - Consumers: `npx @bonesofspring/ai-rules init multi --preset next` on Next repos.
 
 ### OpenCode platform (experimental Next-only)
 
 - New platform **`opencode`**: `npx @bonesofspring/ai-rules init opencode --preset next` installs **`.opencode/**`** plus root `AGENTS.md` and merges MCP into **`opencode.json`**. `clean opencode` is manifest/hash-safe. The CLI never writes `~/.config/opencode/**`.
-- Source: `presets/opencode/next/` derived from `presets/cursor/next` (`adapter-map.json`, `generate-opencode-next.mjs`). `platform-contract.json` `releasedStacks: ["next"]`; nine other stacks deferred.
+- Source: `presets/opencode/<stack>/` derived from `presets/cursor/<stack>` (`adapter-map.json`, `generate-opencode.mjs --stack`). Next-pilot `releasedStacks: ["next"]` expanded in WP-F (see above).
 - Native OpenCode discovery for agents, skills, and slash commands. Rules under `.opencode/rules/` are lazy-loaded from `AGENTS.md` (no `alwaysApply`/`globs` engine). Pipeline hook is manual `chain-team-phases.sh` (no `hooks.json` plugin in v1).
 - Docs: [`docs/OPENCODE.md`](docs/OPENCODE.md) (consumer), [`docs/OPENCODE-COMPATIBILITY.md`](docs/OPENCODE-COMPATIBILITY.md) (docs-floor evidence). Gates: `check-opencode-*`, `test-opencode-context-budget` wired into `check:preset-structure`.
 - Review follow-up: team-agent write-scope lead-in is role-specific; consumer `OPENCODE.md` no longer uses broken relative doc links; orchestrator uses OpenCode `mode`/`permission` wording; `build-verifier` preset-structure lists OpenCode/Mavis derive gates; Cursor/Claude `REPO_AGENTS.md` keep OpenCode/Mavis pointers so mixed-tool `init` does not drop them.
@@ -21,8 +46,8 @@
 ### Mavis platform (MiniMax Code, experimental Next-only)
 
 - New platform **`mavis`** (`mcode` runtime): `npx @bonesofspring/ai-rules init mavis --preset next` installs **`.mavis/**`** plus root `AGENTS.md`. `clean mavis` is manifest/hash-safe. MCP merges to **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`.
-- Source: `presets/mavis/next/` derived from `presets/cursor/next` (`adapter-map.json`, `generate-mavis-next.mjs`). `platform-contract.json` `releasedStacks: ["next"]`; nine other stacks deferred (WP-F).
-- Semi-auto orchestration: `chain-team-phases.sh` on `.mavis/team`; no shipped `hooks.json`. Human gates via `task-continue` → hook `end_human_gate`. Agents upsert `artifact-manifest.json` only — hook owns `status.json` / `metrics.json`.
+- Source: `presets/mavis/<stack>/` derived from `presets/cursor/<stack>` (`adapter-map.json`, `generate-mavis.mjs --stack`). Next-pilot `releasedStacks: ["next"]` expanded in WP-F (see above).
+- Semi-auto orchestration: `chain-team-phases.sh` on `.mavis/team` *(superseded by the shared `.ai.local/team/` runtime — see Unreleased)*; no shipped `hooks.json`. Human gates via `task-continue` → hook `end_human_gate`. Agents upsert `artifact-manifest.json` only — hook owns `status.json` / `metrics.json`.
 - Docs: [`docs/MAVIS.md`](docs/MAVIS.md) (consumer), [`docs/MAVIS-COMPATIBILITY.md`](docs/MAVIS-COMPATIBILITY.md) (probe evidence). Gates: `check-mavis-*`, `test-mavis-*` wired into `check:preset-structure`.
 - Consumers: re-run `npx @bonesofspring/ai-rules init mavis --preset next` after publish. Cursor/Claude installs unchanged.
 
@@ -89,9 +114,9 @@ Grouping for the next npm cut: **(A)** post-`0.2.18` delta — MCP merge, spec P
 - **`specMode`** (`consume` | `generate` | `none`) on `brief.md` / optional `pipeline.json`. Spike/research uses `none` — no dummy INDEX row.
 - **`applyReadiness`:** YAML frontmatter on developer `implementation.md`; JSON-shaped `{ state: blocked|ready|all_done, contextFiles[] }` on the analyst receipt (analyst may emit `blocked` before the authoring gate).
 - Requestable skill **`spec-discovery`** (11 methods, mandatory claim ledger). Analyst loads it only for research-before-spec — not default `/task` consume. Cursor + Claude ×10 stacks.
-- **Memlog** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/…`) — append-only agent notes; hook does not parse it.
+- **Memlog** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/…`) *(path superseded by `.ai.local/team/` — see Unreleased)* — append-only agent notes; hook does not parse it.
 - **Code Map** (3–8 annotated paths) + **Suggested Review Order** when a WP spans more than one layer.
-- Skills README catalogs include **`spec-authoring`** (was missing beside `spec-discovery`). Claude nuxt `task-router` writes `.claude/team` (not `.cursor/team`).
+- Skills README catalogs include **`spec-authoring`** (was missing beside `spec-discovery`). Claude nuxt `task-router` writes `.claude/team` (not `.cursor/team`) *(both paths superseded by `.ai.local/team/` — see Unreleased)*.
 - Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish.
 
 ### Spec workflow P0 hygiene

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Volchenkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,145 +1,69 @@
 # @bonesofspring/ai-rules
 
-Presets for Cursor, Claude Code, **Mavis / MiniMax Code (experimental Next-only)**, and **OpenCode (experimental Next-only)**:
-
-Node 18+.
+Presets for **Cursor**, **Claude Code**, **Mavis** (MiniMax `mcode`), and **OpenCode**. Node 18+.
 
 ```bash
-# from the project root
 npx @bonesofspring/ai-rules init multi --preset next
-npx @bonesofspring/ai-rules clean cursor
-npx @bonesofspring/ai-rules clean mavis
-npx @bonesofspring/ai-rules clean opencode
+npx @bonesofspring/ai-rules clean cursor   # never deletes .ai.local/
 ```
 
-Global: `npm i -g @bonesofspring/ai-rules`, then `ai-rules ...`.
-
-`init` merges into the **current working directory** (or `--cwd <dir>`): dirs are created, matching files are **overwritten**, except **`mcp.json` / `.mcp.json`** where `mcpServers` is **merged** (extra local servers are kept; shipped keys update; nested `env` / `headers` on shipped keys are preserved unless the preset defines them). `--preset` defaults to **`next`**. Supported forms:
-
-```bash
-npx @bonesofspring/ai-rules init cursor --preset next
-npx @bonesofspring/ai-rules init cursor next
-npx @bonesofspring/ai-rules init cursor          # preset next by default
-npx @bonesofspring/ai-rules cursor init --preset next
-```
+Run `init` from the **app root** (`--cwd` if needed). Default `--preset` is `next`. Forms: `init cursor --preset next`, `init cursor next`, `init cursor`. Global: `npm i -g @bonesofspring/ai-rules`.
 
-If `.cursor` does not appear, check the command output for errors and confirm you run init from the **target project root** (where the app lives), not from `node_modules`. Success ends with: `Done. .cursor installed at <absolute-path>`.
+`init` overwrites matching files. MCP is the exception: `mcpServers` is **merged** when the existing file is valid JSON (extra servers kept; shipped keys updated; nested `env`/`headers` on shipped keys kept unless the preset defines them). Invalid JSON is backed up to `*.bak.<iso>` and replaced. Deleting a shipped server is not sticky — the next `init` restores it.
 
-**`mcp.json` troubleshooting:** extra overlay servers survive re-init only when the existing file is **valid JSON**. JSONC / trailing commas / a non-object file is copied to a timestamped `mcp.json.bak.<iso>` (or `.mcp.json.bak.<iso>`) and **replaced with the preset** — extras are not merged on that path. Nested `env` / `headers` on shipped server names are kept when the file is valid. Deleting a shipped server (Playwright, Chrome DevTools, Context7, Figma) is **not sticky**: the next `init` restores it.
+## What `init` writes
 
-### `clean` (breaking vs older wipe behavior)
+| | Cursor | Claude | Mavis | OpenCode |
+|---|--------|--------|-------|----------|
+| Rules / commands / agents / skills / hooks | `.cursor/**` | `.claude/**` | `.mavis/**` | `.opencode/**` |
+| Tool map | `.cursor/AGENTS.md` | `.claude/CLAUDE.md` | `.mavis/AGENTS.md` | `.opencode/AGENTS.md` |
+| MCP | `.cursor/mcp.json` (merge) | **`.mcp.json`** (merge) | `.mavis/mcp.json` (merge) | `opencode.json` (merge) |
+| Root agents | `REPO_AGENTS.md` → `AGENTS.md` (same file on all four) | | | |
+| `/task` artifacts | **`.ai.local/team/`** (shared; templates refreshed; `tasks/<slug>/` never overwritten) | | | |
+| Specs seed | `docs/specs/` copied only if the directory is **absent** | | | |
 
-`clean cursor` / `clean claude` removes **only CLI-managed paths** — not the entire `.cursor/` or `.claude/` tree:
+Living exceptions: **`.ai.local/rules/`** and **`.ai.local/conventions.md`** (`init` does not overwrite them). Overlay does not load `.ai.local/team/**` as rules.
 
-- `rules/`, `commands/`
-- optional dirs when present: `agents/`, `hooks/`, `skills/`, `team/`
-- Cursor root files: `hooks.json`, `BUGBOT.md`, `AGENTS.md`, `MCP.md`, `mcp.json`
-- Claude: `CLAUDE.md`, `MCP.md` under `.claude/`; project `.mcp.json` at repo root
-- **Shared root `AGENTS.md`:** removed only when no other tool install remains (Cursor, Claude, Mavis, or OpenCode markers still on disk)
+**`clean <tool>`** removes only CLI-managed paths under that tool root. It does **not** wipe the whole `.cursor/` / `.claude/` tree, and it **never** deletes `.ai.local/`. Root `AGENTS.md` is removed only when no other tool install remains.
 
-Any other files you added under `.cursor/` or `.claude/` (notes, local overrides, IDE state) are **left intact**. Older releases that deleted the whole tool directory are no longer the behavior.
+Mavis never writes `~/.minimax/**`. OpenCode never writes `~/.config/opencode/**`. Guides: [`docs/MAVIS.md`](docs/MAVIS.md), [`docs/OPENCODE.md`](docs/OPENCODE.md).
 
-Where things go on `init`:
+## Shared vs per-tool
 
-| | Cursor | Claude |
-|---|--------|--------|
-| rules | `.cursor/rules` | `.claude/rules` |
-| commands | `.cursor/commands` | `.claude/commands` |
-| agents | `.cursor/agents` | `.claude/agents` |
-| hooks | `.cursor/hooks`, `.cursor/hooks.json` | `.claude/hooks` |
-| hooks cookbook | `.cursor/hooks/examples/` (not in default `hooks.json`) | `.claude/hooks/examples/` |
-| skills | `.cursor/skills` | `.claude/skills` |
-| team artifacts template | `.cursor/team` (incl. `conventions.md`) | `.claude/team` |
-| MCP | `mcp.json` → `.cursor/mcp.json` (**merge** `mcpServers`), `MCP.md` → `.cursor/` | `mcp.json` → **`.mcp.json`** (project root, **merge** `mcpServers`), `MCP.md` → `.claude/` |
-| tool map | `AGENTS.md` → `.cursor/AGENTS.md`, `BUGBOT.md` | `CLAUDE.md` → `.claude/CLAUDE.md` |
-| **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
-| **docs/specs seed** | When `<cwd>/docs/specs/` is **absent**, copy INDEX stub + `_templates/*` from `presets/_shared/assets/docs-specs/` (never overwrite existing INDEX) | same |
+**Shared:** stack semantics, root `AGENTS.md`, `.ai.local/` overlay, `/task` slugs at `.ai.local/team/tasks/<slug>/` (one `status.json` / `metrics.json`).
 
-**Mavis (MiniMax Code, experimental Next-only):** `ai-rules init mavis --preset next` writes ai-rules-owned **`.mavis/**`** plus root `AGENTS.md`. MCP merges into **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`. `clean mavis` is manifest-owned: unchanged hashes are removed; modified files stay. See [`docs/MAVIS.md`](docs/MAVIS.md), [`presets/mavis/README.md`](presets/mavis/README.md), and [`docs/MAVIS-COMPATIBILITY.md`](docs/MAVIS-COMPATIBILITY.md).
+**Per-tool:** how the chain runs. Cursor auto-chains via `hooks.json` / `subagentStop`. Claude, Mavis, and OpenCode use `bash .<tool>/hooks/chain-team-phases.sh` after a producer receipt (Mavis/OpenCode: semi-auto).
 
-**OpenCode (experimental Next-only):** `ai-rules init opencode --preset next` writes native **`.opencode/**`** plus root `AGENTS.md` and merges MCP into **`opencode.json`**. `clean opencode` is manifest-owned. The CLI never writes `~/.config/opencode/**`. All four next platforms ship the **same** root `AGENTS.md` (last `init` still overwrites, content does not change). See [`docs/OPENCODE.md`](docs/OPENCODE.md), [`presets/opencode/README.md`](presets/opencode/README.md), and [`docs/OPENCODE-COMPATIBILITY.md`](docs/OPENCODE-COMPATIBILITY.md).
+`init multi --preset <stack>` installs every platform that lists the stack in `releasedStacks` (all 10 stacks on all four platforms). Commit the four trees, root `AGENTS.md`, and `.ai.local/team/` templates if you want them in the clone.
 
-### Multi-tool on one branch (Next)
+## Stacks
 
-Install all four from the app root (`init multi` is the one-shot), then commit the four trees plus root `AGENTS.md`. Living exceptions belong in **`.ai.local/`** (init never touches it).
+`next` · `nuxt` · `svelte` · `ios-swift` · `android-kotlin` · `go` · `java` · `mcp-ts` · `php-hexagonal` · `php-laravel`
 
 ```bash
-npx @bonesofspring/ai-rules init multi --preset next
+npx @bonesofspring/ai-rules init multi --preset nuxt
 ```
 
-Per-tool: `init cursor|claude|mavis|opencode --preset next`. On stacks other than `next`, `init multi` still installs Cursor and Claude and **skips** Mavis/OpenCode until those platforms list the stack in `releasedStacks`.
-
-**Shared:** stack rules (packaged per tool), root `AGENTS.md`, `.ai.local/` overlay.
-
-**Not shared:** `/task` pipelines. Each tool writes `.tool/team/tasks/<slug>/` (`status.json` is not cross-tool). Cursor auto-chains via `hooks.json` / `subagentStop`. Claude ships `chain-team-phases.sh` without `hooks.json`. Mavis and OpenCode are semi-auto: `printf '{"status":"completed"}' | bash .tool/hooks/chain-team-phases.sh`. Mavis/OpenCode remain Next-only.
-
-Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `mockup-review` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — Figma mockup reviewer via agent `mockup-reviewer`); `ux-design` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — behavioral UX via `task-analyst`, no agent); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
-
-## Product specs (`docs/specs/`)
-
-Presets support **behavior specs** under `docs/specs/**` (INDEX, frontmatter v1, page/feature templates). Three modes:
-
-| Mode | Trigger | Agent behavior |
-|------|---------|----------------|
-| **Consume** | Default when working on listed routes/features | Discover via INDEX; soft-fail on miss; do not invent product behavior |
-| **Generate** | Brief AC, `/spec-start`, or router `spec-gen` with existing tree | **task-analyst** authors/updates specs + INDEX (skill **`spec-authoring`**) |
-| **Bootstrap** | Same triggers when `docs/specs/` absent | Create INDEX + templates + first domain spec |
-
-**First-time seed:** `init` copies INDEX stub + `_templates/*` from package assets when `<cwd>/docs/specs/` is **absent** (see table above). **Troubleshooting:** if you created an empty `docs/specs/` folder before `init`, seed is skipped — delete the folder and re-run `init`, or copy from `presets/_shared/assets/docs-specs/` manually.
-
-**After a package upgrade:** re-run `init` for your stack to refresh rules, `/spec-start`, and `spec-authoring` skill. Agent-generated specs default to `status: draft` until a human promotes them.
-
-**Optional validation** (from `packages/ai-rules/`): `yarn check:product-specs <repo-root>` (WARN) or `--strict` (FAIL). Monorepo dogfood example: `dogfood/mcp-ts-sample/docs/specs/`.
-
-## OpenSpec (`openspec/**`)
-
-OpenSpec (Fission AI `@fission-ai/openspec`) is a **separate spec-driven tree** that lives alongside `docs/specs/`:
+Help: `ai-rules --help`.
 
-| Tree | Owned by | Where |
-|------|----------|-------|
-| `docs/specs/**` | `tech-writer` (product specs) | Generated/consumed by `task-analyst` + `tech-writer` |
-| `openspec/changes/**` | **`openspec-author`** (new agent) | `proposal.md` / `design.md` / `tasks.md` / `specs/**` deltas per `openspec/config.yaml` schema |
-| `openspec/specs/**` | **`openspec-author`** (new agent) | Applied capabilities; refreshed when a change is archived |
+Skills of note: `write-adr` (all except `mcp-ts`); `spec-authoring` / `/spec-start`; `mockup-review` and `ux-design` on UI stacks; `react-performance` (next), `vue-performance` (nuxt), `svelte-performance` (svelte).
 
-The dedicated agent **`openspec-author`** owns the full lifecycle: `explore → propose → apply → archive`. It is reachable from the new router intent `openspec-change` (`/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes`, `openspec/specs`, "OpenSpec change", "обнови openspec"). Default pipeline: `task-analyst → solution-architect (skipIf no architecture delta) → openspec-author (scope: "openspec:<change-id>")`. Scope is always `openspec:<change-id>` — the legacy `scope: openspec-propose` alias is kept on `tech-writer` for backward compatibility.
+## Product specs and OpenSpec
 
-`openspec-author` is installed for **all 9 installable stacks that ship a `docs-only` intent** (everything except `mcp-ts`): `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `php-hexagonal`, `php-laravel`. Read-only against `app/**` and `docs/specs/**` — the agent only emits the openspec tree and reads production code for evidence.
+`docs/specs/**` — consume (default), generate, or bootstrap via `task-analyst` + skill `spec-authoring`. Empty `docs/specs/` before `init` skips the seed: delete the folder and re-init.
 
-The package ships presets including **`next`** (Next.js stack), **`nuxt`** (Nuxt 3 / Vue 3 / Pinia), **`svelte`** (SvelteKit / Svelte 5 / TypeScript / `store-svelte`), **`ios-swift`** (iOS apps on Swift / SwiftUI), **`android-kotlin`** (Android multimodule Kotlin / Compose / Gradle), **`go`** (Go backends with hexagonal architecture), **`java`** (Java / Spring Boot hexagonal backends), **`mcp-ts`** (TypeScript MCP servers with `@modelcontextprotocol/sdk`), **`php-hexagonal`** (PHP / Composer hexagonal backends), and **`php-laravel`** (Laravel backend/API with Eloquent, Form Requests, Policies, Actions/Services). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Preset name is a single path segment (letters, digits, `.`, `_`, `-`); `..` is rejected.
+`openspec/**` is a separate tree owned by agent `openspec-author` (all stacks except `mcp-ts`). Not a substitute for `docs/specs/`.
 
-```bash
-npx @bonesofspring/ai-rules init cursor --preset nuxt
-npx @bonesofspring/ai-rules init claude --preset nuxt
-npx @bonesofspring/ai-rules init cursor --preset svelte
-npx @bonesofspring/ai-rules init claude --preset svelte
-npx @bonesofspring/ai-rules init cursor --preset ios-swift
-npx @bonesofspring/ai-rules init claude --preset ios-swift
-npx @bonesofspring/ai-rules init cursor --preset android-kotlin
-npx @bonesofspring/ai-rules init claude --preset android-kotlin
-npx @bonesofspring/ai-rules init cursor --preset go
-npx @bonesofspring/ai-rules init claude --preset go
-npx @bonesofspring/ai-rules init cursor --preset java
-npx @bonesofspring/ai-rules init claude --preset java
-npx @bonesofspring/ai-rules init cursor --preset mcp-ts
-npx @bonesofspring/ai-rules init claude --preset mcp-ts
-npx @bonesofspring/ai-rules init cursor --preset php-hexagonal
-npx @bonesofspring/ai-rules init claude --preset php-hexagonal
-npx @bonesofspring/ai-rules init cursor --preset php-laravel
-npx @bonesofspring/ai-rules init claude --preset php-laravel
-```
-
-Help: `ai-rules --help`.
+Optional check: `yarn check:product-specs <repo-root>` (WARN) or `--strict`.
 
-## Contributing to presets
+## Contributing
 
-Presets are developed in this monorepo under `presets/`. If you add or change rules, agents, or platform artifacts:
+- Layers: [`presets/_shared/README.md`](presets/_shared/README.md)
+- Guide: [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md)
+- Overlay: [`docs/LOCAL-OVERLAY.md`](docs/LOCAL-OVERLAY.md)
+- Dogfood: [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (and mavis/opencode siblings) — seeds `.ai.local/team`, preserves slugs
+- Gates: `yarn check:preset-structure`
 
-- **Taxonomy & layers:** [`presets/_shared/README.md`](presets/_shared/README.md) — shared core (`_shared/core`), stack adapters, platform packaging (includes requestable embed stem `architecture/product-specs` for consumer `docs/specs` INDEX discovery)
-- **Contribution guide:** [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md) — SoT, twin sync, embed vs lineage, token budget (Cursor ≤4 / Claude exactly 3 always-on), PR checklist, new stack preset, platform-only files (`BUGBOT.md`, `CLAUDE.md`)
-- **Local overlay (`.ai.local/`):** [`docs/LOCAL-OVERLAY.md`](docs/LOCAL-OVERLAY.md) — consumer-owned rules with priority over preset rules; works for Cursor and Claude Code from the same files
-- **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh). Published npm `files` include `scripts/` so consumers can run `check-product-specs.sh` from the package.
-- **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage, shared-core drift (`AI_RULES_DRIFT_FAIL=1`)
-- **Opt-in rule eval:** `yarn check:rule-eval` + `.github/workflows/rule-eval.yml` (`workflow_dispatch` + paths-scoped PR) — **not** wired into `check:preset-structure`
-- **CLI note:** `_shared` is not an installable `--preset`; `init` copies `presets/cursor/<name>/`, `presets/claude/<name>/`, or `presets/mavis/<name>/` when the stack is in `releasedStacks`
+`_shared` is not an installable `--preset`.
 
 MIT.