@hivehub/rulebook 5.7.0 → 5.8.1

package/templates/libraries/python/PYTEST.md

@@ -0,0 +1,17 @@
+<!-- PYTEST:START -->
+# pytest Rules
+
+## Conventions
+- Use `pytest.fixture` with explicit `scope` (`"function"` default, `"session"` for expensive setup like DB engines).
+- Prefer `conftest.py` for shared fixtures; scope conftest files to the directory that needs them.
+- Use `pytest.mark.parametrize` for data-driven tests; name parameters descriptively with `ids=` when values are not self-documenting.
+- Assert with plain `assert` statements — pytest rewrites them for detailed diffs; avoid `unittest.TestCase` assertion methods.
+- Use `pytest-asyncio` with `asyncio_mode = "auto"` in `pyproject.toml` for async test functions; mark individual tests with `@pytest.mark.asyncio` only when not using auto mode.
+- Isolate side effects with `monkeypatch` or `unittest.mock.patch` as a context manager; prefer `monkeypatch` for environment variables and file system changes.
+
+## Avoid
+- Using `setup_method`/`teardown_method` — replace with fixtures using appropriate scope.
+- Importing test utilities from test files directly; put shared helpers in `conftest.py` or a `tests/helpers/` module.
+- Writing tests that depend on execution order — each test must be independently runnable.
+- Silencing warnings with `filterwarnings = "ignore"` globally; address root causes or scope suppressions narrowly.
+<!-- PYTEST:END -->

package/templates/libraries/python/SQLALCHEMY.md

@@ -0,0 +1,17 @@
+<!-- SQLALCHEMY:START -->
+# SQLAlchemy Rules
+
+## Conventions
+- Use SQLAlchemy 2.x-style mapped classes with `DeclarativeBase` and `Mapped[T]` / `mapped_column()` type annotations.
+- Create one `sessionmaker` / `async_sessionmaker` bound to the engine at startup; inject sessions via dependency injection, not global state.
+- Expire sessions explicitly after commit when needed (`session.expire_on_commit=False` for async patterns to avoid lazy-load errors).
+- Use `select()`, `update()`, `delete()` Core statements with ORM entities rather than legacy `session.query()` API.
+- Enable `echo=True` only in development; use `logging.getLogger("sqlalchemy.engine")` for production query logging.
+- Define relationships with `relationship()` and explicit `back_populates`; set `lazy="selectin"` or `lazy="joined"` deliberately.
+
+## Avoid
+- Mixing sync and async sessions in the same code path — choose one execution style per module.
+- Using `session.execute(text(...))` with f-strings — always bind parameters with `:name` placeholders.
+- Relying on implicit lazy loading in async contexts; it raises `MissingGreenlet` — load eagerly or use `selectinload`.
+- Calling `session.commit()` inside a repository method when the session lifecycle is owned by the caller.
+<!-- SQLALCHEMY:END -->

package/templates/libraries/rust/ACTIX.md

@@ -0,0 +1,17 @@
+<!-- ACTIX:START -->
+# Actix Web Rules
+
+## Conventions
+- Bootstrap with `HttpServer::new(|| App::new().service(...)).bind(addr)?.run().await`
+- Register shared data with `App::app_data(web::Data::new(state))`; extract it in handlers via `web::Data<T>`
+- Group related routes under `web::scope("/prefix")` and register with `App::service(scope)`
+- Use `web::Json<T>` extractor for request bodies; configure size limits via `web::JsonConfig::default().limit(bytes)`
+- Return `impl Responder` or `actix_web::Result<impl Responder>`; use `HttpResponse::Ok().json(body)` for JSON responses
+- Define custom error types implementing `actix_web::ResponseError` to produce structured error responses with correct status codes
+
+## Avoid
+- Do not call blocking code directly in handler async functions — use `web::block(|| ...)` to offload to the blocking thread pool
+- Do not hold `Mutex`-locked state across `.await` points inside handlers; deadlocks are silent
+- Do not clone `web::Data<T>` to pass ownership — `Data<T>` is already an `Arc` wrapper, pass it directly
+- Do not ignore the `JsonConfig` error handler; without it, malformed JSON returns a generic 400 with no actionable message
+<!-- ACTIX:END -->

package/templates/libraries/rust/AXUM.md

