@bonesofspring/ai-rules 0.2.19 → 0.2.21

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

@@ -39,6 +39,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/mcp-ts/skills/code-review/SKILL.md

@@ -9,3 +9,9 @@ description: Reviews MCP TypeScript diffs for boundaries, schema contracts, capa
 2. Flag monolithic entry files, schema/protocol mismatches, unscopeed capabilities, secret leakage.
 3. Phase 1: security-reviewer covers threat model; no separate `code-reviewer` agent yet — parent may apply this skill directly.
 For agent team tasks, write the review artifact and upsert the owned terminal receipt (`completed` or `changes_requested`); do not mutate `status.json`.
+
+## Receiving review feedback
+
+<!-- shared-core: review/receiving-code-review.md -->
+
+When **implementing** review comments (not when issuing them): verify each item against the codebase before changing code; do not perform agreement (`You're absolutely right!`). Unclear items → ask, do not guess.

package/presets/claude/mcp-ts/skills/debug-investigation/SKILL.md

@@ -3,16 +3,44 @@ name: debug-investigation
 description: Investigates MCP server bugs with runtime evidence — schema failures, handler errors, transport startup. Use for failing tests or incorrect tool behavior.
 ---
 
-# Debug investigation (mcp-ts)
+<!-- shared-core: quality/debug-investigation.md -->
+
+# Debug investigation
+
+Stack-agnostic root-cause loop. Consumed by skill `debug-investigation` and agent `debugger`. Platform paths, MCP, and stack commands belong in adapter **Stack notes**.
+
+## When
+
+Any bug, test failure, build failure, or unexpected behavior — **before** proposing a fix.
+
+## Phases (in order)
+
+1. **Evidence** — reproduce, or collect the closest evidence (error output, failing test, logs, user steps).
+2. **Isolate** — expected vs actual in one sentence; smallest relevant slice of the codebase.
+3. **Root cause** — name the cause before editing. One hypothesis at a time; do not stack speculative fixes.
+4. **Minimal fix + verify** — smallest change that preserves architecture and public contracts. Add a regression test when the behavior is user-facing or likely to recur. Re-run the **failing** check first, then the relevant lint/type/test slice.
+
+## 3-fix architecture gate
+
+If **three** fix attempts fail, or the same symptom returns after two supposed fixes: **STOP**. Do not attempt fix #4. Escalate — the design is likely wrong (human partner or `solution-architect`). Chasing symptoms is the failure mode.
+
+## Do not
+
+- Broad refactor during a bugfix.
+- Fix only where the error surfaces if invalid data originates elsewhere.
+- Claim `fixApplied: true` without re-running the failing check (see `quality/verification-before-completion.md`).
+
+## Stack notes
+
+### Stack process
 
 1. Reproduce with unit/contract fixtures before changing code.
 2. Check schema validation vs handler logic vs registration wiring.
 3. Prefer repository tests over ad-hoc Inspector-only claims.
 4. Load `anti-sycophancy-discipline` — report what was verified.
 
-## MCP usage
+### MCP usage
 
 Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
 
 If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
-

package/presets/claude/next/README.md

