@bonesofspring/ai-rules 0.2.17 → 0.2.18

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+### UX design skill (UI stacks)
+
+- New requestable skill/rule **`ux-design`** on **`next`**, **`nuxt`**, **`svelte`**, **`ios-swift`**, **`android-kotlin`** (Cursor + Claude twins). Shared-core checklist: `presets/_shared/core/review/ux-design.md`. Invoked by **`task-analyst`** — **no** `ux-designer` agent, **no** FAIL-only hook, **no** Figma MCP in the skill/rule.
+- Standalone intent **`ux-design`**: synthesize or review behavioral UX (IA, named flows, empty/error/loading matrix) → profile `light`, steps only `task-analyst`, `humanGates: []`. Classify `mockup-review` before `ux-design` before `review-only`.
+- Embedded: on UI required-signal or advisory AC, analyst loads the skill (no new pipeline step). Required `INCOMPLETE` blocks DoR; advisory notes only. Developer gate: required-signal + no Figma + missing/`INCOMPLETE` UX artifact → `blocked`, hand back to analyst.
+- Backend stacks (`go`, `java`, `mcp-ts`, `php-*`) never ship `skills/ux-design` / `rules/ux-design` or `agents/ux-designer.md`; leakage checker forbids those stems.
+- `/task` examples include standalone UX (no Figma). `artifact-manifest.example.json` analysis paths append `ux-design.md` on web stacks.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <ui-stack>` after publish.
+
+### Mockup reviewer (UI stacks)
+
+- New **`mockup-reviewer`** agent + requestable skill/rule **`mockup-review`** on **`next`**, **`nuxt`**, **`svelte`**, **`ios-swift`**, **`android-kotlin`** (Cursor + Claude twins). Shared-core checklist: `presets/_shared/core/review/mockup-review.md`. Report template fence is a single closed block (no stray fence after AC coverage).
+- Standalone intent **`mockup-review`**: `/task` + Figma URL (e.g. «ревью макета …») → profile `light`, steps only `mockup-reviewer`, report-only exit on FAIL (like `perf-audit`).
+- Embedded: `figma.com` in feature/refactor/spike/spec-gen → reviewer after `task-analyst`, before architect/developer. Embedded **FAIL** → receipt `changes_requested` + FAIL-only hook gate (`awaiting_approval`); resume via `/task-continue` only — no `feature-developer` retry. Orchestrator rule 6 and UI `chain-team-phases.sh` parallel-join now match that exception; ios-swift/android-kotlin `AGENT_HANDOFF` includes `mockup-reviewer`. Never put `mockup-reviewer` in `parallel: true`.
+- Figma MCP-first (read-only subset + node caps); `BLOCKED_MCP` when OAuth/MCP unavailable. Go keeps optional Figma MCP for ad-hoc context — **not** a mockup-review pipeline.
+- Backend stacks (`go`, `java`, `mcp-ts`, `php-*`) never schedule `mockup-reviewer`; leakage checker forbids agent stem on backend.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <ui-stack>` after publish.
+
 ### Product specs authoring (Phases A–E)
 
 - **Generation modes** (shared-core): **Consume** (default discovery, soft-fail on miss) · **Generate** (explicit intent / AC / `/spec-start` with existing tree) · **Bootstrap** (same triggers when `docs/specs/` absent). Greenfield policy: no INDEX/spec invention without explicit intent; conflict precedence human > brief AC > approved spec > code.

package/README.md

@@ -52,7 +52,7 @@ Where things go on `init`:
 | **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
 | **docs/specs seed** | When `<cwd>/docs/specs/` is **absent**, copy INDEX stub + `_templates/*` from `presets/_shared/assets/docs-specs/` (never overwrite existing INDEX) | same |
 
-Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
+Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `mockup-review` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — Figma mockup reviewer via agent `mockup-reviewer`); `ux-design` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — behavioral UX via `task-analyst`, no agent); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
 
 ## Product specs (`docs/specs/`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",

package/presets/_shared/README.md

