@bonesofspring/ai-rules 0.2.16 → 0.2.18

package/presets/claude/nuxt/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',
 };
@@ -311,6 +312,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 tooling-and-review/code-review-mr.md. ` +
     `Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
@@ -596,6 +599,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]
@@ -628,6 +643,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/claude/nuxt/rules/README.md

@@ -38,6 +38,8 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 | `architecture-boundaries-ui.mdc` | `architecture/architecture-boundaries-ui.md` |
 | `feature-delivery-workflow.mdc` | `architecture/feature-delivery-workflow.md` |
 | `reference-features.mdc` | `architecture/reference-features.md` |
+| `product-specs.mdc` | `architecture/product-specs.md` |
+| `product-specs-authoring.mdc` | `architecture/product-specs-authoring.md` | Generate/Bootstrap; requestable |
 | `public-imports.mdc` | `architecture/public-imports.md` |
 | `layer-barrel-exports.mdc` | `architecture/layer-barrel-exports.md` |
 | `api-services.mdc` | `api-and-data/api-services.md` |
@@ -56,6 +58,8 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 | `agent-team-intake.mdc` | `tooling-and-review/agent-team-intake.md` |
 | `agent-team-orchestrator.mdc` | `tooling-and-review/agent-team-orchestrator.md` |
 | `technical-retro.mdc` | `tooling-and-review/technical-retro.md` |
+| `mockup-review.mdc` | `tooling-and-review/mockup-review.md` |
+| `ux-design.mdc` | `tooling-and-review/ux-design.md` |
 | `preset-layering.mdc` | `tooling-and-review/preset-layering.md` |
 | `preset-twin-sync.mdc` | `tooling-and-review/preset-twin-sync.md` |
 | `preset-token-budget.mdc` | `tooling-and-review/preset-token-budget.md` |
@@ -73,8 +77,11 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 | `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | thin alias |
 | `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | Nuxt layer checklist |
 | `architecture/reference-features.template.md` | `reference-features.mdc` | path table |
+| `architecture/product-specs.md` | `product-specs.mdc` | INDEX discovery; Stack notes |
 | `review/code-review-mr.md` | `code-review-mr.mdc` | Nuxt checklist refs |
 | `review/technical-retro.md` | `technical-retro.mdc` | thin alias |
+| `review/mockup-review.md` | `mockup-review.mdc` | Stack notes breakpoints; on-demand |
+| `review/ux-design.md` | `ux-design.mdc` | Stack notes form-factor; on-demand |
 | `meta/preset-*.md` | `preset-*.mdc` | author globs only |
 
 ## Folders

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

@@ -15,6 +15,8 @@ paths:
 
 ## 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`, `nuxt-app-core.mdc`.
 
 ## Checklist (work order)
@@ -87,3 +89,7 @@ flowchart LR
 | `tests/e2e/**` | `tests-e2e-structure.mdc`, `playwright-agents.mdc` |
 
 When adding or extending a feature, **walk the checklist** and the rules from the table for affected zones.
+
+## Related
+
+- Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.

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

