@bonesofspring/ai-rules 0.2.17 → 0.2.19

package/presets/claude/svelte/skills/spec-discovery/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: spec-discovery
+description: Opt-in research-before-spec for task-analyst author mode. 11 named methods plus a mandatory claim ledger. Use when the user or AC asks discovery before generating docs/specs — not default /task consume.
+---
+
+# Spec discovery
+
+Requestable — **not** always-on. Load **only** in **task-analyst author mode** when the user or AC asks research-before-spec (including `/spec-start` with that intent). Never default consume `/task`. Not a pipeline step.
+
+Load **`product-specs`** (and **`product-specs-authoring`** after this skill if authoring follows). Do **not** invent product behavior. Do **not** create a second spec-file tree.
+
+## Load policy
+
+1. Pick a **subset** of methods that fit the task — not all 11 every time.
+2. **`claim-ledger` is mandatory** whenever this skill runs.
+3. Write chronological notes to `.claude/team/tasks/<slug>/.memlog.md` (append-only). Do **not** mutate `status.json` / `metrics.json`.
+4. Discovery output lives in memlog + `brief.md` sections. Then hand off to skill **`spec-authoring`** (or stop if `specMode: none`).
+
+Backend / MCP stacks: skip UI-only examples; prefer `analog-scan`, `code-archaeology`, `problem-define`, `assumption-audit`, `claim-ledger`.
+
+## Methods
+
+| Method | Produces | Skip when |
+|--------|----------|-----------|
+| **intake-capture** | Raw idea, origin, first unknowns → memlog + brief Research inputs | User prompt + AC already complete |
+| **index-locator** | Related INDEX rows + linked spec paths + gaps | `specMode: none` or INDEX absent without consume intent |
+| **code-archaeology** | Observed behavior labeled `inferred`/`draft` with path citations | Greenfield with no relevant code |
+| **research-pack-scan** | Claims from `team/tasks/<slug>/research/**` or user-supplied paths | No research paths cited |
+| **evidence-against** | Reasons the idea may fail | Internal spike with no product/external risk |
+| **problem-define** | Who hurts, goals, non-goals, cost of inaction → brief | Brief Goal + Out of scope already exhaustive |
+| **concept-shape** | 2–3 approach options + appetite (small/medium/large); no API design | `architecture.md` exists or one obvious path |
+| **working-backwards-check** | Headline + 5 customer objections + verdict `forged` / `needs-heat` / `cracked` | Consume mode with approved specs |
+| **assumption-audit** | Assumption register → brief Assumptions + `open_questions` | Never skip in author mode (keep lightweight) |
+| **analog-scan** | 2–3 repo analogs via `reference-features` / code search | No plausible analog |
+| **claim-ledger** | Markdown table `source → claim` for every product-behavior claim | **Never skip** when this skill is loaded |
+
+## Claim ledger (required)
+
+Block spec authoring until every product-behavior claim has a source:
+
+```markdown
+| Source | Claim |
+|--------|-------|
+| brief AC-3 | Checkout shows empty cart copy |
+| code-archaeology inferred | Empty state uses an illustration |
+```
+
+Sources: AC / user / UI copy / labeled code inference / research path. Unsourced claims → `open_questions`.
+
+## Memlog
+
+Path: `.claude/team/tasks/<slug>/.memlog.md`. Chronological `## YYYY-MM-DD` headings. Optional tags: `decision`, `assumption`, `override`, `event`, `claim`.
+
+## Forbidden
+
+- 108-technique catalogs, HTML composers, party-mode, five `assess.*` slash commands, Python memlog runtime.
+- Dummy INDEX rows when `specMode: none`.
+- Dumping the whole `docs/specs/**` tree — locator is INDEX → linked page + optional `feature.md`.

package/presets/claude/svelte/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/svelte/team/README.md

@@ -27,6 +27,7 @@ Artifact directory for the Claude Code “agent team” pipeline.
       unit-test-plan.md
       documentation.md
       review.md
+      .memlog.md             # append-only agent notes (optional)
 ```
 
 ## pipeline.json schema
@@ -35,6 +36,7 @@ Artifact directory for the Claude Code “agent team” pipeline.
 {
   "slug": "order-history-date-filter",
   "intent": "feature",
+  "specMode": "consume",
   "summary": "Add date filter to Order History",
   "steps": [
     { "agent": "task-analyst", "label": "Clarify and decompose" },
@@ -59,6 +61,8 @@ Artifact directory for the Claude Code “agent team” pipeline.
 | `skipIf` | `debugger.fixed` \| `ci-investigator.resolved` |
 | `parallel` | Invoke all `agent` values in one parent turn |
 
+Optional top-level **`specMode`:** `consume` | `generate` | `none` (router echo; `brief.md` `## Spec mode` wins).
+
 ## status.json (pipeline mode)
 
 ```json
@@ -112,6 +116,13 @@ Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook ow
 
 Commit task artifacts if you want them to survive `ai-rules clean cursor`. Or copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
 
+
+## specMode, applyReadiness, memlog
+
+- **`specMode`:** `consume` | `generate` | `none` — primary in `brief.md` `## Spec mode`; optional top-level `pipeline.json` `specMode`. `none` skips INDEX/author mode (spike/research).
+- **`applyReadiness`:** YAML frontmatter on developer `implementation.md`; JSON-shaped `{ "state": "blocked"|"ready"|"all_done", "contextFiles": [] }` on the analyst receipt (analyst may emit `blocked` pre-gate). See `agent-artifact-contracts`.
+- **Memlog:** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/team/tasks/<slug>/.memlog.md`) — append-only, agent-written; `/task-continue` may read. Hook does not parse it. Example: `fixtures/memlog.example.md`.
+
 ## Artifact manifest and receipts
 
 Each slug stores one context index at `.claude/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.

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

