@bonesofspring/ai-rules 0.2.20 → 0.2.21

package/presets/claude/nuxt/rules/testing/tests-unit.md

@@ -5,71 +5,84 @@ paths:
   - "**/*.test.{ts,tsx}"
 ---
 
-# General testing rules
+# Testing principles
 
-- **File names:** for **new** tests use the **`*.spec.ts` / `*.spec.ts`** suffix. Do not rename existing **`*.test.ts` / `*.test.tsx`** without a separate task (legacy).
-- **Runner and matchers** — as in the project (often Jest or Vitest); for components — **@vue/test-utils**.
-- Primary goal of tests:
-  - verify **behavior and business rules**, not implementation or internal details.
-- **Unit test naming** (strings in `describe` / `it` / `test`):
-  - consumer apps **may use Russian locale** for titles — clear business phrases (what is checked and expected outcome);
-  - when ESLint enforces Russian (see below), each sentence in the title **must start with a capital letter** (including after `.`, `!`, `?` and with multiple sentences on one line); the first letter of the whole string is capitalized too.
-  - **CI check (when configured):** ESLint (`jest/valid-title` in `eslint.config.mjs`) may require titles to start with a Russian capital letter and forbid a space after `.` followed immediately by a lowercase letter (typical "capital after period" violation).
+Stack-agnostic; concrete paths, runners, and selectors live in the stack adapter (`## Stack notes`).
+
+## Behavior vs. implementation
+
+- Verify **behavior and business rules**, not implementation or internal details.
+
+## File naming
+
+- For **new** tests use `*.spec.ts` / `*.spec.tsx`. Do not rename existing `*.test.ts` / `*.test.tsx` without a separate task (legacy).
+
+## Runner and matchers
+
+- Use the project's runner (Jest or Vitest are common); components — the project's Testing Library integration. Reuse existing matchers — no new micro-framework.
+
+## Test title locale
+
+- Consumer apps **may use the project locale** (often Russian) — clear business phrases stating what is checked and the expected outcome.
+- When ESLint enforces the locale (e.g. `jest/valid-title`): each sentence must start with a **capital letter** (including after `.`, `!`, `?`); a space after `.` followed by a lowercase letter is forbidden ("capital after period" violation).
 
 Good (Russian locale in consumer app):
 
 - `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
-- `it('При ошибке сети показывается сообщение об ошибке', () => {})` <!-- i18n-keep: E5 --> (On network error, an error message is shown)
 
 Bad (no capital after period; or wrong locale for configured ESLint):
 
 - `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
-- `it('Returns empty list when user is guest', () => {})`
+- `it('Returns empty list when user is guest', () => {})` (wrong locale if ESLint enforces Russian)
 
-# Component tests
+## Isolation and mocks
 
-- Use `render` from `@vue/test-utils`.
-- Assertions:
-  - DOM matchers for Testing Library as wired in the project (`toBeInTheDocument`, `toHaveTextContent`, etc.).
-- Interactions:
-  - `userEvent` from `@testing-library/user-event`.
+- Mock at the **public-contract boundary**; use the project's accepted HTTP/API/store mock approach. Do not mock what is part of the feature's public contract if that breaks the test's meaning.
 
-# Isolation and mocks
+## Coverage of cross-cutting modules
 
-- For API/store work:
-  - mock the store (via test-store) or use the project's accepted HTTP/API mock approach.
-- Do not mock what is part of the feature's public contract if that breaks the test's meaning.
+- When changing a **shared cross-cutting module** (e.g. HTTP client body parsing, headers, error / auth handling) — **update or add behavior tests** covering success, error, and edge branches relevant to the module under change.
 
-# HTTP client
+## Data transformation coverage
 
-- When changing the **shared HTTP client implementation** (body parsing, headers, error branches, 401/refresh, `FormData`, `blob`, etc.) — **update or add behavior tests** next to the client module in `lib/clients/**` (prefer `*.spec.ts`; legacy `*.test.ts` — do not touch without a task).
-- Cover meaningful branches: successful JSON, HTTP error, network, auth scenarios relevant to the project.
+- Data transformation functions with computed fields and branches must have unit tests covering edge cases (boundary values, missing fields, unexpected value combinations).
 