@@ -0,0 +1,121 @@
+---
+paths:
+  - docs/specs/**/*
+---
+
+<!-- shared-core: architecture/product-specs-authoring.md -->
+
+# Product specs authoring
+
+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`**.
+
+## Modes
+
+1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
+2. **Generate** — create/update page/feature specs + INDEX rows from brief AC, user intent, Figma, or code archaeology. Inventing *product* behavior is forbidden without a stated source (AC / user / UI copy / code-observed behavior labeled `status: draft` or `inferred`).
+3. **Bootstrap** — create `INDEX.md` + `_templates/` copies + first domain spec under greenfield policy.
+
+## Greenfield policy
+
+Agents **may** create INDEX + first specs **only when** one of:
+
+1. User runs `/spec-start` or explicitly asks to bootstrap `docs/specs`.
+2. Brief/AC includes generation or bootstrap language.
+3. Router detects `spec-gen` intent.
+
+Otherwise: missing INDEX → optional tree; do **not** invent INDEX merely because discovery loaded.
+
+## Conflict precedence
+
+1. **Human gate** decision (approved brief/spec edits).
+2. **Current task `brief.md` AC** — if AC contradicts an existing spec, analyst must reconcile (update spec as `draft` or revise AC) before developer; no silent contradiction.
+3. **Approved `docs/specs/**`** — behavior SoT for feature-developer once gate passed.
+4. **Code / `.ai/context`** — discovery evidence only; never override approved spec without gate.
+
+Label inferred-from-code lines with `status: draft` until human promotes.
+
+## INDEX.md contract (v1)
+
+| Column | Required | Notes |
+|--------|----------|-------|
+| `id` | yes | Stable kebab/id matching frontmatter `id` |
+| `type` | yes | `page` \| `feature` |
+| `domain` | yes | Domain folder under `docs/specs/domains/<domain>/` |
+| `title` | yes | Human label |
+| `path` | yes | Repo-relative path to markdown file |
+| `routes` | no | Summary; may duplicate frontmatter |
+| `aliases` | no | Comma-separated PageName / deep-link aliases |
+| `status` | no | `draft` \| `active` \| `deprecated` |
+
+Layout: `docs/specs/domains/<domain>/<id>.md` (page) and optional `docs/specs/domains/<domain>/feature.md`. Adding/renaming/removing a linked file **must** update INDEX in the **same change set**.
+
+## Frontmatter v1
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string | yes | Unique; matches INDEX |
+| `type` | enum `page` \| `feature` | yes | Backend/MCP: prefer `feature` |
+| `domain` | string | yes | |
+| `routes` | string[] | yes (may be `[]`) | Web: URL paths; mobile: deep links/screens; backend: HTTP paths; mcp-ts: tool names |
+| `ui` | string[] | yes (may be `[]`) | Component/screen refs; empty on backend/mcp |
+| `store` | string[] | yes (may be `[]`) | Slice/module refs; empty when N/A |
+| `api` | string[] | yes (may be `[]`) | Services/ports/tools |
+| `aliases` | string[] | yes (may be `[]`) | |
+| `e2e` | string[] | yes (may be `[]`) | Stack-appropriate test paths |
+| `status` | enum | no | default `draft` on agent generate |
+| `owners` | string[] | no | |
+| `related` | string[] | no | Spec ids or paths |
+
+Arrays are **always present** (empty allowed). Do not omit keys for N/A stacks.
+
+## Body headings (minimum)
+
+**`page` required:** Overview; Entry / actors; Primary flows; States (loading / empty / error / success as applicable — mark N/A explicitly); Acceptance criteria (links or bullets to brief AC / product source).
+
+**`page` optional:** Analytics, Accessibility, Edge cases, Related specs.
+
+**`feature` required:** Overview; Shared behavior / constraints; Related pages (links).
+
+**`feature` optional:** Cross-cutting states, Analytics.
+
+Compliant = valid frontmatter + all required headings present (non-empty prose or explicit `N/A`) + INDEX row with resolvable `path`.
+
+## 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`).
+
+**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.
+
+**Skill fallback:** if consumer `_templates/` missing during author mode, copy from package/skill assets before authoring.
+
+## Author roles
+
+| Role | Responsibility |
+|------|----------------|
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring` |
+| **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 |
+
+## Self-check before handoff (soft block)
+
+Block handoff via `open_questions` until fixed:
+
+- [ ] Required frontmatter keys present; arrays always present (may be `[]`)
+- [ ] Required body headings present (or explicit `N/A`)
+- [ ] INDEX row added/updated with resolvable `path` in the **same change set**
+- [ ] Sources cited; invented product behavior absent (or labeled `draft` / `inferred`)
+- [ ] Conflict with brief AC reconciled or flagged
+
+## Related
+
+- `product-specs` — discovery / consume
+- Skill `spec-authoring` — procedural checklist
+- Optional consumer script `scripts/check-product-specs.sh` (WARN default; `--strict` FAIL)
+
+
+## Stack notes
+
+- Author via skill `spec-authoring`; templates from package assets / consumer `docs/specs/_templates/`.
+- Field semantics match discovery stem (`routes` = URL paths; `e2e` = Playwright).
+- Requestable — not always-on / session-start.

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

@@ -0,0 +1,62 @@
+---
+paths:
+  - docs/specs/**/*
+---
+
+<!-- shared-core: architecture/product-specs.md -->
+
+# Product specs (docs/specs)
+
+Product page/feature **behavior** specs live under the consumer repo `docs/specs/**`. This stem covers **discovery and presence** — not layer implementation order (see `feature-delivery-workflow`) and not code-structure mirroring (see `reference-features`).
+
+**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`).
+
+## Modes (summary)
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **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 |
+
+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 `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.
+
+## Discovery algorithm
+
+1. Always start at `docs/specs/INDEX.md` when present.
+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).
+
+## Miss policy (INDEX present, row or file missing)
+
+- Record the gap in `open_questions` / handoff gaps.
+- Fall back to code discovery and consumer `.ai/context/**` when present.
+- **Do not invent** product behavior, states, interactions, or contracts.
+- Hard-fail / block only when the task’s acceptance criteria explicitly require a named spec that is absent (human/gate decision).
+
+## Authoring pointer
+
+Same-changeset INDEX updates, frontmatter v1, required body headings, templates, and conflict precedence live in **`product-specs-authoring`**. Do not paste the full checklist here.
+
+## Non-goals
+
+- Not a replacement for `.ai/context/**` (external AI Code Review glossary) or `reference-features` (file-layout mirror).
+- Not Tessl / an external host as primary SoT.
+- No stack filesystem path recipes in this core body — path examples belong only in adapter **Stack notes**.
+
+## Related
+
+- `product-specs-authoring` — generation modes, contracts, self-check.
+- `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`: Nuxt/app URL paths. `ui` / `store`: pages/components + Pinia/store paths. `e2e`: Playwright paths under repo `tests/e2e/**` (or equivalent).
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

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

