@bonesofspring/ai-rules 0.2.18 → 0.2.20

package/presets/claude/mcp-ts/team/fixtures/feature-full.json

@@ -1,6 +1,7 @@
 {
   "slug": "example-add-tool-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "summary": "Add MCP tool with schema, handler, registration, and tests",
   "steps": [
@@ -10,7 +11,7 @@
     },
     {
       "agent": "feature-developer",
-      "label": "contract→schema→handler→register→test→package"
+      "label": "contract\u2192schema\u2192handler\u2192register\u2192test\u2192package"
     },
     {
       "agent": "build-verifier",
@@ -22,7 +23,9 @@
       "model": "strong"
     }
   ],
-  "humanGates": ["after:task-analyst"],
+  "humanGates": [
+    "after:task-analyst"
+  ],
   "autoChain": true,
   "skipped": [
     {

package/presets/claude/mcp-ts/team/fixtures/memlog.example.md

@@ -0,0 +1,9 @@
+# Memlog example
+
+Append-only. Agents write; `/task-continue` may read. The hook does not parse this file.
+
+## 2026-08-13
+
+- `decision`: specMode=generate; research-before-spec requested
+- `claim`: empty-cart copy lives in the empty-state handler (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/claude/next/MCP.md

@@ -14,3 +14,25 @@ Copied to the **project root** as `.mcp.json` on `ai-rules init claude --preset
 Do not commit secrets. Optional: `CONTEXT7_API_KEY`. Figma — OAuth (do not write the token to a file). After clone/init Claude Code will ask to approve project MCP (`/mcp`).
 
 For the full Playwright Test Agents loop (`planner_*` / `generator_*` / `test_*`) additionally: `npx playwright init-agents --loop=claude` in an app with `@playwright/test`.
+
+
+## Agent usage
+
+Load requestable rule `mcp-usage`. The **session MCP catalog** is source of truth (this file and `mcp.json` are hints). Discover tool schemas before calling; never invent them.
+
+**Context7 (shipped):** query docs when a third-party API is not confirmed by lockfile + sibling files. Use the installed major. Cap ≤3 doc queries per question. If Context7 is down, mark `// VERIFY` and continue — do not block.
+
+## Local overlay (not shipped)
+
+`init` **merges** `mcpServers`: preset keys are updated; extra local servers are kept. User-level MCP is never touched. Prefer user-level MCP if you do not want overlay servers in the project file.
+
+Use an overlay only when it is **ready** (`serverStatus` not `error` / `needsAuth` / `loading`) **and** the task fits. Absence is not a blocker unless the user required that MCP as source of truth.
+
+| Kind | Typical aliases | When |
+|------|-----------------|------|
+| Observability | `sentry`, `datadog`, `plugin-datadog-*` | production error, event/trace id, APM |
+| Tickets | `linear`, `jira`, `notion`, `plugin-notion-*` | ticket/page URL; read-only; task-folder artifacts remain SoT |
+| GitHub MCP | `github` | optional; native `gh` remains SoT for PRs and checks |
+| Storybook | `storybook`, `user-storybook`, `plugin-storybook`, `storybook-mcp-addon` | component docs/stories/controls; needs Storybook running; not shipped |
+
+**Browser split (this preset):** Playwright MCP → e2e agents and selectors. Chrome DevTools MCP → `debugger` / `performance-auditor` against a running app. Not interchangeable.

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

@@ -47,6 +47,14 @@ PASS | PASS_WITH_NOTES | FAIL
 |-----------|--------|-------|
 ```
 
+
+## 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.
+
+Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools MCP for live-app debug and performance (app must be running). Storybook MCP if present and the work is component docs/stories.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation or UI diff scope, and prior review artifacts when present.

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

@@ -25,6 +25,12 @@ 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.

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

@@ -46,6 +46,14 @@ Commands run and results.
 - If the fix requires feature work beyond CI scope → document in `ci-report.md` and emit owned receipt outcome `completed`; orchestrator/hook may invoke `feature-developer`.
 - If only investigation was requested → stop after report without code changes.
 
+
+## 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.
+
+
 ## 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 when present, failing check context, and prior validation/debug artifacts.
@@ -58,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,22 @@ 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
+
+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 Chrome DevTools MCP is ready and the app is running, use it for console, network, and runtime evidence.
+
+Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools MCP for live-app debug and performance (app must be running). Storybook MCP if present and the work is component docs/stories.
+
+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.
+
+
 ## 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 when present, failing evidence, and related prior artifacts.
@@ -63,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

@@ -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)
 
@@ -64,6 +71,31 @@ When work touches a page/feature/route/alias: if `docs/specs/INDEX.md` exists (o
 Mechanical INDEX/frontmatter fixes only when implementation renames routes/ids. Substantive behavior edits → hand back to task-analyst (or tech-writer where present). If INDEX is absent and generation was not approved, treat specs as optional (greenfield).
 
 
+**specMode `none`:** do not require INDEX; implement from brief/AC only.
+
+**applyReadiness:** YAML frontmatter on `implementation.md`:
+
+```yaml
+applyReadiness:
+  state: ready   # blocked | ready | all_done
+  contextFiles: []
+```
+
+`blocked` if human gate pending, required spec missing, required UX `INCOMPLETE`, or incomplete WP deps. `ready` when the current WP may be implemented. `all_done` on the final receipt when mechanical spec sync is done.
+
+**Code Map + Suggested Review Order:** when this WP spans **>1 layer or module**, add to `implementation.md` a Code Map (3–8 annotated paths) and Suggested Review Order lines `concern | path:line | ≤15 words`. Omit for single-file / single-layer WPs.
+
+**Memlog:** append implementation decisions to `.claude/team/tasks/<slug>/.memlog.md` (append-only).
+
+
+
+## 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.
+
+Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools MCP for live-app debug and performance (app must be running). Storybook MCP if present and the work is component docs/stories.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.

package/presets/claude/next/agents/migration-specialist.md

@@ -53,6 +53,12 @@ Temporary adapters, feature flags, dual-write if needed.
 - Map every phase to concrete decomposition tasks for `feature-developer`.
 - Do not implement code — planning only.
 
+
+## 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.
+
+
 ## 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 stack/version context from the repo.

package/presets/claude/next/agents/performance-auditor.md

@@ -50,6 +50,14 @@ Bundle chunks, Lighthouse hints, or measured timings.
 Ordered list for feature-developer if fixes are requested.
 ```
 
+
+## 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 Chrome DevTools MCP is ready and the app is running, use it for console/network/traces. Do not treat that as an e2e substitute.
+
+
 ## 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 when present and the scoped git diff / routes under audit.

package/presets/claude/next/agents/playwright-test-generator.md

@@ -72,4 +72,14 @@ When you generate tests:
      });
    });
    ```
-   </example-generation>
+   </example-generation>
+
+## 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.
+
+Use Playwright MCP when available for selector checks and failure reproduction. Chrome DevTools is for `debugger` / `performance-auditor`, not this e2e loop. Storybook MCP if present may inform component docs — do not replace `*.cases.md`.
+
+## Completion
+
+Run the affected spec if feasible. Report files changed, tests run, failures, and gaps. For agent team tasks, upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.

package/presets/claude/next/agents/playwright-test-healer.md

@@ -58,4 +58,11 @@ Key principles:
   so that it is skipped during the execution. Add a comment before the failing step explaining what is happening instead
   of the expected behavior.
 - Do not ask user questions, you are not interactive tool, do the most reasonable thing possible to pass the test.
-- Never wait for networkidle or use other discouraged or deprecated apis
+- Never wait for networkidle or use other discouraged or deprecated apis
+
+## 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.
+
+Use Playwright MCP when available for selector checks and failure reproduction. Chrome DevTools is for `debugger` / `performance-auditor`, not this e2e loop. Storybook MCP if present may inform component docs — do not replace `*.cases.md`.
+

package/presets/claude/next/agents/solution-architect.md

@@ -52,6 +52,12 @@ Write `.claude/team/tasks/<slug>/architecture.md`:
 - Flag when decomposition should change — list suggested updates for analyst/developer.
 - Do **not** write production code or tests.
 
+
+## 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.
+
+
 ## 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 applicable prior analysis artifacts.

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

@@ -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.
@@ -107,6 +117,15 @@ Do not invoke the developer or any implementation subagent.
 
 **Author mode (Generate / Bootstrap):** When the user runs `/spec-start`, router intent is `spec-gen` / bootstrap, or brief/AC requests generation: load **`product-specs`** + **`product-specs-authoring`** and skill **`spec-authoring`**. You are the **primary author** (INDEX bootstrap included). Follow frontmatter v1 + required headings; update INDEX in the **same change set**; default `status: draft`. Block handoff via `open_questions` until the authoring self-check passes.
 
+
+**Spec mode:** Write `## Spec mode` in `brief.md` with exactly one of `consume` | `generate` | `none`. Infer if unset: spike/research/preset-only → `none`; `/spec-start` or router `spec-gen` → `generate`; otherwise `consume`. Router may echo `specMode` on `pipeline.json`.
+
+**`none`:** skip INDEX row requirement and author mode; do not invent a dummy INDEX.
+
+**Research-before-spec (opt-in):** load skill **`spec-discovery`** only when the user/AC asks research before authoring (not default consume `/task`). Run a **subset** of methods; **`claim-ledger` is mandatory** whenever the skill loads. Append chronological notes to `.claude/team/tasks/<slug>/.memlog.md` (append-only; do not mutate `status.json`).
+
+**applyReadiness (author blocked):** if specs are drafted but the human gate has not passed, or a required named spec is missing, emit `applyReadiness: { "state": "blocked", "contextFiles": ["…"] }` on the analysis receipt. Do not invoke feature-developer.
+
 ### Brief sections (when author mode or INDEX exists)
 
 Add to `brief.md`:
