@bonesofspring/ai-rules 0.2.16 → 0.2.18

package/presets/claude/mcp-ts/rules/architecture/product-specs-authoring.md

@@ -0,0 +1,121 @@
+---
+paths:
+  - docs/specs/**/*
+---
+
+<!-- shared-core: architecture/product-specs-authoring.md -->
+
+# Product specs authoring
+
+Load when **Generate** or **Bootstrap** is requested (`/spec-start`, router `spec-gen`, brief AC, or analyst author mode). Discovery-only work stays on **`product-specs`**.
+
+## Modes
+
+1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
+2. **Generate** — create/update page/feature specs + INDEX rows from brief AC, user intent, Figma, or code archaeology. Inventing *product* behavior is forbidden without a stated source (AC / user / UI copy / code-observed behavior labeled `status: draft` or `inferred`).
+3. **Bootstrap** — create `INDEX.md` + `_templates/` copies + first domain spec under greenfield policy.
+
+## Greenfield policy
+
+Agents **may** create INDEX + first specs **only when** one of:
+
+1. User runs `/spec-start` or explicitly asks to bootstrap `docs/specs`.
+2. Brief/AC includes generation or bootstrap language.
+3. Router detects `spec-gen` intent.
+
+Otherwise: missing INDEX → optional tree; do **not** invent INDEX merely because discovery loaded.
+
+## Conflict precedence
+
+1. **Human gate** decision (approved brief/spec edits).
+2. **Current task `brief.md` AC** — if AC contradicts an existing spec, analyst must reconcile (update spec as `draft` or revise AC) before developer; no silent contradiction.
+3. **Approved `docs/specs/**`** — behavior SoT for feature-developer once gate passed.
+4. **Code / `.ai/context`** — discovery evidence only; never override approved spec without gate.
+
+Label inferred-from-code lines with `status: draft` until human promotes.
+
+## INDEX.md contract (v1)
+
+| Column | Required | Notes |
+|--------|----------|-------|
+| `id` | yes | Stable kebab/id matching frontmatter `id` |
+| `type` | yes | `page` \| `feature` |
+| `domain` | yes | Domain folder under `docs/specs/domains/<domain>/` |
+| `title` | yes | Human label |
+| `path` | yes | Repo-relative path to markdown file |
+| `routes` | no | Summary; may duplicate frontmatter |
+| `aliases` | no | Comma-separated PageName / deep-link aliases |
+| `status` | no | `draft` \| `active` \| `deprecated` |
+
+Layout: `docs/specs/domains/<domain>/<id>.md` (page) and optional `docs/specs/domains/<domain>/feature.md`. Adding/renaming/removing a linked file **must** update INDEX in the **same change set**.
+
+## Frontmatter v1
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string | yes | Unique; matches INDEX |
+| `type` | enum `page` \| `feature` | yes | Backend/MCP: prefer `feature` |
+| `domain` | string | yes | |
+| `routes` | string[] | yes (may be `[]`) | Web: URL paths; mobile: deep links/screens; backend: HTTP paths; mcp-ts: tool names |
+| `ui` | string[] | yes (may be `[]`) | Component/screen refs; empty on backend/mcp |
+| `store` | string[] | yes (may be `[]`) | Slice/module refs; empty when N/A |
+| `api` | string[] | yes (may be `[]`) | Services/ports/tools |
+| `aliases` | string[] | yes (may be `[]`) | |
+| `e2e` | string[] | yes (may be `[]`) | Stack-appropriate test paths |
+| `status` | enum | no | default `draft` on agent generate |
+| `owners` | string[] | no | |
+| `related` | string[] | no | Spec ids or paths |
+
+Arrays are **always present** (empty allowed). Do not omit keys for N/A stacks.
+
+## Body headings (minimum)
+
+**`page` required:** Overview; Entry / actors; Primary flows; States (loading / empty / error / success as applicable — mark N/A explicitly); Acceptance criteria (links or bullets to brief AC / product source).
+
+**`page` optional:** Analytics, Accessibility, Edge cases, Related specs.
+
+**`feature` required:** Overview; Shared behavior / constraints; Related pages (links).
+
+**`feature` optional:** Cross-cutting states, Analytics.
+
+Compliant = valid frontmatter + all required headings present (non-empty prose or explicit `N/A`) + INDEX row with resolvable `path`.
+
+## Templates & assets
+
+**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; optional `schemas/frontmatter-v1.schema.json`).
+
+**CLI `init`:** when consumer `docs/specs/` is **absent**, copy INDEX stub + `_templates/*` (idempotent; **never overwrite** existing INDEX). When the tree already exists, skip seed entirely.
+
+**Skill fallback:** if consumer `_templates/` missing during author mode, copy from package/skill assets before authoring.
+
+## Author roles
+
+| Role | Responsibility |
+|------|----------------|
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring` |
+| **tech-writer** | Post-delivery sync where present; never invent product behavior without AC/code source |
+| **feature-developer** | Consumes approved specs as SoT; mechanical INDEX/frontmatter fixes only on renames |
+| **mcp-ts** | No tech-writer — author + post-sync via **task-analyst** only |
+
+## Self-check before handoff (soft block)
+
+Block handoff via `open_questions` until fixed:
+
+- [ ] Required frontmatter keys present; arrays always present (may be `[]`)
+- [ ] Required body headings present (or explicit `N/A`)
+- [ ] INDEX row added/updated with resolvable `path` in the **same change set**
+- [ ] Sources cited; invented product behavior absent (or labeled `draft` / `inferred`)
+- [ ] Conflict with brief AC reconciled or flagged
+
+## Related
+
+- `product-specs` — discovery / consume
+- Skill `spec-authoring` — procedural checklist
+- Optional consumer script `scripts/check-product-specs.sh` (WARN default; `--strict` FAIL)
+
+
+## Stack notes
+
+- Author via skill `spec-authoring` + **task-analyst only** (no tech-writer on this stack).
+- `routes` = tool names; `ui`/`store` = `[]`; prefer `type: feature`.
+- Requestable — not always-on / session-start.

package/presets/claude/mcp-ts/rules/architecture/product-specs.md

@@ -0,0 +1,63 @@
+---
+paths:
+  - docs/specs/**/*
+---
+
+<!-- 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`: MCP **tool names**. `ui` / `store`: `[]`. `api`: tools/handlers. `e2e`: contract/unit paths.
+- Prefer `type: feature`. **Forbidden:** requiring `app/src/ui`, Playwright paths, or Next lint recipes.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/claude/mcp-ts/rules/tooling-and-review/agent-team-orchestrator.md