@@ -0,0 +1,18 @@
+<!-- AXUM:START -->
+# Axum Rules
+
+## Conventions
+- Define routes with `Router::new().route("/path", get(handler))` and compose sub-routers via `Router::merge` or `Router::nest`
+- Extract shared state via `State<Arc<AppState>>` derived from `axum::extract::State`; register it with `Router::with_state`
+- Use typed extractors (`Json<T>`, `Path<T>`, `Query<T>`) as handler function arguments; let Axum reject invalid requests automatically
+- Return `impl IntoResponse` from handlers; use `(StatusCode, Json<T>)` tuples or a custom error type that implements `IntoResponse`
+- Apply middleware with `tower::ServiceBuilder` and `.layer()`; keep middleware order explicit (outermost = first to run)
+- Handle errors uniformly: define an `AppError(anyhow::Error)` newtype that implements `IntoResponse` returning structured JSON
+- Use `axum::serve(listener, app)` (axum 0.7+) instead of the deprecated `axum::Server::bind`
+
+## Avoid
+- Do not store non-`Clone` or non-`Send` types directly in `State`; wrap in `Arc<Mutex<T>>` when mutation is needed
+- Do not ignore extractor rejection by returning `200 OK` — let the extractor's `rejection` propagate or map it explicitly
+- Do not mix `axum` 0.6 and 0.7 APIs in the same project; the handler and middleware traits changed incompatibly
+- Do not spawn blocking work inside async handlers — use `tokio::task::spawn_blocking` instead
+<!-- AXUM:END -->

package/templates/libraries/rust/SERDE.md

@@ -0,0 +1,16 @@
+<!-- SERDE:START -->
+# Serde Rules
+
+## Conventions
+- Derive `Serialize, Deserialize` on data types; add `#[serde(deny_unknown_fields)]` on strict API contracts to reject unexpected keys
+- Use `#[serde(rename_all = "camelCase")]` at the struct level instead of per-field `rename` for consistent naming conventions
+- Mark optional fields with `#[serde(skip_serializing_if = "Option::is_none")]` to keep serialized output clean
+- Use `#[serde(default)]` on fields that should fall back to `Default::default()` when the key is absent during deserialization
+- For enums, use `#[serde(tag = "type")]` (internally tagged) or `#[serde(untagged)]` to control the wire representation explicitly
+- Use `#[serde(with = "module")]` or `#[serde(serialize_with / deserialize_with)]` to apply custom logic to individual fields without newtype wrappers
+
+## Avoid
+- Do not use `serde_json::Value` as a field type when the shape is known — use a concrete type for compile-time guarantees
+- Do not derive `Deserialize` on types with `#[non_exhaustive]` without `#[serde(deny_unknown_fields)]`; silent data loss is likely
+- Do not mix `#[serde(flatten)]` with `#[serde(deny_unknown_fields)]` on the same struct — the combination is unsupported and panics at runtime
+<!-- SERDE:END -->

package/templates/libraries/rust/SQLX.md

@@ -0,0 +1,17 @@
+<!-- SQLX:START -->
+# SQLx Rules
+
+## Conventions
+- Use `sqlx::query_as!` and `sqlx::query!` macros for compile-time verified SQL; set `DATABASE_URL` at build time for macro expansion
+- Create a connection pool with `PgPoolOptions::new().max_connections(N).connect(url).await?` and share it via `Arc` or framework state
+- Run migrations at startup with `sqlx::migrate!("./migrations").run(&pool).await?`; keep migration files append-only
+- Use `query.fetch_one`, `fetch_optional`, and `fetch_all` purposefully — `fetch_one` returns an error on zero rows; `fetch_optional` does not
+- Wrap multi-statement operations in `pool.begin().await?` and call `tx.commit().await?` explicitly; `tx.rollback()` is called on drop
+- Bind user input exclusively through `query.bind(value)` — never interpolate values into raw SQL strings
+
+## Avoid
+- Do not use `query!` macros pointing to a non-existent or out-of-date schema — the compile error is cryptic; run pending migrations first
+- Do not acquire a connection manually from the pool (`pool.acquire()`) when `pool` itself implements `Executor` and can be passed directly
+- Do not ignore `RowNotFound` from `fetch_one` — map it to a domain-level `NotFound` error before it reaches the API layer
+- Do not store `PoolConnection<Db>` in long-lived structs; connections should be borrowed for a single logical operation, then released
+<!-- SQLX:END -->