@@ -39,7 +39,7 @@ Do **not** expect lineage adapters to byte-match core. Embed adapters should mat
 | `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8) |
 | `core/agent-team/` | Orchestrator + intake (pipeline language) |
 | `core/architecture/` | Feature-delivery abstract + reference-features template + product-specs (+ product-specs-authoring) + assets/docs-specs templates |
-| `core/review/` | Code-review MR + technical-retro alias |
+| `core/review/` | Code-review MR + technical-retro alias + mockup-review checklist + ux-design checklist |
 | `core/meta/` | Author-facing preset meta-rules |
 
 ## CLI note

package/presets/_shared/core/agent-team/agent-artifact-contracts.md

@@ -103,12 +103,15 @@ A producer finishes its step by upserting only its owned artifact entry and term
 | `security-reviewer` | `security-review` | `security-review.md` |
 | `accessibility-reviewer` | `a11y-review` | `a11y-review.md` |
 | `performance-auditor` | `perf-report` | `perf-report.md` |
+| `mockup-reviewer` | `mockup-review` | `mockup-review.md` |
 | `api-contract-reviewer` | `api-contract-review` | `api-contract-review.md` |
 | `qa-tester` / unit or e2e planners | stack-native test IDs | plan/spec paths named in the agent prompt |
 | `tech-writer` | `documentation` | `documentation.md` |
 
 Use these defaults unless a step's `artifactOutputId` / `artifactOutputIds` assigns a distinct owned ID (parallel reviewers must not share one `id`). `artifactInputIds` defaults to the applicable authoritative entries already present in the manifest.
 
+**v1 UX artifact:** when `task-analyst` produces `ux-design.md`, append it to the **`analysis`** entry `authoritativePaths` and `evidencePaths`. Do **not** add a default producer row for `ux-designer` in v1.
+
 ## Minimal terminal handoff
 
 Report the owned entry ID, outcome, authoritative paths, covered AC/task IDs, and remaining gaps. The hook advances pipeline state from the terminal receipt; the agent receipt is evidence that drives the state transition, not a substitute for writing `status.json`.

package/presets/_shared/core/agent-team/agent-team-orchestrator.md

@@ -20,9 +20,9 @@ Roster of specialists is **stack-specific** (agent names and write scopes differ
 
 | Kind | Examples (names vary by stack) |
 |------|--------------------------------|
-| Planning | `task-router`, `task-analyst`, `solution-architect`, `migration-specialist` |
+| Planning | `task-router`, `task-analyst` (plus skill `ux-design` for behavioral UX **where the stack has a UI surface**), `solution-architect`, `migration-specialist` |
 | Implementation | `feature-developer`, `debugger`, `ci-investigator` |
-| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer **only when the stack has a UI surface** |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer and `mockup-reviewer` **only when the stack has a UI surface** |
 | Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
 | Docs | `tech-writer` |
 
@@ -158,8 +158,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 (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
-6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
+5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`, `mockup-review.md`, `ux-design.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer. Exception: embedded `mockup-reviewer` FAIL (`changes_requested` while the completed/current agent is `mockup-reviewer`) → `awaiting_approval` / `/task-continue` only — do **not** `retryAfterFix` to 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/_shared/core/architecture/feature-delivery-workflow.md

@@ -8,7 +8,7 @@ Typical feature with data and UI. Concrete directories and rule stems — in the
 2. **Transport / DTO** — DTOs and mappers Domain ↔ transport (must not leak into UI).
 3. **Services / Data** — repository / API-service implementations via the stack’s public clients.
 4. **State** — store / ViewModel / use cases; no direct HTTP and no DTOs in UI.
-5. **UI** — thin views/components; data via state; design system.
+5. **UI** — thin views/components; data via state; design system. If the prompt or `brief.md` contains a `figma.com` URL, **mockup review must complete** (or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue`) **before UI work**. When required-signal and **no** `figma.com`, **`ux-design.md` must exist** (not `INCOMPLETE`) before UI work — else blocked, hand back to analyst. Non-UI tasks no-op these gates.
 6. **Tests** — unit for mappers / non-trivial logic; e2e/UI per stack convention.
 7. **Completion** — stack post-change gate (lint/build) + package/toolchain rules.
 