@@ -28,7 +28,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 |
 | `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 +38,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 +54,10 @@ 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).
 
 ## Dynamic pipeline
@@ -145,8 +150,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/claude/nuxt/rules/tooling-and-review/mockup-review.md

@@ -0,0 +1,118 @@
+---
+description: Figma mockup review checklist (DS, coverage, viewports). On-demand — load via mockup-reviewer / skill mockup-review.
+paths:
+  - .claude/commands/**/*
+  - .claude/team/**/*
+---
+
+<!-- shared-core: review/mockup-review.md -->
+
+# Mockup review checklist
+
+On-demand reviewer checklist for Figma mockups. **Procedure:** skill `mockup-review`. **Agent:** `mockup-reviewer`. Do not inline this checklist into the agent prompt.
+
+Stack-agnostic: no app-source globs, Playwright, or `xcodebuild`. Breakpoint **examples** live in adapter **Stack notes** only — do not FAIL on exact pixels.
+
+## When to load
+
+- Pipeline step `mockup-reviewer` (standalone intent `mockup-review` or embedded after analyst)
+- Prompt or `brief.md` contains a `figma.com` URL on a UI-capable stack
+- User asks to review a mockup / Figma file (not a code MR)
+
+## Inputs
+
+1. Task `artifact-manifest.json`, then prompt Figma URL(s); `brief.md` / `decomposition.md` when present
+2. Skill `mockup-review` + this rule
+3. 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-first
+
+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` / out of scope (do not call `get_figjam` unless the URL is a FigJam board — then still `BLOCKED_MCP`).
+
+Cite `fileKey` + node IDs. Screenshots are supporting evidence, not a second reviewer. No screenshot-only path.
+
+**Node caps:** ≤12 screen-level frames; `get_metadata` depth ≤3 named-frame levels; ≤3 screenshots (prefer one per small/medium/large). `search_design_system` once; `get_variable_defs` once per file. No node-id on URL: pick top-level frames matching the feature name; if still unbounded → `BLOCKED_MCP` (or `PASS_WITH_NOTES` only if MCP returned a tiny file) — do not dump the whole file.
+
+**Degradation:** MCP unavailable or OAuth fail → verdict `BLOCKED_MCP`. Do **not** invent DS compliance claims.
+
+## Review dimensions
+
+### DS components (AC-4)
+
+When an attached library is detectable (`search_design_system` / `get_metadata`): list **library component instances vs custom frames** with file/node references. Flag substitutions where a DS equivalent exists.
+
+- Critical DS reimplementation (custom frame where an attached-library component exists) → **FAIL**
+- One-off frame, no DS equivalent; mixed/unpublished library → WARN or notes (`PASS_WITH_NOTES`)
+- No attached library detectable → notes only; do not invent DS claims (`PASS_WITH_NOTES`)
+
+Confidence: `high` (MCP library match) / `low` (unpublished or mixed) — prefer `PASS_WITH_NOTES` over FAIL when confidence is low.
+
+### Tokens (AC-5)
+
+When variables/styles are available (`get_variable_defs`, style metadata): flag fills, strokes, spacing, or typography that use raw values instead of bound variables/styles.
+
+- Isolated unbound values → **WARN** (`PASS_WITH_NOTES`)
+- Wholesale token ignore on a library-attached file (systemic; treat as critical DS with AC-4) → **FAIL**
+
+### Quality (AC-6)
+
+Cover at minimum, each item PASS / WARN / FAIL eligible:
+
+- Layer/frame naming hygiene
+- Auto-layout vs absolute positioning for responsive regions
+- Text style usage
+- Component variant/property correctness
+- Detached or orphaned component instances
+
+Naming hygiene, minor detached instances, text-style drift → **WARN**. Detached **core** DS component that is a substitution → **FAIL** (same as AC-4 critical). Absolute layout on a region that is the only «responsive» evidence → WARN unless it also fails viewports.
+
+### Feature coverage (AC-7)
+
+Map **flows → screens/frames**, **actions → interactive elements**, and **states** (empty, loading, error, success, disabled/validation). List explicit **missing** items. Label scope **`inferred`** when only a URL is provided (no brief AC).
+
+- Missing **core** flow or primary action from brief AC (or labeled `inferred` primary flow from the URL) → **FAIL**
+- Missing empty/loading/error/success on a form/list called out in AC → **FAIL**
+- Missing secondary states (disabled/validation) not in AC → **WARN**
+
+### Viewports (AC-8)
+
+Verify **≥3 viewport representations** (small / medium / large) via dedicated frames, Figma viewport presets, or responsive component variants.
+
+- Fewer than 3 → **FAIL**
+- 3 exist but sizes ≠ stack example buckets → **WARN** only (no exact pixel enforcement in core)
+
+## Severity (v1)
+
+Isolated **WARN** never blocks. Overall verdict = worst FAIL > BLOCKED_MCP > PASS_WITH_NOTES > PASS. Multiple WARNs without FAIL → `PASS_WITH_NOTES`, not FAIL.
+
+## Report headings
+
+Write `mockup-review.md` with these headings (must match the agent template):
+
+```markdown
+# Mockup review: <slug>
+
+## Verdict
+PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP
+
+## Scope
+- Figma fileKey / node IDs
+- MCP: available | unavailable (reason)
+- Feature scope source: brief AC | prompt | inferred
+
+## Critical (must fix)
+## Warnings (should fix)
+## Suggestions
+## DS compliance (AC-4, AC-5)
+## Quality (AC-6)
+## Feature coverage (AC-7)
+## Viewport matrix (AC-8)
+## AC coverage
+| Criterion | Status | Notes |
+```
+
+## Stack notes
+
+Illustrative web buckets (not enforced pixels): ~375 / ~768 / ~1280 mapped to small / medium / large.

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