@@ -137,6 +156,14 @@ Write `.claude/team/tasks/<slug>/ux-design.md` with the headings in rule `ux-des
 
 When produced, append `ux-design.md` to this step's **`analysis`** `authoritativePaths` / `evidencePaths`. No new manifest producer row.
 
+
+## 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 the prompt/brief has a tracker URL (Linear/Jira/Notion/…) and that MCP is ready, pull AC **read-only**. Task-folder artifacts remain SoT.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.

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

@@ -45,6 +45,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 |
@@ -113,6 +127,7 @@ Claude Code mapping when orchestrator invokes Agent tool: `cheap` → `haiku` (o
 | Intent | Default humanGates |
 |--------|-------------------|
 | `feature`, `refactor`, `test-only`, `a11y` | `["after:task-analyst"]` |
+| `spec-gen` | `["after:task-analyst"]` |
 | `migration` | `["after:migration-specialist"]` |
 | `docs-only` | `["after:task-analyst"]` |
 | `unit-only` | `["after:unit-test-planner"]` when new plan; `[]` for healer |
@@ -148,6 +163,11 @@ Detect and set routing reasons when the user asks to **generate / bootstrap prod
 
 Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
 
+
+**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.
+
+Do **not** add a pipeline step for `spec-discovery`. Instruct analyst to load that skill only when the user/AC asks research-before-spec.
+
 ## Runtime initialization
 
 Return the routing receipt to the orchestrator. The orchestration runtime/hook exclusively initializes and updates `status.json`, `metrics.json`, attempt identities, and gate lifecycle; the router does not write those shared runtime files.

package/presets/claude/next/commands/feature-continue.md

@@ -3,50 +3,21 @@ name: feature-continue
 description: Legacy alias for /task-continue that resumes a feature pipeline after human approval or pause.
 ---
 
-# Feature continue — resume after brief approval
+# Feature continue — legacy alias
 
-Legacy command to continue after a human gate. For new pipelines with `pipeline.json`, use the same rules as `/task-continue`.
+> **Prefer:** `/task-continue <slug>` — same behavior, respects `pipeline.json`.
 
-## Arguments
+Continue after a human gate. Full logic — in **`task-continue.md`**.
 
-`<slug>` — task id under `.claude/team/tasks/<slug>/`.
+## Short form
 
-## Preconditions
+1. Read `pipeline.json` (if present) and `status.json`.
+2. Clear `awaitingHumanGate`; determine the next step from `pipelineIndex`.
+3. Invoke the subagent for `currentAgent`.
+4. The hook continues the chain when `autoChain: true`.
 
-1. Read `.claude/team/tasks/<slug>/brief.md` and `decomposition.md`.
-2. If `pipeline.json` exists, delegate behavior to `/task-continue <slug>`.
-3. If there is no `pipeline.json`, read `status.json`. Continue only if:
-   - `phase` is `analysis` and `state` is `awaiting_approval` (user explicitly approved via this command), **or**
-   - `phase` is `development`/`review`/`testing` and work should resume.
+See `task-continue.md` for details and the handoff table.
 
-## Legacy algorithm without `pipeline.json`
+## Product specs (docs/specs)
 
-1. Update `status.json`:
-   ```json
-   {
-     "slug": "<slug>",
-     "phase": "development",
-     "state": "approved",
-     "updatedAt": "<ISO8601>"
-   }
-   ```
-   Then immediately set `"state": "in_progress"` before calling the developer.
-
-2. Write `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
-
-3. Call subagent **feature-developer** with context:
-   - paths to `brief.md`, `decomposition.md`, `status.json`;
-   - instruction to follow `rules/architecture/feature-delivery-workflow.md`.
-   - if `docs/specs/INDEX.md` exists: load **`product-specs`** and honor **Related specs** from `brief.md` (soft-fail on miss; never invent behavior).
-
-4. After the developer finishes, continue review → QA per `rules/tooling-and-review/agent-team-orchestrator.md`.
-
-## If review returned changes_requested
-
-- Set `phase` back to `development`, `state` to `in_progress`.
-- Call **feature-developer** again with the reviewer’s change list.
-
-## Do not
-
-- Skip the human gate without an explicit `/feature-continue`.
-- Combine developer and reviewer roles in one subagent call.
+When the next agent is **feature-developer** (or other implementer): if `docs/specs/INDEX.md` exists, instruct them to load **`product-specs`** and honor **Related specs** from `brief.md` (behavior SoT). Soft-fail on miss; never invent product behavior. No-op if INDEX is absent.

