@bonesofspring/ai-rules 0.2.17 → 0.2.18

package/presets/claude/android-kotlin/rules/architecture/feature-delivery.md

@@ -8,6 +8,8 @@ paths:
   - "**/*.{kt,kts}"
 ---
 
+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.
+
 <!-- shared-core: architecture/feature-delivery-workflow.md -->
 
 # Feature delivery (Android Kotlin)

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

@@ -31,7 +31,7 @@ Work request without `/task` — see **`tooling-and-review/agent-team-intake.md`
 | Agent | Prod writes | Typical intent |
 |-------|-------------|----------------|
 | `task-router` | no (team) | Every `/task` |
-| `task-analyst` | no | feature, refactor, test-only, a11y, docs, migration |
+| `task-analyst` | no | feature, refactor, test-only, a11y, docs, migration, ux-design |
 | `solution-architect` | no | spike, cross-layer Feature |
 | `migration-specialist` | no | Android Studio / AGP/Gradle modules/Android upgrades |
 | `api-contract-reviewer` | no | OpenAPI / Kotlin codegen contracts |
@@ -41,6 +41,7 @@ Work request without `/task` — see **`tooling-and-review/agent-team-intake.md`
 | `build-verifier` | no | ./gradlew + ktlint/detekt/Format + unit smoke; preset-structure for preset PRs |
 | `accessibility-reviewer` | no | TalkBack / font scale / semantics |
 | `performance-auditor` | no | launch / Profiler / Macrobenchmark |
+| `mockup-reviewer` | no (team only) | mockup-review, feature/refactor/spike/spec-gen with `figma.com` |
 | `code-reviewer` | no | most pipelines, review-only |
 | `security-reviewer` | no | Android Keystore / encrypted storage, network security / cleartext, PII |
 | `qa-tester` | tests | feature, bugfix, test-only |
@@ -54,6 +55,8 @@ Work request without `/task` — see **`tooling-and-review/agent-team-intake.md`
 
 Full prompts: `.claude/agents/*.md`. Artifact conventions: `.claude/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 **`tooling-and-review/preset-pr-checklist.md`** (+ twin-sync / layering / token-budget / leakage meta-rules).
@@ -103,8 +106,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.
 4. **Never** skip `humanGates` without `/task-continue` or explicit approval.
-5. Persist handoffs to disk under `.claude/team/tasks/<slug>/` via **Write** (not Shell `mkdir`).
-6. On `changes_requested`: developer → same reviewer.
+5. Persist handoffs to disk under `.claude/team/tasks/<slug>/` via **Write** (not Shell `mkdir`), including `mockup-review.md` / `ux-design.md` when those producers ran.
+6. On `changes_requested`: developer → same reviewer. Exception: embedded `mockup-reviewer` FAIL → `awaiting_approval` / `/task-continue` only (no developer retry).
 7. On `validation_failed`: developer → build-verifier.
 8. When all steps complete, suggest `/technical-retro <slug>`.
 9. If `autoChain: false`, do not rely on hook.

package/presets/claude/android-kotlin/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 Android buckets (not enforced pixels): ~sw360 / sw600 / sw840 (phone / tablet / large) mapped to small / medium / large.

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

@@ -70,7 +70,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`).
 