@@ -23,6 +23,7 @@ Rule files are ordinary Markdown with optional YAML frontmatter (`paths:` for pa
 - **Cursor SoT:** `presets/cursor/next/` — this preset is the derived twin; edit Cursor first, same PR
 - **Cursor→Claude map + core table:** [`rules/README.md`](./rules/README.md)
 - **Author meta:** `tooling-and-review/preset-*.md` (`paths:` on `packages/ai-rules/presets/**` only)
+- **Local overlay:** `tooling-and-review/ai-local-overlay.md` (also present in Cursor) — see [`../../docs/LOCAL-OVERLAY.md`](../../docs/LOCAL-OVERLAY.md)
 
 ## Agent team workflow
 

package/presets/claude/next/agents/README.md

@@ -54,6 +54,7 @@ Specialized subagents (personas) — per [Claude Code documentation](https://cod
 | Agent | File | Production code |
 |-------|------|----------------|
 | Tech writer | `tech-writer.md` | docs only |
+| OpenSpec author | `openspec-author.md` | `openspec/**` only (proposal/design/tasks/spec deltas; reads `app/**` for evidence) |
 
 The folder is copied to `.claude/agents/` on `ai-rules init claude --preset next`.
 
@@ -64,7 +65,7 @@ Default SoT — YAML `model` in each agent file. Optional `steps[].model` (`chea
 | Tier | Default frontmatter | Agents |
 |------|---------------------|--------|
 | **cheap** | `fast` | `task-router`, `task-analyst`, `build-verifier`, `code-reviewer`, `tech-writer`, `codebase-analyzer` |
-| **standard** | `inherit` or `sonnet` | `feature-developer`, `debugger`, `ci-investigator`, `api-contract-reviewer`, `accessibility-reviewer`, `qa-tester`, `unit-test-*`, `playwright-test-*` (`sonnet` where already pinned) |
+| **standard** | `inherit` or `sonnet` | `feature-developer`, `debugger`, `ci-investigator`, `api-contract-reviewer`, `accessibility-reviewer`, `qa-tester`, `unit-test-*`, `playwright-test-*`, `openspec-author` (`sonnet` where already pinned) |
 | **strong** | `opus` | `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor`, `mockup-reviewer` |
 
 **Notes**
@@ -79,7 +80,6 @@ Default SoT — YAML `model` in each agent file. Optional `steps[].model` (`chea
 |---------|------------|
 | `/task <desc>` | Router → dynamic pipeline → first agent |
 | `/task-continue <slug>` | After human gate |
-| `/feature-start`, `/feature-continue` | Legacy (compatibility) |
 
 Rule: `tooling-and-review/agent-team-orchestrator.md`. Plan: `pipeline.json` in `.claude/team/tasks/<slug>/`.
 

package/presets/claude/next/agents/build-verifier.md

@@ -25,13 +25,19 @@ Use **`rules/tooling-and-review/package-manager.md`** for the repo package manag
 
 Prefer **`lint`** (= js + css + type-check) before handoff on large changes.
 
+## Verification before completion
+
+<!-- shared-core: quality/verification-before-completion.md -->
+
+Before writing `validation-report.md` or claiming PASS: IDENTIFY the commands, RUN them, READ exit codes, VERIFY they match the verdict, THEN claim. Do not mark PASS from memory of a prior developer run.
+
 ## Preset-structure validation (when scope is preset / packages/ai-rules)
 
 When validating **preset packaging** changes (paths under `packages/ai-rules/presets/**`, or `scope: preset-structure-validation` / `preset-artifacts-only`), run these checks. Skip app lint if there are **no** app source changes.
 
 ### FAIL (all stacks)
 
-1. **Token budget:** Cursor `alwaysApply: true` count ≤ **3**; Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be session-start (must have `paths:`).
+1. **Token budget:** Cursor `alwaysApply: true` count ≤ **4** (4th slot reserved for `ai-local-overlay`); Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be session-start (must have `paths:`).
 2. **Leakage (next):** hooks/agents must not require `xcuitest-test-*` handoffs or `xcodebuild` as the default Next post-change gate. See `tooling-and-review/preset-no-cross-stack-leakage.md`.
 3. **Mapping / README:** `rules/README.md` must include a Cursor→Claude mapping table; document core→stack mapping when `_shared` consumers exist.
 4. **shared-core consumers:** if `_shared/core/**` changed, every file with matching `<!-- shared-core: … -->` in this PR must be updated (or intentional fork documented).
@@ -59,6 +65,16 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 - Thin aliases may be &lt;15 body lines.
 - Embed vs lineage: `docs/PRESET-CONTRIBUTION.md`, `_shared/README.md`.
 
+### Local overlay compliance (soft gate)
+
+When the agent's transcript touches files in the repo, do a **soft check** on `.ai.local/`:
+
+1. **Existence probe.** If `.ai.local/` exists at the repo root or any nesting depth, the agent's transcript must contain an acknowledgement line of the form `Using .ai.local: <rule-name>(, <rule-name>)*` (the `ai-local-overlay` rule mandates this format). Missing acknowledgement → **soft WARN**.
+2. **Override honours.** If a local rule contains `override: kill <preset-rule-name>`, the agent's reasoning must not invoke the killed preset rule. Violation → **soft WARN**.
+3. **No drift on init.** If `.ai.local/` exists and `init` would overwrite a file under `.ai.local/rules/`, warn the user — `init` does not touch `.ai.local/` today, but if a future `init` change does, this gate is the surface to flag it.
+
+Soft WARNs do **not** fail the pipeline. They appear in the validation report under `## Soft notes` and are reviewed by the human gate. Repeated soft WARNs across runs on the same repo → log a recommendation to promote the local rule to a preset rule (`docs/LOCAL-OVERLAY.md` § "When to upgrade to a preset change").
+
 ### ios-swift-only checks
 
 When ios-swift paths are also in the PR, apply ios-swift verifier checks (chain fork, Playwright leakage) — **FAIL**.

package/presets/claude/next/agents/ci-investigator.md

@@ -66,3 +66,4 @@ Provide summary: failed check, root cause, files changed, validation commands ru
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+- When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.

package/presets/claude/next/agents/code-reviewer.md

@@ -14,6 +14,8 @@ You are a senior code reviewer. You may write only review artifacts under `.clau
 
 Apply the **`code-review` skill** and **`rules/tooling-and-review/code-review-mr.md`** checklist.
 
+You **issue** reviews. Implementers acting on your findings must verify each item against the codebase and must not perform agreement. Do not require gratitude in replies.
+
 ## Tests gate
 
 - If diff changes mappers, store reducers/thunks, or domain logic **without** new/updated `*.spec.ts` → **REQUEST_CHANGES** unless task scope explicitly excludes tests.

package/presets/claude/next/agents/debugger.md

@@ -45,6 +45,10 @@ fixApplied: false
 
 5. If fix is trivial and clearly scoped, you **may** apply the minimal fix and set `fixApplied: true` in the report. Otherwise leave implementation to **feature-developer** with `fixApplied: false`.
 
+## 3-fix architecture gate
+
+After **three** unsuccessful fix attempts (or the same symptom returning twice): STOP. Do not attempt fix #4. Escalate architecture with the human or `solution-architect`. Follow skill `debug-investigation`. Before `fixApplied: true`, re-run the failing check.
+
 
 ## MCP usage
 
@@ -75,3 +79,4 @@ Do not perform formal code review or write e2e plans — those are separate agen
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+- When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.

package/presets/claude/next/agents/feature-developer.md

@@ -1,6 +1,6 @@
 ---
 name: feature-developer
-description: Feature implementation specialist for Next.js stack. Implements tasks from decomposition.md following feature-delivery workflow. Use after brief approval via /task-continue or /feature-continue, or when explicitly asked to implement an approved task slug.
+description: Feature implementation specialist for Next.js stack. Implements tasks from decomposition.md following feature-delivery workflow. Use after brief approval via /task-continue, or when explicitly asked to implement an approved task slug.
 model: inherit
 ---
 
@@ -46,6 +46,13 @@ Do not perform formal code review — that is the code-reviewer subagent's job.
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+- When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.
+
+## Verification before completion
+
+<!-- shared-core: quality/verification-before-completion.md -->
+
+Before handoff, IDENTIFY→RUN→READ→VERIFY the scoped checks for this WP, THEN claim. Do not say the work is done without that evidence in the same turn. Full-project lint is `build-verifier`.
 
 ## Anti-hallucination (Next / React / RTK)
 

package/presets/claude/next/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/next/agents/task-analyst.md

@@ -1,6 +1,6 @@
 ---
 name: task-analyst
-description: Task analysis specialist. Clarifies requirements, validates acceptance criteria, and decomposes work into concrete tasks. Use for /feature-start, task intake, or when the user asks to analyze or decompose a feature before coding. Writes only team artifacts; never writes production code.
+description: Task analysis specialist. Clarifies requirements, validates acceptance criteria, and decomposes work into concrete tasks. Use for task intake, or when the user asks to analyze or decompose a feature before coding. Writes only team artifacts; never writes production code.
 model: fast
 ---
 
@@ -8,10 +8,20 @@ You are a senior business/technical analyst for a Next.js frontend team.
 
 Your job is to reach **Definition of Ready (DoR)** before any implementation starts. You may write only `.claude/team/**` artifacts. You do **not** write production code or modify application source files.
 
+## Classify first
+
+<!-- shared-core: agent-team/task-classification.md -->
+
+Before decomposing, name the class: **spike** / **bounded** / **architectural**. Maps to existing pipeline profiles — do not invent a second orchestrator.
+
+- **Spike** — research DoR; no implement tasks.
+- **Bounded** — few tasks, only layers actually touched; do not pad types/api/store/ui.
+- **Architectural** — full layer table; architect when boundaries are unclear.
+
 ## Clarification cycle (must)
 
 1. Rephrase the task in your own words (goal, user value, boundaries).
-2. Ask **1–3 questions per iteration** — never more than 3 at once.
+2. Ask questions — **prefer one** unblocking question; **never more than 3** per iteration.
 3. List explicit **assumptions** when information is missing.
 4. Do **not** decompose until acceptance criteria are **testable and unambiguous**.
 5. If critical unknowns remain, mark them in `open_questions` and ask the user before finalizing.

package/presets/claude/next/agents/task-router.md

@@ -29,6 +29,7 @@ You are a task router for a Next.js frontend agent team. You **do not** implemen
 | `unit-only` | «unit», «юнит» (unit), «mapper tests», «покрой маппер» (cover mapper), «почини unit» (fix unit) <!-- i18n-keep: E4 --> | unit-test-planner → unit-test-generator, or unit-test-healer |
 | `e2e-only` | «e2e», «playwright», «browser test», «сценарии e2e» (e2e scenarios), «почини e2e» (fix e2e) <!-- i18n-keep: E4 --> | playwright-test-planner → playwright-test-generator, or playwright-test-healer |
 | `docs-only` | «документация» (documentation), «README», «changelog», «ADR», «migration guide» <!-- i18n-keep: E4 --> | task-analyst → tech-writer |
+| `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 <!-- i18n-keep: E4 --> | task-analyst → solution-architect (skipIf no architecture delta) → openspec-author (scope: `openspec:<change-id>`) |
 | `refactor` | «рефакторинг» (refactor), «без изменения поведения» (no behavior change), «почисти» (clean up) <!-- i18n-keep: E4 --> | task-analyst → feature-developer → build-verifier → code-reviewer |
 | `spike` | «исследуй» (investigate), «оцени» (estimate), «можно ли» (is it possible), «spike», proof of concept <!-- i18n-keep: E4 --> | task-analyst → solution-architect |
 | `retro` | «ретро» (retro), «разбор» (postmortem), «postmortem» <!-- i18n-keep: E4 --> | (no pipeline — orchestrator runs `/technical-retro`) |
@@ -45,6 +46,20 @@ Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.j
 
 **Light signals:** one file, one layer, explicit AC in prompt, no architectural risk. **Never skip `build-verifier`** after developer when `app/**` changed. **Skip `code-reviewer`** in light only for non-prod preset/docs tasks — for `app/src` changes prefer standard.
 
+## Task class (spike / bounded / architectural)
+
+<!-- shared-core: agent-team/task-classification.md -->
+
+Name the class in `routingReasons`. Maps to profiles already in this file — do not add a parallel step table.
+
+| Class | Use existing |
+|-------|----------------|
+| Spike | intent `spike` |
+| Bounded | `profile: light` (or skip analyst when AC is complete) |
+| Architectural | `profile: full` + `solution-architect` when boundaries unclear |
+
+SoT: `agent-team/task-classification` (shared-core marker above; do not invent a second pipeline).
+
 **Light by intent:**
 
 | intent | light steps |
@@ -116,6 +131,7 @@ Claude Code mapping when orchestrator invokes Agent tool: `cheap` → `haiku` (o
 | `spec-gen` | `["after:task-analyst"]` |
 | `migration` | `["after:migration-specialist"]` |
 | `docs-only` | `["after:task-analyst"]` |
+| `openspec-change` | `["after:task-analyst"]` (human approves brief + AC; openspec-author emits drafts and validator receipts under the assigned change-id) |
 | `unit-only` | `["after:unit-test-planner"]` when new plan; `[]` for healer |
 | `e2e-only` | `["after:playwright-test-planner"]` when new plan; `[]` for healer |
 | `bugfix`, `review-only`, `ci-fix` | `[]` |
@@ -147,7 +163,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 above. 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/next/agents/tech-writer.md

@@ -42,6 +42,10 @@ Conventional commit / release note snippet.
 - Do not duplicate entire decomposition — summarize outcomes and how to use/extend.
 - May create or update files under `docs/**` when the task explicitly requests it; otherwise keep primary output in team artifacts.
 
+## 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/next/commands/README.md

@@ -6,8 +6,6 @@ Slash-command definitions and on-demand scenarios. Copied to `.claude/commands/`
 |------|---------|
 | `task.md` | Single entry: router → dynamic pipeline → first agent |
 | `task-continue.md` | Resume after human gate / pause via `pipeline.json` |
-| `feature-start.md` | Legacy analyst-only start without router |
-| `feature-continue.md` | Legacy continue; for `pipeline.json` delegates to `/task-continue` semantics |
 | `technical-retro.md` | Technical retro facilitation, including the “Agent work” block |
 
 See also the preset root `README.md` — Claude Code uses `skills/`, `agents/`, `hooks/`, `team/` in addition to `rules/` and `commands/`.

package/presets/claude/next/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/next/commands/task.md

@@ -36,7 +36,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 hook returns `followup_message`).
-7. **Human gate** — if there is a gate in `humanGates` after the current step (`after:<agent>`), **stop** after the agent finishes and ask for `/task-continue <slug>` (or `/feature-continue <slug>`).
+7. **Human gate** — if there is a gate in `humanGates` after the current step (`after:<agent>`), **stop** after the agent finishes and ask for `/task-continue <slug>`.
 
 ## Do not
 
@@ -49,9 +49,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
 

package/presets/claude/next/hooks/chain-team-phases.sh

@@ -138,6 +138,14 @@ const DEFAULT_ARTIFACT_OUTPUT_IDS = {
   'mockup-reviewer': 'mockup-review',
   'api-contract-reviewer': 'api-contract-review',
   'tech-writer': 'documentation',
+  'openspec-author': 'openspec-change',
+  'qa-tester': 'qa',
+  'unit-test-planner': 'unit-test-plan',
+  'unit-test-generator': 'unit-test-spec',
+  'unit-test-healer': 'unit-test-heal',
+  'playwright-test-planner': 'e2e-plan',
+  'playwright-test-generator': 'e2e-spec',
+  'playwright-test-healer': 'e2e-heal',
 };
 function artifactOutputIdFor(step, agent) {
   if (step && typeof step.artifactOutputId === 'string') return step.artifactOutputId;
@@ -242,7 +250,17 @@ function recordSkippedStep(step, stepIndex) {
 function writeStatus(next) {
   status = { ...status, ...next, slug, updatedAt: now };
   const temporary = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(temporary, JSON.stringify(status, null, 2) + '\n');
+  // Open + write + fsync + rename so the durable file lands on disk before
+  // the orchestrator reads it. Closes the race window where a subagent that
+  // completed milliseconds before writeStatus() could otherwise invoke the
+  // next step on a stale status (in particular the human-gate write).
+  const fd = fs.openSync(temporary, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(status, null, 2) + '\n');
+    try { fs.fsyncSync(fd); } catch {}
+  } finally {
+    fs.closeSync(fd);
+  }
   fs.renameSync(temporary, statusPath);
 }
 
@@ -339,6 +357,12 @@ const AGENT_HANDOFF = {
     `Use playwright MCP when available. Follow testing/playwright-agents.md and debug-investigation. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'tech-writer': (s) =>
     `Invoke tech-writer for slug "${s}". Write documentation.md from task artifacts. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
+  'openspec-author': (s, scope) =>
+    `Invoke openspec-author for slug "${s}"${scope ? ` (scope: ${scope})` : ''}. ` +
+    `Read openspec/config.yaml schema + rules; if openspec/** is absent, emit blocked ("openspec/** not initialized"). ` +
+    `Author openspec/changes/<change-id>/{proposal.md, design.md, tasks.md, .openspec.yaml} and the capability spec delta per phase (explore|propose|apply|archive). ` +
+    `Run \`openspec validate <change-id> --type change --strict\` and \`openspec validate --specs --strict\` (Phase 3); surface FAIL output verbatim. ` +
+    `Upsert the owned terminal receipt (artifactOutputId \`openspec-change\`) in artifact-manifest.json with validator exit code + evidence paths; do not mutate status.json lifecycle fields. `,
 };
 
 const REVIEW_AGENTS = new Set([
@@ -512,9 +536,37 @@ if (!fs.existsSync(pipelinePath)) {
 }
 
 let pipeline;
+let pipelineParseError = null;
 try {
   pipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8'));
-} catch {
+} catch (error) {
+  pipelineParseError = error;
+}
+// Modern pipelines carry an `intent` field. If pipeline.json is present but
+// unparseable, surface the error so the orchestrator can stop and report
+// instead of falling back to legacyFlow() — which silently drops modern
+// roles like `openspec-author`, `qa-tester`, and the test-planner trio.
+if (pipelineParseError) {
+  if (fs.existsSync(pipelinePath)) {
+    const raw = fs.readFileSync(pipelinePath, 'utf8');
+    const hasModernIntent = /"intent"\s*:/.test(raw);
+    appendMetric({
+      eventId: `${status.metricsRunId || slug}:pipeline_parse_error:${Date.now()}`,
+      type: 'pipeline_parse_error',
+      at: now,
+      source: 'hook',
+      attributionConfidence: 'high',
+      error: String(pipelineParseError.message || pipelineParseError),
+      hasModernIntent,
+    });
+    if (hasModernIntent) {
+      writeStatus({ state: 'blocked', phase: 'blocked', currentAgent: 'task-router' });
+      process.stdout.write(JSON.stringify({
+        followup_message: `pipeline.json is malformed for slug "${slug}" — JSON parse error: ${pipelineParseError.message}. Re-run the task-router to regenerate pipeline.json, then resume via /task-continue ${slug}.`,
+      }));
+      process.exit(0);
+    }
+  }
   legacyFlow();
 }
 

package/presets/claude/next/rules/README.md

@@ -38,6 +38,7 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads:
 | `next-app-core.mdc` | `stack/next-app-core.md` |
 | `package-manager.mdc` | `tooling-and-review/package-manager.md` |
 | `code-quality-and-refactoring.mdc` | `tooling-and-review/code-quality.md` |
+| `ai-local-overlay.mdc` | `tooling-and-review/ai-local-overlay.md` |
 | `anti-sycophancy-discipline.mdc` | `tooling-and-review/anti-sycophancy-discipline.md` |
 | `react-next-anti-hallucination.mdc` | `anti-hallucination/react-next-anti-hallucination.md` |
 | `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |

package/presets/claude/next/rules/testing/README.md

@@ -9,3 +9,9 @@ Unit, e2e, Playwright agents.
 | `tests-e2e-structure.md` | `*.cases.md`, page objects, data-testid | `paths: app/__tests__/e2e/**` |
 
 See also `.claude/agents/playwright-test-*.md` after `ai-rules init`.
+
+## Shared core
+
+| Shared core | Cursor adapter | Claude twins |
+|-------------|----------------|--------------|
+| `testing/testing-principles.md` | `tests-unit.mdc`, `tests-e2e-structure.mdc` | `tests-unit.md`, `tests-e2e-structure.md` |