@bonesofspring/ai-rules 0.2.18 → 0.2.19

package/presets/claude/php-laravel/team/fixtures/feature-full.json

@@ -2,14 +2,43 @@
   "profile": "full",
   "summary": "Laravel full feature delivery",
   "steps": [
-    { "agent": "task-analyst", "label": "Decompose" },
-    { "agent": "solution-architect", "label": "Design", "model": "strong" },
-    { "agent": "feature-developer", "label": "Implement" },
-    { "agent": "unit-test-planner", "label": "Plan unit tests" },
-    { "agent": "unit-test-generator", "label": "Generate unit tests" },
-    { "agent": "integration-test-planner", "label": "Plan Feature/integration tests" },
-    { "agent": "integration-test-generator", "label": "Generate Feature tests" },
-    { "agent": "build-verifier", "label": "php artisan test / composer test / static analysis", "model": "cheap" },
-    { "agent": "code-reviewer", "label": "Review" }
+    {
+      "agent": "task-analyst",
+      "label": "Decompose"
+    },
+    {
+      "agent": "solution-architect",
+      "label": "Design",
+      "model": "strong"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Implement"
+    },
+    {
+      "agent": "unit-test-planner",
+      "label": "Plan unit tests"
+    },
+    {
+      "agent": "unit-test-generator",
+      "label": "Generate unit tests"
+    },
+    {
+      "agent": "integration-test-planner",
+      "label": "Plan Feature/integration tests"
+    },
+    {
+      "agent": "integration-test-generator",
+      "label": "Generate Feature tests"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "php artisan test / composer test / static analysis",
+      "model": "cheap"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Review"
+    }
   ]
 }

package/presets/claude/php-laravel/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/svelte/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 into the 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 the 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/svelte/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/svelte/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.

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

@@ -45,6 +45,18 @@ 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`.
 
+
+## 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.

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

@@ -64,6 +64,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/svelte/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/svelte/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/svelte/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/svelte/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/svelte/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/svelte/agents/task-analyst.md

@@ -107,6 +107,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 +146,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/svelte/agents/task-router.md

@@ -114,6 +114,7 @@ Cursor mapping when orchestrator invokes Task: `cheap` → pass `model: "fast"`
 | 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 |
@@ -149,6 +150,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/svelte/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/svelte/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/svelte/rules/README.md

@@ -28,6 +28,7 @@ In Claude Code all `.md` under `rules/` are **discovered recursively**. Bodies a
 | `anti-sycophancy-discipline.mdc` | `tooling-and-review/anti-sycophancy-discipline.md` |
 | `svelte-sveltekit-anti-hallucination.mdc` | `anti-hallucination/svelte-sveltekit-anti-hallucination.md` |
 | `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |
+| `mcp-usage.mdc` | `tooling-and-review/mcp-usage.md` |
 | `sveltekit-routing.mdc` | `stack/sveltekit-routing.md` |
 | `svelte-script-conventions.mdc` | `stack/svelte-script-conventions.md` |
 | `types-jsdoc.mdc` | `stack/types-jsdoc.md` |
@@ -73,6 +74,7 @@ In Claude Code all `.md` under `rules/` are **discovered recursively**. Bodies a
 | `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` / `code-quality.md` | + Stack notes (ESLint/Svelte/CSS) |
 | `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` | requestable |
 | `quality/design-guidance.md` | `design-guidance.mdc` | requestable |