package/presets/claude/next/commands/spec-start.md

@@ -14,7 +14,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 3. Ensure `.claude/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
 4. Write `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
 5. Write minimal `pipeline.json`: task-analyst → (optional stop) → feature-developer only if user asked implement-after. **No separate spec-author agent.**
-6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate.
+6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate. Optional: if arguments/AC ask research-before-spec, also load skill **`spec-discovery`** (not default).
 7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.
 
 ## Human gate

package/presets/claude/next/mcp.json

@@ -2,15 +2,15 @@
   "mcpServers": {
     "context7": {
       "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
+      "args": ["-y", "@upstash/context7-mcp@4.0.2"]
     },
     "playwright-test": {
       "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest"]
+      "args": ["-y", "@playwright/mcp@0.0.79"]
     },
     "chrome-devtools": {
       "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"]
+      "args": ["-y", "chrome-devtools-mcp@1.7.0"]
     },
     "figma": {
       "type": "http",

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

@@ -9,14 +9,14 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 | **SoT** | `presets/cursor/next/rules/*.mdc` — edit here first |
 | **Derive** | Claude topic `.md` = body + `paths:` (from Cursor `globs:` / requestable triggers) |
 | **Drop** | Cursor-only keys (`alwaysApply`); keep short `description` |
-| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — next, ios-swift, and go; see `preset-twin-sync` / build-verifier) |
+| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — all 10 installable stacks; see `preset-twin-sync` / build-verifier) |
 | **Shared core** | `presets/_shared/core/**` — see `<!-- shared-core: … -->` markers; taxonomy in `_shared/README.md` |
 
 ## Loading strategy
 
 - **Session start (no `paths:`):** exactly **3** — `next-app-core`, `package-manager`, `code-quality`