@@ -25,7 +25,7 @@
       "id": "analysis",
       "producer": "task-analyst",
       "status": "completed",
-      "authoritativePaths": ["brief.md", "decomposition.md"],
+      "authoritativePaths": ["brief.md", "decomposition.md", "ux-design.md"],
       "acceptanceCriteriaIds": ["AC-1", "AC-2"],
       "taskIds": ["T1", "T2"],
       "timestamps": {
@@ -36,7 +36,7 @@
       "receipt": {
         "outcome": "completed",
         "summary": "The acceptance criteria and implementation tasks are ready.",
-        "evidencePaths": ["brief.md", "decomposition.md"]
+        "evidencePaths": ["brief.md", "decomposition.md", "ux-design.md"]
       }
     },
     {
@@ -56,6 +56,24 @@
         "summary": "Implementation and focused unit coverage are complete.",
         "evidencePaths": ["implementation.md"]
       }
+    },
+    {
+      "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/svelte/team/fixtures/feature-full.json

@@ -1,10 +1,15 @@
 {
   "slug": "example-feature-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "routingDecision": {
     "complexity": "high",
-    "riskFlags": ["cross-layer", "public-contract", "broad-test-surface"],
+    "riskFlags": [
+      "cross-layer",
+      "public-contract",
+      "broad-test-surface"
+    ],
     "routingReasons": [
       "The feature spans UI, state, and API boundaries, so architecture and implementation checkpoints are required.",
       "The public contract and e2e acceptance surface require independent validation and review."
@@ -14,15 +19,44 @@
   },
   "summary": "Multi-layer feature with e2e 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": "Validation gate", "model": "cheap" },
-    { "agent": "security-reviewer", "label": "Security review", "model": "strong" },
-    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" },
-    { "agent": "qa-tester", "label": "E2E", "scope": "e2e-only" }
+    {
+      "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": "Validation gate",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "E2E",
+      "scope": "e2e-only"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
   ],
-  "humanGates": ["after:task-analyst"],
   "autoChain": true,
   "skipped": []
 }

package/presets/claude/svelte/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/svelte/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/svelte/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 CartEmpty.tsx (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/claude/svelte/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/svelte/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/svelte/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/cursor/android-kotlin/MCP.md

@@ -13,4 +13,23 @@ Playwright / Chrome DevTools are **not** part of the **android-kotlin preset** (
 
 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/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/cursor/android-kotlin/agents/accessibility-reviewer.md

@@ -48,6 +48,12 @@ PASS | PASS_WITH_NOTES | FAIL
 |-----------|--------|-------|
 ```
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation or UI diff scope, and prior review artifacts when present.

package/presets/cursor/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/cursor/android-kotlin/agents/ci-investigator.md

@@ -60,6 +60,14 @@ Commands run and results.
 
 Write the owned terminal receipt described under **Artifact contract**.
 
+
+## 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.
+
+
 ## 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`, and other authoritative prior artifacts for this step.

package/presets/cursor/android-kotlin/agents/debugger.md

@@ -57,6 +57,14 @@ fixApplied: false
 
 Write the owned terminal receipt described under **Artifact contract**.
 
+
+## 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.
+
+
 ## 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`, and other authoritative prior artifacts for this step.

package/presets/cursor/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.
@@ -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/android-kotlin/agents/migration-specialist.md

@@ -60,6 +60,12 @@ Temporary adapters, feature flags, dual code paths if needed.
 
 Write the owned terminal receipt described under **Artifact contract**.
 
+
+## 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`, and other authoritative prior artifacts for this step.

package/presets/cursor/android-kotlin/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 Android Kotlin / Jetpack Compose 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/android-kotlin/agents/performance-auditor.md

@@ -51,6 +51,12 @@ Profiler / Macrobenchmark notes, launch timings, or measured scroll hitch hints.
 Ordered list for feature-developer if fixes are requested.
 ```
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief when present and the scoped git diff / screens under audit.

package/presets/cursor/android-kotlin/agents/solution-architect.md

@@ -16,6 +16,12 @@ You are a solution architect for **Android Feature modules** (Presentation / Dom
 
 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.