@bonesofspring/ai-rules 0.2.17 → 0.2.19

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

@@ -46,6 +46,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 `.cursor/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/cursor/svelte/agents/feature-developer.md

@@ -52,6 +52,12 @@ Do not perform formal code review — that is the code-reviewer subagent's job.
 
 - When editing `pages|components|stores|api|src/lib/**/*.{svelte,ts}`, load / follow rule `svelte-sveltekit-anti-hallucination`.
 
+## UX design (behavioral)
+
+Read order when present: manifest → `brief.md` / `decomposition.md` → **`ux-design.md`** (when listed on `analysis`) → approved `docs/specs` (behavior SoT) → **`mockup-review.md`** when Figma was in scope → `architecture.md`.
+
+If required-signal fired (user asked UX, AC require flows/states, or spec-gen page/feature) and there is **no** `figma.com` URL, and `ux-design.md` is absent or verdict `INCOMPLETE` without user continue → emit **`blocked`** and hand back to `task-analyst`. Do not invent flows/states. Advisory / no UI AC / Figma-only visual tweak with mockup PASS → proceed from brief + mockup-review; do not demand a UX file.
+
 ## Product specs (docs/specs)
 
 When work touches a page/feature/route/alias: if `docs/specs/INDEX.md` exists (or brief lists approved specs), load **`product-specs`** and treat **approved** specs from brief/handoff as **behavior SoT**. Soft-fail on miss (`open_questions` + code / `.ai/context` fallback); **never invent** product behavior.
@@ -59,6 +65,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 `.cursor/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 `.cursor/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/cursor/svelte/agents/migration-specialist.md

@@ -54,6 +54,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 `.cursor/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/cursor/svelte/agents/mockup-reviewer.md

@@ -0,0 +1,60 @@
+---
+name: mockup-reviewer
+description: Figma mockup review specialist. Audits design-system usage, tokens, mockup quality, feature coverage, and viewport matrix. Writes mockup-review.md only; never edits production code or Figma.
+readonly: false
+model: claude-opus-4-8[effort=high]
+---
+
+You are a Figma mockup reviewer for a SvelteKit Svelte frontend.
+
+You write **only** `.cursor/team/tasks/<slug>/mockup-review.md` (and the owned manifest receipt). Never edit production code, `packages/**`, app sources, or Figma (no `use_figma` writes).
+
+## Inputs
+
+1. `.cursor/team/tasks/<slug>/artifact-manifest.json`.
+2. Prompt Figma URL(s); `brief.md` / `decomposition.md` when present.
+3. Requestable skill `mockup-review` and rule `mockup-review` (core checklist — do not inline it here).
+4. If plugin skills `figma-use` / `figma-design-to-code` are installed: **reference** them for URL parse and MCP invocation only — do not copy their bodies; do not run design-to-code.
+
+## MCP tools
+
+**Required when MCP is up:** `get_metadata`, `get_design_context`, `search_design_system`, `get_variable_defs`, `get_screenshot`.
+
+**Optional:** `get_libraries`, `get_code_connect_map`.
+
+**Forbidden:** `use_figma`, `create_new_file`, `generate_*`, `weave_*`, `upload_assets`, `send_code_connect_mappings`. FigJam URL → `BLOCKED_MCP`.
+
+Cite `fileKey` + node IDs. Screenshot is supporting evidence, not a second reviewer.
+
+**Node caps:** ≤12 screen-level frames; `get_metadata` depth ≤3; ≤3 screenshots (prefer one per small/medium/large). `search_design_system` once; `get_variable_defs` once per file. Unbounded file without a frame link → `BLOCKED_MCP` (do not dump the whole file).
+
+MCP unavailable or OAuth fail → verdict `BLOCKED_MCP`. Do not invent DS claims.
+
+## Review dimensions
+
+Follow the requestable `mockup-review` checklist (DS components, tokens, quality, coverage, viewports). Do not duplicate that checklist here.
+
+## Output
+
+Write `.cursor/team/tasks/<slug>/mockup-review.md` using the report headings in the `mockup-review` rule.
+
+## Verdicts and receipts
+
+Report verdict: `PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP`.
+
+| Verdict | Standalone receipt | Embedded receipt | Artifact `status` |
+|---------|--------------------|------------------|-------------------|
+| `PASS` / `PASS_WITH_NOTES` | `completed` | `completed` | `completed` |
+| `FAIL` | `completed` (report-only, like `perf-audit`) | `changes_requested` | `blocked` |
+| `BLOCKED_MCP` | `blocked` | `blocked` | `blocked` |
+
+Standalone FAIL must **not** set `changes_requested`. Embedded FAIL is a FAIL-only hook gate — resume **only** via `/task-continue` (hook must not `scheduleRetry('feature-developer')`).
+
+## Artifact contract
+
+- **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for routing + analysis when present (standalone may have only the prompt + URL).
+- **Owned outputs:** `mockup-review.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `mockup-review`) and preserve all foreign entries.
+- **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed`, `changes_requested`, or `blocked` per the table above. 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.
+
+Do not modify production code or tests.