package/presets/_shared/core/meta/preset-no-cross-stack-leakage.md

@@ -59,7 +59,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`).
 
@@ -71,7 +72,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/_shared/core/review/mockup-review.md

@@ -0,0 +1,105 @@
+# 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 |
+```

package/presets/_shared/core/review/ux-design.md

@@ -0,0 +1,97 @@
+# 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
+```

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

@@ -27,7 +27,7 @@ When copying next pipeline templates: put Playwright / XCUITest / integration-te
 | feature-developer | yes (Kotlin/Android sources) |
 | build-verifier | no (report only) |
 | debugger, ci-investigator | minimal |
-| code-reviewer, accessibility-reviewer, security-reviewer, performance-auditor | team only |
+| code-reviewer, accessibility-reviewer, security-reviewer, performance-auditor, mockup-reviewer | team only |
 | qa-tester, unit-test-*, instrumentation-test-* | tests only |
 | tech-writer | docs only |
 
@@ -37,7 +37,7 @@ When copying next pipeline templates: put Playwright / XCUITest / integration-te
 |------|------------|----------------|
 | **cheap** | `fast` / cheap | build-verifier, some generators/healers |
 | **standard** | `inherit` | feature-developer, debugger, ci-investigator, a11y, qa, unit-*, instrumentation-* |
-| **strong** | `strong` | solution-architect, security-reviewer (when scheduled) |
+| **strong** | `strong` | solution-architect, security-reviewer, mockup-reviewer (when scheduled) |
 
 ## Pipeline schema
 

package/presets/claude/android-kotlin/agents/build-verifier.md

@@ -46,6 +46,12 @@ When validating **android-kotlin preset** changes (or `scope: preset-structure-v
 13. **AC-11 vendor neutrality:** no private consumer repo names, brand/product vendor strings, or org-specific type names in `presets/{cursor,claude}/android-kotlin/**`.
 14. Prefer `yarn check:preset-structure` (twin-map + token-budget + leakage + i18n).
 
+
+**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
 
 - Thin aliases (`agent-team-intake`, `technical-retro`) may be <15 body lines; domain rules ≥15.

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

package/presets/claude/android-kotlin/agents/mockup-reviewer.md

@@ -0,0 +1,59 @@
+---
+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.
+model: opus
+---
+
+You are a Figma mockup reviewer for an Android Kotlin / Jetpack Compose frontend.
+
+You write **only** `.claude/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. `.claude/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 `.claude/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 `.claude/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/claude/android-kotlin/agents/task-analyst.md