@@ -188,3 +188,5 @@ When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync o
 - **Phase 1 artifacts:** `brief.md`, `decomposition.md`, `architecture.md`, `validation-report.md`, `security-review.md`; schema/style review via parent skill `code-review` → `review.md`. Shared-core names like `a11y-review.md`, `ci-report.md`, `unit-test-plan.md` are N/A until Phase 2 agents ship.
 - **Review-only:** pipeline step = `security-reviewer` for threat/capability diffs; parent applies skill `code-review` for schema/contract/style (no `code-reviewer` agent in Phase 1).
 - After TS changes, pipeline includes **build-verifier** with repository typecheck/test via `post-change-test` / `mcp-ts-tooling`.
+
+**Product specs:** When `/task`, `/feature-start`, or `/spec-start` touches pages/features/`docs/specs`: if INDEX exists and no generate intent → instruct next agent to load requestable **`product-specs`** (consume; soft-fail; never invent). If generate/bootstrap/`spec-gen` → load **`product-specs-authoring`** + skill **`spec-authoring`** inside **task-analyst** (not a separate pipeline step); pass created spec paths + INDEX diff in handoff; human gate must approve before feature-developer. No-op if INDEX absent and no author intent.

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

@@ -70,7 +70,8 @@ Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
 - `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
 - Positive yarn recipes `lint:js` / `lint:css`
 - `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