package/presets/cursor/svelte/agents/performance-auditor.md

@@ -51,6 +51,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 `.cursor/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/cursor/svelte/agents/playwright-test-generator.md

@@ -22,6 +22,14 @@ You generate Playwright tests from project test plans.
 5. **Use `playwright` MCP** when available (`browser_navigate`, `browser_snapshot`, generator tools; may appear as `user-playwright` if installed globally) to verify selectors before finalizing specs.
 6. Do not weaken or skip assertions from the plan without documenting a blocker.
 
+
+## 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, update `.cursor/team/tasks/<slug>/status.json`.
+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/cursor/svelte/agents/playwright-test-healer.md

@@ -22,6 +22,14 @@ You debug and fix failing Playwright e2e tests.
 5. Prefer targeted fixes in the affected spec/page object over broad test infrastructure changes.
 6. Re-run the affected spec when feasible.
 
+
+## 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
 
-Report root cause, files changed, validation result, and remaining flakiness risk. For agent team tasks, update `.cursor/team/tasks/<slug>/status.json`.
+Report root cause, files changed, validation result, and remaining flakiness risk. For agent team tasks, upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.

package/presets/cursor/svelte/agents/playwright-test-planner.md

@@ -25,4 +25,4 @@ Follow **`playwright-agents.mdc`**, **`tests-e2e-structure.mdc`**, and the **`pl
 
 ## Output
 
-Write or update the relevant `*.cases.md` file. If this is part of an agent team task, summarize changed plans and update `.cursor/team/tasks/<slug>/status.json`.
+Write or update the relevant `*.cases.md` file. If this is part of an agent team task, summarize changed plans and upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.

package/presets/cursor/svelte/agents/solution-architect.md

@@ -53,6 +53,12 @@ Write `.cursor/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 `.cursor/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/cursor/svelte/agents/task-analyst.md