@@ -66,7 +66,8 @@ Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
 - `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
 - Positive yarn recipes `lint:js` / `lint:css`
 - `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
-- Agent file `accessibility-reviewer` (no UI surface)
+- Agent files `accessibility-reviewer`, `mockup-reviewer`, `ux-designer` (no UI surface)
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
 
 Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`), `java-tooling` (`mvn test` / `./gradlew test`), or `php-tooling` (`php artisan test` / `composer test` / `vendor/bin/phpunit`).
 
@@ -78,7 +79,8 @@ Same UI/mobile bans as backend stacks, plus:
 - Positive yarn recipes `lint:js` / `lint:css` as required gates
 - `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
 - Go tool commands as required MCP delivery gates: `go test`, `go vet`, `golangci-lint`
-- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`
+- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`, `mockup-reviewer`, `ux-designer`
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
 
 Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`, `post-change-test`); Phase 1 gates `build-verifier` + `security-reviewer`.
 

package/presets/claude/nuxt/rules/tooling-and-review/ux-design.md

@@ -0,0 +1,110 @@
+---
+description: Behavioral UX design checklist (IA, flows, states). On-demand — load via task-analyst / skill ux-design.
+paths:
+  - .claude/commands/**/*
+  - .claude/team/**/*
+---
+
+<!-- shared-core: review/ux-design.md -->
+
+# UX design checklist
+
+On-demand behavioral UX checklist (IA, named flows, state matrix). **Procedure:** skill `ux-design`. **Producer:** `task-analyst` (not a pipeline agent). Do not inline this checklist into the analyst prompt.
+
+Stack-agnostic: no app-source globs, Playwright, or `xcodebuild`. Form-factor **examples** live in adapter **Stack notes** only.
+
+## When to load
+
+- Standalone `/task` intent `ux-design` (modes `synthesize` | `review`; profile `light`; steps only `task-analyst`)
+- Embedded on a UI-capable stack when **required-signal** or advisory UI AC fires on `feature` / `refactor` / `spike` / `spec-gen`
+- Required-signal (any one): the user asked for UX, **or** AC explicitly require flows/states, **or** intent is `spec-gen` / `/spec-start` for a **page/feature**. Else **advisory** (notes only; skip if no UI surface)
+- **Do not** load for backend-only AC even on a UI stack. Classify `mockup-review` (Figma) before `ux-design` before `review-only`
+
+## Inputs
+
+1. Task `artifact-manifest.json`, then prompt / `brief.md` / `decomposition.md` when present
+2. Skill `ux-design` + this rule
+3. Approved `docs/specs` only as product-behavior SoT **after** UX synthesis maps via Spec feed — do not write INDEX here
+
+## Forbidden Figma MCP
+
+Do **not** call Figma MCP. Only `mockup-reviewer` reads Figma. Forbidden by name: `get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`.
+
+When `figma.com` is present and required-signal fires, emit a **thin** `ux-design.md` from AC only (IA/flows the mockup must cover; no visual or DS claims). If the user only pasted a URL and AC are visual, the UX file may be omitted; `mockup-review.md` coverage stands.
+
+Do **not** write BMAD-style `DESIGN.md` or a second visual spine. One experience artifact: `ux-design.md`.
+
+## Modes
+
+| Mode | When |
+|------|------|
+| `synthesize` | Design UX from a brief/AC (standalone «разработай UX» / embedded required-signal) | <!-- i18n-keep: E4 -->
+| `review` | Critique a brief/wireframe/description **without** Figma («ревью UX»). Figma + review-not-implement remains intent `mockup-review` | <!-- i18n-keep: E4 -->
+
+## Required vs advisory
+
+- **Required** when required-signal fires (user-asked-ux / ac-requires-flows-states / spec-gen-page-feature)
+- **Advisory** otherwise (UI AC without those signals). Advisory `INCOMPLETE` → notes only; DoR may complete
+- Skip the skill when there is no UI surface or the prompt is empty of UX-relevant AC
+
+## Verdicts
+
+`PASS` | `PASS_WITH_NOTES` | `INCOMPLETE`. Never copy the mockup FAIL-only hook (`changes_requested` + do-not-retry-developer). Incomplete UX is an analyst/DoR problem.
+
+| Verdict | Required step | Advisory step | Standalone intent `ux-design` |
+|---------|---------------|---------------|-------------------------------|
+| `PASS` / `PASS_WITH_NOTES` | Analysis may complete DoR | Analysis may complete | `completed` |
+| `INCOMPLETE` | DoR **not** met: `open_questions` / blocked analysis; existing `after:task-analyst` gate | Notes only; DoR may complete | `completed` (report-only) |
+
+**Block (`INCOMPLETE` as DoR failure) only when the step was required and primary flows *or* the empty/error/loading matrix are missing.** Isolated missing microcopy or optional protagonist names never block.
+
+## Surface-closure
+
+Each stated need → a surface; each surface → a flow that lands there. If closure fails, list probes under **Open probes** — **do not invent** screens, flows, or copy to fill gaps.
+
+## Spec feed
+
+Analyst remains the **only** writer of `docs/specs` INDEX and page/feature files. Map `ux-design.md` → templates **after** UX synthesis (UX before `spec-authoring` author mode):
+
+| `ux-design.md` heading | Page template | Feature template |
+|------------------------|---------------|------------------|
+| Scope + IA | **Overview** | **Overview** |
+| Entry / actors | **Entry / actors** | — (page-level) |
+| Primary flows | **Primary flows** | **Shared behavior / constraints** when a flow is cross-page |
+| States | **States** (loading/empty/error/success) | **Cross-cutting states** when shared |
+| Interaction notes + microcopy direction | Inform **Acceptance criteria**; leftover → **Edge cases** | Shared constraints |
+| Accessibility floor (behavioral) | Testable AC without pixels; else Edge cases | Shared constraints |
+| Surface-closure probes | Analyst `open_questions` — **do not** invent spec rows | Same |
+
+## Manifest
+
+When produced, append `ux-design.md` to the **`analysis`** entry `authoritativePaths` and `evidencePaths`. Do **not** add a new default producer row for v1 (`ux-designer` is deferred).
+
+## Report headings
+
+Write `ux-design.md` with these headings (must match the architecture artifact contract):
+
+```markdown
+# UX design: <slug>
+## Mode
+synthesize | review
+## Verdict
+PASS | PASS_WITH_NOTES | INCOMPLETE
+## Scope
+- Form factor: web | ios | android | mixed
+- Figma present: yes | no
+- Required-signal: user-asked-ux | ac-requires-flows-states | spec-gen-page-feature | advisory
+## Information architecture
+## Entry / actors
+## Primary flows
+## States
+## Interaction notes
+## Microcopy direction
+## Accessibility floor (behavioral)
+## Spec feed
+## Open probes
+```
+
+## Stack notes
+
+Form-factor **web**: browser chrome, responsive layout, pointer + keyboard. Do not FAIL on exact pixels; name surfaces (page, modal, drawer) as in the product.

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

@@ -5,6 +5,8 @@
 | Skill | When to use |
 |-------|-------------|
 | `feature-delivery` | End-to-end feature work across types, API, store, UI, tests |
+| `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 |
 | `debug-investigation` | Reproducing and fixing bugs with root-cause evidence |
 | `ci-investigation` | Diagnosing and fixing failing CI checks on PRs/branches |