@@ -82,7 +83,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`.
 
@@ -94,7 +96,6 @@ Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`,
 ## Chain fork
 
 `hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).
-
 ## Stack notes
 
 - **Authoring meta:** forbidden/required sections above describe **other stacks** (and this one) for preset authors. Consumer installs of `android-kotlin` must still keep foreign agent stems out of required handoffs.

package/presets/claude/android-kotlin/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 **android**: navigation chrome, system back, TalkBack / font-scale intent. Same `ux-design.md` schema as web; put sw/window-size examples here only — do not FAIL on exact dp.

package/presets/claude/android-kotlin/skills/README.md

@@ -3,6 +3,8 @@
 | Skill | Purpose |
 |-------|---------|
 | `feature-delivery` | Domain → Data → VM → View → tests → post-change-build |
+| `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` | Android MR checklist |
 | `unit-testing` | JUnit 4/5 (repo default) |
 | `instrumentation-ui-e2e` | Android instrumentation plan/generate/heal (← next `playwright-e2e`) |

package/presets/claude/android-kotlin/skills/feature-delivery/SKILL.md

@@ -19,6 +19,9 @@ description: Delivers Android Kotlin/Jetpack Compose features end-to-end across
 - **Don't** invent alternate architecture or persistence stacks (e.g. MVI frameworks, Room vs SQLDelight) unless the repo already uses them.
 - **Don't** use yarn, browser e2e, or `app/src` paths — wrong stack.
 
+- 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
 
 Implement only the current AC / decomposition task. Clarify ambiguity before coding; do not add unrelated hardening, polish, or drive-by refactors. See `feature-developer` → **Zero improvisation**.

package/presets/claude/android-kotlin/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.

package/presets/claude/android-kotlin/skills/ux-design/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ux-design
+description: Behavioral UX synthesis and review for task-analyst. Modes synthesize|review. Standalone intent ux-design or embedded required-signal / advisory UI AC. No Figma MCP; no DESIGN.md.
+---
+
+# UX design
+
+Requestable procedure for **task-analyst** (not a pipeline agent). Checklist lives in rule `ux-design` — do not duplicate it here.
+
+**Not** a Figma workflow: do not call Figma MCP; do not write `DESIGN.md`. Visual/DS/viewport audit stays with `mockup-reviewer` / skill `mockup-review`.
+
+## When to run
+
+- Standalone `/task` intent `ux-design` (report-only; profile `light`; steps only `task-analyst`; modes `synthesize` | `review`; `humanGates: []`).
+- Embedded: `feature` / `refactor` / `spike` / `spec-gen` on a UI stack when required-signal or advisory UI AC fires — inside the analyst step (no new pipeline agent). Required-signal: user asked UX, or AC require flows/states, or spec-gen page/feature.
+
+## Modes
+
+- `synthesize` — elicit IA, named primary flows, empty/error/loading matrix from the brief/AC.
+- `review` — critique a brief/wireframe/description **without** Figma. A `figma.com` URL with review-not-implement language is intent `mockup-review`, not this skill.
+
+## Order
+
+UX synthesis **before** skill `spec-authoring` / author mode when both apply. Analyst remains the only INDEX writer. Map headings via the rule's Spec feed table; do not paste the whole UX file into `docs/specs`.
+
+## Forbidden Figma MCP
+
+Do not call `get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`. Only `mockup-reviewer` reads Figma.
+
+## Load the checklist
+
+Load requestable rule `ux-design` and follow its required-signal vs advisory rules, forbidden MCP list, verdicts, surface-closure, and report headings.
+
+## Output
+
+Write `.claude/team/tasks/<slug>/ux-design.md` and append that path to the **`analysis`** manifest entry (`authoritativePaths` / `evidencePaths`). Do **not** create a new producer row. Receipt stays on `analysis`: required `INCOMPLETE` (missing primary flows or empty/error/loading matrix) → DoR not met; advisory `INCOMPLETE` → notes only. Never copy the mockup FAIL-only hook.

package/presets/claude/android-kotlin/team/fixtures/artifact-manifest.example.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "slug": "example-mockup-review",
+  "updatedAt": "2026-07-31T12:05:45.000Z",
+  "artifacts": [
+    {
+      "id": "mockup-review",
+      "producer": "mockup-reviewer",
+      "status": "completed",
+      "authoritativePaths": ["mockup-review.md"],
+      "acceptanceCriteriaIds": ["AC-4", "AC-5", "AC-6", "AC-7", "AC-8"],
+      "taskIds": [],
+      "timestamps": {
+        "createdAt": "2026-07-31T12:05:30.000Z",
+        "updatedAt": "2026-07-31T12:05:45.000Z",
+        "completedAt": "2026-07-31T12:05:45.000Z"
+      },
+      "receipt": {
+        "outcome": "completed",
+        "summary": "Mockup review completed with verdict PASS_WITH_NOTES.",
+        "evidencePaths": ["mockup-review.md"]
+      }
+    }
+  ]
+}

package/presets/claude/android-kotlin/team/fixtures/feature-with-figma-url.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-figma",
+  "intent": "feature",
+  "profile": "full",
+  "summary": "Feature with Figma mockup URL — mockup-reviewer after analyst, before architect and developer",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" },
+    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}

package/presets/claude/android-kotlin/team/fixtures/feature-with-ux-no-figma.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-ux-no-figma",
+  "intent": "feature",
+  "profile": "standard",
+  "summary": "Feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; no mockup-reviewer step",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify, UX design, decompose" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; analyst skill ux-design covers behavioral UX" }
+  ]
+}

package/presets/claude/android-kotlin/team/fixtures/mockup-review-fail-embedded-status.json

@@ -0,0 +1,8 @@
+{
+  "slug": "example-mockup-fail-gate",
+  "state": "awaiting_approval",
+  "currentAgent": "mockup-reviewer",
+  "awaitingHumanGate": true,
+  "retryAfterFix": null,
+  "note": "Embedded mockup FAIL: hook must NOT set retryAfterFix to feature-developer. Resume only via /task-continue."
+}

package/presets/claude/android-kotlin/team/fixtures/mockup-review-standalone.json

@@ -0,0 +1,14 @@
+{
+  "slug": "example-mockup-review-standalone",
+  "intent": "mockup-review",
+  "profile": "light",
+  "summary": "Standalone Figma mockup review (report-only)",
+  "steps": [
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone mockup-review is report-only" }
+  ]
+}

package/presets/claude/android-kotlin/team/fixtures/ux-design-standalone.json

@@ -0,0 +1,15 @@
+{
+  "slug": "example-ux-design-standalone",
+  "intent": "ux-design",
+  "profile": "light",
+  "summary": "Standalone behavioral UX design (analyst + skill ux-design; report-only; no developer)",
+  "steps": [
+    { "agent": "task-analyst", "label": "UX design (skill ux-design)" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone ux-design is report-only" },
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; not a mockup review" }
+  ]
+}

package/presets/claude/go/MCP.md

@@ -11,6 +11,6 @@ Copied to `.mcp.json` on `ai-rules init claude --preset go`.
 
 Browser e2e MCP (Playwright / Chrome DevTools) are **not** part of the go preset.
 
-Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token).
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token). Optional Figma MCP is design context only — **not** a mockup-review pipeline (this preset never schedules `mockup-reviewer`).
 
 After init: Claude Code MCP → enable servers. `init` overwrites the same-named `mcp.json`.

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

@@ -34,6 +34,12 @@ Document PASS/FAIL in `validation-report.md`.
 3. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel → **FAIL** (leakage). Prefer `check:preset-leakage`.
 4. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.
 
+
+**Forbidden mockup-reviewer:** agent file `agents/mockup-reviewer.md` or required `AGENT_HANDOFF` / pipeline handoff for `mockup-reviewer` → **FAIL** (no UI mockup reviewer).
+
+**Forbidden ux-designer / ux-design:** agent file `agents/ux-designer.md` or required `skills/ux-design` / `rules/ux-design` / pipeline handoff stem `ux-design` → **FAIL** (no UI UX surface).
+
+
 ## 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 evidence, pipeline scope, and changed files.

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

@@ -31,7 +31,7 @@ You are a task router for a **Go hexagonal backend** agent team. You **do not**
 | `spike` | «исследуй» (explore), "spike", proof of concept | task-analyst → solution-architect | <!-- i18n-keep: E4 -->
 | `retro` | «ретро» (retro), "postmortem" | (orchestrator → `/technical-retro`) | <!-- i18n-keep: E4 -->
 
-**Never schedule** Playwright (`playwright-test-*`), XCUITest (`xcuitest-test-*`), or `accessibility-reviewer`. Put them in `skipped` with reason "Go backend uses integration-test trio".
+**Never schedule** Playwright (`playwright-test-*`), XCUITest (`xcuitest-test-*`), or `accessibility-reviewer` / `mockup-reviewer`. Put them in `skipped` with reason "Go backend uses integration-test trio".
 
 ## Pipeline profiles
 

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

@@ -70,7 +70,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`).
 