@@ -47,9 +47,26 @@ 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 `.claude/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.
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
-- **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/claude/android-kotlin/agents/task-router.md

@@ -23,6 +23,8 @@ You are a task router for an **Android Kotlin/Jetpack Compose** agent team. You
 | `migration` | “migration”, “upgrade”, “update Android Studio / AGP/Gradle modules” | task-analyst → migration-specialist → feature-developer → build-verifier → code-reviewer |
 | `perf-audit` | “performance”, “Profiler”, “Macrobenchmark”, “launch”, “slow” | performance-auditor |
 | `a11y` | “a11y”, “TalkBack”, “font scale”, “semantics”, “contentDescription”, “accessibility” | task-analyst → feature-developer → build-verifier → accessibility-reviewer → code-reviewer |
+| `mockup-review` | “mockup review”, “check Figma”, “figma review”, mockup + review verb, `figma.com` + review-not-implement | mockup-reviewer |
+| `ux-design` | «разработай UX» (design UX), «спроектируй» (design) flows, “journey”, “IA”, “state matrix”, «ревью UX» (UX review) without Figma | task-analyst | <!-- i18n-keep: E4 -->
 | `review-only` | “review”, “review MR”, “check the diff” | code-reviewer |
 | `test-only` | “cover with tests” (unit+UI, no impl) | task-analyst → qa-tester |
 | `unit-only` | “unit”, “JUnit”, “cover mapper” | unit-test-planner → unit-test-generator, or unit-test-healer |
@@ -33,10 +35,15 @@ You are a task router for an **Android Kotlin/Jetpack Compose** agent team. You
 | `retro` | “retro”, “postmortem” | (orchestrator → `/technical-retro`) |
 
 **Never schedule Playwright agents** (`playwright-test-*`). If a next template mentions them, put in `skipped` with reason "Android uses Android instrumentation" and use instrumentation-test trio.
+**Light by intent:** `mockup-review` → only `mockup-reviewer` (`model: "strong"`, never `cheap`). `ux-design` → only `task-analyst` (skill `ux-design`; analyst default model, not `strong`). Classify `mockup-review` **before** `ux-design` **before** `review-only`. A `figma.com` URL with review-not-implement language remains `mockup-review` even if the user said «ревью UX». <!-- i18n-keep: E4 -->
+**Embed UX:** on `feature` / `refactor` / `spike` / `spec-gen` with required-signal or advisory UI AC, instruct **task-analyst** to load skill `ux-design` (no new pipeline step).
+
+**Embed `figma.com`:** on `feature` / `refactor` / `spike` / `spec-gen`, insert `mockup-reviewer` after `task-analyst` (when present) and before `solution-architect` and `feature-developer`. Do **not** add static `humanGates: ["after:mockup-reviewer"]` (FAIL-only gate is a hook exception). Never put `mockup-reviewer` in a `parallel: true` step.
+
 
 ## Pipeline profiles
 
-`"profile": "full" | "standard" | "light"`. Default: **standard** for feature/refactor/bugfix; **light** for review-only/perf; **full** when cross-layer or UI-test AC.
+`"profile": "full" | "standard" | "light"`. Default: **standard** for feature/refactor/bugfix; **light** for review-only/perf/mockup-review/ux-design; **full** when cross-layer or UI-test AC.
 
 **Never skip `build-verifier`** after developer when Kotlin/Android Studio / AGP sources changed.
 
@@ -66,7 +73,7 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 Optional: `"model": "cheap" | "standard" | "strong"`. Same policy as **cursor/next** `task-router.md`:
 
 - `light` → `cheap` on all steps (debugger unclear root cause → `strong`)
-- `full` / `spike` / security|perf specialists → `strong` on architect, migration, security, perf steps
+- `full` / `spike` / security|perf|mockup specialists → `strong` on architect, migration, security, perf, and `mockup-reviewer` steps
 - never `strong` on build-verifier / tech-writer / task-router
 - omit on `standard` → agent frontmatter (`fast` / `inherit` / `claude-opus-4-8[effort=high]`)
 
@@ -81,6 +88,8 @@ Fixtures: `.claude/team/fixtures/` (feature-full, feature-light, bugfix-standard
 | unit-only | `["after:unit-test-planner"]` when new plan |
 | e2e-only | `["after:instrumentation-test-planner"]` when new plan |
 | bugfix, review-only, ci-fix | `[]` |
+| mockup-review | `[]` |
+| ux-design | `[]` |
 | spike | `["after:solution-architect"]` |
 
 ## Output

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

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

package/presets/claude/android-kotlin/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 Presentation/Jetpack Compose (or Android View system) diff for TalkBack/font scale/semantics/testTag; 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}". Audit launch/Jetpack Compose performance risks; 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.md. ` +
     `Upsert the owned terminal receipt in artifact-manifest.json; do not mutate status.json lifecycle fields.`,
@@ -593,6 +596,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] ? { attemptId: outcomes[retryReviewer].attemptId, confidence: outcomes[retryReviewer].confidence } : finishedAttempt;
@@ -610,6 +625,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/android-kotlin/rules/README.md

@@ -47,6 +47,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` |