@bonesofspring/ai-rules 0.2.18 → 0.2.20

package/presets/cursor/ios-swift/team/README.md

@@ -13,6 +13,7 @@ Artifact directory for the iOS agent-team pipeline.
     status.json
     brief.md
     decomposition.md
+    .memlog.md
     …
 ```
 
@@ -30,6 +31,13 @@ Artifact directory for the iOS agent-team pipeline.
 
 Bootstrap `tasks/<slug>/` by **writing** artifacts (Write tool), not Shell `mkdir`. Cursor sandbox → `Operation not permitted` otherwise (worse on Desktop/Documents).
 
+
+## 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 `.cursor/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/cursor/ios-swift/team/fixtures/feature-full.json

@@ -1,23 +1,53 @@
 {
   "slug": "example-feature-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "summary": "Multi-layer Feature with XCUITest 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": "xcodebuild + lint + unit smoke", "model": "cheap" },
-    { "agent": "security-reviewer", "label": "Security review", "model": "strong" },
-    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" },
-    { "agent": "qa-tester", "label": "XCUITest", "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": "xcodebuild + lint + unit smoke",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "XCUITest",
+      "scope": "e2e-only"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
   ],
-  "humanGates": ["after:task-analyst"],
   "autoChain": true,
   "skipped": [
     {
       "agent": "playwright-test-planner",
-      "reason": "iOS uses XCUITest — see xcuitest-test-* agents"
+      "reason": "iOS uses XCUITest \u2014 see xcuitest-test-* agents"
     },
     {
       "agent": "playwright-test-generator",

package/presets/cursor/ios-swift/team/fixtures/memlog.example.md

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

package/presets/cursor/java/AGENTS.md

@@ -25,7 +25,7 @@ Copies rules/agents/hooks/skills/commands/team + `REPO_AGENTS.md` → root `AGEN
 ## Inventory
 
 - **21 agents** — see `agents/README.md` (no a11y / Playwright / XCUITest)
-- **8 skills** — `feature-delivery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`
+- **10 skills** — `feature-delivery`, `spec-authoring`, `spec-discovery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`
 - **5 commands** — `/task`, `/task-continue`, `/feature-start`, `/feature-continue`, `/technical-retro`
 
 ## Dogfood (5 scenarios)

package/presets/cursor/java/MCP.md

@@ -12,4 +12,23 @@ Figma and browser e2e MCP (Playwright / Chrome DevTools) are **not** part of the
 
 Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment.
 
-After init: Settings → MCP → enable servers. `init` overwrites the 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/java/agents/build-verifier.md

@@ -17,6 +17,12 @@ You are the build verifier for **Java hexagonal** services (and for **ai-rules p
 
 **Never** require Playwright, XCUITest, `lint:js`/`lint:css`, or `xcodebuild`/`SwiftLint` as the Java gate.
 
+## Verification before completion
+
+<!-- shared-core: quality/verification-before-completion.md -->
+
+Before writing `validation-report.md` or claiming PASS: IDENTIFY the commands, RUN them, READ exit codes, VERIFY they match the verdict, THEN claim. Do not mark PASS from memory of a prior developer run.
+
 ## Preset-structure validation (when editing `packages/ai-rules/presets/**`)
 
 From `packages/ai-rules/`:

package/presets/cursor/java/agents/ci-investigator.md

@@ -16,6 +16,15 @@ Triage red CI for Java repos (and ai-rules preset-structure when relevant).
 
 - Never treat `lint:js` / Playwright / xcodebuild as the Java default gate.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+- When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.

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

@@ -16,6 +16,8 @@ You are a senior Java hexagonal code reviewer. Write only review artifacts under
 
 Apply skill `code-review` and `code-review-mr.mdc`. Weigh `architecture-boundaries.mdc`, `domain-layer.mdc`, `application-usecases.mdc`, `ports-interfaces.mdc`, `adapters-driving.mdc`, `adapters-driven.mdc`, `composition-root.mdc`, `java-conventions.mdc`, `tests-unit.mdc`, `tests-integration.mdc`, `security-java.mdc`.
 
+You **issue** reviews. Implementers acting on your findings must verify each item against the codebase and must not perform agreement. Do not require gratitude in replies.
+
 ## Review focus (Java 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.

package/presets/cursor/java/agents/debugger.md

@@ -6,6 +6,8 @@ readonly: false
 
 Investigate with **runtime evidence**: failing `mvn test` / `./gradlew test` output, logs, stack traces, minimal repro.
 
+Use the **`debug-investigation` skill** for the investigation loop.
+
 ## Approach
 
 1. Reproduce with `mvn test` / `./gradlew test` / focused class/package tests.
@@ -20,6 +22,18 @@ Investigate with **runtime evidence**: failing `mvn test` / `./gradlew test` out
 
 Write `.cursor/team/tasks/<slug>/debug-report.md`.
 
+
+## 3-fix architecture gate
+
+After **three** unsuccessful fix attempts (or the same symptom returning twice): STOP. Do not attempt fix #4. Escalate architecture with the human or `solution-architect`. Follow skill `debug-investigation`. Before `fixApplied: true`, re-run the failing check.
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
@@ -27,3 +41,4 @@ Write `.cursor/team/tasks/<slug>/debug-report.md`.
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+- When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.

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

@@ -45,6 +45,13 @@ Update `.cursor/team/tasks/<slug>/implementation.md` and the owned implementatio
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
+- When acting on review feedback (`changes_requested` / human comments): verify each item against the codebase before implementing; no performative agreement.
+
+## Verification before completion
+
+<!-- shared-core: quality/verification-before-completion.md -->
+
+Before handoff, IDENTIFY→RUN→READ→VERIFY the scoped checks for this WP, THEN claim. Do not say the work is done without that evidence in the same turn. Full-project lint is `build-verifier`.
 
 ## Product specs (docs/specs)
 
@@ -53,6 +60,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/java/agents/migration-specialist.md

@@ -26,6 +26,12 @@ Write `.cursor/team/tasks/<slug>/migration-plan.md`:
 - Do not invent a new HTTP framework mid-migration without AC.
 - Handoff to feature-developer for execution after human gate when required.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/java/agents/performance-auditor.md

@@ -17,6 +17,12 @@ Audit Java performance risks on the task scope.
 
 `.cursor/team/tasks/<slug>/perf-report.md`. No production edits. Not Instruments/Xcode.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/java/agents/solution-architect.md

@@ -23,6 +23,12 @@ Design solutions for **Java hexagonal** services.
 - Do not invent Next/iOS layer names.
 - No production code.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/java/agents/task-analyst.md

@@ -7,6 +7,16 @@ model: fast
 
 Analyze and decompose work for **Java hexagonal** backends.
 
+## Classify first
+
+<!-- shared-core: agent-team/task-classification.md -->
+
+Before decomposing, name the class: **spike** / **bounded** / **architectural**. Maps to existing pipeline profiles — do not invent a second orchestrator.
+
+- **Spike** — research DoR; no implement tasks.
+- **Bounded** — few tasks, only layers actually touched; do not pad types/api/store/ui.
+- **Architectural** — full layer table; architect when boundaries are unclear.
+
 ## Deliverables
 
 - `brief.md` — goals, non-goals, AC, open questions
@@ -30,6 +40,15 @@ Emit an analysis receipt; the runtime applies any configured human gate.
 
 **Author mode (Generate / Bootstrap):** When the user runs `/spec-start`, router intent is `spec-gen` / bootstrap, or brief/AC requests generation: load **`product-specs`** + **`product-specs-authoring`** and skill **`spec-authoring`**. You are the **primary author** (INDEX bootstrap included). Follow frontmatter v1 + required headings; update INDEX in the **same change set**; default `status: draft`. Block handoff via `open_questions` until the authoring self-check passes.
 
+
+**Spec mode:** Write `## Spec mode` in `brief.md` with exactly one of `consume` | `generate` | `none`. Infer if unset: spike/research/preset-only → `none`; `/spec-start` or router `spec-gen` → `generate`; otherwise `consume`. Router may echo `specMode` on `pipeline.json`.
+
+**`none`:** skip INDEX row requirement and author mode; do not invent a dummy INDEX.
+
+**Research-before-spec (opt-in):** load skill **`spec-discovery`** only when the user/AC asks research before authoring (not default consume `/task`). Run a **subset** of methods; **`claim-ledger` is mandatory** whenever the skill loads. Append chronological notes to `.cursor/team/tasks/<slug>/.memlog.md` (append-only; do not mutate `status.json`).
+
+**applyReadiness (author blocked):** if specs are drafted but the human gate has not passed, or a required named spec is missing, emit `applyReadiness: { "state": "blocked", "contextFiles": ["…"] }` on the analysis receipt. Do not invoke feature-developer.
+
 ### Brief sections (when author mode or INDEX exists)
 
 Add to `brief.md`:
@@ -43,6 +62,14 @@ Add to `brief.md`:
 ```
 
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If the prompt/brief has a tracker URL (Linear/Jira/Notion/…) and that MCP is ready, pull AC **read-only**. Task-folder artifacts remain SoT.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.

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

@@ -39,6 +39,20 @@ You are a task router for a **Java hexagonal backend** agent team. You **do not*
 
 **Never skip `build-verifier`** after developer when Java sources changed.
 
+## Task class (spike / bounded / architectural)
+
+<!-- shared-core: agent-team/task-classification.md -->
+
+Name the class in `routingReasons`. Maps to profiles already in this file — do not add a parallel step table.
+
+| Class | Use existing |
+|-------|----------------|
+| Spike | intent `spike` |
+| Bounded | `profile: light` (or skip analyst when AC is complete) |
+| Architectural | `profile: full` + `solution-architect` when boundaries unclear |
+
+SoT: `agent-team/task-classification` (shared-core marker above; do not invent a second pipeline).
+
 ## Routing decision rubric
 
 Keep top-level `profile` and emit this top-level object in every new `pipeline.json`:
@@ -75,6 +89,7 @@ Fixtures: `.cursor/team/fixtures/` (feature-full, feature-light, bugfix-standard
 | Intent | Default humanGates |
 |--------|-------------------|
 | feature, refactor, test-only | `["after:task-analyst"]` |
+| spec-gen | `["after:task-analyst"]` |
 | migration | `["after:migration-specialist"]` |
 | unit-only | `["after:unit-test-planner"]` when new plan |
 | e2e-only / integration | `["after:integration-test-planner"]` when new plan |
@@ -100,6 +115,11 @@ Detect and set routing reasons when the user asks to **generate / bootstrap prod
 
 Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
 
+
+**specMode (optional `pipeline.json` field):** `none` for spike/research; `generate` for `spec-gen` / `/spec-start`; `consume` default when INDEX exists. Echo top-level `specMode`. Brief `## Spec mode` wins on conflict.
+
+Do **not** add a pipeline step for `spec-discovery`. Instruct analyst to load that skill only when the user/AC asks research-before-spec.
+
 ## Runtime initialization
 
 Return the routing receipt to the orchestrator. The orchestration runtime/hook exclusively initializes and updates `status.json`, `metrics.json`, attempt identities, and gate lifecycle; the router does not write those shared runtime files.

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

@@ -14,7 +14,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 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.
+6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate. Optional: if arguments/AC ask research-before-spec, also load skill **`spec-discovery`** (not default).
 7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.
 
 ## Human gate

package/presets/cursor/java/mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@upstash/context7-mcp"
+        "@upstash/context7-mcp@4.0.2"
       ]
     }
   }

package/presets/cursor/java/rules/README.md

@@ -19,7 +19,7 @@
 ## Loading strategy
 
 - **`alwaysApply: true`** (Cursor) / **without `paths:`** (Claude) — base invariants only (**3**): `java-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`
-- **On-demand / requestable** — `post-change-test`, `java-tooling`, `agent-team-intake`, `agent-team-orchestrator`, hexagonal domain/adapters, tests, feature-delivery-workflow, reference-features, product-specs, product-specs-authoring, `design-guidance`, `anti-sycophancy-discipline`, `technical-retro`
+- **On-demand / requestable** — `post-change-test`, `java-tooling`, `agent-team-intake`, `agent-team-orchestrator`, hexagonal domain/adapters, tests, feature-delivery-workflow, reference-features, product-specs, product-specs-authoring, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `technical-retro`
 - **Preset author meta** (globs `packages/ai-rules/presets/**`, never alwaysApply): `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`
 - **Skills** — Phase C (deferred): `feature-delivery`, `code-review`, `integration-testing`, …
 
@@ -43,6 +43,7 @@ SoT prose: `packages/ai-rules/presets/_shared/core/**` (see `_shared/README.md`)
 | `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` | embed | Stack notes: Java packages/ports, exceptions, `post-change-test` |
 | `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` | embed | requestable full VERIFY/discipline set |
 | `quality/design-guidance.md` | `design-guidance.mdc` | embed | requestable smells/GoF; Java Stack notes |
+| `quality/mcp-usage.md` | `mcp-usage.mdc` | embed | requestable Context7 + overlay MCP |
 | `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | lineage | Roles (`integration-test-*`); preset PR pointer |
 | `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | embed | thin alias |
 | `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | lineage | Java hexagonal checklist |

package/presets/cursor/java/rules/agent-team-orchestrator.mdc

@@ -19,6 +19,7 @@ Work request without `/task` — see **agent-team-intake** (when to suggest the
 | `/task-continue <slug>` | After human gate or pause |
 | `/feature-start <desc>` | Legacy: analyst-only start (no router) |
 | `/feature-continue <slug>` | Alias of task-continue |
+| `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
 | `/technical-retro [slug]` | Retro with agent team block |
 
 ## Roles (shared catalog)

package/presets/cursor/java/rules/anti-sycophancy-discipline.mdc

@@ -11,7 +11,7 @@ alwaysApply: false
 
 Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
 
-1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If you cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If that is not enough and Context7 MCP is available, load **`mcp-usage`** and query docs for the **installed major**. If you still cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
 2. **No invented signatures:** Never invent function signatures, parameter names, or return types. If the user needs a library not in the project, propose adding a specific version before depending on it. Silent stubs are worse than refusal.
 3. **Enumerate edge cases before validating:** When asked "is this correct?" or "does this work?", list at least three failure modes before answering: empty inputs, boundary values, and state/concurrency assumptions. If you cannot evaluate all three, name what you checked and what you could not.
 4. **Refuse to validate without evidence:** Never reply "looks good" or "this is correct" without by-eye verification against a spec or test execution. If no spec exists, ask for one or refuse to validate.

package/presets/cursor/java/rules/code-quality-and-refactoring.mdc

@@ -33,7 +33,7 @@ alwaysApply: true
 
 Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
 
-- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- Unverifiable third-party API → if Context7 is up, load **`mcp-usage`** and query the installed major; else mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
 - Before "is this correct?" — ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
 - Refactor without tests → propose characterization test; if declined, label `UNTESTED`.
 - Comments = WHY only when non-obvious; ban self-referential "added for issue Y".

package/presets/cursor/java/rules/feature-delivery-workflow.mdc

@@ -15,7 +15,7 @@ Order of work:
 4. **Driving adapters** — HTTP/gRPC/CLI mapping DTOs (`adapters-driving`, `api-http`; stubs for gRPC/messaging).
 5. **Composition root** — wire in `configuration/` / `*Application.java` (`composition-root`).
 6. **Tests** — unit (domain/app) → integration (adapters) → optional e2e smoke.
-7. **Gate** — `post-change-test` (+ `java-tooling`).
+7. **Gate** — `post-change-test` (+ `java-tooling`). When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
 
 ```mermaid
 flowchart LR
@@ -45,6 +45,7 @@ flowchart LR
 - **Ubiquitous language:** Domain names/boundaries reflect the feature domain — do not mix transport/framework terms into domain without need.
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
 - Spring Boot is the default edge; plain Java / Quarkus / Micronaut keep the same layer order with different wiring.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
 
 ## Related
 

package/presets/cursor/java/rules/mcp-usage.mdc

@@ -0,0 +1,97 @@
+---
+description: When to call shipped Context7 and local overlay MCP — detect presence, use if the task fits, degrade.
+alwaysApply: false
+---
+
+<!-- shared-core: quality/mcp-usage.md -->
+
+# MCP usage
+
+Requestable protocol for **shipped** and **local-overlay** MCP servers. Agents load this stem via one-liner wiring — do not copy tool schemas into prompts; discover them at runtime.
+
+Does not replace Figma mockup-review (that checklist stays on `mockup-review`). Does not add pipeline agents or required handoff stems.
+
+## Presence (runtime catalog is SoT)
+
+1. Inspect the **session MCP catalog** (server names + `serverStatus`). Project `mcp.json` / `.mcp.json` is a hint, not proof the server is up (user-level and plugin servers never appear there).
+2. Treat `error`, `needsAuth`, and `loading` as **unavailable**. Authenticate only when this task needs that server.
+3. **Discover tool schemas before calling.** Never invent tool names or arguments from memory.
+4. Match overlay servers by **documented aliases** or exact catalog ids. Prefer a ready `plugin-*` id over an unknown similarly named server; if several match, ask rather than guessing.
+5. If two servers expose the same product (plugin + project entry), use the **ready** one; do not call both.
+
+## Classes
+
+| Class | Who adds it | Policy |
+|-------|-------------|--------|
+| **Shipped** | Preset `mcp.json` | Assume it should be there; call when the task fits; degrade if down (do not block unless noted below) |
+| **Local overlay** | Consumer project or user MCP | Use only when present **and** the task fits. Never a required pipeline step |
+
+Shipped in every preset: **Context7** (library docs). Other shipped servers are stack-specific — see adapter **Stack notes**.
+
+## Context7 (shipped)
+
+**When to call** (after lockfile / manifest + sibling files still do not confirm the symbol):
+
+- Third-party API that would otherwise get `// VERIFY: lib.symbol @ version`
+- Version-sensitive framework or SDK APIs
+- Migrations / major upgrades
+- Library is in the lockfile but the signature is unclear
+
+**When not to call:** repo public API; a sibling file already imports the symbol; a trivial call already in this module.
+
+**Flow:**
+
+1. Discover server `context7`.
+2. Resolve a library id, then query docs (read the live schema; typical names `resolve-library-id` then `query-docs`).
+3. Put the **installed major** from the project manifest into the query.
+4. Cap: **≤3 doc queries per question**.
+5. Source priority: lockfile / sibling code **>** Context7 **>** training data. If docs disagree with the installed major, keep the installed API.
+6. If Context7 is down: `// VERIFY` (or stack equivalent) and say MCP was unavailable. **Do not block** the task.
+
+## Local overlay protocol
+
+If a matching server is ready and a **task signal** fires → discover and use. Otherwise continue from files / native tools (`gh`, repo docs, source).
+
+Absence of an overlay is **not** `BLOCKED` unless the user required that MCP as source of truth.
+
+### Observability (Sentry, Datadog, similar)
+
+**Signal:** production error, event/trace id, APM / latency, pasted dashboard or issue URL.
+
+Use the **first ready** observability MCP. Do not invent metrics or stack traces. Do not require two observability servers.
+
+### Tickets (Linear, Jira, Notion, similar)
+
+**Signal:** ticket/page URL in the prompt or brief, or an explicit “pull from \<tracker\>”.
+
+Read-only by default. Task-folder artifacts (`brief.md`, `decomposition.md`) remain SoT — do not replace them with a tracker page. Write back to the tracker **only** if the user asked.
+
+### Component-library overlay
+
+**Signal:** UI component public API, stories, controls, or explicit component-docs MCP.
+
+If such a server is ready, use it for documented props/variants instead of inventing them. If it is down, read story/source files. **Block** only when the user required that MCP as SoT.
+
+Usual aliases and runtime needs live in frontend **Stack notes**. Do not ship this server in preset `mcp.json`.
+
+### GitHub MCP
+
+Native `gh` / git remain SoT for PRs and checks. A GitHub MCP may be used when present; do not require it.
+
+## Figma
+
+Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plugin** and a project `figma` server are both present, use the ready one and do not duplicate calls.
+
+## Forbidden
+
+- Secrets in `mcp.json` / `.mcp.json`
+- New pipeline agents or required handoffs for overlay MCP
+- Treating overlay absence as blocked (except user-required SoT)
+- Tracker/admin write tools without an explicit ask
+- Calling overlay MCP “just in case” on unrelated tasks
+
+## Stack notes
+
+- Shipped MCP is Context7 only. Do **not** require Storybook, Playwright, Chrome DevTools, or Figma as delivery gates.
+- Observability and ticket overlays still apply when present.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept.

package/presets/cursor/java/rules/preset-no-cross-stack-leakage.mdc

@@ -23,6 +23,7 @@ Ban leakage of stack-specific names, paths, and handoff stems across presets.
 - `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Android instrumentation agents, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
 - `mcp-ts` must not ship Go tool commands (`go test`, `go vet`, `golangci-lint`) or `integration-test-*` agents as required delivery gates.
 - Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
+- Storybook / Chrome DevTools MCP must **not** be required handoffs or agent stems (`storybook-reviewer`) on backend or mobile stacks. Frontend overlay mentions in `MCP.md` / `mcp-usage` Stack notes are OK.
 
 ## Forbidden in ios-swift hooks/agents (FAIL)
 

package/presets/cursor/java/rules/product-specs-authoring.mdc

@@ -11,6 +11,8 @@ alwaysApply: false
 
 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`**.
 
+**Optional prefix:** when the user or AC asks **research-before-spec**, load skill **`spec-discovery`** first (subset of methods; **claim-ledger** mandatory). Not the default `/task` consume path and not a new pipeline step.
+
 ## Modes
 
 1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
@@ -84,7 +86,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 ## 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`).
+**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; `schemas/frontmatter-v1.schema.json` is a documentation artifact — the checker does not evaluate it).
 
 **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.
 
@@ -94,7 +96,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 | Role | Responsibility |
 |------|----------------|
-| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring` |
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring`; optional skill `spec-discovery` when research-before-spec |
 | **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 |
@@ -113,8 +115,8 @@ Block handoff via `open_questions` until fixed:
 
 - `product-specs` — discovery / consume
 - Skill `spec-authoring` — procedural checklist
-- Optional consumer script `scripts/check-product-specs.sh` (WARN default; `--strict` FAIL)
-
+- Skill `spec-discovery` — opt-in research-before-spec (not default)
+- Optional consumer script `scripts/check-product-specs.sh` (ships in the npm package; WARN default; `--strict` FAIL). Bash checks INDEX links, required frontmatter keys, and body headings — it does **not** evaluate `frontmatter-v1.schema.json`
 
 ## Stack notes