package/templates/libraries/rust/TOKIO.md

@@ -0,0 +1,16 @@
+<!-- TOKIO:START -->
+# Tokio Rules
+
+## Conventions
+- Annotate the main entry point with `#[tokio::main]`; use `#[tokio::main(flavor = "current_thread")]` for single-threaded scenarios
+- Spawn independent tasks with `tokio::spawn`; always `.await` or store the returned `JoinHandle` to surface panics
+- Use `tokio::sync::Mutex` (not `std::sync::Mutex`) when the lock must be held across `.await` points
+- Prefer `tokio::sync::mpsc` for task communication and `tokio::sync::broadcast` for fan-out messaging
+- Use `tokio::time::timeout(duration, future)` to add cancellation deadlines; handle `Elapsed` explicitly
+- Offload CPU-bound or blocking I/O with `tokio::task::spawn_blocking`; never call `std::thread::sleep` inside async code
+
+## Avoid
+- Do not hold a `std::sync::MutexGuard` across an `.await` — the future is not `Send` and the runtime can deadlock
+- Do not `unwrap()` on `JoinHandle` results without checking for panics; use `handle.await?` or inspect the `JoinError`
+- Do not create a second `#[tokio::main]` runtime inside an existing async context — use `tokio::runtime::Handle::current()` instead
+<!-- TOKIO:END -->

package/templates/libraries/typescript/ANGULAR.md

@@ -0,0 +1,17 @@
+<!-- ANGULAR:START -->
+# Angular Rules
+
+## Conventions
+- Use standalone components (`standalone: true`) for all new code; NgModules are legacy in Angular 17+
+- Inject dependencies with the `inject()` function inside the constructor or field initializer instead of constructor parameter injection for standalone
+- Use signals (`signal()`, `computed()`, `effect()`) for reactive local state in Angular 17+; prefer over `BehaviorSubject` for component state
+- Use the `@if`, `@for`, `@switch` built-in control flow blocks (Angular 17+) instead of `*ngIf`/`*ngFor` structural directives
+- Always unsubscribe from Observables — prefer `takeUntilDestroyed()` from `@angular/core/rxjs-interop`
+- Type HTTP responses with generics: `HttpClient.get<MyType>(url)` — never cast with `as`
+
+## Avoid
+- Using `any` type for component inputs or service return values
+- Manually calling `ChangeDetectorRef.detectChanges()` when signals or `async` pipe would handle it
+- Subscribing inside templates — use the `async` pipe or signal reads
+- Importing `CommonModule` in standalone components — import specific directives instead
+<!-- ANGULAR:END -->

package/templates/libraries/typescript/DRIZZLE.md

@@ -0,0 +1,16 @@
+<!-- DRIZZLE:START -->
+# Drizzle ORM Rules
+
+## Conventions
+- Define schema in dedicated `schema.ts` files co-located by domain; export tables and inferred types together
+- Use `drizzle-zod` or `drizzle-valibot` to derive insert/select validation schemas from table definitions — single source of truth
+- Use `db.transaction(async (tx) => { ... })` for atomic multi-step operations; pass `tx` to all writes inside
+- Prefer `.returning()` after inserts/updates instead of a separate select round-trip
+- Type query results with `typeof table.$inferSelect` and `typeof table.$inferInsert` — never manually duplicate column types
+- Use `sql` tagged template from `drizzle-orm` for raw SQL fragments; never interpolate user input directly
+
+## Avoid
+- Importing the db instance inside schema files — schema must be a pure declaration with no runtime dependencies
+- Running `drizzle-kit push` in production — use `drizzle-kit generate` + migration files for reproducible deploys
+- Chaining `.where()` conditions with string concatenation — use `and()`, `or()`, `eq()` operators from `drizzle-orm`
+<!-- DRIZZLE:END -->

package/templates/libraries/typescript/EXPRESS.md