package/presets/claude/nuxt/skills/feature-delivery/SKILL.md

@@ -6,9 +6,13 @@ description: Delivers Nuxt 3 frontend features end-to-end across domain types, A
 # Feature Delivery
 
 1. Read task brief, acceptance criteria, and decomposition if present.
-2. Read **`rules/architecture/feature-delivery-workflow.md`** and **`rules/architecture/reference-features.md`** — follow layer order and mirror closest reference feature.
-3. Add or update focused tests for changed behavior.
-4. Validation from repository root: **invoke** **`rules/tooling-and-review/post-change-lint.md`** after code edits (requestable, not session-start — but **must** when code changed). Pipeline: scoped lint OK if next step is `build-verifier`.
+2. If `docs/specs/INDEX.md` exists **or** brief/handoff lists approved generated specs, resolve via **`product-specs`** and treat approved specs as behavior SoT before layer work (soft-fail on miss — do not invent behavior). If generation was requested but not yet approved, stop for human gate — do not implement against draft-only gaps.
+3. Read **`rules/architecture/feature-delivery-workflow.md`** and **`rules/architecture/reference-features.md`** — follow layer order and mirror closest reference feature.
+4. Add or update focused tests for changed behavior.
+5. Validation from repository root: **invoke** **`rules/tooling-and-review/post-change-lint.md`** after code edits (requestable, not session-start — but **must** when code changed). Pipeline: scoped lint OK if next step is `build-verifier`.
+
+- If the prompt or brief contains a `figma.com` URL, load requestable skill `mockup-review` and do not start UI work until the mockup-reviewer step is completed or the user continued past FAIL/`BLOCKED_MCP`.
+- When required-signal (user asked UX, AC require flows/states, or spec-gen page/feature) and **no** `figma.com` URL: `ux-design.md` must exist on the analysis manifest entry (verdict not `INCOMPLETE`) before UI work. If missing, **blocked** — hand back to `task-analyst`. Parallel to the mockup gate when Figma exists.
 
 ## Scope discipline
 