-- **On-demand (`paths:` or via commands):** `post-change-lint` (**must after code edits**), `agent-team-intake`, `agent-team-orchestrator`, `code-review-mr`, `security-next`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, next-app-router, react-a11y-coding, `technical-retro`, `mockup-review`, `ux-design`, **preset-*** meta (paths on `packages/ai-rules/presets/**`)
-- **Skills:** long workflows (`feature-delivery`, `code-review`, …)
+- **On-demand (`paths:` or via commands):** `post-change-lint` (**must after code edits**), `agent-team-intake`, `agent-team-orchestrator`, `code-review-mr`, `security-next`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, next-app-router, react-a11y-coding, `technical-retro`, `mockup-review`, `ux-design`, **preset-*** meta (paths on `packages/ai-rules/presets/**`)
+- **Skills:** long workflows (`feature-delivery`, `spec-authoring`, `spec-discovery`, `code-review`, …)
 
 ### UI edit bundle (consolidated paths)
 
@@ -41,6 +41,7 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads:
 | `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` |
+| `mcp-usage.mdc` | `tooling-and-review/mcp-usage.md` |
 | `next-app-router.mdc` | `stack/next-app-router.md` |
 | `arrow-functions.mdc` | `stack/arrow-functions.md` |
 | `types-jsdoc.mdc` | `stack/types-jsdoc.md` |
