@bonesofspring/ai-rules 0.2.9 → 0.2.11

package/presets/cursor/mcp-ts/rules/technical-retro.mdc

@@ -0,0 +1,18 @@
+---
+description: Technical retrospective facilitator (on-demand /technical-retro)
+alwaysApply: false
+---
+
+<!-- shared-core: review/technical-retro.md -->
+
+# Техническое ретро — rule alias
+
+Полный сценарий (включая блок **«Работа агентов»** для slug из team tasks) — в slash-команде:
+
+**`commands/technical-retro.md`** → `/technical-retro`
+
+Используй rule только если command недоступен. Не дублируй содержимое command в ответе — следуй command-файлу и skill `technical-retro`.
+
+## Stack notes
+
+- **Phase 1:** skill `technical-retro` is not shipped — follow `commands/technical-retro.md` only; do not fail if the skill is absent (Phase 2 may add the skill).

package/presets/cursor/mcp-ts/rules/tests-unit.mdc

@@ -0,0 +1,31 @@
+---
+description: Unit testing conventions for MCP handlers and schemas
+globs:
+  - **/*.{test,spec}.{ts,tsx,js}
+  - **/__tests__/**/*
+alwaysApply: false
+---
+
+# Unit tests (MCP)
+
+- Table-driven tests for schema parse failures and handler outcomes.
+- Test **pure** handler logic with fakes for FS/network capabilities — no live MCP client required.
+- Cover invalid inputs that schemas should reject **before** side effects.
+- Prefer repository runner (Vitest/Jest/node:test) discovered via tooling rules.
+
+## Required shapes (when capability applies)
+
+- `schema.parse` / Zod: valid input; missing field; wrong type; empty string where non-empty required.
+- Path tools: reject `../` escape and symlink-outside-root (fake FS); accept in-root relative paths.
+- URL/fetch tools: deny blocked hosts (metadata IP, link-local) when allowlist is in play.
+- Auth-sensitive handlers: assert secrets never appear in returned content or thrown messages.
+
+## Forbidden smells
+
+- Hitting real external APIs in unit tests without an explicit integration harness and AC.
+- Asserting on unstable SDK private fields.
+- Browser e2e frameworks (Playwright) as the unit gate.
+
+## Naming
+
+- `toolName.validInput`, `toolName.rejectsPathTraversal`, `schema.parse.*` — follow repo style.

package/presets/cursor/mcp-ts/skills/README.md

@@ -0,0 +1,12 @@
+# Skills (mcp-ts Phase 1)
+
+| Skill | Use |
+|-------|-----|
+| `feature-delivery` | End-to-end MCP feature flow |
+| `unit-testing` | Schema/handler unit tests |
+| `code-review` | Diff review checklist |
+| `debug-investigation` | Bug investigation |
+
+Phase 2 may add `ci-investigation`, `technical-retro`, `write-adr`, `mcp-contract-testing` skills.
+
+Until then: `/technical-retro` uses `commands/technical-retro.md` (no skill required); review-only uses skill `code-review` on the parent (no `code-reviewer` agent).

package/presets/cursor/mcp-ts/skills/code-review/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: code-review
+description: Reviews MCP TypeScript diffs for boundaries, schema contracts, capability scope, and secrets. Use for MR review or when code-review workflow is requested.
+---
+
+# Code review (mcp-ts)
+
+1. Follow `code-review-mr.mdc`, `mcp-server-boundaries.mdc`, `mcp-tool-design.mdc`, `security-mcp.mdc`.
+2. Flag monolithic entry files, schema/protocol mismatches, unscopeed capabilities, secret leakage.
+3. Phase 1: security-reviewer covers threat model; no separate `code-reviewer` agent yet — parent may apply this skill directly.

package/presets/cursor/mcp-ts/skills/debug-investigation/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: debug-investigation
+description: Investigates MCP server bugs with runtime evidence — schema failures, handler errors, transport startup. Use for failing tests or incorrect tool behavior.
+---
+
+# Debug investigation (mcp-ts)
+
+1. Reproduce with unit/contract fixtures before changing code.
+2. Check schema validation vs handler logic vs registration wiring.
+3. Prefer repository tests over ad-hoc Inspector-only claims.
+4. Load `anti-sycophancy-discipline` — report what was verified.

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

