@bonesofspring/ai-rules 0.2.9 → 0.2.11

package/presets/claude/mcp-ts/rules/api-and-data/mcp-auth-secrets.md

@@ -0,0 +1,44 @@
+---
+description: MCP env config, remote auth, redaction, secret handling
+paths:
+  - **/auth/**/*
+  - **/config/**/*
+  - **/.env*
+  - **/secrets/**/*
+---
+
+# MCP auth and secrets
+
+## Local stdio
+
+- Prefer env-based configuration for API keys and tokens; never commit live secrets.
+- Redact secrets in logs, error strings, and tool results.
+- Handlers receive only the credentials they need via narrow capability adapters — not `process.env` wholesale.
+
+## Remote / HTTP servers
+
+When remote transport is enabled (see `mcp-transport-packaging`):
+
+- Choose an auth mode explicitly (none only for trusted local-only; bearer/OAuth when exposed).
+- Fail closed when required auth config is missing in non-dev environments.
+- **Per-request authorization (required for bearer/OAuth):** on every request, validate token **issuer**, **audience**, **expiry**, and **scopes/roles** before tool/resource/prompt dispatch. Reject with a safe error if any check fails.
+- Place the authenticated principal (subject + granted scopes) into a **trusted request context** owned by the transport/auth layer — handlers must not re-parse raw `Authorization` headers.
+- Authorize each tool/resource against that context (capability ≠ “any authenticated caller”).
+- Validate and canonicalize untrusted inputs at the boundary before handlers run.
+- **TLS required** for any non-localhost exposure (or a trusted TLS-terminating proxy with a documented trust boundary). Never send bearer/OAuth tokens in plaintext over the network. Bind `127.0.0.1` for local remote-dev; treat `0.0.0.0` as exposed.
+- Safe errors: no token, cookie, or raw header echo in HTTP or tool error bodies.
+- OAuth redirect URIs: allowlist exact redirect targets — reject open redirects.
+
+## Forbidden
+
+- Hardcoded API keys/tokens in source or example configs with live-looking values.
+- Returning raw Authorization headers, cookies, or private keys in tool output.
+- Broad filesystem or network tools that inherit ambient credentials without AC.
+- Trusting client-supplied identity claims without server-side token validation.
+- Putting live tokens into shipped client `mcp.json` / `.mcp.json`.
+
+## Tests
+
+- Negative fixtures: logs/results must not contain bearer tokens or secret env values.
+- Misconfigured auth refuses to start or rejects requests (fail closed).
+- Expired / wrong-audience / insufficient-scope tokens are rejected before handlers run.

package/presets/claude/mcp-ts/rules/api-and-data/mcp-contract-testing.md

@@ -0,0 +1,42 @@
+---
+description: MCP schema snapshots, contract fixtures, optional Inspector smoke
+paths:
+  - **/*.{test,spec}.{ts,tsx,js}
+  - **/fixtures/**/*
+  - src/tools/**/*
+  - src/resources/**/*
+  - src/prompts/**/*
+---
+
+# MCP contract testing
+
+Protect tool/resource/prompt **schemas and protocol behavior** — not browser E2E and not Go/Java adapter integration suites.
+
+## What to cover
+
+1. **Schema snapshots / fixtures** — registered input/output JSON Schema (or SDK registration result) matches the intended contract.
+2. **Handler unit tests** — validated inputs → expected results/errors (table-driven).
+3. **Compatibility** — additive changes OK; breaking field renames/removals need versioning or new tool names.
+4. **Inspector smoke (optional)** — MCP Inspector CLI may be used as evidence; it is **not** a required Phase 1 gate.
+
+## Workflow (Phase 1)
+
+- `feature-developer` owns contract verification inline (no `contract-test-*` agents yet).
+- Prefer repository test runner discovered via `mcp-ts-tooling`.
+- Store fixtures next to tools/tests (`*.fixture.json`, schema snapshots) per repo convention.
+
+## Security negatives (when capability touches FS / net / auth)
+
+Require at least one deny fixture per exposed capability:
+
+- FS: path traversal / outside-root rejected; secret paths not readable without AC.
+- Net: blocked host / metadata IP rejected; allowlisted host OK.
+- Auth: expired / wrong-audience / insufficient-scope rejected before handler; results must not echo tokens (`mcp-auth-secrets`).
+
+Align shapes with `tests-unit` and `security-mcp`.
+
+## Anti-patterns
+
+- Claiming "works in Inspector" without schema/unit coverage for the change.
+- Testing only TypeScript types without runtime validation of invalid inputs.
+- Requiring Playwright, XCUITest, or Next e2e paths.

