@bonesofspring/ai-rules 0.2.17 → 0.2.19

package/presets/cursor/go/team/fixtures/feature-full.json

@@ -1,20 +1,56 @@
 {
   "slug": "example-feature-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "summary": "Multi-layer Go use case with integration-test coverage",
   "steps": [
-    { "agent": "task-analyst", "label": "Clarify and decompose" },
-    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
-    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
-    { "agent": "build-verifier", "label": "go test / go vet / golangci-lint", "model": "cheap" },
-    { "agent": "security-reviewer", "label": "Security review", "model": "strong" },
-    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" },
-    { "agent": "qa-tester", "label": "Integration tests", "scope": "e2e-only" },
-    { "agent": "integration-test-planner", "label": "Plan integration coverage" },
-    { "agent": "integration-test-generator", "label": "Generate integration tests" }
+    {
+      "agent": "task-analyst",
+      "label": "Clarify and decompose"
+    },
+    {
+      "agent": "solution-architect",
+      "label": "Design boundaries",
+      "model": "strong"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Implement + unit tests",
+      "scope": "unit-in-dev"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "go test / go vet / golangci-lint",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "Integration tests",
+      "scope": "e2e-only"
+    },
+    {
+      "agent": "integration-test-planner",
+      "label": "Plan integration coverage"
+    },
+    {
+      "agent": "integration-test-generator",
+      "label": "Generate integration tests"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
   ],
-  "humanGates": ["after:task-analyst"],
   "autoChain": true,
   "skipped": [
     {

package/presets/cursor/go/team/fixtures/memlog.example.md

@@ -0,0 +1,9 @@
+# Memlog example
+
+Append-only. Agents write; `/task-continue` may read. The hook does not parse this file.
+
+## 2026-08-13
+
+- `decision`: specMode=generate; research-before-spec requested
+- `claim`: empty-cart copy lives in the empty-state handler (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/cursor/ios-swift/MCP.md

@@ -13,4 +13,23 @@ Playwright / Chrome DevTools are **not** part of the ios preset (browser e2e is
 
 Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token).
 
-After init: Settings → MCP → enable servers. `init` overwrites a same-named `mcp.json`.
+
+## Agent usage
+
+Load requestable rule `mcp-usage`. The **session MCP catalog** is source of truth (this file and `mcp.json` are hints). Discover tool schemas before calling; never invent them.
+
+**Context7 (shipped):** query docs when a third-party API is not confirmed by lockfile + sibling files. Use the installed major. Cap ≤3 doc queries per question. If Context7 is down, mark `// VERIFY` and continue — do not block.
+
+## Local overlay (not shipped)
+
+`init` **merges** `mcpServers`: preset keys are updated; extra local servers are kept. User-level MCP is never touched. Prefer user-level MCP if you do not want overlay servers in the project file.
+
+Use an overlay only when it is **ready** (`serverStatus` not `error` / `needsAuth` / `loading`) **and** the task fits. Absence is not a blocker unless the user required that MCP as source of truth.
+
+| Kind | Typical aliases | When |
+|------|-----------------|------|
+| Observability | `sentry`, `datadog`, `plugin-datadog-*` | production error, event/trace id, APM |
+| Tickets | `linear`, `jira`, `notion`, `plugin-notion-*` | ticket/page URL; read-only; task-folder artifacts remain SoT |
+| GitHub MCP | `github` | optional; native `gh` remains SoT for PRs and checks |
+
+Do **not** require Storybook, Playwright, or Chrome DevTools MCP as delivery gates on this preset.

package/presets/cursor/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/cursor/ios-swift/agents/accessibility-reviewer.md

@@ -24,6 +24,12 @@ You are an accessibility reviewer for an **iOS SwiftUI / UIKit** frontend.
 - Focus / rotor order for custom controls; hit targets roughly ≥44pt when obvious from layout.
 - Sheet/modal dismissal discoverability for VoiceOver users.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Output
 
 Write `.cursor/team/tasks/<slug>/a11y-review.md`:
@@ -50,17 +56,8 @@ PASS | PASS_WITH_NOTES | FAIL
 
 ## On completion
 
-Update `status.json`:
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "accessibility-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
 
 If **FAIL**, set `"state": "changes_requested"` and list specific fixes for `feature-developer`.
 

package/presets/cursor/ios-swift/agents/api-contract-reviewer.md

@@ -55,17 +55,8 @@ For feature-developer before or during implementation.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "api-contract-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 If **MISALIGNED**, set `"state": "changes_requested"` when blocking implementation.
 

package/presets/cursor/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 (navigation, persistence, security, modules, networking, UI).

package/presets/cursor/ios-swift/agents/ci-investigator.md

@@ -58,20 +58,19 @@ Commands run and results.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "ci-investigator",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Provide summary: failed check, root cause, files changed, validation commands run, `resolved`.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.

package/presets/cursor/ios-swift/agents/debugger.md

@@ -55,22 +55,21 @@ fixApplied: false
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "debugger",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Handoff summary: root cause, recommended fix, files touched (if any), `fixApplied`.
 
 Do not perform formal code review or write XCUITest plans — those are separate agents.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/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.
@@ -62,6 +68,29 @@ When work touches a page/feature/route/alias: if `docs/specs/INDEX.md` exists (o
 Mechanical INDEX/frontmatter fixes only when implementation renames routes/ids. Substantive behavior edits → hand back to task-analyst (or tech-writer where present). If INDEX is absent and generation was not approved, treat specs as optional (greenfield).
 
 
+**specMode `none`:** do not require INDEX; implement from brief/AC only.
+
+**applyReadiness:** YAML frontmatter on `implementation.md`:
+
+```yaml
+applyReadiness:
+  state: ready   # blocked | ready | all_done
+  contextFiles: []
+```
+
+`blocked` if human gate pending, required spec missing, required UX `INCOMPLETE`, or incomplete WP deps. `ready` when the current WP may be implemented. `all_done` on the final receipt when mechanical spec sync is done.
+
+**Code Map + Suggested Review Order:** when this WP spans **>1 layer or module**, add to `implementation.md` a Code Map (3–8 annotated paths) and Suggested Review Order lines `concern | path:line | ≤15 words`. Omit for single-file / single-layer WPs.
+
+**Memlog:** append implementation decisions to `.cursor/team/tasks/<slug>/.memlog.md` (append-only).
+
+
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.

package/presets/cursor/ios-swift/agents/migration-specialist.md

@@ -58,20 +58,17 @@ Temporary adapters, feature flags, dual code paths if needed.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "migration-specialist",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Hand off: orchestrator runs human gate (if configured), then `feature-developer` executes phases from the plan.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/ios-swift/agents/mockup-reviewer.md

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

package/presets/cursor/ios-swift/agents/performance-auditor.md

@@ -55,22 +55,19 @@ Ordered list for feature-developer if fixes are requested.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "performance-auditor",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 For standalone `perf-audit` intent, suggest `/technical-retro` or a follow-up `/task` to implement fixes.
 
 Do not modify production code.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/ios-swift/agents/qa-tester.md

@@ -45,17 +45,8 @@ When the task is mostly UI e2e, prefer `xcuitest-test-planner`, `xcuitest-test-g
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "qa-tester",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Provide summary:
 

package/presets/cursor/ios-swift/agents/security-reviewer.md

@@ -52,17 +52,8 @@ PASS | PASS_WITH_NOTES | FAIL
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "security-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 If **FAIL**, set `"state": "changes_requested"`.
 

package/presets/cursor/ios-swift/agents/solution-architect.md

@@ -16,6 +16,12 @@ You are a solution architect for **iOS Feature modules** (Presentation / Domain
 
 Handoff: architecture approved or awaiting gate → status update.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/ios-swift/agents/task-analyst.md

@@ -34,6 +34,15 @@ Do not invent architecture stacks (TCA, SwiftData, …) — frame “as in the r
 
 **Author mode (Generate / Bootstrap):** When the user runs `/spec-start`, router intent is `spec-gen` / bootstrap, or brief/AC requests generation: load **`product-specs`** + **`product-specs-authoring`** and skill **`spec-authoring`**. You are the **primary author** (INDEX bootstrap included). Follow frontmatter v1 + required headings; update INDEX in the **same change set**; default `status: draft`. Block handoff via `open_questions` until the authoring self-check passes.
 
+
+**Spec mode:** Write `## Spec mode` in `brief.md` with exactly one of `consume` | `generate` | `none`. Infer if unset: spike/research/preset-only → `none`; `/spec-start` or router `spec-gen` → `generate`; otherwise `consume`. Router may echo `specMode` on `pipeline.json`.
+
+**`none`:** skip INDEX row requirement and author mode; do not invent a dummy INDEX.
+
+**Research-before-spec (opt-in):** load skill **`spec-discovery`** only when the user/AC asks research before authoring (not default consume `/task`). Run a **subset** of methods; **`claim-ledger` is mandatory** whenever the skill loads. Append chronological notes to `.cursor/team/tasks/<slug>/.memlog.md` (append-only; do not mutate `status.json`).
+
+**applyReadiness (author blocked):** if specs are drafted but the human gate has not passed, or a required named spec is missing, emit `applyReadiness: { "state": "blocked", "contextFiles": ["…"] }` on the analysis receipt. Do not invoke feature-developer.
+
 ### Brief sections (when author mode or INDEX exists)
 
 Add to `brief.md`:
@@ -47,9 +56,34 @@ Add to `brief.md`:
 ```
 
 
+## UX design (behavioral)
+
+Load requestable skill **`ux-design`** and rule **`ux-design`** when:
+- standalone router intent `ux-design`, or
+- **required-signal:** the user asked for UX, **or** AC explicitly require flows/states, **or** `spec-gen` / `/spec-start` for a **page/feature**, or
+- advisory UI AC on this UI stack (notes only; skip if no UI surface).
+
+**Order:** write `ux-design.md` **before** author mode / skill `spec-authoring` when both apply. You remain the only INDEX writer.
+
+Write `.cursor/team/tasks/<slug>/ux-design.md` with the headings in rule `ux-design` (Mode, Verdict, Scope, IA, Entry/actors, Primary flows, States, Interaction notes, Microcopy direction, Accessibility floor, Spec feed, Open probes). Modes: `synthesize` | `review`.
+
+**Required vs advisory:** required-signal + missing named primary flows **or** empty/error/loading matrix → DoR not met (`open_questions` / blocked analysis). Isolated missing microcopy never blocks. Advisory `INCOMPLETE` → notes only. Do **not** copy the mockup FAIL-only hook.
+
+**Forbidden:** Figma MCP tools (`get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`). When Figma is present and required-signal fires, emit a **thin** `ux-design.md` from AC only (no visual claims). Only `mockup-reviewer` reads Figma.
+
+When produced, append `ux-design.md` to this step's **`analysis`** `authoritativePaths` / `evidencePaths`. No new manifest producer row.
+
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If the prompt/brief has a tracker URL (Linear/Jira/Notion/…) and that MCP is ready, pull AC **read-only**. Task-folder artifacts remain SoT.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
-- **Owned outputs:** `brief.md` and `decomposition.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
+- **Owned outputs:** `brief.md` and `decomposition.md` (plus `ux-design.md` when produced); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/ios-swift/agents/task-router.md

@@ -23,6 +23,8 @@ You are a task router for an **iOS Swift/SwiftUI** agent team. You **do not** im
 | `migration` | “migration”, “upgrade”, “update Xcode/SPM/iOS” | task-analyst → migration-specialist → feature-developer → build-verifier → code-reviewer |
 | `perf-audit` | “performance”, “Instruments”, “launch”, “slow” | performance-auditor |
 | `a11y` | “a11y”, “VoiceOver”, “Dynamic Type”, “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”, “XCTest”, “cover mapper” | unit-test-planner → unit-test-generator, or unit-test-healer |
@@ -33,10 +35,15 @@ You are a task router for an **iOS Swift/SwiftUI** agent team. You **do not** im
 | `retro` | “retro”, “postmortem” | (orchestrator → `/technical-retro`) |
 
 **Never schedule Playwright agents** (`playwright-test-*`). If a next template mentions them, put in `skipped` with reason "iOS uses XCUITest" and use xcuitest 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 Swift/Xcode 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]`)
 
@@ -77,10 +84,13 @@ Fixtures: `.cursor/team/fixtures/` (feature-full, feature-light, bugfix-standard
 | Intent | Default humanGates |
 |--------|-------------------|
 | feature, refactor, test-only, a11y | `["after:task-analyst"]` |
+| spec-gen | `["after:task-analyst"]` |
 | migration | `["after:migration-specialist"]` |
 | unit-only | `["after:unit-test-planner"]` when new plan |
 | e2e-only | `["after:xcuitest-test-planner"]` when new plan |
 | bugfix, review-only, ci-fix | `[]` |
+| mockup-review | `[]` |
+| ux-design | `[]` |
 | spike | `["after:solution-architect"]` |
 
 ## Output
@@ -102,6 +112,11 @@ Detect and set routing reasons when the user asks to **generate / bootstrap prod
 
 Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
 
+
+**specMode (optional `pipeline.json` field):** `none` for spike/research; `generate` for `spec-gen` / `/spec-start`; `consume` default when INDEX exists. Echo top-level `specMode`. Brief `## Spec mode` wins on conflict.
+
+Do **not** add a pipeline step for `spec-discovery`. Instruct analyst to load that skill only when the user/AC asks research-before-spec.
+
 ## Runtime initialization
 
 Return the routing receipt to the orchestrator. The orchestration runtime/hook exclusively initializes and updates `status.json`, `metrics.json`, attempt identities, and gate lifecycle; the router does not write those shared runtime files.

package/presets/cursor/ios-swift/agents/unit-test-generator.md

@@ -41,17 +41,8 @@ You generate unit tests from project test plans for **iOS Swift**.
 
 Run affected unit tests via `xcodebuild test` (`xcode-tooling.mdc`) when feasible. Report commands, pass/fail, and gaps.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-generator",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 ## Design guidance
 

package/presets/cursor/ios-swift/agents/unit-test-healer.md

@@ -40,17 +40,8 @@ Short root-cause note in the handoff (and optionally `.cursor/team/tasks/<slug>/
 
 Report root cause, files changed, validation result, and remaining risk.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-healer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 ## Design guidance