+| `quality/mcp-usage.md` | `mcp-usage.mdc` | 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` | SvelteKit layer checklist |

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

@@ -31,7 +31,7 @@ Canonical paths: `src/routes/**`, `src/lib/{components,stores,api,clients,types}
 6. **UI** — `src/routes/**`, `src/lib/components/**`; data via store / facades / `load`.
 7. **Unit** — colocated `*.spec.ts` (Vitest + Testing Library Svelte).
 8. **E2E** — `tests/e2e/<Area>/<plan>.cases.md` + `*.spec.ts`.
-9. **Gate** — `post-change-lint`: `lint:js`, `lint:css`, `check`.
+9. **Gate** — `post-change-lint`: `lint:js`, `lint:css`, `check`. 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.
 
 ## Partial scenarios
 
@@ -50,6 +50,7 @@ Canonical paths: `src/routes/**`, `src/lib/{components,stores,api,clients,types}
 - `{...props}` / `$$restProps` without discipline — `no-rest-props-spread`.
 - RTK / Pinia / Vue / Nuxt APIs as defaults.
 - Load `design-guidance` when assessing structure / smells.
+- 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`.
 
 ## Zone → rules matrix
 

package/presets/claude/svelte/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/svelte/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`: SvelteKit URL paths. `ui` / `store`: routes/components + store modules. `e2e`: Playwright paths under repo `tests/e2e/**` (or equivalent).

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

@@ -20,6 +20,7 @@ Work request without `/task` — see **`agent-team-intake.md`** (when to suggest
 | `/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 |
 
 ## Stack notes
@@ -29,7 +30,7 @@ Work request without `/task` — see **`agent-team-intake.md`** (when to suggest
 | Agent | App / prod writes | Typical intent |
 |-------|-------------------|----------------|
 | `task-router` | no (team only) | Every `/task` — writes `pipeline.json` |
-| `task-analyst` | no (team only) | feature, refactor, test-only, a11y, docs-only, migration, ux-design |
+| `task-analyst` | no (team only) | feature, refactor, test-only, a11y, docs-only, migration, ux-design, spec-gen |
 | `solution-architect` | no (team only) | spike, complex cross-layer feature |
 | `migration-specialist` | no (team only) | migration — phased upgrade plan |
 | `api-contract-reviewer` | no (team only) | new/changed backend API contracts |

package/presets/claude/svelte/rules/tooling-and-review/anti-sycophancy-discipline.md

@@ -10,7 +10,7 @@ paths:
 
 Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
 
-1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If you cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If that is not enough and Context7 MCP is available, load **`mcp-usage`** and query docs for the **installed major**. If you still cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
 2. **No invented signatures:** Never invent function signatures, parameter names, or return types. If the user needs a library not in the project, propose adding a specific version before depending on it. Silent stubs are worse than refusal.
 3. **Enumerate edge cases before validating:** When asked "is this correct?" or "does this work?", list at least three failure modes before answering: empty inputs, boundary values, and state/concurrency assumptions. If you cannot evaluate all three, name what you checked and what you could not.
 4. **Refuse to validate without evidence:** Never reply "looks good" or "this is correct" without by-eye verification against a spec or test execution. If no spec exists, ask for one or refuse to validate.

package/presets/claude/svelte/rules/tooling-and-review/code-quality.md

@@ -32,7 +32,7 @@ description: Maintain and improve code quality and architecture
 
 Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
 
-- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- Unverifiable third-party API → if Context7 is up, load **`mcp-usage`** and query the installed major; else mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
 - Before "is this correct?" — ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
 - Refactor without tests → propose characterization test; if declined, label `UNTESTED`.
 - Comments = WHY only when non-obvious; ban self-referential "added for issue Y".

package/presets/claude/svelte/rules/tooling-and-review/mcp-usage.md

@@ -0,0 +1,101 @@
+---
+description: When to call shipped Context7 and local overlay MCP — detect presence, use if the task fits, degrade.
+paths:
+  - **/*.{ts,tsx,svelte}
+---
+
+<!-- shared-core: quality/mcp-usage.md -->
+
+# MCP usage
+
+Requestable protocol for **shipped** and **local-overlay** MCP servers. Agents load this stem via one-liner wiring — do not copy tool schemas into prompts; discover them at runtime.
+
+Does not replace Figma mockup-review (that checklist stays on `mockup-review`). Does not add pipeline agents or required handoff stems.
+
+## Presence (runtime catalog is SoT)
+
+1. Inspect the **session MCP catalog** (server names + `serverStatus`). Project `mcp.json` / `.mcp.json` is a hint, not proof the server is up (user-level and plugin servers never appear there).
+2. Treat `error`, `needsAuth`, and `loading` as **unavailable**. Authenticate only when this task needs that server.
+3. **Discover tool schemas before calling.** Never invent tool names or arguments from memory.
+4. Match overlay servers by **documented aliases** or exact catalog ids. Prefer a ready `plugin-*` id over an unknown similarly named server; if several match, ask rather than guessing.
+5. If two servers expose the same product (plugin + project entry), use the **ready** one; do not call both.
+
+## Classes
+
+| Class | Who adds it | Policy |
+|-------|-------------|--------|
+| **Shipped** | Preset `mcp.json` | Assume it should be there; call when the task fits; degrade if down (do not block unless noted below) |
+| **Local overlay** | Consumer project or user MCP | Use only when present **and** the task fits. Never a required pipeline step |
+
+Shipped in every preset: **Context7** (library docs). Other shipped servers are stack-specific — see adapter **Stack notes**.
+
+## Context7 (shipped)
+
+**When to call** (after lockfile / manifest + sibling files still do not confirm the symbol):
+
+- Third-party API that would otherwise get `// VERIFY: lib.symbol @ version`
+- Version-sensitive framework or SDK APIs
+- Migrations / major upgrades
+- Library is in the lockfile but the signature is unclear
+
+**When not to call:** repo public API; a sibling file already imports the symbol; a trivial call already in this module.
+
+**Flow:**
+
+1. Discover server `context7`.
+2. Resolve a library id, then query docs (read the live schema; typical names `resolve-library-id` then `query-docs`).
+3. Put the **installed major** from the project manifest into the query.
+4. Cap: **≤3 doc queries per question**.
+5. Source priority: lockfile / sibling code **>** Context7 **>** training data. If docs disagree with the installed major, keep the installed API.
+6. If Context7 is down: `// VERIFY` (or stack equivalent) and say MCP was unavailable. **Do not block** the task.
+
+## Local overlay protocol
+
+If a matching server is ready and a **task signal** fires → discover and use. Otherwise continue from files / native tools (`gh`, repo docs, source).
+
+Absence of an overlay is **not** `BLOCKED` unless the user required that MCP as source of truth.
+
+### Observability (Sentry, Datadog, similar)
+
+**Signal:** production error, event/trace id, APM / latency, pasted dashboard or issue URL.
+
+Use the **first ready** observability MCP. Do not invent metrics or stack traces. Do not require two observability servers.
+
+### Tickets (Linear, Jira, Notion, similar)
+
+**Signal:** ticket/page URL in the prompt or brief, or an explicit “pull from \<tracker\>”.
+
+Read-only by default. Task-folder artifacts (`brief.md`, `decomposition.md`) remain SoT — do not replace them with a tracker page. Write back to the tracker **only** if the user asked.
+
+### Component-library overlay
+
+**Signal:** UI component public API, stories, controls, or explicit component-docs MCP.
+
+If such a server is ready, use it for documented props/variants instead of inventing them. If it is down, read story/source files. **Block** only when the user required that MCP as SoT.
+
+Usual aliases and runtime needs live in frontend **Stack notes**. Do not ship this server in preset `mcp.json`.
+
+### GitHub MCP
+
+Native `gh` / git remain SoT for PRs and checks. A GitHub MCP may be used when present; do not require it.
+
+## Figma
+
+Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plugin** and a project `figma` server are both present, use the ready one and do not duplicate calls.
+
+## Forbidden
+
+- Secrets in `mcp.json` / `.mcp.json`
+- New pipeline agents or required handoffs for overlay MCP
+- Treating overlay absence as blocked (except user-required SoT)
+- Tracker/admin write tools without an explicit ask
+- Calling overlay MCP “just in case” on unrelated tasks
+
+## Stack notes
+
+- Pipeline **`mockup-reviewer`** is the only agent that reads Figma for mockup review. See `mockup-review`.
+- Shipped besides Context7: browser automation MCP (`playwright` / `playwright-test` / `user-playwright`) and `chrome-devtools`.
+- **Split:** Playwright MCP → e2e agents (planner/generator/healer), selector checks, spec reproduction. Chrome DevTools MCP → `debugger` / `performance-auditor` against a **running app** (console, network, traces). Not a substitute for e2e.
+- **Storybook overlay** (not shipped): aliases `storybook`, `user-storybook`, `plugin-storybook`, `storybook-mcp-addon`. Needs Storybook running (often `http://localhost:6006/mcp`). Discover docs/dev/testing toolsets. If down, read story/source files. Block only if the user required Storybook MCP as SoT.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept. User-level MCP is never touched.
+- If a Figma plugin is already connected, do not also require the project `figma` server.