@@ -0,0 +1,17 @@
+<!-- EXPRESS:START -->
+# Express Rules
+
+## Conventions
+- Type request and response with generics: `Request<Params, ResBody, ReqBody, Query>` — avoids `any` in handlers
+- Use a centralized error-handling middleware `(err, req, res, next): void` registered last with four parameters
+- Validate request bodies, params, and query strings at the route level before business logic — use Zod or a validation middleware
+- Group routes by domain in separate `express.Router()` instances and mount them in `app.ts`
+- Use `express.json()` and `express.urlencoded()` middleware explicitly — do not rely on body parsing being enabled by default
+- Return consistent JSON error shapes: `{ error: string; code?: string }` — never leak stack traces in production
+
+## Avoid
+- Calling `next()` after sending a response — it triggers double-response errors
+- Using `req.query` values as raw strings in database queries — always validate and sanitize
+- Defining async route handlers without wrapping in a try/catch or using an async error wrapper — unhandled promise rejections bypass the error middleware
+- Mutating `req.body` directly — treat it as read-only input
+<!-- EXPRESS:END -->

package/templates/libraries/typescript/HEROUI.md

@@ -0,0 +1,16 @@
+<!-- HEROUI:START -->
+# HeroUI Rules
+
+## Conventions
+- Wrap the app in `<HeroUIProvider>` at the root; pass `navigate` from your router for link support
+- Use the `color`, `variant`, and `size` props from the component API instead of overriding with raw Tailwind classes
+- Extend or override tokens via `heroui()` plugin in `tailwind.config.ts` — never patch component internals
+- Use `classNames` prop (object with slot keys) for targeted per-slot styling instead of wrapping with extra divs
+- Prefer controlled components (`value` + `onChange`) for form inputs to keep state in one place
+- Use `isDisabled`, `isLoading`, and `isInvalid` boolean props rather than custom conditional classes
+
+## Avoid
+- Importing components from deep internal paths — always import from `@heroui/react`
+- Overriding component styles with `!important` — use slot-based `classNames` instead
+- Rendering HeroUI components outside `<HeroUIProvider>` — theme context will be missing
+<!-- HEROUI:END -->

package/templates/libraries/typescript/JEST.md

@@ -0,0 +1,17 @@
+<!-- JEST:START -->
+# Jest Rules
+
+## Conventions
+- Use `jest.config.ts` (TypeScript) with `ts-jest` or `@swc/jest` transform for type-safe configuration
+- Mock modules with `jest.mock('../path/to/module')` at the top of the file — Jest hoists these automatically
+- Use `jest.spyOn(object, 'method').mockReturnValue(value)` for partial mocks; restore with `jest.restoreAllMocks()` in `afterEach`
+- Use `expect.assertions(n)` in async tests that rely on callbacks to catch silent failures
+- Use `jest.useFakeTimers()` for time-dependent tests; advance with `jest.advanceTimersByTimeAsync(ms)` (Jest 29+)
+- Isolate module state between tests with `jest.isolateModules()` when a module has side-effectful initialization
+
+## Avoid
+- Using `test.only` or `fdescribe` — remove before committing
+- Mocking entire large modules when only one method needs to change — use `spyOn` for surgical mocking
+- Relying on test execution order — each test must set up and tear down its own state independently
+- Using `done` callback pattern for async tests — use `async/await` or return a Promise instead
+<!-- JEST:END -->

package/templates/libraries/typescript/NESTJS.md

@@ -0,0 +1,17 @@
+<!-- NESTJS:START -->
+# NestJS Rules
+
+## Conventions
+- Use constructor injection for all dependencies — never instantiate services manually inside other services
+- Validate all incoming DTOs with `class-validator` decorators and enable `ValidationPipe` globally with `whitelist: true, forbidNonWhitelisted: true`
+- Use `@nestjs/config` with a typed `ConfigService` — never read `process.env` directly outside of config factories
+- Scope providers explicitly: default (singleton) for stateless services; `REQUEST` scope only when truly per-request state is needed
+- Use `@nestjs/swagger` decorators (`@ApiProperty`, `@ApiResponse`) on DTOs and controllers to keep OpenAPI spec in sync with code
+- Handle async lifecycle with `OnModuleInit` and `OnApplicationShutdown` hooks — not ad-hoc timeouts
+
+## Avoid
+- Using `@Inject(TOKEN)` with string tokens for services that can be injected by class reference — string tokens lose type safety
+- Throwing raw `Error` objects — use NestJS built-in exceptions (`NotFoundException`, `BadRequestException`, etc.)
+- Circular module imports — restructure with a shared module or `forwardRef()` only as a last resort
+- Putting business logic in controllers — controllers are thin; all logic belongs in services
+<!-- NESTJS:END -->

