@bonesofspring/ai-rules 0.2.16 → 0.2.18

package/presets/cursor/android-kotlin/rules/product-specs.mdc

@@ -0,0 +1,64 @@
+---
+description: Product page/feature specs under docs/specs — INDEX discovery for agents
+globs:
+  - docs/specs/**/*
+alwaysApply: false
+---
+
+<!-- shared-core: architecture/product-specs.md -->
+
+# Product specs (docs/specs)
+
+Product page/feature **behavior** specs live under the consumer repo `docs/specs/**`. This stem covers **discovery and presence** — not layer implementation order (see `feature-delivery-workflow`) and not code-structure mirroring (see `reference-features`).
+
+**Authoring** (Generate / Bootstrap modes, INDEX/frontmatter v1, body checklist, greenfield, conflict precedence) → load **`product-specs-authoring`** when generation is requested (`/spec-start`, brief AC, or router `spec-gen`).
+
+## Modes (summary)
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Consume** (default) | INDEX exists or globs hit `docs/specs/**` without generate intent | Discover via INDEX; soft-fail on miss; **never invent** INDEX/specs |
+| **Generate** | Explicit generate intent / AC / `/spec-start` with existing tree | Create/update page/feature specs + INDEX from stated sources |
+| **Bootstrap** | Explicit bootstrap / `/spec-start` when tree absent | Create INDEX + templates + first domain spec |
+
+Greenfield: agents may create INDEX/specs **only** on explicit intent, AC, or `/spec-start`. Missing INDEX alone does **not** authorize inventing the tree.
+
+## Presence policy
+
+- If `docs/specs/INDEX.md` is **missing** → the tree is **optional** (greenfield OK for *consume*). Continue with code/brief discovery; do not invent an INDEX solely because this stem loaded.
+- If INDEX **exists** → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+
+## Discovery algorithm
+
+1. Always start at `docs/specs/INDEX.md` when present.
+2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
+3. Read the linked page spec (and optional domain `feature.md` when the INDEX or page Related links it).
+
+## Miss policy (INDEX present, row or file missing)
+
+- Record the gap in `open_questions` / handoff gaps.
+- Fall back to code discovery and consumer `.ai/context/**` when present.
+- **Do not invent** product behavior, states, interactions, or contracts.
+- Hard-fail / block only when the task’s acceptance criteria explicitly require a named spec that is absent (human/gate decision).
+
+## Authoring pointer
+
+Same-changeset INDEX updates, frontmatter v1, required body headings, templates, and conflict precedence live in **`product-specs-authoring`**. Do not paste the full checklist here.
+
+## Non-goals
+
+- Not a replacement for `.ai/context/**` (external AI Code Review glossary) or `reference-features` (file-layout mirror).
+- Not Tessl / an external host as primary SoT.
+- No stack filesystem path recipes in this core body — path examples belong only in adapter **Stack notes**.
+
+## Related
+
+- `product-specs-authoring` — generation modes, contracts, self-check.
+- `reference-features` — code structure mirror (how to layout files), not product behavior.
+- Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.
+
+
+## Stack notes
+
+- `routes`: deep links / screen ids. `ui` / `store`: feature presentation / ViewModel (`features/**` or `features/<name>/impl/**/presentation/`) — **not** web `app/src/ui` or iOS `Features/**`. `e2e`: instrumentation test paths.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/cursor/android-kotlin/rules/ux-design.mdc

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

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

@@ -3,6 +3,8 @@
 | Skill | Purpose |
 |-------|---------|
 | `feature-delivery` | Domain → Data → VM → View → tests → post-change-build |
+| `mockup-review` | Figma mockup review: DS, coverage, viewports (standalone or embedded) |
+| `ux-design` | Behavioral UX synthesis/review via task-analyst (standalone or embedded; no Figma MCP) |
 | `code-review` | Android MR checklist |
 | `unit-testing` | JUnit 4/5 (repo default) |
 | `instrumentation-ui-e2e` | Android instrumentation plan/generate/heal (← next `playwright-e2e`) |

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

@@ -6,10 +6,11 @@ description: Delivers Android Kotlin/Jetpack Compose features end-to-end across
 # Feature Delivery (Android)
 
 1. Read task brief, acceptance criteria, and decomposition if present.