@@ -0,0 +1,29 @@
+---
+name: feature-delivery
+description: Delivers TypeScript MCP server features end-to-end across contracts, schemas, handlers, registration, tests, and package validation. Use when implementing or extending a feature, especially through /task or feature-developer.
+---
+
+# 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`).
+
+## Do / Don't
+
+- **Do** Zod-first authoring with JSON Schema-compatible protocol contracts.
+- **Don't** invent SDK APIs; use VERIFY markers / Context7.
+- **Don't** use Playwright, XCUITest, Next lint, or Go tools as this stack's gate.
+
+## Scope discipline
+
+Implement only the current AC / decomposition task. See `feature-developer` → **Zero improvisation**.
+
+## Handoff
+
+Summarize by layer + validation. Update `.cursor/team/tasks/<slug>/status.json`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/mcp-ts/skills/unit-testing/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: unit-testing
+description: Plans and writes unit tests for MCP schemas and handlers using the repository test runner. Use for schema/handler coverage and fixing failing unit tests.
+---
+
+# Unit testing (mcp-ts)
+
+1. Prefer table-driven tests for schema reject/accept and handler outcomes.
+2. Fake FS/network capabilities — no live MCP client required for unit scope.
+3. Follow `tests-unit.mdc` and `mcp-contract-testing.mdc`.
+4. Discover runner via `mcp-ts-tooling` (Vitest/Jest/node:test).
+
+## Out of scope (Phase 1)
+
+- Dedicated `contract-test-*` agents (Phase 2).
+- Browser e2e (Playwright) — forbidden.

package/presets/cursor/mcp-ts/team/README.md

@@ -0,0 +1,17 @@
+# Team artifacts (mcp-ts)
+
+| Path | Purpose |
+|------|---------|
+| `tasks/<slug>/` | Pipeline artifacts (`brief.md`, `status.json`, …) |
+| `fixtures/` | Example pipelines for dogfood |
+| `conventions.md` | Living gotchas (consumer-owned) |
+
+Phase 1 agents: see `agents/README.md`.
+
+## Fixture policy (Phase 1)
+
+`team/fixtures/*.json` may list in `skipped[]` **only** agents that exist in the Phase 1 roster:
+
+`task-router`, `task-analyst`, `solution-architect`, `feature-developer`, `build-verifier`, `security-reviewer`.
+
+Do **not** name Phase 2 agents (`contract-test-*`, `debugger`, Playwright stems, etc.) in fixture JSON — even as skips. Defer those until the agents ship.

package/presets/cursor/mcp-ts/team/conventions.md

@@ -0,0 +1,14 @@
+# Team conventions (mcp-ts)
+
+Fill after init with living gotchas for this MCP server repo.
+
+## Suggested topics
+
+- Package manager + test/typecheck scripts actually used
+- SDK version pin and VERIFY notes
+- stdio entry / `bin` packaging
+- Capability allowlists (FS roots, outbound hosts)
+
+## Fixture policy
+
+Phase 1 fixtures: `skipped[]` may name only Phase 1 roster agents (see `team/README.md`).

package/presets/cursor/mcp-ts/team/fixtures/bugfix-standard.json

@@ -0,0 +1,32 @@
+{
+  "slug": "example-schema-bugfix",
+  "intent": "bugfix",
+  "profile": "standard",
+  "summary": "Fix schema validation rejecting valid tool input",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Reproduce + AC"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Fix schema/handler + tests"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "security-reviewer",
+      "reason": "Proven schema/style-only bugfix — no auth/**, secrets, or FS/net capability change (document skip; otherwise route security-reviewer)"
+    },
+    {
+      "agent": "solution-architect",
+      "reason": "Localized schema bugfix"
+    }
+  ]
+}

package/presets/cursor/mcp-ts/team/fixtures/feature-full.json

@@ -0,0 +1,33 @@
+{
+  "slug": "example-add-tool-full",
+  "intent": "feature",
+  "profile": "full",
+  "summary": "Add MCP tool with schema, handler, registration, and tests",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Brief + decomposition"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "contract→schema→handler→register→test→package"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Capability / secrets review",
+      "model": "strong"
+    }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "solution-architect",
+      "reason": "Straightforward tool add; architecture spike not required"
+    }
+  ]
+}

package/presets/cursor/mcp-ts/team/fixtures/feature-light.json

@@ -0,0 +1,34 @@
+{
+  "slug": "example-add-tool-light",
+  "intent": "feature",
+  "profile": "light",
+  "summary": "Add a single MCP tool with explicit AC",
+  "steps": [
+    {
+      "agent": "feature-developer",
+      "label": "Implement tool schema/handler/register",
+      "model": "cheap"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests",
+      "model": "cheap"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "task-analyst",
+      "reason": "Explicit AC and single-tool scope"
+    },
+    {
+      "agent": "security-reviewer",
+      "reason": "Light profile valid only with no FS/net/auth expansion — otherwise use standard/full and include security-reviewer"
+    },
+    {
+      "agent": "solution-architect",
+      "reason": "Light profile — no architecture spike"
+    }
+  ]
+}

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