package/templates/libraries/typescript/NEXT.md

@@ -0,0 +1,18 @@
+<!-- NEXT:START -->
+# Next.js Rules
+
+## Conventions
+- Use the App Router (`app/`) for all new projects; Pages Router is legacy
+- Mark components `"use client"` only when they require browser APIs or interactivity; keep the default server-component boundary
+- Fetch data in Server Components using `async/await` directly — avoid `useEffect` data fetching
+- Use `next/image` for all images with explicit `width`/`height` or `fill` to avoid layout shift
+- Colocate route-specific logic in `app/<segment>/page.tsx`; share layouts via `layout.tsx`
+- Use `next/font` to load fonts — never load external font URLs in `<head>` manually
+- Type `searchParams` and `params` as `Promise<...>` in Next.js 15+ page/layout props
+
+## Avoid
+- Importing server-only modules into Client Components (triggers runtime errors)
+- Using `getServerSideProps` or `getStaticProps` in the App Router — they don't exist there
+- Wrapping the entire app in `"use client"` — it defeats server rendering
+- Hardcoding `localhost` URLs; use environment variables for all API base URLs
+<!-- NEXT:END -->

package/templates/libraries/typescript/PRISMA.md

@@ -0,0 +1,16 @@
+<!-- PRISMA:START -->
+# Prisma Rules
+
+## Conventions
+- Instantiate `PrismaClient` once as a singleton and export it — never instantiate per-request (especially in Next.js dev with hot-reload)
+- Use `prisma.$transaction([...])` for multi-step writes that must be atomic; use the interactive transaction callback form for reads-then-writes
+- Always select only the fields you need with `select` or omit sensitive fields with `omit` — never return full records containing passwords/tokens
+- Use `include` for eager-loading relations; use nested `select` inside `include` to avoid over-fetching
+- Run `prisma migrate dev` in development and `prisma migrate deploy` in CI/production — never use `db push` in production
+- Type query results with `Prisma.UserGetPayload<{ select: { ... } }>` for precise return types
+
+## Avoid
+- Calling `prisma.$disconnect()` in serverless/edge functions per-invocation — let the connection pool manage lifecycle
+- Using raw `prisma.$queryRaw` without `Prisma.sql` tagged template — SQL injection risk
+- Checking `prisma.model.findFirst` for existence checks in a loop — use `findMany` with `where` or `count`
+<!-- PRISMA:END -->

package/templates/libraries/typescript/RADIX.md

@@ -0,0 +1,16 @@
+<!-- RADIX:START -->
+# Radix UI Rules
+
+## Conventions
+- Install individual `@radix-ui/react-<primitive>` packages — never install the entire `@radix-ui/react` meta-package
+- Compose primitives using the compound-component pattern (`Dialog.Root`, `Dialog.Trigger`, `Dialog.Content`, etc.) — never use internal sub-components directly
+- Always provide accessible labels: use `VisuallyHidden` with `DialogTitle` / `AlertDialogTitle` to satisfy screen-reader requirements even when visually hidden
+- Forward refs through custom wrappers using `React.forwardRef` so Radix can attach behavior correctly
+- Control open state externally (`open` + `onOpenChange`) for dialogs and popovers that need lifecycle hooks (e.g., analytics, focus management)
+- Use `asChild` to delegate rendering to your own element without adding extra DOM nodes
+
+## Avoid
+- Styling Radix components by targeting generated class names — use `data-*` attribute selectors (`data-state="open"`)
+- Mixing multiple open-state sources (both `defaultOpen` and `open`) on the same component
+- Removing `Dialog.Overlay` to skip the backdrop — it handles focus-trap and pointer-event blocking
+<!-- RADIX:END -->

package/templates/libraries/typescript/REACT.md

@@ -0,0 +1,18 @@
+<!-- REACT:START -->
+# React Rules
+
+## Conventions
+- Use function components with hooks exclusively; never write class components in new code
+- Co-locate state as close to the consumer as possible; lift only when two or more siblings need it
+- Derive computed values inline or with `useMemo` — avoid storing derived state in `useState`
+- Stabilize callbacks passed to children with `useCallback` to prevent unnecessary re-renders
+- Use the `key` prop on list items with stable, unique IDs — never array indices for dynamic lists
+- Prefer `useReducer` over multiple `useState` calls when state transitions have logic dependencies
+- Type component props with explicit interfaces; avoid `React.FC` — declare return type as `React.ReactElement` when needed
+
+## Avoid
+- Mutating state directly — always return a new reference from `setState` / reducer
+- Triggering side effects during render (network calls, subscriptions outside `useEffect`)
+- Overusing `useEffect` for data that can be derived synchronously
+- Reading stale closure values — include all referenced variables in the `useEffect` dependency array
+<!-- REACT:END -->