@@ -86,6 +87,7 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads:
 | `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` / `code-quality.md` | + Stack notes (ESLint/CSS) |
 | `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` / `anti-sycophancy-discipline.md` | requestable full VERIFY/discipline set |
 | `quality/design-guidance.md` | `design-guidance.mdc` / `design-guidance.md` | requestable smells/GoF |
+| `quality/mcp-usage.md` | `mcp-usage.mdc` / `mcp-usage.md` | requestable Context7 + overlay MCP |
 | `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | Roles in Stack notes |
 | `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | thin alias |
 | `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | Next layer checklist in Stack notes |

package/presets/claude/next/rules/architecture/feature-delivery-workflow.md

@@ -25,7 +25,7 @@ Typical feature with backend data and shared state. Layer details — `architect
 6. **UI** — `@/types`, no DTOs (`ui-and-accessibility/react-ui.md`, `architecture/architecture-boundaries-ui.md`, `ui-and-accessibility/no-props-spread.md`).
 7. **Mocks** — `app/src/mocks/**`; register in `handlers.ts` (see below).
 8. **Tests** — unit (`testing/tests-unit.md`); e2e (`testing/tests-e2e-structure.md`, `testing/playwright-agents.md`).
-9. **Completion** — **`tooling-and-review/post-change-lint.md`**.
+9. **Completion** — **`tooling-and-review/post-change-lint.md`**. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
 
 ## Data flow
 
@@ -71,6 +71,7 @@ flowchart LR
 - `{...props}` — `ui-and-accessibility/no-props-spread.md`.
 - **Ubiquitous language:** Domain/type names reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need.
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
 
 ## Matrix: zone → rules
 

package/presets/claude/next/rules/architecture/product-specs-authoring.md

@@ -9,6 +9,8 @@ paths:
 
 Load when **Generate** or **Bootstrap** is requested (`/spec-start`, router `spec-gen`, brief AC, or analyst author mode). Discovery-only work stays on **`product-specs`**.
 
+**Optional prefix:** when the user or AC asks **research-before-spec**, load skill **`spec-discovery`** first (subset of methods; **claim-ledger** mandatory). Not the default `/task` consume path and not a new pipeline step.
+
 ## Modes
 
 1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
@@ -82,7 +84,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 ## Templates & assets
 
-**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; optional `schemas/frontmatter-v1.schema.json`).
+**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; `schemas/frontmatter-v1.schema.json` is a documentation artifact — the checker does not evaluate it).
 
 **CLI `init`:** when consumer `docs/specs/` is **absent**, copy INDEX stub + `_templates/*` (idempotent; **never overwrite** existing INDEX). When the tree already exists, skip seed entirely.
 
@@ -92,7 +94,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 | Role | Responsibility |
 |------|----------------|
-| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring` |
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring`; optional skill `spec-discovery` when research-before-spec |
 | **tech-writer** | Post-delivery sync where present; never invent product behavior without AC/code source |
 | **feature-developer** | Consumes approved specs as SoT; mechanical INDEX/frontmatter fixes only on renames |
 | **mcp-ts** | No tech-writer — author + post-sync via **task-analyst** only |