@@ -82,7 +83,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/ios-swift/agents/README.md

@@ -22,7 +22,7 @@ When copying next pipeline templates: put Playwright stems in `skipped` with rea
 | feature-developer | yes |
 | build-verifier | no |
 | debugger, ci-investigator | minimal |
-| code-reviewer, accessibility-reviewer, security-reviewer, performance-auditor | no |
+| code-reviewer, accessibility-reviewer, security-reviewer, performance-auditor, mockup-reviewer | no |
 | qa-tester, unit-test-*, xcuitest-test-* | tests only |
 | tech-writer | docs only |
 
@@ -38,7 +38,7 @@ Same tiers as **cursor/next** (see that README for full notes). Defaults in this
 |------|-------------|--------|
 | **cheap** | `fast` | router, analyst, build-verifier, code-reviewer, tech-writer, codebase-analyzer |
 | **standard** | `inherit` | developer, debugger, ci-investigator, api-contract, a11y, qa, unit-*, xcuitest-* |
-| **strong** | `claude-opus-4-8[effort=high]` | solution-architect, migration-specialist, security-reviewer, performance-auditor |
+| **strong** | `claude-opus-4-8[effort=high]` | solution-architect, migration-specialist, security-reviewer, performance-auditor, mockup-reviewer |
 
 Optional `steps[].model`: `cheap` \| `standard` \| `strong` (router/orchestrator policy — same as next).
 

package/presets/claude/ios-swift/agents/build-verifier.md

@@ -42,6 +42,12 @@ When validating **ios-swift preset** changes (or `scope: preset-structure-valida
 10. **Embed drift (hard in `check:preset-structure`):** `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1`.
 11. **Dogfood (monorepo soft):** `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass deletion without migration doc → risk / FAIL for maintainers.
 
+
+**mockup-reviewer (UI):** `agents/mockup-reviewer.md` and `skills/mockup-review/` must exist (Cursor + Claude). Missing → **FAIL**. Backend stacks must **not** ship that agent file or a required `mockup-reviewer` chain handoff → **FAIL** if present.
+
+**ux-design (UI):** `skills/ux-design/` and requestable rule `ux-design` (`ux-design.mdc` / `tooling-and-review/ux-design.md`) must exist (Cursor + Claude). Missing → **FAIL**. Do **not** require `agents/ux-designer.md`. Backend stacks must **not** ship that agent file or a required `ux-design` skill/rule/handoff → **FAIL** if present.
+
+
 ### Soft rules (do not FAIL alone)
 
 - **Thin aliases:** `agent-team-intake`, `technical-retro` may be <15 body lines. Enforce ≥15 on **domain** rules.

package/presets/claude/ios-swift/agents/feature-developer.md

@@ -55,6 +55,12 @@ Emit the owned implementation receipt with outcome `completed`. Handoff by layer
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
 
+## 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.