-- Agent file `accessibility-reviewer` (no UI surface)
+- Agent files `accessibility-reviewer`, `mockup-reviewer`, `ux-designer` (no UI surface)
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
 
 Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`), `java-tooling` (`mvn test` / `./gradlew test`), or `php-tooling` (`php artisan test` / `composer test` / `vendor/bin/phpunit`).
 
@@ -82,7 +83,8 @@ Same UI/mobile bans as backend stacks, plus:
 - Positive yarn recipes `lint:js` / `lint:css` as required gates
 - `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
 - Go tool commands as required MCP delivery gates: `go test`, `go vet`, `golangci-lint`
-- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`
+- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`, `mockup-reviewer`, `ux-designer`
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
 
 Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`, `post-change-test`); Phase 1 gates `build-verifier` + `security-reviewer`.
 

package/presets/claude/mcp-ts/skills/feature-delivery/SKILL.md

@@ -6,9 +6,10 @@ description: Delivers TypeScript MCP server features end-to-end across contracts
 # Feature Delivery (mcp-ts)
 
 1. Read brief, AC, and decomposition.
-2. Follow `feature-delivery-workflow.mdc` + `reference-features.mdc`: contract → schema → handler → register → unit/contract tests → package validation.
-3. Keep transport/lifecycle in the entry module; tools stay in registration modules.
-4. After TS edits: **invoke** `post-change-test.mdc` (+ `mcp-ts-tooling.mdc`).
+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. Follow `feature-delivery-workflow.mdc` + `reference-features.mdc`: contract → schema → handler → register → unit/contract tests → package validation.
+4. Keep transport/lifecycle in the entry module; tools stay in registration modules.
+5. After TS edits: **invoke** `post-change-test.mdc` (+ `mcp-ts-tooling.mdc`).
 
 ## Do / Don't
 

package/presets/claude/mcp-ts/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/claude/next/agents/README.md

@@ -35,6 +35,7 @@ Specialized subagents (personas) — per [Claude Code documentation](https://cod
 | A11y reviewer | `accessibility-reviewer.md` | no |
 | Security reviewer | `security-reviewer.md` | no |
 | Performance auditor | `performance-auditor.md` | no |
+| Mockup reviewer | `mockup-reviewer.md` | no |
 
 ## Testing
 
@@ -64,7 +65,7 @@ Default SoT — YAML `model` in each agent file. Optional `steps[].model` (`chea
 |------|---------------------|--------|
 | **cheap** | `fast` | `task-router`, `task-analyst`, `build-verifier`, `code-reviewer`, `tech-writer`, `codebase-analyzer` |
 | **standard** | `inherit` or `sonnet` | `feature-developer`, `debugger`, `ci-investigator`, `api-contract-reviewer`, `accessibility-reviewer`, `qa-tester`, `unit-test-*`, `playwright-test-*` (`sonnet` where already pinned) |
-| **strong** | `opus` | `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor` |
+| **strong** | `opus` | `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor`, `mockup-reviewer` |
 
 **Notes**
 

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

@@ -45,6 +45,15 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 11. **Performance skill by stack:** next → `react-performance`; nuxt → `vue-performance`. **No react-performance/vue-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`.
 12. **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`.
 
+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.
+
+
+**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 notes
 
 - Thin aliases may be <15 body lines.

package/presets/claude/next/agents/code-reviewer.md

@@ -19,6 +19,7 @@ Apply the **`code-review` skill** and **`rules/tooling-and-review/code-review-mr
 - If diff changes mappers, store reducers/thunks, or domain logic **without** new/updated `*.spec.ts` → **REQUEST_CHANGES** unless task scope explicitly excludes tests.
 - If `validation-report.md` exists and verdict is FAIL → **REQUEST_CHANGES** (developer must fix before review passes).
 - User-flow changes without e2e plan/spec updates → note in warnings; REQUEST_CHANGES when AC requires e2e.
+- 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.
 
 ## Review artifact
 

package/presets/claude/next/agents/feature-developer.md

@@ -51,6 +51,19 @@ Do not perform formal code review — that is the code-reviewer subagent's job.
 
 - When editing `app/**/*.{ts,tsx}`, load / follow rule `react-next-anti-hallucination`.
 
+## 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.
+
+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 `.claude/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/claude/next/agents/mockup-reviewer.md

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