-# Mappers and data transformation
+## Reuse fixtures over ad-hoc random data
 
-- Data mapping functions (DTO → domain model and back), especially with computed fields and branches, must have unit tests.
-- In mapper tests, pay special attention to edge cases and business-rule regression (for example, boundary values, missing fields, unexpected value combinations).
+- Prefer shared fixtures / handlers from the project's accepted mocks module; do not duplicate interfaces in tests. Use the API response types (DTO types) and the **target domain types** from the project's public type surface.
 
-# Agent requirement
+## E2E: one canonical scenario plan per feature
 
-When adding tests:
-- Follow existing test structure and patterns in the repository: `*.spec.ts(x)` next to the module or in a shared test directory — as in neighboring features.
-- Add tests for critical logic branches and edge cases.
- - When working with data:
-   - use **response types** from the API (DTO types) and **target domain types** from `@/types`; do not duplicate interfaces in tests;
-   - when possible, rely on data and handlers from `mocks/**` (or repo equivalent), not ad-hoc random test data.
- - Placement:
-   - for **UI components** — **do not create** a `__tests__` subdirectory inside the component folder; the test is a sibling `*.spec.ts`.
-   - in **other modules** (for example `api/services`) an existing `__tests__` layout is acceptable — do not break it for UI uniformity.
-   - **new** files — `*.spec.ts` / `*.spec.ts` (see "File names" above).
-## Incorrect
+- For each feature keep a **single canonical scenario plan** (distinct from implementation specs; the stack adapter names the file — typically `*.cases.md`).
 
-```ts
-it('returns empty list when guest', () => {})
-```
+## E2E: scenario ↔ test traceability
 
-- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- Every scenario has a corresponding test. **Do not weaken** assertions to match an outdated implementation — tests must reflect business expectations from the plan. Colocate plan and executable tests in the same directory.
+
+## E2E: page objects / shared helpers
+
+- Prefer page objects and shared helpers over scattered selectors and per-test setup duplication.
+
+## E2E: stable identifiers (PREFIX-XXX)
+
+- When scenarios need stable IDs, prefix the title with `PREFIX-XXX`: `PREFIX` = first letters of words in the entity under test (Latin uppercase); `XXX` = sequential number with three digits and leading zeros. Within one `PREFIX`, numbers must form a consistent sequence with no duplicates.
+- Example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+
+## E2E: selector priority
+
+- Prefer role/label selectors for accessibility and forms; fall back to `data-testid` for stable elements. Use a **hierarchical naming convention** on page roots and key interactive elements (stack adapter defines the scheme — typically `{parent}__{element}`).
+
+## E2E: keep plans and selectors in sync with UI
+
+- When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.
 
-## Correct
+## Stack notes
 
-- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `render` and DOM matchers (`toBeInTheDocument`, `toHaveTextContent`, …) from `@vue/test-utils`.
+- `userEvent` from `@testing-library/user-event`.
+- `jest/valid-title` ESLint rule in `eslint.config.mjs` (Nuxt project root; no `app/` prefix) — capital-after-period.
+- HTTP-client behavior tests next to `lib/clients/**` (Nuxt convention, no `app/` prefix).
+- Shared fixtures live in `mocks/**`; DTO types from API + `@/types` for domain types — never duplicate interfaces in tests.
+- Mock the store via `test-store` (Pinia) or the project's accepted HTTP/API mock approach.
+- UI placement: sibling `*.spec.ts` (no `__tests__/` inside component folder); `api/services` `__tests__` layout is acceptable.
+- `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.

package/presets/claude/nuxt/rules/tooling-and-review/agent-team-orchestrator.md

@@ -1,5 +1,5 @@
 ---
-description: Orchestrates the agent team via task-router and pipeline.json. Use for /task, /task-continue, /feature-start, task decomposition, or when the user describes a feature, bug, or review request.
+description: Orchestrates the agent team via task-router and pipeline.json. Use for /task, /task-continue, task decomposition, or when the user describes a feature, bug, or review request.
 paths: .claude/team/**
 ---
 
@@ -17,8 +17,6 @@ Work request without `/task` — see **`agent-team-intake.mdc`** (when to sugges
 |---------|------|
 | **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
 | `/task-continue <slug>` | After human gate or pause |
-| `/feature-start <desc>` | Legacy: analyst-only start (no router) |
-| `/feature-continue <slug>` | Alias of task-continue |
 | `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
 | `/technical-retro [slug]` | Retro with agent team block |
 