@@ -37,7 +37,7 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 3. **Mapping / README:** `claude/next/rules/README.md` must include a Cursor→Claude mapping table; stack `rules/README.md` should document core→stack mapping when `_shared` consumers exist.
 4. **shared-core consumers:** if `_shared/core/**` changed, every file with matching `<!-- shared-core: … -->` in this PR must be updated (or intentional fork documented in validation-report).
 5. **Twin presence:** Cursor rule change without Claude twin same PR → **FAIL** (next, ios-swift, go, and java). Domain twin body ≥15 lines; thin aliases (`agent-team-intake`, `technical-retro`) may be shorter.
-6. **Session-start body budget (soft→document, FAIL if grossly over):** sum body lines of the **3** intended always-on / session-start rules ≤ **120** (stretch ≤100); do **not** include `**/README.md`. Record the sum in validation-report.
+6. **Session-start body budget (soft→document, FAIL if grossly over):** sum body lines of the **3** intended always-on / session-start rules ≤ **140** (stretch ≤120); do **not** include `**/README.md`. Record the sum in validation-report.
 7. **Embed drift (hard in `check:preset-structure`):** run `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1` (bundled by the structure orchestrator). Lineage stems are excluded from body equality.
 8. **Dogfood (monorepo soft):** if root `.cursor/` is in the PR, prefer sync via `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass deletion of tracked dogfood without migration doc → note as risk / FAIL for maintainers.
 

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

@@ -17,7 +17,8 @@ alwaysApply: false
 
 - `next` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
 - `ios-swift` must not ship Playwright handoffs or Next lint recipes as required commands.
-- `go` / `java` must not ship Playwright, XCUITest, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
+- `go` / `java` / `mcp-ts` must not ship Playwright, XCUITest, 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`).
 
 ## Forbidden in ios-swift hooks/agents (FAIL)
@@ -46,6 +47,18 @@ Shared backend-stack bans (both `go` and `java`):
 
 Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`) or `java-tooling` (`mvn test` / `./gradlew test`).
 
+## Forbidden in mcp-ts hooks/agents (FAIL)
+
+Same UI/mobile bans as backend stacks, plus:
+
+- `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
+- Positive yarn recipes `lint:js` / `lint:css` as required gates
+- `xcuitest-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-*`, `integration-test-*`, `accessibility-reviewer`
+
+Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`, `post-change-test`); Phase 1 gates `build-verifier` + `security-reviewer`.
+
 ## Soft / document
 
 - Mentioning the other stack in **docs** comparing presets is OK.
@@ -53,4 +66,4 @@ Required instead: `integration-test-*`; build-verifier / `post-change-test` plus
 
 ## Chain fork
 
-`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, `go`, and `java` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, `go`, `java`, and `mcp-ts` (per platform).

package/presets/cursor/next/rules/preset-token-budget.mdc

@@ -22,7 +22,7 @@ alwaysApply: false
 
 **Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
 
-Session-start body budget (где задокументировано): ≤120 строк суммарно (stretch ≤100).
+Session-start body budget (где задокументировано): ≤140 строк суммарно (stretch ≤120).
 
 ## Meta / author rules
 

package/presets/cursor/next/rules/preset-twin-sync.mdc

@@ -21,6 +21,7 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 | `ios-swift` | `presets/cursor/ios-swift/rules/*.mdc` | `presets/claude/ios-swift/rules/<topic>/` | Keep in `claude/ios-swift/rules/README.md` |
 | `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Keep in `claude/go/rules/README.md` |
 | `java` | `presets/cursor/java/rules/*.mdc` | `presets/claude/java/rules/<topic>/` | Keep in `claude/java/rules/README.md` |
+| `mcp-ts` | `presets/cursor/mcp-ts/rules/*.mdc` | `presets/claude/mcp-ts/rules/<topic>/` | Keep in `claude/mcp-ts/rules/README.md` |
 
 ## Same-PR checklist
 
@@ -40,5 +41,6 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 - **ios-swift:** missing Claude twin for a changed Cursor rule → **FAIL**.
 - **go:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift; mapping table required).
 - **java:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go; mapping table required).
+- **mcp-ts:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java; mapping table required).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.