package/presets/claude/mcp-ts/rules/api-and-data/mcp-tool-design.md

@@ -0,0 +1,37 @@
+---
+description: MCP tool/resource/prompt design: names, schemas, errors, least surprise
+paths:
+  - src/tools/**/*
+  - src/resources/**/*
+  - src/prompts/**/*
+---
+
+# MCP tool design
+
+Model-facing tools, resources, and prompts are **public contracts**. Optimize for least surprise for the calling model.
+
+## Names and descriptions
+
+- Use stable, verb-oriented tool names (`read_file`, `list_tickets`) — not internal codenames.
+- Descriptions must state **what** the tool does, **when** to use it, and key constraints (side effects, required scopes).
+- Prefer enums / closed sets over free-form strings when the domain is finite.
+- Document idempotency and destructive effects explicitly in the description.
+
+## Schemas (Zod-first authoring)
+
+- Author validation with **Zod** (or the repo's schema library) for TypeScript types + runtime checks.
+- MCP-facing input/output schemas are **JSON Schema-compatible protocol contracts**.
+- Convert with an **SDK-supported** path — never pass a Zod object as the wire schema without verifying the installed `@modelcontextprotocol/sdk` API.
+- When unsure: `// VERIFY: @modelcontextprotocol/sdk @ <version>` and look up docs (Context7).
+
+## Errors and results
+
+- Map failures to clear, actionable error messages; do not leak stack traces, secrets, or absolute internal paths.
+- Keep success payloads structured and stable; avoid dumping entire process env or large blobs by default.
+- Version breaking schema changes (new tool name or documented major) rather than silently reshaping fields.
+
+## Anti-patterns
+
+- Generic "execute_anything" / "run_shell" tools without AC and capability scoping.
+- Duplicated ad-hoc schemas in registration and handler.
+- Side effects inside registration helpers.

package/presets/claude/mcp-ts/rules/api-and-data/mcp-transport-packaging.md

@@ -0,0 +1,43 @@
+---
+description: MCP stdio lifecycle, optional remote transport, bin/npx packaging
+paths:
+  - src/index.ts
+  - package.json
+  - **/Dockerfile
+  - **/docker-compose*.yml
+---
+
+# MCP transport and packaging
+
+## Default: stdio
+
+- Local Cursor/Claude use → **stdio** transport from the server entry (`src/index.ts` or equivalent).
+- Entry owns connect/listen lifecycle and graceful shutdown; tools must not open competing transports.
+- Fail closed on missing required startup configuration.
+
+## Packaging
+
+- Expose a `bin` / `npx`-friendly entry in `package.json` that runs the compiled or `tsx` entry as appropriate for the repo.
+- Keep `files` / publish contents minimal; do not ship secrets, `.env`, or local credentials.
+- Document install and run commands in the consumer README — not by registering a half-built server into shipped client MCP JSON.
+
+## Optional remote transport
+
+- Streamable HTTP / SSE / remote hosting is **opt-in** — load this rule + `mcp-auth-secrets` + `security-mcp`.
+- Require explicit AC for auth mode, network exposure, and rate limits.
+- Before exposing remotely: implement **per-request** token validation (issuer/audience/expiry/scopes) and trusted request context per `mcp-auth-secrets`; treat retrieved content as untrusted per `security-mcp`.
+- Do not mandate Docker/OAuth/Inspector for every stdio-only server.
+
+## Threat model by transport
+
+| Mode | Trust boundary | Who can invoke tools | Required controls |
+|------|----------------|----------------------|-------------------|
+| **stdio** (default) | Same machine / IDE process | Host user + IDE agent session | Least-privilege tools; no network AuthN assumed; secrets via env; fail closed on missing config |
+| **HTTP / SSE** (opt-in) | Network-reachable process | Any client that can reach bind address | **TLS required** for non-localhost (or trusted TLS-terminating proxy with documented boundary); localhost-only bind OK without TLS; auth fail-closed; per-request issuer/audience/expiry/scopes; rate limits; safe errors (no token echo) |
+
+- Prefer bind `127.0.0.1` for local remote-dev; treat `0.0.0.0` as production exposure needing AC + TLS (or documented TLS-terminating proxy). Never expose bearer/OAuth over plaintext off-localhost.
+- Stdio inherits host privileges — do not compensate by adding “execute anything” tools.
+
+## VERIFY
+
+- Transport constructor and `Server` / `McpServer` APIs drift across SDK versions — verify against the installed package before inventing calls.

package/presets/claude/mcp-ts/rules/architecture/README.md

@@ -0,0 +1,3 @@
+# architecture
+
+Boundaries, feature delivery, reference features.

package/presets/claude/mcp-ts/rules/architecture/feature-delivery.md

@@ -0,0 +1,45 @@
+---
+description: End-to-end delivery checklist for TypeScript MCP features
+paths:
+  - src/**/*
+  - package.json
+---
+
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (TypeScript MCP)
+
+Order of work:
+
+1. **Contract** — tool/resource/prompt name, description, input/output shape (`mcp-tool-design`).
+2. **Schema** — Zod authoring + JSON Schema-compatible registration (`mcp-ts-conventions`).
+3. **Handler** — validated inputs → scoped capability → safe result/error mapping.
+4. **Registration** — wire into server modules; keep entry (`src/index.ts`) free of tool business logic.
+5. **Tests** — unit + contract fixtures (`tests-unit`, `mcp-contract-testing`).
+6. **Package validation** — typecheck/test; optional Inspector smoke; `bin`/entry OK (`mcp-transport-packaging`).
+7. **Gate** — `post-change-test` (+ `mcp-ts-tooling`).
+
+```mermaid
+flowchart LR
+  C[Contract] --> S[Schema]
+  S --> H[Handler]
+  H --> R[Register]
+  R --> T[Unit/contract tests]
+  T --> P[Package validate]
+```
+
+## Matrix
+
+| Path | Rules |
+|------|-------|
+| `src/tools/**`, `src/resources/**`, `src/prompts/**` | `mcp-tool-design`, `mcp-server-boundaries` |
+| schemas / validation | `mcp-ts-conventions`, `mcp-contract-testing` |
+| `src/index.ts`, package `bin` | `mcp-transport-packaging` |
+| auth/config | `mcp-auth-secrets`, `security-mcp` |
+| After `*.ts` edits | `post-change-test` |
+
+## Anti-patterns
+
+- Monolithic `index.ts`; unscoped shell/FS tools; inventing SDK APIs; skipping schema tests "for speed".
+- Prescribing Go hexagonal folders or Next `app/src/**`.
+- Load `design-guidance` when assessing structure, smells, or pattern fit.

package/presets/claude/mcp-ts/rules/architecture/mcp-server-boundaries.md

@@ -0,0 +1,28 @@
+---
+description: MCP server module boundaries: registration, handler, capability, lifecycle
+---
+
+# Границы MCP-сервера
+
+Dependency direction:
+
+```text
+MCP client → transport/entry → registration → schema + handler → scoped capability
+```
+
+- **Registration** (`src/tools|resources|prompts`): owns protocol names, descriptions, schemas, result mapping. No unrelated side effects; no hidden validation skips.
+- **Handlers**: receive **validated** inputs; depend on **narrow** capability adapters (FS paths, APIs). No process-wide secrets, arbitrary filesystem, or ambient client state.
+- **Contracts**: tool/resource/prompt schemas are **versioned public interfaces**. Do not prescribe UI, DB controllers, or Go-style `domain/application/adapters` layouts.
+- **Startup / transport** (`src/index.ts`): owns transport selection, lifecycle, fail-closed config. Do not duplicate startup inside tools.
+
+# Edit bundles (load on matching paths)
+
+- `src/tools|resources|prompts/**` → `mcp-tool-design` (+ `mcp-contract-testing` when changing schemas)
+- `src/index.ts`, package/`bin` → `mcp-transport-packaging`
+- auth/config/env → `mcp-auth-secrets` + `security-mcp`
+- After `*.ts` edits → `post-change-test` (+ `mcp-ts-tooling`)
+
+# Требование к агенту
+
+- Keep registration, validation, and handlers separable — avoid a monolithic `index.ts`.
+- Prefer least privilege for every tool capability.

package/presets/claude/mcp-ts/rules/architecture/reference-features.md

@@ -0,0 +1,33 @@
+---
+description: Reference paths for MCP server layout (dogfood-aligned Phase 1)
+paths:
+  - src/**/*
+---
+
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features (mcp-ts) — Phase 1
+
+Canonical layout matches `dogfood/mcp-ts-sample/` (consumer repos may rename; prefer the same shapes).
+
+| Area | Example path | Glob hint |
+|------|--------------|-----------|
+| Entry / transport | `src/index.ts` | `src/index.ts` |
+| Tools | `src/tools/echo.ts` | `src/tools/**` |
+| Tool tests | `src/tools/echo.spec.ts` | `src/tools/**/*.{test,spec}.ts` |
+| Resources | `src/resources/` (optional) | `src/resources/**` |
+| Prompts | `src/prompts/` (optional) | `src/prompts/**` |
+| Schemas | colocated next to tool (or `schemas.ts`) | `**/schemas.ts`, `src/tools/**` |
+| Build output | `dist/index.js` | `dist/**` |
+
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.cursor/team/conventions.md`** (and Claude twin path if both tools installed).
+
+## Dogfood scenarios (Phase 1)
+
+1. `/task` add tool — contract → schema → handler → register → tests → package (`dogfood/mcp-ts-sample`).
+2. Schema validation bug — unit + contract fixtures on `src/tools/*.spec.ts`.
+3. Capability / secrets review — security-reviewer + `security-mcp` (e.g. FS allowlist tool when added).
+
+Init (maintainer): `node packages/ai-rules/bin/cli.js init cursor --preset mcp-ts --cwd dogfood/mcp-ts-sample` — do not commit generated `.cursor/` into the sample unless the team decides otherwise.

package/presets/claude/mcp-ts/rules/stack/README.md

@@ -0,0 +1,3 @@
+# stack
+
+Stack always-on / conventions (`mcp-ts-app-core`, `mcp-ts-conventions`).

package/presets/claude/mcp-ts/rules/stack/mcp-ts-app-core.md

@@ -0,0 +1,27 @@
+---
+description: TypeScript MCP stack, layout, stdio-first entry (mcp-ts preset)
+---
+
+# Стек и окружение
+
+Версии Node, TypeScript и `@modelcontextprotocol/sdk` — **из `package.json` / lockfile целевого репозитория**. Рамка preset:
+
+- **Язык / платформа:** TypeScript (Node); package manager — discover from lockfile / `packageManager`.
+- **SDK:** official `@modelcontextprotocol/sdk` — verify APIs before use (`VERIFY:` markers when unsure).
+- **Транспорт по умолчанию:** **stdio-first**; remote HTTP/auth — requestable rules only.
+- **Точка входа:** `src/index.ts` (or repo equivalent) owns transport + lifecycle — not individual tools.
+- **Тесты:** repository runner (Vitest/Jest/node:test); contract fixtures for schemas — see `mcp-contract-testing`.
+- **Наблюдаемость:** only if already in repo — never log secrets or full tool payloads with credentials.
+
+# Структура (suggested)
+
+```text
+src/index.ts                 # transport + server lifecycle
+src/tools/                   # tool registration + handlers
+src/resources/               # resource registration (if used)
+src/prompts/                 # prompt registration (if used)
+src/**/schemas.ts            # Zod authoring schemas
+package.json                 # bin / main for stdio packaging
+```
+
+Границы — **`mcp-server-boundaries`**. Tooling — requestable **`mcp-ts-tooling`**. После правок TS — **`post-change-test`**.

package/presets/claude/mcp-ts/rules/stack/mcp-ts-conventions.md

@@ -0,0 +1,29 @@
+---
+description: Strict TypeScript, Zod validation, safe errors, SDK verification for MCP
+paths:
+  - src/**/*.ts
+  - src/**/*.tsx
+---
+
+# TypeScript conventions (MCP servers)
+
+- Prefer **strict** TypeScript (`strict` true when adding a new tsconfig; do not weaken existing strictness without AC).
+- Validate tool inputs with Zod (or repo schema lib) **before** side effects.
+- Export narrow types for handler inputs inferred from schemas (`z.infer<typeof schema>`).
+- Errors returned to clients: safe messages; log details server-side with redaction.
+- Avoid `any`; prefer `unknown` + narrowing at boundaries.
+- SDK calls: confirm symbols against installed `@modelcontextprotocol/sdk` — use `// VERIFY: @modelcontextprotocol/sdk @ <version>` when unsure.
+- Do not invent hexagonal `internal/domain|application|adapters` layouts unless the target repo already uses them.
+
+## Registration flow
+
+1. Define Zod (or equivalent) input schema next to the tool.
+2. Map schema → JSON Schema / SDK registration shape the repo uses.
+3. Implement a pure handler that accepts validated args + narrow capability ports (FS/net/secrets).
+4. Register the tool once from the server entry (`src/index.ts` or a dedicated register module) — handlers must not open a second transport.
+5. Cover invalid inputs and happy path in colocated `*.spec.ts` / `*.test.ts` before packaging.
+
+## Errors and types
+
+- Prefer typed result/error unions over throwing across the MCP boundary when the SDK pattern allows.
+- Never put stack traces, env dumps, or tokens in tool results.

package/presets/claude/mcp-ts/rules/testing/README.md

@@ -0,0 +1,3 @@
+# testing
+
+Unit testing conventions.

package/presets/claude/mcp-ts/rules/testing/unit.md

@@ -0,0 +1,30 @@
+---
+description: Unit testing conventions for MCP handlers and schemas
+paths:
+  - **/*.{test,spec}.{ts,tsx,js}
+  - **/__tests__/**/*
+---
+
+# 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/claude/mcp-ts/rules/tooling-and-review/README.md

@@ -0,0 +1,3 @@
+# tooling-and-review
+
+Quality, tooling, security, agent-team, preset meta.

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

@@ -0,0 +1,23 @@
+---
+description: Suggest /task for work requests without a slash command (mcp-ts)
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+---
+
+<!-- shared-core: agent-team/agent-team-intake.md -->
+
+# Agent team intake
+
+When the user message looks like a **work request** (implement, add, fix, refactor, review MR, write tests, spike) — not a question about how code works:
+
+1. Prefer **`/task <their request>`** or invoke **task-router** first.
+2. Do not jump straight to coding without router + pipeline when scope is non-trivial.
+3. Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
+
+Exceptions: user explicitly says «без pipeline», «просто сделай», or continues an active slug.
+
+## Stack notes
+
+- Scope: TypeScript MCP server modules (`src/tools|resources|prompts`, `src/index.ts`) — not Next `app/src`, iOS `Features/`, Go `cmd/`/`internal/**`, or Playwright/XCUITest UI flows.
+- **Phase 1 override:** no `codebase-analyzer` agent. For explain-as-is («как работает X»), answer inline or load requestable MCP rules (`mcp-server-boundaries`, `mcp-tool-design`) — do **not** invoke a missing subagent.

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

@@ -0,0 +1,161 @@
+---
+description: Orchestrates the agent team via task-router and pipeline.json for mcp-ts presets
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+---
+
+<!-- shared-core: agent-team/agent-team-orchestrator.md -->
+
+# Agent team orchestrator
+
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.cursor/team/tasks/<slug>/` (Claude: `.claude/team/tasks/<slug>/`).
+
+Work request без `/task` — см. **agent-team-intake** (когда предлагать router вместо прямого кодинга).
+
+## Entry points
+
+| Command | When |
+|---------|------|
+| **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After human gate or pause |
+| `/feature-start <desc>` | Legacy: analyst-only start (no router) |
+| `/feature-continue <slug>` | Alias of task-continue |
+| `/technical-retro [slug]` | Retro with agent team block |
+
+## Roles (shared catalog)
+
+Roster of specialists is **stack-specific** (agent names and write scopes differ). See **Stack notes** in the stack adapter for the live Roles table. Common patterns:
+
+| Kind | Examples (names vary by stack) |
+|------|--------------------------------|
+| Planning | `task-router`, `task-analyst`, `solution-architect`, `migration-specialist` |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor` (no `accessibility-reviewer`) |
+| Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
+| Docs | `tech-writer` |
+
+**Cursor frontmatter:** all team pipeline agents use `readonly: false` so they can write team artifacts. Production/app restrictions live in the agent prompt body — do **not** set `readonly: true`.
+
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`.
+
+## Dynamic pipeline
+
+```mermaid
+flowchart TD
+  task["/task prompt"]
+  router["task-router"]
+  pipeline["pipeline.json"]
+  step0["steps 0..N"]
+  gate{"humanGates?"}
+  hook["subagentStop hook"]
+  retro["/technical-retro"]
+
+  task --> router
+  router --> pipeline
+  pipeline --> step0
+  step0 --> gate
+  gate -->|"/task-continue"| step0
+  step0 --> hook
+  hook --> step0
+  step0 --> retro
+```
+
+**Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
+
+## status.json (pipeline mode)
+
+```json
+{
+  "slug": "...",
+  "intent": "feature",
+  "pipelineIndex": 0,
+  "currentAgent": "task-analyst",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false
+}
+```
+
+| state | Meaning |
+|-------|---------|
+| `in_progress` | Current step running |
+| `completed` | Current step done; hook advances |
+| `awaiting_approval` | Human gate; wait for `/task-continue` |
+| `changes_requested` | Reviewer blocked; re-run developer (`retryAfterFix`) |
+| `validation_failed` | build-verifier failed; re-run developer then build-verifier |
+
+## Pipeline step options
+
+| Field | Use |
+|-------|-----|
+| `skipIf` | `debugger.fixed` / `ci-investigator.resolved` — hook skips step when artifact says fix applied |
+| `parallel: true` | `agent` is array — invoke **all** agents in one parent turn; each appends to `parallelCompleted` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only`, `preset-artifacts-only` — passed to developer/qa |
+| `model` | `cheap` \| `standard` \| `strong` — optional tier override |
+
+## Rules (strict)
+
+1. **`/task` always starts with task-router** (except user says "skip router" with documented pipeline).
+2. Read `pipeline.json` before every subagent invocation.
+3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
+4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
+5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`).
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
+7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
+8. When all steps complete, suggest `/technical-retro <slug>`.
+9. If `autoChain: false` in pipeline, do not rely on hook — manual step only.
+
+## Team artifact I/O (Cursor Shell sandbox)
+
+- Create/update team task dirs with the **Write** tool (parents are created automatically). Do **not** bootstrap slug dirs with Shell `mkdir -p` — default sandbox returns `Operation not permitted` (worse on macOS Desktop/Documents with TCC).
+- If Shell must touch team paths and fails with EPERM, retry with `required_permissions: ["all"]`. Prefer Write for artifacts.
+- Prefer repo under `~/Projects` / `WebstormProjects` over `~/Desktop` when using agent team heavily.
+
+## Invoking agents
+
+Use Task tool or `/agent-name`. Pass: slug, artifact paths, step `scope` if set.
+
+### Model when invoking (Task)
+
+1. Read `steps[i].model` if present; else use the agent’s frontmatter `model` (see `agents/README.md` matrix).
+2. Map abstract tiers:
+   - **`cheap`** → pass Task `model: "fast"` when the tool accepts it (or rely on agent `fast`).
+   - **`standard`** → omit Task `model` (frontmatter `inherit` / mid default).
+   - **`strong`** → **never** pass `fast`; rely on agent pin or parent Max model.
+3. Parallel steps: apply the step-level `model` to **each** agent in the array (or omit → each agent’s own frontmatter).
+
+After each agent completes, ensure `status.json` has `state: completed` (or `awaiting_approval` if gate applies).
+
+## Legacy mode
+
+If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+
+## Skip pipeline when
+
+Do **not** run `/task` + router for:
+
+- Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners.
+- Typo / one-file fix / trivial config with no architecture risk.
+- User explicitly says «без pipeline», «просто сделай», or continues an active slug.
+- Single-line `docs-only` with no code impact.
+
+Borderline work requests — см. **agent-team-intake**.
+
+## Auto-detection (optional)
+
+When user describes a **non-trivial task** (not a question), suggest `/task <message>` or run router if they agree.
+
+## Preset authoring
+
+When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync of presets), follow meta-rules: **preset-pr-checklist**, **preset-twin-sync**, **preset-layering**, **preset-token-budget**, **preset-no-cross-stack-leakage**.
+
+## Stack notes
+
+- Scope: TypeScript MCP server modules (`src/tools|resources|prompts`, `src/index.ts`) — not Next `app/src`, iOS `Features/`, or Go hexagonal trees.
+- **Phase 1 roster only:** `task-router`, `task-analyst`, `solution-architect`, `feature-developer`, `build-verifier`, `security-reviewer`.
+- **No** `accessibility-reviewer`, Playwright, XCUITest, `integration-test-*`, `contract-test-*`, or `codebase-analyzer` (Phase 2) — do not schedule them.
+- **Explain-as-is override:** shared catalog mentions `codebase-analyzer` — in Phase 1 answer inline or load requestable MCP rules; do not invoke a missing agent.
+- **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`.

package/presets/claude/mcp-ts/rules/tooling-and-review/anti-sycophancy-discipline.md

@@ -0,0 +1,34 @@
+---
+description: Anti-sycophancy discipline for code generation and review
+paths:
+  - **/*.ts
+  - **/*.tsx
+---
+
+<!-- shared-core: quality/anti-sycophancy-discipline.md -->
+
+# Anti-sycophancy discipline (requestable)
+
+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.
+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.
+5. **Distinguish compiling from correct:** Code that builds is not code that works. Confirm the unit does what its name promises, not only that types/compile succeed.
+6. **Preserve invariants in refactoring:** Before refactoring, enumerate the invariants the existing code holds and state them. After the refactor, verify each still holds.
+7. **Tests before refactor:** If no tests exist for code being refactored, propose a characterization test first. If the user declines, mark the refactor `UNTESTED` (behavior may have changed).
+8. **Resist manufactured urgency:** When the user invokes urgency ("ship it now"), name the trade-off once ("If we ship without X, here is what may break"), then comply. Do not repeat the warning or apologize in a loop.
+9. **Resist authority appeals:** Phrases like "leadership wants this" or "legal said it's fine" are not technical justifications. Evaluate on technical grounds.
+10. **Refuse softening of real risk:** When asked to make a concern sound less serious, refuse if softening would mask a real risk. If the risk is genuinely minor, comply and explain why.
+11. **Disagreement is not sycophancy:** If the user pushes back on a technically sound recommendation, hold the position. Update only on new evidence, not on emotional pressure or repetition.
+12. **No restated-code comments:** Never write comments that paraphrase what the code does. Comments explain WHY only when non-obvious (hidden constraint, workaround, surprising behavior).
+13. **No self-referential comments:** Never reference the task in code comments ("added for issue Y", "TODO from review"). Those belong in commits/PRs and rot as the codebase evolves.
+14. **Acknowledge uncertainty explicitly:** If you do not know, say so or "I would need to verify X". Do not invent a plausible-sounding answer.
+15. **Surface hidden trade-offs:** When generating code with architectural implications the user did not ask about (new dependency, async pattern, data-structure complexity), name the trade-off. Do not bury it.
+16. **Match verification to risk:** Trivial → syntax/type check. Logic → manual trace. Concurrency/state → written scenario. Skipping verification proportional to risk is the failure mode.
+17. **Honest status reporting:** When asked "is X done?", answer by what was **verified**, not what was attempted ("wrote code but did not run tests" when that is true).
+
+## Stack notes
+
+- **Phase 1:** load for `feature-developer` and parent review flows only. `debugger` / `ci-investigator` are Phase-2 reserved — ignore those agent names in the shared prose above until they ship.