package/presets/claude/svelte/rules/tooling-and-review/preset-no-cross-stack-leakage.md

@@ -22,6 +22,7 @@ Ban leakage of stack-specific names, paths, and handoff stems across presets.
 - `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Android instrumentation agents, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
 - `mcp-ts` must not ship Go tool commands (`go test`, `go vet`, `golangci-lint`) or `integration-test-*` agents as required delivery gates.
 - Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
+- Storybook / Chrome DevTools MCP must **not** be required handoffs or agent stems (`storybook-reviewer`) on backend or mobile stacks. Frontend overlay mentions in `MCP.md` / `mcp-usage` Stack notes are OK.
 
 ## Forbidden in ios-swift hooks/agents (FAIL)
 

package/presets/claude/svelte/skills/README.md

@@ -5,6 +5,8 @@
 | Skill | When to use |
 |-------|-------------|
 | `feature-delivery` | End-to-end feature work across types, API, store, UI, tests |
+| `spec-authoring` | Author or bootstrap docs/specs (INDEX, page/feature templates); `/spec-start` / analyst author mode |
+| `spec-discovery` | Opt-in research-before-spec in analyst author mode (claim ledger; not default `/task` consume) |
 | `mockup-review` | Figma mockup review: DS, coverage, viewports (standalone or embedded) |
 | `ux-design` | Behavioral UX synthesis/review via task-analyst (standalone or embedded; no Figma MCP) |
 | `code-review` | MR/diff review using project architecture and test standards |