package/templates/libraries/typescript/SHADCN.md

@@ -0,0 +1,16 @@
+<!-- SHADCN:START -->
+# shadcn/ui Rules
+
+## Conventions
+- Add components with `npx shadcn@latest add <component>` — components are copied into `components/ui/` and owned by your repo
+- Customize component source directly in `components/ui/` — shadcn/ui components are not a dependency, they are source code
+- Use the `cn()` utility (auto-generated in `lib/utils.ts`) for all className merging within component files
+- Keep shadcn/ui components as thin wrappers — add domain logic in separate consumer components, not inside `components/ui/`
+- Re-run `npx shadcn@latest add <component>` to pull upstream changes; review the diff before accepting
+- Use the `variant` and `size` props from `cva` variants instead of ad-hoc conditional classes
+
+## Avoid
+- Editing generated component files and then expecting `shadcn add` updates to merge cleanly — commit your customizations clearly
+- Importing directly from `@radix-ui/*` inside application code when a shadcn wrapper already exists
+- Adding business logic or data-fetching inside `components/ui/` files
+<!-- SHADCN:END -->

package/templates/libraries/typescript/SVELTE.md

@@ -0,0 +1,16 @@
+<!-- SVELTE:START -->
+# Svelte Rules
+
+## Conventions
+- Use Svelte 5 runes (`$state`, `$derived`, `$effect`, `$props`) for all new code; legacy reactive declarations (`$:`) are deprecated
+- Declare component props with `let { propName } = $props()` and type them with TypeScript interfaces
+- Use `$derived` for computed values instead of `$effect` with an intermediate variable
+- Scope side effects that depend on reactive state inside `$effect`; clean up by returning a teardown function
+- Use `{#each items as item (item.id)}` with a key expression to enable efficient DOM reconciliation
+- Prefer Svelte stores (`writable`, `readable`, `derived`) for cross-component shared state
+
+## Avoid
+- Using `$effect` to synchronize two pieces of state — use `$derived` instead
+- Directly mutating arrays/objects in `$state` without reassignment when deep reactivity is needed — use `$state` with structural replacement or `SvelteMap`/`SvelteSet`
+- Importing browser globals at module level — guard with `if (browser)` from `$app/environment`
+<!-- SVELTE:END -->

package/templates/libraries/typescript/TAILWIND.md

@@ -0,0 +1,16 @@
+<!-- TAILWIND:START -->
+# Tailwind CSS Rules
+
+## Conventions
+- Compose utilities directly in markup; extract to components or `@apply` only for highly repeated multi-class patterns
+- Use the `cn()` helper (clsx + tailwind-merge) to merge conditional classes — avoids specificity conflicts
+- Configure custom design tokens in `tailwind.config.ts` under `theme.extend` — never override the default scale unless intentional
+- Use `dark:` variant classes for dark mode; configure `darkMode: "class"` for manual toggle control
+- Prefer responsive prefixes (`sm:`, `md:`, `lg:`) on the variant side rather than writing separate media queries
+- Use `group` and `peer` utilities for parent-driven and sibling-driven state styling
+
+## Avoid
+- Mixing arbitrary values (`w-[347px]`) for dimensions that belong in the design token scale
+- Writing long `className` strings inline without `cn()` — order-dependent merges produce hard-to-debug styles
+- Using `!important` modifiers (`!text-red-500`) to override conflicts — fix the specificity root cause instead
+<!-- TAILWIND:END -->

package/templates/libraries/typescript/TRPC.md