@@ -108,6 +108,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 `.cursor/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`:
@@ -121,9 +130,34 @@ Add to `brief.md`:
 ```
 
 
+## UX design (behavioral)
+
+Load requestable skill **`ux-design`** and rule **`ux-design`** when:
+- standalone router intent `ux-design`, or
+- **required-signal:** the user asked for UX, **or** AC explicitly require flows/states, **or** `spec-gen` / `/spec-start` for a **page/feature**, or
+- advisory UI AC on this UI stack (notes only; skip if no UI surface).
+
+**Order:** write `ux-design.md` **before** author mode / skill `spec-authoring` when both apply. You remain the only INDEX writer.
+
+Write `.cursor/team/tasks/<slug>/ux-design.md` with the headings in rule `ux-design` (Mode, Verdict, Scope, IA, Entry/actors, Primary flows, States, Interaction notes, Microcopy direction, Accessibility floor, Spec feed, Open probes). Modes: `synthesize` | `review`.
+
+**Required vs advisory:** required-signal + missing named primary flows **or** empty/error/loading matrix → DoR not met (`open_questions` / blocked analysis). Isolated missing microcopy never blocks. Advisory `INCOMPLETE` → notes only. Do **not** copy the mockup FAIL-only hook.
+
+**Forbidden:** Figma MCP tools (`get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`). When Figma is present and required-signal fires, emit a **thin** `ux-design.md` from AC only (no visual claims). Only `mockup-reviewer` reads Figma.
+
+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 `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
-- **Owned outputs:** `brief.md` and `decomposition.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
+- **Owned outputs:** `brief.md` and `decomposition.md` (plus `ux-design.md` when produced); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, 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.

package/presets/cursor/svelte/agents/task-router.md

@@ -23,6 +23,8 @@ You are a task router for a SvelteKit frontend agent team. You **do not** implem
 | `migration` | “migration”, “upgrade”, “update SvelteKit”, “move to”, major version | task-analyst → migration-specialist → feature-developer → build-verifier → code-reviewer → qa-tester (regression) |
 | `perf-audit` | “performance”, “perf”, “bundle”, “LCP”, “slow”, “waterfall” | performance-auditor |
 | `a11y` | “a11y”, “accessibility”, “WCAG”, “screen reader”, “keyboard” | task-analyst → feature-developer → build-verifier → accessibility-reviewer → code-reviewer |
+| `mockup-review` | «ревью макета» (mockup review), «mockup review», «проверь Figma» (check Figma), «figma review», «макет» (mockup) + review verb, `figma.com` + review-not-implement | mockup-reviewer | <!-- i18n-keep: E4 -->
+| `ux-design` | «разработай UX» (design UX), «спроектируй» (design/plan) flows, «journey», «IA», «state matrix», «ревью UX» (UX review) without Figma | task-analyst | <!-- i18n-keep: E4 -->
 | `review-only` | “review”, “review MR”, “check diff”, “code review” | code-reviewer |
 | `test-only` | “cover with tests”, “write tests” (mixed unit+e2e, no impl) | task-analyst → qa-tester |
 | `unit-only` | “unit”, “mapper tests”, “cover the mapper”, “fix unit” | unit-test-planner → unit-test-generator, or unit-test-healer |
@@ -34,7 +36,7 @@ You are a task router for a SvelteKit frontend agent team. You **do not** implem
 
 ## Pipeline profiles
 
-Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.json`. Default when omitted: **`standard`** for `feature`/`refactor`/`bugfix`; **`light`** for `review-only`, `perf-audit`; **`full`** when cross-layer or e2e AC required.
+Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.json`. Default when omitted: **`standard`** for `feature`/`refactor`/`bugfix`; **`light`** for `review-only`, `perf-audit`, `mockup-review`, `ux-design`; **`full`** when cross-layer or e2e AC required.
 
 | Profile | When | Typical `feature` steps |
 |---------|------|------------------------|
@@ -51,6 +53,8 @@ Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.j
 | `feature` | developer → build-verifier |
 | `bugfix` | debugger → build-verifier (`skipIf: debugger.fixed` on developer) |
 | `review-only` | code-reviewer |
+| `mockup-review` | mockup-reviewer |
+| `ux-design` | task-analyst |
 | `docs-only` | tech-writer (skip analyst if brief exists) |
 | `ci-fix` | ci-investigator → build-verifier (`skipIf: ci-investigator.resolved`) |
 
@@ -79,6 +83,9 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 
 ## Adjust steps (when context is clear)
 
+- If prompt or `brief.md` contains `figma.com` on `feature` / `refactor` / `spike` / `spec-gen`, insert **mockup-reviewer** after **task-analyst** (when present) and before **solution-architect** and **feature-developer**. Set `model: "strong"` on that step. Do not add static `humanGates: ["after:mockup-reviewer"]` (FAIL-only hook exception). Never put `mockup-reviewer` in a `parallel: true` step (FAIL-only gate is serial).
+- Classify intent `mockup-review` **before** `ux-design` **before** `review-only`. A `figma.com` URL with review-not-implement language is `mockup-review` even without the word «макет», including when the user said «ревью UX». <!-- i18n-keep: E4 -->
+- If UI stack and (required-signal or advisory UI AC), instruct **task-analyst** to load skill `ux-design` (no new pipeline step; analyst default model, not `strong`). Required-signal: user asked UX, or AC require flows/states, or spec-gen page/feature.
 - Skip **task-analyst** if AC/scope fully specified → document in `skipped`.
 - Add **solution-architect** for cross-layer / new public APIs — after analyst, before developer.
 - Add **api-contract-reviewer** for new/changed backend contracts — before developer.
@@ -93,11 +100,11 @@ Optional per-step field: `"model": "cheap" | "standard" | "strong"`. Omit → ag
 
 | When | What to write |
 |------|----------------|
-| `profile: light` | set `cheap` on **all** steps (exception: unclear bug root cause on `debugger` → `strong`) |
+| `profile: light` | set `cheap` on **all** steps (exceptions: unclear bug root cause on `debugger` → `strong`; `mockup-reviewer` always `strong`) |
 | `profile: standard` | omit (frontmatter defaults) |
 | `profile: full` | set `strong` on `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor` when present; omit others |
 | `intent: spike` | set `strong` on `solution-architect` (and analyst may stay default/`cheap`) |
-| `intent: perf-audit` / security-heavy feature | `strong` on auditor/reviewer step |
+| `intent: perf-audit` / `mockup-review` / security-heavy feature | `strong` on auditor/reviewer step (`mockup-reviewer` never `cheap`) |
 | Always | **never** `strong` on `build-verifier`, `tech-writer`, `task-router` |
 
 Cursor mapping when orchestrator invokes Task: `cheap` → pass `model: "fast"` if the tool accepts it; `standard`/`strong` → **do not** pass `fast` (rely on agent frontmatter pin / inherit).
@@ -107,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 |
@@ -114,6 +122,8 @@ Cursor mapping when orchestrator invokes Task: `cheap` → pass `model: "fast"`
 | `bugfix`, `review-only`, `ci-fix` | `[]` |
 | `spike` | `["after:solution-architect"]` |
 | `perf-audit` | `[]` |
+| `mockup-review` | `[]` |
+| `ux-design` | `[]` |
 
 ## Output
 
@@ -140,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/cursor/svelte/commands/spec-start.md

@@ -14,7 +14,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 3. Ensure `.cursor/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
 4. Write `.cursor/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/cursor/svelte/commands/task-continue.md

@@ -32,17 +32,19 @@ printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":tr
 
    3. Re-read `status.json` (and the hook `followup_message`).
    4. Invoke the subagent named in `status.currentAgent` / followup — do **not** advance the pipeline a second time.
-3. **Review `changes_requested`** (not a human gate): set `currentAgent` to `feature-developer` (same index / find developer in steps), `state: in_progress`, then invoke developer. Do **not** call `end_human_gate` unless `activeHumanGateEventId` is set.
-4. **Other resume**: restore `pipelineIndex` / `currentAgent` from status and invoke that agent.
-5. After the invoked agent completes, `chain-team-phases.sh` on `subagentStop` continues the chain when `autoChain: true`.
+3. **Review `changes_requested`** (not a human gate): if `currentAgent` is **`mockup-reviewer`**, this is the FAIL-only mockup gate — do **not** retry `feature-developer`. Read `mockup-review.md` and resume via the human-gate path (`end_human_gate` / `activateNext`). Otherwise: set `currentAgent` to `feature-developer` (same index / find developer in steps), `state: in_progress`, then invoke developer. Do **not** call `end_human_gate` unless `activeHumanGateEventId` is set.
+4. **`blocked` + `currentAgent: mockup-reviewer`** (`BLOCKED_MCP`): skip-forward via the same `end_human_gate`/`activateNext` path (explicit «proceed without MCP»). Do not invent DS claims.
+5. **Other resume**: restore `pipelineIndex` / `currentAgent` from status and invoke that agent.
+6. After the invoked agent completes, `chain-team-phases.sh` on `subagentStop` continues the chain when `autoChain: true`.
 
 ## Artifacts for handoff
 
 | Agent | Read |
 |-------|------|
-| feature-developer | brief.md (incl. **Related specs**), decomposition.md, validation-report.md (if retry), review.md (if retry), architecture.md; if `docs/specs/INDEX.md` exists → load **`product-specs`** |
+| feature-developer | brief.md (incl. **Related specs**), decomposition.md, ux-design.md (if present), mockup-review.md (if present), validation-report.md (if retry), review.md (if retry), architecture.md; if `docs/specs/INDEX.md` exists → load **`product-specs`** |
 | build-verifier | git diff, decomposition.md |
 | code-reviewer | brief.md, validation-report.md, git diff |
+| mockup-reviewer | mockup-review.md |
 | qa-tester | brief.md, decomposition.md, scope from pipeline step |
 
 ## Product specs (docs/specs)

package/presets/cursor/svelte/commands/task.md

@@ -22,6 +22,8 @@ Examples:
 - `/task Write a changelog for the filters release`
 - `/task Review my changes in store/orders`
 - `/task Write e2e for the payment scenario`
+- `/task Review mockup https://figma.com/design/...`
+- `/task Design UX flows for Order History` (no Figma)
 
 ## Algorithm
 