@@ -111,8 +113,8 @@ Block handoff via `open_questions` until fixed:
 
 - `product-specs` — discovery / consume
 - Skill `spec-authoring` — procedural checklist
-- Optional consumer script `scripts/check-product-specs.sh` (WARN default; `--strict` FAIL)
-
+- Skill `spec-discovery` — opt-in research-before-spec (not default)
+- Optional consumer script `scripts/check-product-specs.sh` (ships in the npm package; WARN default; `--strict` FAIL). Bash checks INDEX links, required frontmatter keys, and body headings — it does **not** evaluate `frontmatter-v1.schema.json`
 
 ## Stack notes
 

package/presets/claude/next/rules/architecture/product-specs.md

@@ -11,6 +11,8 @@ Product page/feature **behavior** specs live under the consumer repo `docs/specs
 
 **Authoring** (Generate / Bootstrap modes, INDEX/frontmatter v1, body checklist, greenfield, conflict precedence) → load **`product-specs-authoring`** when generation is requested (`/spec-start`, brief AC, or router `spec-gen`).
 
+**Pipeline `specMode`:** `consume` (this stem) · `generate` (authoring stem) · `none` (spike/research — skip INDEX row requirement; do not invent a dummy INDEX). Primary field: `brief.md` `## Spec mode`; optional `pipeline.json` `specMode`.
+
 ## Modes (summary)
 
 | Mode | When | Behavior |
@@ -18,19 +20,21 @@ Product page/feature **behavior** specs live under the consumer repo `docs/specs
 | **Consume** (default) | INDEX exists or globs hit `docs/specs/**` without generate intent | Discover via INDEX; soft-fail on miss; **never invent** INDEX/specs |
 | **Generate** | Explicit generate intent / AC / `/spec-start` with existing tree | Create/update page/feature specs + INDEX from stated sources |
 | **Bootstrap** | Explicit bootstrap / `/spec-start` when tree absent | Create INDEX + templates + first domain spec |
+| **None** (`specMode: none`) | Spike / research / preset-only | Skip INDEX requirement and author mode; no dummy INDEX row |
 
 Greenfield: agents may create INDEX/specs **only** on explicit intent, AC, or `/spec-start`. Missing INDEX alone does **not** authorize inventing the tree.
 
 ## Presence policy
 
+- If `specMode` is **`none`** → do **not** require an INDEX row; continue from brief/AC. Do not invent INDEX.
 - If `docs/specs/INDEX.md` is **missing** → the tree is **optional** (greenfield OK for *consume*). Continue with code/brief discovery; do not invent an INDEX solely because this stem loaded.
-- If INDEX **exists** → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+- If INDEX **exists** and `specMode` is not `none` → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
 
 ## Discovery algorithm
 
-1. Always start at `docs/specs/INDEX.md` when present.
+1. Always start at `docs/specs/INDEX.md` when present (skip when `specMode: none`).
 2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
-3. Read the linked page spec (and optional domain `feature.md` when the INDEX or page Related links it).
+3. Read the **linked page** spec and, when INDEX or page Related links it, the optional domain `feature.md`. Do **not** dump the whole `docs/specs/**` tree into the prompt — locator = those linked files.
 
 ## Miss policy (INDEX present, row or file missing)
 
@@ -52,10 +56,10 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 ## Related
 
 - `product-specs-authoring` — generation modes, contracts, self-check.
+- Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
 - `reference-features` — code structure mirror (how to layout files), not product behavior.
 - Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.
 
-
 ## Stack notes
 
 - `routes`: app URL paths. `ui` / `store`: presentation + RTK/store paths (e.g. `app/src/ui/pages/...`). `e2e`: Playwright paths under `app/__tests__/e2e/**` (or repo equivalent).

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

@@ -75,4 +75,9 @@ it('returns empty list when guest', () => {})
 
 ## Correct
 
+```ts
+it('Возвращает пустой список. Пользователь не авторизован', () => {})
+```
+<!-- i18n-keep: E5 -->
+
 - `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->