@@ -50,6 +48,7 @@ Work request without `/task` — see **`agent-team-intake.mdc`** (when to sugges
 | `playwright-test-generator` | e2e tests | e2e spec generation |
 | `playwright-test-healer` | e2e fixes | failing/flaky e2e fixes |
 | `tech-writer` | docs / team | docs-only, feature/migration docs |
+| `openspec-author` | `openspec/**` only | openspec-change (`/opsx:propose`, `/opsx:apply`, `/opsx:archive`, openspec refresh) |
 
 **Cursor frontmatter:** all team pipeline agents use `readonly: false` so they can write `.cursor/team/**`. Production/app restrictions live in the agent prompt body — do **not** set `readonly: true` (Cursor blocks *all* file writes, including team artifacts).
 
@@ -57,7 +56,7 @@ Full prompts: `.cursor/agents/*.md`. Artifact conventions: `.cursor/team/README.
 
 **Behavioral UX:** `task-analyst` loads requestable skill `ux-design` for standalone intent `ux-design` and embedded required-signal / advisory UI AC. No `ux-designer` agent in v1.
 
-**Product specs:** When `/task`, `/feature-start`, or `/spec-start` touches pages/features/`docs/specs`: if INDEX exists and no generate intent → instruct next agent to load requestable **`product-specs`** (consume; soft-fail; never invent). If generate/bootstrap/`spec-gen` → load **`product-specs-authoring`** + skill **`spec-authoring`** inside **task-analyst** (not a separate pipeline step); pass created spec paths + INDEX diff in handoff; human gate must approve before feature-developer. No-op if INDEX absent and no author intent.
+**Product specs:** When `/task` or `/spec-start` touches pages/features/`docs/specs`: if INDEX exists and no generate intent → instruct next agent to load requestable **`product-specs`** (consume; soft-fail; never invent). If generate/bootstrap/`spec-gen` → load **`product-specs-authoring`** + skill **`spec-authoring`** inside **task-analyst** (not a separate pipeline step); pass created spec paths + INDEX diff in handoff; human gate must approve before feature-developer. No-op if INDEX absent and no author intent.
 
 When editing `packages/ai-rules/presets/**`, follow **`preset-pr-checklist.mdc`** (+ twin-sync / layering / token-budget / leakage meta-rules).
 
@@ -180,7 +179,7 @@ After each agent completes, verify its terminal manifest receipt, then let the o
 
 ## Legacy mode
 
-If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+If `pipeline.json` is missing, fall back to fixed phases: analysis → development → review → testing. Hook supports both.
 
 ## Skip pipeline when
 
@@ -196,3 +195,7 @@ Borderline work requests — see **`agent-team-intake.mdc`**.
 ## Auto-detection (optional)
 
 When user describes a **non-trivial task** (not a question), suggest `/task <message>` or run router if they agree.
+
+## Preset authoring
+
+When the work edits `packages/ai-rules/presets/**` (or dogfood `.claude/` sync of presets), follow meta-rules: **preset-pr-checklist**, **preset-twin-sync**, **preset-layering**, **preset-token-budget**, **preset-no-cross-stack-leakage**.

package/presets/claude/nuxt/rules/tooling-and-review/ai-local-overlay.md

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

package/presets/claude/nuxt/rules/tooling-and-review/preset-pr-checklist.md

@@ -15,11 +15,15 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
-- [ ] **Token budget:** alwaysApply / session-start ≤ 3; meta rules not always-on
+- [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
+- [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
+- [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.
+- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` across the 10 stacks × 2 platforms (20 hooks) holds. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
 - [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
 - [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
 - [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
+- [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
 - [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (or document intentional skip) when maintaining this monorepo
 - [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
 

package/presets/claude/nuxt/rules/tooling-and-review/preset-token-budget.md

@@ -14,12 +14,16 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | Platform | Always-on | Cap |
 |----------|-----------|-----|
-| Cursor | `alwaysApply: true` | **≤ 3** |
+| Cursor | `alwaysApply: true` | **≤ 4** |
 | Claude | rules **without** `paths:` | **exactly 3** |
 
+**Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
+
 **Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
 
-Session-start body budget (where documented): ≤140 lines total (stretch ≤120).
+Session-start body budget:
+- Claude trio: ≤140 lines total (stretch ≤120).
+- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
 
 ## Meta / author rules
 
@@ -35,4 +39,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## Verifier
 
-build-verifier **FAIL** if alwaysApply / session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.
+build-verifier **FAIL** if Cursor `alwaysApply` count exceeds 4, Claude session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/claude/nuxt/rules/tooling-and-review/preset-twin-sync.md

@@ -35,6 +35,8 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 
 - **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
 - **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
+- **Slim-companion rules** (UI-edit bundle, slim app-cores, slim tooling): may be shorter than 15 lines **if and only if** the body is a pointer into shared-core / stack-prose (no standalone prose). Examples live in stack `rules/README.md` (e.g. `cursor/next/rules/README.md` "UI-edit bundle" intent).
+  - **Mechanical enforcement is pending.** Today build-verifier excludes only `agent-team-intake` / `technical-retro` / `preset-layering`; slim-companion rules currently pass under the same human-judgement path as thin aliases. Follow-up: add `allow_slim_stems` to `packages/ai-rules/scripts/check-preset-token-budget.sh` analogous to `trio_stems_allowlist`.
 
 ## Severity (build-verifier)
 

package/presets/claude/nuxt/team/README.md

@@ -106,8 +106,6 @@ Prefer **`executing`** for pipeline mode. Legacy: `analysis`, `development`, `re
 /technical-retro <slug>
 ```
 
-Legacy: `/feature-start`, `/feature-continue`.
-
 ## 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).
@@ -116,7 +114,6 @@ Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook ow
 
 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).

package/presets/claude/php-hexagonal/CLAUDE.md

@@ -16,7 +16,7 @@ Preset for PHP backends using ports & adapters (PSR / Composer-first).
 
 - **21 agents** — `agents/README.md` (no a11y / Playwright / XCUITest)
 - **10 skills** — feature-delivery, spec-authoring, spec-discovery, unit-testing, integration-testing, ci-investigation, debug-investigation, code-review, technical-retro, write-adr
-- **5 commands** — `/task`, `/task-continue`, `/feature-start`, `/feature-continue`, `/technical-retro`
+- **3 commands** — `/task`, `/task-continue`, `/technical-retro`
 
 ## Dogfood (5 scenarios)
 

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

@@ -8,7 +8,7 @@ Role subagents for the Claude Code agent-team pipeline (PHP hexagonal).
 |-------|------|-----------------|
 | Codebase analyzer | `codebase-analyzer.md` | no (explain-as-is only) |
 
-## Roster (21)
+## Roster (22)
 
 | Agent | Production writes |
 |-------|-------------------|
@@ -19,6 +19,7 @@ Role subagents for the Claude Code agent-team pipeline (PHP hexagonal).
 | debugger, ci-investigator | minimal |
 | code-reviewer, security-reviewer, performance-auditor | team only |
 | migration-specialist, api-contract-reviewer, tech-writer | team / docs |
+| openspec-author | `openspec/**` only — used only when the consumer repo has `openspec/` initialized |
 | qa-tester, unit-test-*, integration-test-* | tests |
 
 **No** `accessibility-reviewer`, Playwright, or XCUITest stems. Replace those intents with **`integration-test-*`**.
@@ -28,5 +29,5 @@ Role subagents for the Claude Code agent-team pipeline (PHP hexagonal).
 | Tier | Agents |
 |------|--------|
 | **cheap** | router, analyst, build-verifier, code-reviewer, tech-writer, codebase-analyzer |
-| **standard** | developer, debugger, ci-investigator, api-contract, qa, unit-*, integration-* |
+| **standard** | developer, debugger, ci-investigator, api-contract, qa, unit-*, integration-*, openspec-author |
 | **strong** | solution-architect, migration-specialist, security-reviewer, performance-auditor |

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

@@ -0,0 +1,163 @@
+---
+name: openspec-author
+description: OpenSpec (spec-driven SDD) specialist. Explores openspec/specs/**, authors/refreshes/archives openspec/changes/** proposal–design–tasks–spec deltas per openspec/config.yaml schema. Reads app/** for evidence; never edits production code. Use when pipeline steps reference openspec/changes, /opsx:propose, /opsx:apply, /opsx:archive, openspec/specs, or scope is a change-id.
+model: inherit
+---
+
+You are an **OpenSpec** (Fission AI spec-driven SDD) author for a frontend/backend agent team.
+
+Your only writes target `openspec/**` (and team artifact manifests). Production code lives behind `feature-developer`; you are **docs / spec only**.
+
+## When to load
+
+You are invoked when:
+
+- Pipeline step `agent` is `openspec-author`.
+- Pipeline step `scope` is `openspec:<change-id>` (preferred) or `openspec-propose` (legacy alias — treat as `openspec:openspec-<change-id>` only when the handoff brief explicitly names the change-id).
+- Prompt includes `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes`, `openspec/specs`, `openspec/config.yaml`, or `openspec validate`.
+- Per task-analyst / solution-architect handoff, refresh an existing capability or scaffold a brand-new change.
+
+If `openspec/` is absent in the repo, stop and report `blocked` with the message *"openspec/** not initialized — run `openspec init` first"* — never invent directories.
+
+## 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`.
+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.
+6. Source tree for code-evidence reads only — `app/src/**`, `src/**`, or stack equivalent. **Never edit.** Cite path:line in requirements, scenarios, design notes.
+7. Pipeline step `scope` — must be `openspec:<change-id>` (e.g. `openspec:MEDCARD-11762-sync-offline-consultation-spec`).
+
+## Phase discipline (mirrors `/opsx:propose` → `/opsx:apply` → `/opsx:archive`)
+
+Pipeline step `scope` may encode a single phase or full lifecycle. Match the body to the phase, do not skip phases within a single invocation.
+
+### Phase 1 — Explore
+
+1. Read `openspec/config.yaml`. Confirm `schema:` and the four `rules.*` blocks.
+2. Read `openspec/specs/**/spec.md` (one file per capability) — note each capability's `## Purpose` and current `## Requirements`.
+3. Read `openspec/changes/archive/**/proposal.md` for prior decisions and OQ defaults that map to this change.
+4. Code-archaeology (read-only) on the affected source tree: list concrete routes, flags, slices, thunks, record statuses. Label every observation `code-evidence`.
+5. Emit a capability delta as `NEW | MODIFIED | REMOVED | RENAMED` with affected file paths.
+6. If a required source artefact is missing (e.g. `architecture.md` not produced), set `blocked` with the gap, do not invent.
+
+### Phase 2 — Propose
+
+Scaffold `openspec/changes/<change-id>/`:
+
+```
+openspec/changes/<change-id>/
+├── .openspec.yaml          # schema mirror, change-id, created date
+├── proposal.md             # Why / What Changes / Capabilities / Non-goals / Impact — under 500 words per config.rules.proposal
+├── design.md               # Context / Goals / Decisions (D-1..) / Data flow (mermaid) / Open questions (OQ-1..)
+├── tasks.md                # 1.1, 1.2, … — AC + verification checklists for future SDD
+└── specs/<capability>/
+    └── spec.md             # delta block: `## MODIFIED Requirements` and/or `## REMOVED Requirements`
+```
+
+Hard constraints (read `config.yaml rules.proposal` first — they win):
+
+- `proposal.md` ≤ 500 words.
+- `## Non-goals` section mandatory (omit → `blocked`).
+- `## What Changes` lists capability deltas **only**; no implementation steps.
+- `## Capabilities` table groups deltas by capability slug; cite spec paths.
+- Spec deltas use `## MODIFIED Requirements` heading (or `## REMOVED Requirements`); Each `### Requirement:` block carries `SHALL` statements and `#### Scenario:` Given/When/Then. Mirror existing capability voice.
+- `design.md` data-flow is mermaid or ascii (no proprietary XML). Document **current as-is** unless the change is explicitly redesign.
+- `tasks.md` 1.1, 1.2, 1.3 — each ≤ 5 acceptance bullets + verification note. **No production code in tasks**; tasks are **for future SDD implementation/tests**, not for rewriting the page now.
+
+### Phase 3 — Apply (validate, do not merge to specs)
+
+Run from repo root:
+
+```bash
+openspec validate <change-id> --type change --strict   # must pass
+openspec validate --specs --strict                     # must pass — surviving capabilities
+openspec show  <change-id> --json --deltas-only        # handoff receipt
+```
+
+On FAIL: fix the offending markdowns (cite config rule that failed), re-run. On second FAIL: stop, emit `blocked`, attach the validator output.
+
+Do **not** move the change into `openspec/specs/` — that is the human merge step (`/opsx:apply` after review).
+
+### Phase 4 — Archive (post-merge)
+
+After a human gate `applied` confirmation:
+
+```bash
+# Move the approved change into archive; preserve prior archive intact.
+mv openspec/changes/<change-id> openspec/changes/archive/<YYYY-MM-DD>-<change-id>
+```
+
+Update `openspec/changes/archive/INDEX.md` if present. Verify that no surviving capability now references the archived `proposal.md` accidentally.
+
+If `scope` carries multiple phases (e.g. `openspec:<change-id>:propose+apply`), one invocation may emit all four files and the validator receipts. If `scope` is single-phase, emit only the matching files.
+
+## Source discipline
+
+- **Never invent** product behavior. Cite `path:line` for every requirement that depends on code. Label inferred lines as `> Status: inferred (no AC)` rather than fabricating fields.
+- Reuse archive decisions: if `archive/.../proposal.md` records `D-3: X`, only fork when code-evidence contradicts X — append `D-N+1` rather than rewriting.
+- Resolve OQ defaults from the most recent archive that touched the same capability; otherwise raise the OQ in the new change and stop until the human answers.
+- Capability naming mirrors surviving `openspec/specs/<capability>/spec.md` slugs; new capabilities use the same domain vocabulary as `config.yaml context`.
+
+## Will / Will not
+
+**Will**
+
+- Read `app/src/**` (or stack equivalent) for evidence; never write.
+- Create or update files under `openspec/changes/<change-id>/**` and the associated `specs/<capability>/spec.md` delta.
+- Move an approved change into `openspec/changes/archive/<YYYY-MM-DD>-<change-id>/`.
+- Run `openspec validate` and `openspec show --deltas-only`; surface FAIL output verbatim.
+- Reference `openspec/config.yaml` rules in any deviation comment.
+
+**Will not**
+
+- Edit `app/**`, `app/src/**`, `src/**`, or any production-code tree.
+- Edit `docs/specs/**` — that file tree belongs to skill `spec-authoring` (`docs/specs/INDEX.md` + page/feature templates). Hand off via `open_questions` if a request conflates the two.
+- Edit `openspec/specs/**` directly (apply via the change, never in place).
+- Skip the `## Non-goals` section in `proposal.md` even when the user omits it.
+- Use `scope: openspec-propose` in **new** pipelines — it is a legacy alias for `openspec:<change-id>`; keep emitting the correct scope name. (Tech-writer still carries the legacy alias for in-flight replays.)
+- Invent routes, flags, status names, or DTO fields. Cite or raise OQ.
+
+## 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`).
+- **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`:
+
+```markdown
+# OpenSpec change: <change-id>
+
+## Phase emitted
+explore | propose | apply | archive | full
+
+## Capabilities touched
+- <slug> — NEW | MODIFIED | REMOVED | RENAMED (cite openspec/specs/<slug>/spec.md or planned spec path)
+
+## Validator receipt
+- `openspec validate <change-id> --type change --strict` → <PASS|FAIL> (exit <n>)
+- `openspec validate --specs --strict` → <PASS|FAIL> (n surviving)
+- `openspec show <change-id> --json --deltas-only` → paths: ...
+
+## Open questions (forwarded to human gate)
+- OQ-N: …
+```
+
+## Anti-sycophancy
+
+Match `code-quality-and-refactoring.mdc`:
+
+- Verbatim third-party API (openspec CLI flags) → never invent flags; `// VERIFY: openspec.<flag> @ <version>` if uncertain; consult `npx openspec --help`.
+- Before "is this correct?" — list ≥3 failure modes for the chosen delta (capability obsolescence, schema drift, archive mismatch, prod code-only evidence, conflict with prior D-N).
+- Refactor without tests — N/A (docs only) but if the team lacks an existing spec for the change, raise OQ before proposing.
+- Comments — WHY only when non-obvious (e.g. when forking `config.yaml rules.proposal`); never narrate.
+- Urgency — name the trade-off (e.g. "Use spec-driven character sketch over future-SDD rewrite because config.rules.design forbids redesign") and comply.
+
+## MCP usage (on-demand)
+
+Load `mcp-usage` only when needing Context7 for an unknown openspec CLI flag or third-party library. Default: rely on `npx openspec --help` and `openspec/config.yaml` rules; mark `// VERIFY: openspec.<flag>` if behavior is unclear.

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

@@ -27,6 +27,7 @@ You are a task router for a **PHP hexagonal backend** agent team. You **do not**
 | `unit-only` | «unit», «юнит» (unit), «покрой use case» (cover use case) | unit-test-planner → unit-test-generator, or unit-test-healer | <!-- i18n-keep: E4 -->
 | `e2e-only` / integration | «integration», «e2e», «HTTP controller tests», «integration DB fixtures» | **integration-test-planner** → **integration-test-generator**, or **integration-test-healer** |
 | `docs-only` | «документация» (documentation), «README», «changelog» | task-analyst → tech-writer | <!-- i18n-keep: E4 -->
+| `openspec-change` | `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes`, `openspec/specs`, `openspec/config.yaml`, «обнови openspec» (refresh openspec), «OpenSpec change», «open-spec propose», openspec refresh | task-analyst → solution-architect (skipIf no architecture delta) → openspec-author (scope: `openspec:<change-id>`) | <!-- i18n-keep: E4 -->
 | `refactor` | «рефакторинг» (refactoring), «без изменения поведения» (no behavior change) | task-analyst → feature-developer → build-verifier → code-reviewer | <!-- i18n-keep: E4 -->
 | `spike` | «исследуй» (investigate), «spike», proof of concept | task-analyst → solution-architect | <!-- i18n-keep: E4 -->
 | `retro` | «ретро» (retro), «postmortem» | (orchestrator → `/technical-retro`) | <!-- i18n-keep: E4 -->
@@ -90,6 +91,7 @@ Fixtures: `.claude/team/fixtures/` (feature-full, feature-light, bugfix-standard
 |--------|-------------------|
 | feature, refactor, test-only | `["after:task-analyst"]` |
 | spec-gen | `["after:task-analyst"]` |
+| openspec-change | `["after:task-analyst"]` (human approves brief + AC; openspec-author emits drafts and validator receipts under the assigned change-id) |
 | migration | `["after:migration-specialist"]` |
 | unit-only | `["after:unit-test-planner"]` when new plan |
 | e2e-only / integration | `["after:integration-test-planner"]` when new plan |
@@ -113,7 +115,9 @@ Detect and set routing reasons when the user asks to **generate / bootstrap prod
 | `/spec-start`, "bootstrap docs/specs", "generate product spec" | `spec-gen` | task-analyst (**author mode**) → human gate → stop (or continue to feature-developer only if implement-after) |
 | Feature/task with AC "generate specs" / missing INDEX + bootstrap AC | `spec-gen` inside feature profile | task-analyst author mode first; **not** a separate agent step |
 
-Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
+Do **not** add a dedicated `spec-author` agent for `docs/specs/**`. Do not require solution-architect for routine spec authoring of `docs/specs/**`.
+
+**openspec is a different file tree** (`openspec/changes/`, `openspec/specs/`) — it is not `docs/specs/`. The dedicated agent `openspec-author` lives in `agents/openspec-author.md`; it owns `openspec/changes/<id>/**` end-to-end (explore → propose → validate → archive) and is reachable via the `openspec-change` intent row in § Intent detection. Any pipeline that asks for `/opsx:*` or targets `openspec/**` should route there instead of `spec-gen`.
 
 
 **specMode (optional `pipeline.json` field):** `none` for spike/research; `generate` for `spec-gen` / `/spec-start`; `consume` default when INDEX exists. Echo top-level `specMode`. Brief `## Spec mode` wins on conflict.

package/presets/claude/php-hexagonal/agents/tech-writer.md

@@ -14,6 +14,10 @@ Write documentation from task artifacts (brief, architecture, implementation, re
 
 Do not change production `.php` business logic.
 
+## OpenSpec (`openspec/changes/**`, `openspec/specs/**`)
+
+The `openspec/**` file tree is owned by the dedicated agent **`openspec-author`**, not by this agent. When a handoff brief or pipeline step mentions `/opsx:propose`, `/opsx:apply`, `/opsx:archive`, `openspec/changes/`, or `openspec/specs/`, hand off to `openspec-author` instead of authoring here. The legacy pipeline scope `openspec-propose` (used in early emedcard-web pipelines) maps to the new scope `openspec:<change-id>` and the new agent — keep emitting the legacy scope only as a backward-compatible alias while in-flight replays complete.
+
 ## Product specs (docs/specs)
 
 Post-delivery: when behavior or public docs changed and `docs/specs/` is in play, load **`product-specs`** (+ **`product-specs-authoring`** if updating specs). Sync page/feature specs + INDEX in the **same change set**. **Never invent** product behavior without AC/code source; label inferred lines `status: draft`. Soft-fail on miss; no-op if INDEX absent and sync not requested.

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

@@ -6,8 +6,6 @@ Slash-command definitions and on-demand scenarios. Copied to `.claude/commands/`
 |------|---------|
 | `task.md` | Unified entry point: router → dynamic pipeline → first agent |
 | `task-continue.md` | Continue after human gate / pause using `pipeline.json` |
-| `feature-start.md` | Legacy analyst-only start without router |
-| `feature-continue.md` | Legacy continue; with `pipeline.json` delegates to `/task-continue` semantics |
 | `technical-retro.md` | Facilitate a technical retro, 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/`.

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

@@ -5,7 +5,7 @@ description: Continue an agent-team task after a human gate, pause, or review ch
 
 # Task continue — after human gate or pause
 
-Resume the pipeline from `pipeline.json`. Semantic alias: `/feature-continue`.
+Resume the pipeline from `pipeline.json`.
 
 ## Arguments
 

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

@@ -33,7 +33,7 @@ Examples:
    - **do not** write lifecycle fields in `status.json` / `metrics.json` yourself — orchestration runtime/hook owns them (see **agent-artifact-contracts**). If `status.json` is missing, only minimal bootstrap is allowed (`slug`, `intent`, `pipelineIndex: 0`, `currentAgent: steps[0]`, `state: in_progress`) — **do not** increment `pipelineIndex` manually;
    - invoke subagent for `pipeline.steps[0].agent` (slug, artifact paths, scope).
 6. **After each agent** — wait for hook handoff / reconciliation terminal receipt → `status.state`; do not start the next step until `status.json` reflects handoff (or until there is a `followup_message` from the hook).
-7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for `/task-continue <slug>` (or `/feature-continue <slug>`).
+7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for `/task-continue <slug>`.
 
 ## Do not
 
@@ -46,9 +46,6 @@ Examples:
 - `awaitingHumanGate` / `state: awaiting_approval` → offer artifact review or `/task-continue <slug>`.
 - `in_progress` → ask: continue or new slug.
 
-## Legacy
-
-`/feature-start` and `/feature-continue` remain compatible; for new tasks prefer `/task`.
 
 ## Metrics