-2. Read `feature-delivery-workflow.mdc` and `reference-features.mdc` — Domain → Data → ViewModel → View → tests; mirror the closest Feature.
-3. Wire DI in `applications/` composition root; keep Views thin; keep DTOs out of ViewModels.
-4. Add or update focused JUnit for mappers / use cases / ViewModels (`tests-unit.mdc`).
-5. After Kotlin edits: **invoke** `post-change-build.mdc` (+ `gradle-tooling.mdc`). Pipeline: scoped build OK if next step is `build-verifier`.
+2. If `docs/specs/INDEX.md` exists **or** brief/handoff lists approved generated specs, resolve via **`product-specs`** and treat approved specs as behavior SoT before layer work (soft-fail on miss — do not invent behavior). If generation was requested but not yet approved, stop for human gate — do not implement against draft-only gaps.
+3. Read `feature-delivery-workflow.mdc` and `reference-features.mdc` — Domain → Data → ViewModel → View → tests; mirror the closest Feature.
+4. Wire DI in `applications/` composition root; keep Views thin; keep DTOs out of ViewModels.
+5. Add or update focused JUnit for mappers / use cases / ViewModels (`tests-unit.mdc`).
+6. After Kotlin edits: **invoke** `post-change-build.mdc` (+ `gradle-tooling.mdc`). Pipeline: scoped build OK if next step is `build-verifier`.
 
 ## Do / Don't
 
@@ -18,6 +19,9 @@ description: Delivers Android Kotlin/Jetpack Compose features end-to-end across
 - **Don't** invent alternate architecture or persistence stacks (e.g. MVI frameworks, Room vs SQLDelight) unless the repo already uses them.
 - **Don't** use yarn, browser e2e, or `app/src` paths — wrong stack.
 
+- If the prompt or brief contains a `figma.com` URL, load requestable skill `mockup-review` and do not start UI work until the mockup-reviewer step is completed or the user continued past FAIL/`BLOCKED_MCP`.
+- When required-signal (user asked UX, AC require flows/states, or spec-gen page/feature) and **no** `figma.com` URL: `ux-design.md` must exist on the analysis manifest entry (verdict not `INCOMPLETE`) before UI work. If missing, **blocked** — hand back to `task-analyst`. Parallel to the mockup gate when Figma exists.
+
 ## Scope discipline
 
 Implement only the current AC / decomposition task. Clarify ambiguity before coding; do not add unrelated hardening, polish, or drive-by refactors. See `feature-developer` → **Zero improvisation**.

package/presets/cursor/android-kotlin/skills/mockup-review/SKILL.md

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

package/presets/cursor/android-kotlin/skills/spec-authoring/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: spec-authoring
+description: Author or bootstrap consumer docs/specs (INDEX, page/feature templates, frontmatter v1). Use with task-analyst author mode, /spec-start, or when brief AC requests Generate/Bootstrap.
+---
+
+# Spec authoring
+
+Requestable — not always-on. Load **`product-specs`** + **`product-specs-authoring`** first.
+
+## Steps
+
+1. **Resolve mode** — Generate (tree exists) vs Bootstrap (create INDEX + templates + first spec). Refuse inventing INDEX without explicit intent/AC/`/spec-start`.
+2. **Ensure templates** — if consumer `docs/specs/_templates/` missing, copy from package SoT `presets/_shared/assets/docs-specs/_templates/` (or seeded init assets).
+3. **Fill frontmatter v1** — all array keys present (may be `[]`); prefer `type: feature` on backend/MCP; default `status: draft`.
+4. **Fill required body headings** — page: Overview, Entry/actors, Primary flows, States, Acceptance criteria; feature: Overview, Shared behavior/constraints, Related pages. Use `N/A` explicitly when needed.
+5. **Update INDEX** in the **same change set** (columns: id, type, domain, title, path, optional routes/aliases/status).
+6. **Self-check** against `product-specs-authoring` checklist; put blockers in `open_questions`.
+7. **Handoff** — list created/updated paths + INDEX diff for human gate (`after:task-analyst`). Approve before feature-developer.
+
+## Sources
+
+Cite AC / user / Figma / labeled code inference. Do not invent product behavior.
+
+## mcp-ts
+
+Analyst-only path (no tech-writer). `routes` = tool names; `ui`/`store` = `[]`.

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

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

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

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

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

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

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

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

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

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

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

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

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

package/presets/cursor/go/MCP.md

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

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

@@ -34,9 +34,18 @@ Document PASS/FAIL in `validation-report.md`.
 3. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel → **FAIL** (leakage). Prefer `check:preset-leakage`.
 4. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.
 
+
+**Forbidden mockup-reviewer:** agent file `agents/mockup-reviewer.md` or required `AGENT_HANDOFF` / pipeline handoff for `mockup-reviewer` → **FAIL** (no UI mockup reviewer).
+
+**Forbidden ux-designer / ux-design:** agent file `agents/ux-designer.md` or required `skills/ux-design` / `rules/ux-design` / pipeline handoff stem `ux-design` → **FAIL** (no UI UX surface).
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.
 - **Owned outputs:** `validation-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `validation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `validation_failed`. 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.