@@ -0,0 +1,16 @@
+<!-- TRPC:START -->
+# tRPC Rules
+
+## Conventions
+- Define all procedures in a router tree and export the `AppRouter` type — this is the contract shared with the client
+- Validate all inputs with Zod schemas passed to `input()` — never trust raw input inside procedure handlers
+- Use `protectedProcedure` (a middleware-wrapped base procedure) to enforce authentication — never check session ad-hoc inside handlers
+- Use `useUtils()` (tRPC v11) for cache invalidation after mutations — call `utils.<router>.<procedure>.invalidate()`
+- Co-locate server-side router files under `server/routers/`; keep the client-side `trpc` init in a single `lib/trpc.ts`
+- Use `createCallerFactory` for server-side tRPC calls within Server Components or server actions — avoids HTTP round-trips
+
+## Avoid
+- Exposing the server router object to the client bundle — only the `AppRouter` type should cross the boundary
+- Returning raw database models from procedures — map to response DTOs to avoid leaking sensitive fields
+- Fetching data with `useQuery` inside event handlers — use `utils.<procedure>.fetch()` for imperative calls
+<!-- TRPC:END -->

package/templates/libraries/typescript/VITEST.md

@@ -0,0 +1,17 @@
+<!-- VITEST:START -->
+# Vitest Rules
+
+## Conventions
+- Configure Vitest in `vitest.config.ts` (not inside `vite.config.ts`) for clarity — use `defineConfig` from `vitest/config`
+- Use `vi.mock()` at the top of the file (hoisted automatically); use `vi.importMock()` for dynamic mocks
+- Reset mocks between tests with `vi.clearAllMocks()` in `afterEach` or set `clearMocks: true` globally in config
+- Use `expect.assertions(n)` in async tests that must reach a callback to prevent silent false-positives
+- Use `vi.useFakeTimers()` + `vi.runAllTimersAsync()` for testing debounce, throttle, and setTimeout logic
+- Type spy return values: `vi.spyOn(service, "method").mockResolvedValue(typed value)` — avoids `any` leaking into assertions
+
+## Avoid
+- Using `test.only` or `describe.only` — remove before committing; they silently skip all other tests
+- Importing from `vitest` and `jest` in the same file — pick one globals source
+- Asserting on implementation details (internal function call counts) when behavior tests suffice
+- Using `setTimeout` with real delays in tests — always fake timers for time-dependent logic
+<!-- VITEST:END -->

package/templates/libraries/typescript/VUE.md

@@ -0,0 +1,17 @@
+<!-- VUE:START -->
+# Vue Rules
+
+## Conventions
+- Use the Composition API with `<script setup>` for all new components; Options API is legacy
+- Declare reactive state with `ref()` for primitives and `reactive()` for objects; unwrap refs in templates automatically
+- Use `computed()` for derived state — never compute values inside templates beyond simple expressions
+- Define component props with `defineProps<{ ... }>()` using TypeScript generics for full type safety
+- Use `defineEmits<{ ... }>()` to type emitted events explicitly
+- Prefer `watch` with `{ immediate: true }` over duplicating logic in `onMounted` + `watch`
+
+## Avoid
+- Mutating props directly — emit an event and let the parent update state
+- Using `$refs` to imperatively manipulate child component internals
+- Mixing Composition API and Options API in the same component
+- Relying on `v-html` with unsanitized user input — XSS risk
+<!-- VUE:END -->

package/templates/libraries/typescript/ZOD.md

@@ -0,0 +1,17 @@
+<!-- ZOD:START -->
+# Zod Rules
+
+## Conventions
+- Define schemas once and derive TypeScript types with `z.infer<typeof schema>` — never duplicate types manually
+- Use `.parse()` at trust boundaries (API routes, form submissions, env vars); use `.safeParse()` when you need to handle errors without throwing
+- Coerce external string inputs (query params, form fields) with `z.coerce.number()` / `z.coerce.boolean()` instead of manual casting
+- Validate environment variables at startup with a Zod schema and export the typed result — fail fast on misconfiguration
+- Use `.transform()` to normalize data (e.g., trim strings, lowercase emails) in the same schema that validates it
+- Use `z.discriminatedUnion("type", [...])` for tagged union types — faster and produces better error messages than `z.union`
+
+## Avoid
+- Using `.optional()` on fields that should always be present — it widens the type unnecessarily
+- Calling `.parse()` on already-validated internal data — validate once at the boundary, pass typed values inward
+- Building complex conditional logic with `.superRefine()` when `.refine()` covers the case
+- Catching Zod errors generically — use `err instanceof ZodError` and inspect `err.errors` for structured messages
+<!-- ZOD:END -->