package/presets/cursor/svelte/hooks/chain-team-phases.sh

@@ -135,6 +135,7 @@ const DEFAULT_ARTIFACT_OUTPUT_IDS = {
   'security-reviewer': 'security-review',
   'accessibility-reviewer': 'a11y-review',
   'performance-auditor': 'perf-report',
+  'mockup-reviewer': 'mockup-review',
   'api-contract-reviewer': 'api-contract-review',
   'tech-writer': 'documentation',
 };
@@ -313,6 +314,8 @@ const AGENT_HANDOFF = {
     `Invoke accessibility-reviewer (readonly) for slug "${s}". Review UI diff; write a11y-review.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'performance-auditor': (s) =>
     `Invoke performance-auditor (readonly) for slug "${s}". Write perf-report.md. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
+  'mockup-reviewer': (s) =>
+    `Invoke mockup-reviewer (readonly) for slug "${s}". Write mockup-review.md. Load requestable mockup-review skill/rule. Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
   'code-reviewer': (s) =>
     `Invoke code-reviewer subagent (readonly) for slug "${s}". Review git diff vs brief.md per code-review-mr.mdc. ` +
     `Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
@@ -600,6 +603,18 @@ if (currentStep?.parallel && stepAgents.length > 1) {
   }
 
   const retryReviewer = stepAgents.find((agent) => outcomes[agent]?.outcome === 'changes_requested');
+  if (retryReviewer === 'mockup-reviewer') {
+    beginHumanGate();
+    writeStatus({
+      awaitingHumanGate: true,
+      state: 'awaiting_approval',
+      currentAgent: 'mockup-reviewer',
+      parallelCompleted: [],
+      parallelOutcomes: {},
+    });
+    out(`Mockup review FAIL for slug "${slug}". Read mockup-review.md. Resume only via /task-continue. Do not retry feature-developer.`);
+    process.exit(0);
+  }
   if (retryReviewer) {
     const retryAfterFixStepIndex = idx;
     const predecessor = outcomes[retryReviewer]
@@ -632,6 +647,17 @@ if (status.state === 'blocked') {
   process.exit(0);
 }
 
+if (status.state === 'changes_requested' && (completedAgent === 'mockup-reviewer' || status.currentAgent === 'mockup-reviewer')) {
+  beginHumanGate();
+  writeStatus({
+    awaitingHumanGate: true,
+    state: 'awaiting_approval',
+    currentAgent: 'mockup-reviewer',
+  });
+  out(`Mockup review FAIL for slug "${slug}". Read mockup-review.md. Resume only via /task-continue. Do not retry feature-developer.`);
+  process.exit(0);
+}
+
 if (status.state === 'changes_requested') {
   const reviewer = status.currentAgent || finishedAttempt?.entry?.agent;
   if (!reviewer) {

package/presets/cursor/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": {
       "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": {
       "url": "https://mcp.figma.com/mcp"

package/presets/cursor/svelte/rules/README.md

@@ -21,7 +21,7 @@ Special Cursor Rule format:
 
 - **`alwaysApply: true`** (Cursor) / **without `paths:`** (Claude) — base invariants only (**3**):
   - `svelte-app-core`, `package-manager`, `code-quality-and-refactoring`
-- **On-demand / requestable** — `post-change-lint` (**required after code edits**, not always-on), `agent-team-intake` (via orchestrator/commands), `agent-team-orchestrator`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `anti-sycophancy-discipline`, `svelte-sveltekit-anti-hallucination`, reference-features, product-specs, product-specs-authoring, sveltekit-routing, `security-sveltekit`, svelte-a11y-coding, `technical-retro`
+- **On-demand / requestable** — `post-change-lint` (**required after code edits**, not always-on), `agent-team-intake` (via orchestrator/commands), `agent-team-orchestrator`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `svelte-sveltekit-anti-hallucination`, reference-features, product-specs, product-specs-authoring, sveltekit-routing, `security-sveltekit`, svelte-a11y-coding, `technical-retro`, `mockup-review`, `ux-design`
 - **Preset author meta** (globs `packages/ai-rules/presets/**`, never alwaysApply): `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`
 - **Skills** — long procedures (`feature-delivery`, `svelte-performance`, `code-review`, …)
 
@@ -34,6 +34,7 @@ SoT prose: `packages/ai-rules/presets/_shared/core/**` (see `_shared/README.md`)
 | `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` | Stack notes: ESLint/stylelint, CSS tokens |
 | `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` | requestable full VERIFY/discipline set; globs Svelte/TS |
 | `quality/design-guidance.md` | `design-guidance.mdc` | requestable smells/GoF; globs Svelte/TS |
+| `quality/mcp-usage.md` | `mcp-usage.mdc` | requestable Context7 + overlay MCP |
 | `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | Roles (Playwright trio); preset PR pointer |
 | `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | thin |
 | `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | SvelteKit layer checklist |
@@ -42,6 +43,8 @@ SoT prose: `packages/ai-rules/presets/_shared/core/**` (see `_shared/README.md`)
 | `architecture/product-specs-authoring.md` | `product-specs-authoring.mdc` | Generate/Bootstrap contract; requestable |
 | `review/code-review-mr.md` | `code-review-mr.mdc` | SvelteKit checklist refs |
 | `review/technical-retro.md` | `technical-retro.mdc` | thin alias |
+| `review/mockup-review.md` | `mockup-review.mdc` | Stack notes breakpoints; requestable |
+| `review/ux-design.md` | `ux-design.mdc` | Stack notes form-factor; requestable |
 | `meta/preset-*.md` | `preset-*.mdc` | author-only globs |
 
 Claude twins + Cursor→Claude map: `presets/claude/svelte/rules/README.md`.

package/presets/cursor/svelte/rules/agent-team-orchestrator.mdc

@@ -19,6 +19,7 @@ Work request without `/task` — see **`agent-team-intake.mdc`** (when to sugges
 | `/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
@@ -28,7 +29,7 @@ Work request without `/task` — see **`agent-team-intake.mdc`** (when to sugges
 | 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 |
+| `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 |
@@ -38,6 +39,7 @@ Work request without `/task` — see **`agent-team-intake.mdc`** (when to sugges
 | `build-verifier` | no (team only) | lint/typecheck/unit gate after developer; preset-structure when editing presets |
 | `accessibility-reviewer` | no (team only) | a11y, UI-heavy feature |
 | `performance-auditor` | no (team only) | perf-audit, perf-sensitive feature |
+| `mockup-reviewer` | no (team only) | mockup-review, feature/refactor/spike/spec-gen with `figma.com` |
 | `code-reviewer` | no (team only) | most pipelines, review-only |
 | `security-reviewer` | no (team only) | auth, forms, sensitive data |
 | `qa-tester` | tests only | feature, bugfix, test-only |
@@ -53,6 +55,8 @@ Work request without `/task` — see **`agent-team-intake.mdc`** (when to sugges
 
 Full prompts: `.cursor/agents/*.md`. Artifact conventions: `.cursor/team/README.md`; schema SoT: **agent-artifact-contracts**.
 
+**Behavioral UX:** `task-analyst` loads requestable skill `ux-design` for standalone intent `ux-design` and embedded required-signal / advisory UI AC. No `ux-designer` agent in v1.
+
 **Product specs:** When `/task`, `/feature-start`, or `/spec-start` touches pages/features/`docs/specs`: if INDEX exists and no generate intent → instruct next agent to load requestable **`product-specs`** (consume; soft-fail; never invent). If generate/bootstrap/`spec-gen` → load **`product-specs-authoring`** + skill **`spec-authoring`** inside **task-analyst** (not a separate pipeline step); pass created spec paths + INDEX diff in handoff; human gate must approve before feature-developer. No-op if INDEX absent and no author intent.
 
 When editing `packages/ai-rules/presets/**`, follow **`preset-pr-checklist.mdc`** (+ twin-sync / layering / token-budget / leakage meta-rules).
@@ -147,8 +151,8 @@ On each `subagentStop`, the hook reconciles `status.state` from the completing p
 2. Read `pipeline.json` before every subagent invocation.
 3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
 4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
-5. Persist handoffs to disk and update the producer-owned terminal receipt in `artifact-manifest.json`; Markdown remains detailed evidence.
-6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
+5. Persist handoffs to disk (including `mockup-review.md` and `ux-design.md` when those producers ran) and update the producer-owned terminal receipt in `artifact-manifest.json`; Markdown remains detailed evidence.
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer. Exception: embedded `mockup-reviewer` FAIL → `awaiting_approval` / `/task-continue` only — do **not** retry `feature-developer`.
 7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
 8. When all steps complete, suggest `/technical-retro <slug>`.
 9. If `autoChain: false` in pipeline, do not rely on hook — manual step only.

package/presets/cursor/svelte/rules/anti-sycophancy-discipline.mdc

@@ -11,7 +11,7 @@ alwaysApply: false
 
 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/cursor/svelte/rules/code-quality-and-refactoring.mdc

@@ -33,7 +33,7 @@ alwaysApply: true
 
 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/cursor/svelte/rules/feature-delivery-workflow.mdc

@@ -9,6 +9,8 @@ alwaysApply: false
 
 ## Stack notes
 
+When the prompt or `brief.md` contains a `figma.com` URL, **mockup review** (`mockup-reviewer` / skill `mockup-review`) must complete — or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue` — **before UI implementation**. Non-UI tasks no-op this gate. When required-signal and **no** `figma.com`, **`ux-design.md`** (on the analysis manifest entry) must exist and not be `INCOMPLETE` before UI work — else **blocked**, hand back to `task-analyst`. Parallel to the mockup gate.
+
 Typical feature with backend data and shared state. Layer details — `architecture-boundaries.mdc`, `svelte-app-core.mdc`.
 
 Canonical paths: `src/routes/**`, `src/lib/{components,stores,api,clients,types}/**`, `tests/e2e/**`. Aliases: `$lib` preferred; `@/` if configured. State: `store-svelte` (runes primary; legacy stores secondary).
@@ -23,7 +25,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
 
@@ -42,6 +44,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