package/presets/claude/nuxt/skills/mockup-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: mockup-review
+description: Reviews a Figma mockup for design-system compliance, feature coverage, and viewport matrix via Figma MCP. Use for standalone mockup-review intent or when a feature/refactor/spike/spec-gen task includes a figma.com URL.
+---
+
+# Mockup review
+
+Requestable procedure for agent `mockup-reviewer`. Checklist lives in rule `mockup-review` — do not duplicate it here.
+
+## When to run
+
+- Standalone `/task` intent `mockup-review` (report-only; profile `light`; steps only `mockup-reviewer`).
+- Embedded: `feature` / `refactor` / `spike` / `spec-gen` whose prompt or `brief.md` contains a `figma.com` URL on a UI stack — after `task-analyst` (when present), before architect and developer.
+
+## MCP OAuth preflight
+
+Confirm Figma MCP is configured (see `MCP.md`). Do not ship secrets. If MCP is down or auth fails, write `mockup-review.md` with verdict `BLOCKED_MCP` and receipt `blocked`. Do not invent DS claims. Embedded skip-forward is `/task-continue` (explicit «proceed without MCP»).
+
+## Plugin skills
+
+If plugin skills `figma-design-to-code` / `figma-use` are installed, load them for MCP invocation recipes; do not paste their bodies; do not run design-to-code. Preset owns the checklist, agent, and routing; plugin owns MCP recipes.
+
+## Load the checklist
+
+Load requestable rule `mockup-review` and follow its review dimensions, node caps, and report headings.
+
+## Output
+
+Write `.claude/team/tasks/<slug>/mockup-review.md` and upsert manifest entry id `mockup-review` (producer `mockup-reviewer`). Receipt mapping is in the agent prompt.