+
+13. **Product-specs assets (FAIL):** package must ship `presets/_shared/assets/docs-specs/INDEX.md`, `_templates/page.md`, `_templates/feature.md`. Cursor+Claude twins for `product-specs` and `product-specs-authoring` must embed matching shared-core markers; both stems **requestable** (`alwaysApply: false` / Claude `paths: docs/specs/**`) — never session-start.
+14. **Optional consumer check (WARN default):** `scripts/check-product-specs.sh` + schema stub may exist for opt-in consumer CI; **FAIL** only with `--strict` or AC that requires named specs — do not force consumer CI.

package/presets/cursor/go/agents/code-reviewer.md

@@ -18,6 +18,8 @@ Apply skill `code-review` and `code-review-mr.mdc`. Weigh `architecture-boundari
 
 ## Review focus (Go hexagonal)
 
+- If the MR touches `docs/specs/**`, load **`product-specs`** (+ **`product-specs-authoring`** when new/changed specs): **WARN** code/spec drift; **FAIL** broken INDEX `path` link or missing required frontmatter keys/arrays on touched spec files; required body headings missing → **FAIL** on touched files. Do not invent missing product behavior.
+
 - **Layers:** domain has no HTTP/SQL/framework imports; application defines ports and has no concrete adapters; handlers map DTO↔domain at the edge only.
 - **DI:** composition root in `cmd/` / `internal/app` — no business logic in wiring.
 - **Errors / context:** `%w` wrapping; `context.Context` on I/O boundaries; no swallowed errors.

package/presets/cursor/go/agents/feature-developer.md

@@ -46,6 +46,13 @@ Update `.cursor/team/tasks/<slug>/implementation.md` and the owned implementatio
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
 
+## 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.
+
+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).
+
+
 ## 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/go/agents/task-analyst.md

@@ -24,6 +24,25 @@ Emit an analysis receipt; the runtime applies any configured human gate.
 
 - Optional: Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit — only when decomposing refactor/architecture tasks (not default).
 
+## Product specs (docs/specs)
+
+**Consume (default):** When work touches a page/feature/route/alias and `docs/specs/INDEX.md` exists, load **`product-specs`**, resolve the linked page/feature spec, and cite it under **Related specs** in `brief.md`. Soft-fail on miss (`open_questions` + code / `.ai/context` fallback); **never invent** product behavior. If INDEX is absent, treat specs as optional unless author mode applies.
+
+**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.
+
+### Brief sections (when author mode or INDEX exists)
+
+Add to `brief.md`:
+
+```markdown
+## Related specs
+- path or id (or N/A)
+
+## Spec gaps / generation requested
+- [ ] none | generate | bootstrap — sources: …
+```
+
+
 ## 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.

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

@@ -31,7 +31,7 @@ You are a task router for a **Go hexagonal backend** agent team. You **do not**
 | `spike` | «исследуй» (explore), "spike", proof of concept | task-analyst → solution-architect | <!-- i18n-keep: E4 -->
 | `retro` | «ретро» (retro), "postmortem" | (orchestrator → `/technical-retro`) | <!-- i18n-keep: E4 -->
 
-**Never schedule** Playwright (`playwright-test-*`), XCUITest (`xcuitest-test-*`), or `accessibility-reviewer`. Put them in `skipped` with reason "Go backend uses integration-test trio".
+**Never schedule** Playwright (`playwright-test-*`), XCUITest (`xcuitest-test-*`), or `accessibility-reviewer` / `mockup-reviewer`. Put them in `skipped` with reason "Go backend uses integration-test trio".
 
 ## Pipeline profiles
 
@@ -89,6 +89,17 @@ Write `.cursor/team/tasks/<slug>/pipeline.json` and initialize the routing entry
 
 Intent + steps table + skipped + gates → invoke `steps[0].agent` (unless retro).
 
+## Spec generation intents
+
+Detect and set routing reasons when the user asks to **generate / bootstrap product specs**, mentions `docs/specs`, or runs `/spec-start`:
+
+| Signal | Intent | Steps |
+|--------|--------|-------|
+| `/spec-start`, "bootstrap docs/specs", "generate product spec" | `spec-gen` | task-analyst (**author mode**) → human gate → stop (or continue to feature-developer only if implement-after) |
+| Feature/task with AC "generate specs" / missing INDEX + bootstrap AC | `spec-gen` inside feature profile | task-analyst author mode first; **not** a separate agent step |
+
+Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
+
 ## 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/go/agents/tech-writer.md

@@ -13,3 +13,8 @@ Write documentation from task artifacts (brief, architecture, implementation, re
 - For ai-rules preset tasks: update PRESET-CONTRIBUTION / package README as scoped — docs only.
 
 Do not change production `.go` business logic.
+
+## Product specs (docs/specs)
+
+Post-delivery: when behavior or public docs changed and `docs/specs/` is in play, load **`product-specs`** (+ **`product-specs-authoring`** if updating specs). Sync page/feature specs + INDEX in the **same change set**. **Never invent** product behavior without AC/code source; label inferred lines `status: draft`. Soft-fail on miss; no-op if INDEX absent and sync not requested.
+

package/presets/cursor/go/commands/feature-continue.md

@@ -17,3 +17,7 @@ Continue after a human gate. Full logic lives in **`task-continue.md`**.
 4. The hook continues the chain when `autoChain: true`.
 
 See `task-continue.md` for details and the handoff table.
+
+## Product specs (docs/specs)
+
+When the next agent is **feature-developer** (or other implementer): if `docs/specs/INDEX.md` exists, instruct them to load **`product-specs`** and honor **Related specs** from `brief.md` (behavior SoT). Soft-fail on miss; never invent product behavior. No-op if INDEX is absent.

package/presets/cursor/go/commands/feature-start.md

@@ -19,11 +19,19 @@ Starts the **analysis phase** without the router. The parent agent acts as orche
 6. Invoke subagent **task-analyst** (Task tool) with the full task description and artifact paths.
 7. Wait for the analyst to finish. **Do not invoke developer** at this stage.
 
+## Product specs (docs/specs)
+
+When invoking **task-analyst**: if `docs/specs/INDEX.md` exists, instruct consume via **`product-specs`** and cite **Related specs**. Soft-fail on miss; never invent behavior.
+
+If the user/AC requests generation or bootstrap, or INDEX is missing **with** bootstrap AC / `/spec-start` intent: instruct **author mode** inside the same analyst step — load **`product-specs-authoring`** + skill **`spec-authoring`**. Authoring is **not** a separate pipeline agent. Handoff must list created paths + INDEX diff; human gate must approve generated specs before feature-developer.
+
+
 ## Human gate
 
 After the analyst:
 
 - Show the user links to `brief.md` and `decomposition.md`.
+- Also ask them to check **Related specs** in `brief.md` when `docs/specs/INDEX.md` exists.
 - Ask them to review and approve or send edits.
 - To continue: `/task-continue <slug>` or `/feature-continue <slug>`.
 

package/presets/cursor/go/commands/spec-start.md

@@ -0,0 +1,29 @@
+---
+name: spec-start
+description: Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate.
+---
+
+# Spec start — generate / bootstrap product specs
+
+Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mode** → human gate (`after:task-analyst`) → stop, or continue to feature-developer if the user asked to implement after.
+
+## What to do
+
+1. Extract description from arguments after `/spec-start` (domain, page/feature ids, sources).
+2. Generate a **slug** (kebab-case, ≤48 chars), e.g. `spec-<domain>-<id>`.
+3. Ensure `.cursor/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
+4. Write `.cursor/team/active-task.json` → `{ "slug": "<slug>" }`.
+5. Write minimal `pipeline.json`: task-analyst → (optional stop) → feature-developer only if user asked implement-after. **No separate spec-author agent.**
+6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate.
+7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.
+
+## Human gate
+
+- Show created/updated spec paths and INDEX diff.
+- Ask user to approve drafts (`status: draft` → promote) or send edits.
+- Continue: `/task-continue <slug>` only after approval when implementation follows; otherwise stop after docs.
+
+## Notes
+
+- Greenfield invent of INDEX is allowed **only** via this command, explicit ask, or AC bootstrap language.
+- mcp-ts: analyst-only author/sync (no tech-writer).

package/presets/cursor/go/commands/task-continue.md

@@ -40,11 +40,14 @@ printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":tr
 
 | Agent | Read |
 |-------|------|
-| feature-developer | brief.md, decomposition.md, validation-report.md (if retry), review.md (if retry), architecture.md |
+| 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`** |
 | build-verifier | git diff, decomposition.md |
 | code-reviewer | brief.md, validation-report.md, git diff |
 | qa-tester | brief.md, decomposition.md, scope from pipeline step |
 
-## Metrics
+## Product specs (docs/specs)
+
+When the next agent is **feature-developer** (or other implementer): if `docs/specs/INDEX.md` exists or brief lists approved specs, instruct them to load **`product-specs`** and honor **Related specs** / approved generated specs as behavior SoT. Soft-fail on miss; never invent product behavior.
+
+If analyst ran **author mode**, confirm human approved drafts before developer. Pass spec paths + INDEX diff in the handoff. No-op if INDEX is absent and no approved specs.
 
-On human-gate resume, the hook action above appends `human_gate_ended` under the per-task lock **before** any new `attempt_started`. Agents must not calculate durations.