package/presets/claude/next/agents/task-analyst.md

@@ -101,9 +101,45 @@ Do not invoke the developer or any implementation subagent.
 
 - 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: …
+```
+
+
+## UX design (behavioral)
+
+Load requestable skill **`ux-design`** and rule **`ux-design`** when:
+- standalone router intent `ux-design`, or
+- **required-signal:** the user asked for UX, **or** AC explicitly require flows/states, **or** `spec-gen` / `/spec-start` for a **page/feature**, or
+- advisory UI AC on this UI stack (notes only; skip if no UI surface).
+
+**Order:** write `ux-design.md` **before** author mode / skill `spec-authoring` when both apply. You remain the only INDEX writer.
+
+Write `.claude/team/tasks/<slug>/ux-design.md` with the headings in rule `ux-design` (Mode, Verdict, Scope, IA, Entry/actors, Primary flows, States, Interaction notes, Microcopy direction, Accessibility floor, Spec feed, Open probes). Modes: `synthesize` | `review`.
+
+**Required vs advisory:** required-signal + missing named primary flows **or** empty/error/loading matrix → DoR not met (`open_questions` / blocked analysis). Isolated missing microcopy never blocks. Advisory `INCOMPLETE` → notes only. Do **not** copy the mockup FAIL-only hook.
+
+**Forbidden:** Figma MCP tools (`get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`). When Figma is present and required-signal fires, emit a **thin** `ux-design.md` from AC only (no visual claims). Only `mockup-reviewer` reads Figma.
+
+When produced, append `ux-design.md` to this step's **`analysis`** `authoritativePaths` / `evidencePaths`. No new manifest producer row.
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.
-- **Owned outputs:** `brief.md` and `decomposition.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
+- **Owned outputs:** `brief.md` and `decomposition.md` (plus `ux-design.md` when produced); upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `analysis`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

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

@@ -22,6 +22,8 @@ You are a task router for a Next.js frontend agent team. You **do not** implemen
 | `migration` | «миграция» (migration), «upgrade», «обнови Next» (upgrade Next), «переход на» (move to), major version <!-- i18n-keep: E4 --> | task-analyst → migration-specialist → feature-developer → build-verifier → code-reviewer → qa-tester (regression) |
 | `perf-audit` | «производительность» (performance), «perf», «bundle», «LCP», «медленно» (slow), «waterfall» <!-- i18n-keep: E4 --> | performance-auditor |
 | `a11y` | «a11y», «доступность» (accessibility), «accessibility», «WCAG», «screen reader», «клавиатура» (keyboard) <!-- i18n-keep: E4 --> | task-analyst → feature-developer → build-verifier → accessibility-reviewer → code-reviewer |
+| `mockup-review` | «ревью макета» (mockup review), «mockup review», «проверь Figma» (check Figma), «figma review», «макет» (mockup) + review verb, `figma.com` + review-not-implement <!-- i18n-keep: E4 --> | mockup-reviewer |
+| `ux-design` | «разработай UX» (design UX), «спроектируй» (design/plan) flows, «journey», «IA», «state matrix», «ревью UX» (UX review) without Figma <!-- i18n-keep: E4 --> | task-analyst |
 | `review-only` | «ревью» (review), «review MR», «проверь diff» (check diff), «code review» <!-- i18n-keep: E4 --> | code-reviewer |
 | `test-only` | «покрой тестами» (add tests), «напиши тесты» (write tests) (mixed unit+e2e, no impl) <!-- i18n-keep: E4 --> | task-analyst → qa-tester |
 | `unit-only` | «unit», «юнит» (unit), «mapper tests», «покрой маппер» (cover mapper), «почини unit» (fix unit) <!-- i18n-keep: E4 --> | unit-test-planner → unit-test-generator, or unit-test-healer |
@@ -33,7 +35,7 @@ You are a task router for a Next.js frontend agent team. You **do not** implemen
 
 ## Pipeline profiles
 
-Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.json`. Default when omitted: **`standard`** for `feature`/`refactor`/`bugfix`; **`light`** for `review-only`, `perf-audit`; **`full`** when cross-layer or e2e AC required.
+Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.json`. Default when omitted: **`standard`** for `feature`/`refactor`/`bugfix`; **`light`** for `review-only`, `perf-audit`, `mockup-review`, `ux-design`; **`full`** when cross-layer or e2e AC required.
 
 | Profile | When | Typical `feature` steps |
 |---------|------|------------------------|
@@ -50,6 +52,8 @@ Set optional top-level `"profile": "full" | "standard" | "light"` in `pipeline.j
 | `feature` | developer → build-verifier |
 | `bugfix` | debugger → build-verifier (`skipIf: debugger.fixed` on developer) |
 | `review-only` | code-reviewer |
+| `mockup-review` | mockup-reviewer |
+| `ux-design` | task-analyst |
 | `docs-only` | tech-writer (skip analyst if brief exists) |
 | `ci-fix` | ci-investigator → build-verifier (`skipIf: ci-investigator.resolved`) |
 
@@ -78,6 +82,9 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 
 ## Adjust steps (when context is clear)
 
+- If prompt or `brief.md` contains `figma.com` on `feature` / `refactor` / `spike` / `spec-gen`, insert **mockup-reviewer** after **task-analyst** (when present) and before **solution-architect** and **feature-developer**. Set `model: "strong"` on that step. Do not add static `humanGates: ["after:mockup-reviewer"]` (FAIL-only hook exception). Never put `mockup-reviewer` in a `parallel: true` step (FAIL-only gate is serial).
+- Classify intent `mockup-review` **before** `ux-design` **before** `review-only`. A `figma.com` URL with review-not-implement language is `mockup-review` even without the word «макет», including when the user said «ревью UX». <!-- i18n-keep: E4 -->
+- If UI stack and (required-signal or advisory UI AC), instruct **task-analyst** to load skill `ux-design` (no new pipeline step; analyst default model, not `strong`). Required-signal: user asked UX, or AC require flows/states, or spec-gen page/feature.
 - Skip **task-analyst** if AC/scope fully specified → document in `skipped`.
 - Add **solution-architect** for cross-layer / new public APIs — after analyst, before developer.
 - Add **api-contract-reviewer** for new/changed backend contracts — before developer.
@@ -92,11 +99,11 @@ Optional per-step field: `"model": "cheap" | "standard" | "strong"`. Omit → ag
 
 | When | What to write |
 |------|----------------|
-| `profile: light` | set `cheap` on **all** steps (exception: unclear bug root cause on `debugger` → `strong`) |
+| `profile: light` | set `cheap` on **all** steps (exceptions: unclear bug root cause on `debugger` → `strong`; `mockup-reviewer` always `strong`) |
 | `profile: standard` | omit (frontmatter defaults) |
 | `profile: full` | set `strong` on `solution-architect`, `migration-specialist`, `security-reviewer`, `performance-auditor` when present; omit others |
 | `intent: spike` | set `strong` on `solution-architect` (and analyst may stay default/`cheap`) |
-| `intent: perf-audit` / security-heavy feature | `strong` on auditor/reviewer step |
+| `intent: perf-audit` / `mockup-review` / security-heavy feature | `strong` on auditor/reviewer step (`mockup-reviewer` never `cheap`) |
 | Always | **never** `strong` on `build-verifier`, `tech-writer`, `task-router` |
 
 Claude Code mapping when orchestrator invokes Agent tool: `cheap` → `haiku` (or rely on frontmatter `fast`); `standard` → omit / `sonnet` / inherit; `strong` → pass `opus` (or rely on frontmatter `opus`). Prefer explicit per-invocation `model` when frontmatter is unreliable.
@@ -113,6 +120,8 @@ Claude Code mapping when orchestrator invokes Agent tool: `cheap` → `haiku` (o
 | `bugfix`, `review-only`, `ci-fix` | `[]` |
 | `spike` | `["after:solution-architect"]` |
 | `perf-audit` | `[]` |
+| `mockup-review` | `[]` |
+| `ux-design` | `[]` |
 
 ## Output
 
@@ -128,6 +137,17 @@ Write `.claude/team/tasks/<slug>/pipeline.json` and initialize the routing entry
 
 Do not invoke implementation agents yourself.
 
+## 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/claude/next/agents/tech-writer.md

@@ -42,6 +42,11 @@ Conventional commit / release note snippet.
 - Do not duplicate entire decomposition — summarize outcomes and how to use/extend.
 - May create or update files under `docs/**` when the task explicitly requests it; otherwise keep primary output in team artifacts.
 
+## 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.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition and available architecture/migration/review artifacts.

package/presets/claude/next/commands/feature-continue.md

@@ -37,6 +37,7 @@ Legacy command to continue after a human gate. For new pipelines with `pipeline.
 3. Call subagent **feature-developer** with context:
    - paths to `brief.md`, `decomposition.md`, `status.json`;
    - instruction to follow `rules/architecture/feature-delivery-workflow.md`.
+   - if `docs/specs/INDEX.md` exists: load **`product-specs`** and honor **Related specs** from `brief.md` (soft-fail on miss; never invent behavior).
 
 4. After the developer finishes, continue review → QA per `rules/tooling-and-review/agent-team-orchestrator.md`.
 

package/presets/claude/next/commands/feature-start.md

@@ -16,11 +16,19 @@ Starts the **analysis phase** for a new task. For new work, prefer `/task` becau
 5. Invoke subagent **task-analyst** with the full task description and artifact paths.
 6. 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: `/feature-continue <slug>` or `/task-continue <slug>`.
 

package/presets/claude/next/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 `.claude/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
+4. Write `.claude/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/claude/next/commands/task-continue.md

@@ -32,19 +32,24 @@ printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":tr
 
    3. Re-read `status.json` (and the hook `followup_message`).
    4. Invoke the subagent named in `status.currentAgent` / followup — do **not** advance the pipeline a second time.
-3. **Review `changes_requested`** (not a human gate): set `currentAgent` to `feature-developer` (same index / find developer in steps), `state: in_progress`, then invoke developer. Do **not** call `end_human_gate` unless `activeHumanGateEventId` is set.
-4. **Other resume**: restore `pipelineIndex` / `currentAgent` from status and invoke that agent.
-5. After the invoked agent completes, `chain-team-phases.sh` on `subagentStop` continues the chain when `autoChain: true`.
+3. **Review `changes_requested`** (not a human gate): if `currentAgent` is **`mockup-reviewer`**, this is the FAIL-only mockup gate — do **not** retry `feature-developer`. Read `mockup-review.md` and resume via the human-gate path (`end_human_gate` / `activateNext`). Otherwise: set `currentAgent` to `feature-developer` (same index / find developer in steps), `state: in_progress`, then invoke developer. Do **not** call `end_human_gate` unless `activeHumanGateEventId` is set.
+4. **`blocked` + `currentAgent: mockup-reviewer`** (`BLOCKED_MCP`): skip-forward via the same `end_human_gate`/`activateNext` path (explicit «proceed without MCP»). Do not invent DS claims.
+5. **Other resume**: restore `pipelineIndex` / `currentAgent` from status and invoke that agent.
+6. After the invoked agent completes, `chain-team-phases.sh` on `subagentStop` continues the chain when `autoChain: true`.
 
 ## Artifacts for handoff
 
 | Agent | Read |
 |-------|------|
-| feature-developer | brief.md, decomposition.md, validation-report.md (if retry), review.md (if retry), architecture.md |
+| feature-developer | brief.md (incl. **Related specs**), decomposition.md, ux-design.md (if present), mockup-review.md (if present), validation-report.md (if retry), review.md (if retry), architecture.md; if `docs/specs/INDEX.md` exists → load **`product-specs`** |
 | build-verifier | git diff, decomposition.md |
 | code-reviewer | brief.md, validation-report.md, git diff |
+| mockup-reviewer | mockup-review.md |
 | qa-tester | brief.md, decomposition.md, scope from pipeline step |
 
-## 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.