ai-ops-compiler 0.1.0

package/data/rules/flutter.yaml

@@ -0,0 +1,40 @@
+id: flutter
+category: framework
+tags:
+  - dart
+  - flutter
+  - riverpod
+  - mobile
+priority: 30
+content:
+  constraints:
+    - 'DO NOT use `dynamic` type. Use `Object` or sealed class + pattern matching instead.'
+    - 'DO NOT place business logic inside Widget `build()`. Widgets are UI declarations only; move logic to Notifier/Controller or `*.logic.dart` pure functions.'
+    - "DO NOT use StatefulWidget for shared state that outlives a single widget's lifecycle. Use Riverpod provider instead."
+    - 'DO NOT use GlobalKey to access widget state. Pass data via provider or callback props to preserve tree encapsulation.'
+    - 'DO NOT use mutable class fields. All fields must be `final`; use freezed/copyWith for data class updates.'
+    - 'DO NOT block the UI thread with heavy synchronous operations (e.g., large JSON parsing, image processing). Use `compute` or a dedicated Isolate.'
+  guidelines:
+    - 'Use Riverpod with code generation (`@riverpod` annotation). Co-locate providers with the feature directory that consumes them.'
+    - 'Adopt feature-first directory structure: `lib/features/<feature>/{view,model,provider,logic}`. Shared code goes in `lib/core/`.'
+    - 'Use sealed class + switch expression for union types (Dart 3 pattern). Apply to AsyncValue and Result patterns.'
+    - "Prefer `const` constructors on all widgets and data classes to enable Flutter's rebuild optimization."
+    - 'Use GoRouter for declarative routing and deep-link support. Avoid imperative `Navigator.push()`/`pop()`.'
+    - 'Use `freezed` (`@freezed` annotation) for immutable data classes to auto-generate copyWith, equality, and JSON serialization. Never implement `==`/`hashCode` manually.'
+    - 'Write widget tests with `pumpWidget` + `ProviderScope.overrides` for DI mocking. Test pure logic functions with plain unit tests.'
+    - 'Use `RepaintBoundary` to isolate expensive subtree repaints. Profile with Flutter DevTools before optimizing; avoid premature optimization.'
+    - 'Handle async states explicitly using Riverpod AsyncValue or a Result pattern (loading / success / failure). Set a global error boundary to prevent unhandled exceptions from reaching the UI.'
+    - 'Abstract all external data access behind a Repository interface. Providers must never call APIs or databases directly; they receive a Repository implementation via Riverpod DI.'
+  decision_table:
+    - when: 'State is ephemeral and scoped to a single widget (e.g., form field focus, animation toggle)'
+      then: 'Use StatefulWidget or flutter_hooks useState'
+      avoid: 'Creating a Riverpod provider for trivial local UI state'
+    - when: "State is shared across widgets or must persist beyond a single widget's lifecycle"
+      then: 'Use Riverpod Notifier or AsyncNotifier'
+      avoid: 'StatefulWidget with callback prop drilling or InheritedWidget'
+    - when: 'A data class requires equality, copyWith, or JSON serialization'
+      then: 'Annotate with `@freezed` and run build_runner'
+      avoid: 'Manually implementing `==`, `hashCode`, or `copyWith`'
+    - when: 'Navigating between screens or handling deep links'
+      then: 'Declare routes with GoRouter configuration'
+      avoid: 'Imperative Navigator.push() / Navigator.pop()'

package/data/rules/graphql.yaml

@@ -0,0 +1,34 @@
+id: graphql
+category: api
+tags:
+  - graphql
+  - api
+  - schema-design
+priority: 48
+content:
+  constraints:
+    - 'DO NOT rely on implicit nullability defaults. Every field MUST declare nullability explicitly — non-null (!) is the default intent; nullable fields are intentional design decisions (e.g., optional profile picture). Implicit nullability causes mismatches between schema and client expectations.'
+    - 'DO NOT perform side effects (data mutations) in Query resolvers. Reads belong in Query, writes belong in Mutation — strict separation ensures idempotent caching, safe retry behavior, and predictable client behavior.'
+    - 'DO NOT use a generic `Error` type as a return value. Define domain-specific union error types per operation (e.g., `union CreateUserResult = User | EmailTakenError | ValidationError`). Generic errors give clients no actionable structure for error handling.'
+    - 'DO NOT return unbounded lists. Every collection field MUST apply pagination (`first`/`after` for cursor-based or `limit`/`offset` for offset-based). Unbounded lists are a DoS vector and cause memory exhaustion at scale.'
+    - 'DO NOT expose internal implementation details in enum value names. Use SCREAMING_SNAKE_CASE semantic names (e.g., `PENDING`, `IN_PROGRESS`) — never leak DB column names, internal state machine names, or numeric codes that require server-side knowledge to interpret.'
+  guidelines:
+    - 'Prefer cursor-based pagination (`first`/`after`) using UUID v7 PKs as the cursor — eliminates offset drift on live data and supports infinite scroll reliably. A minimal connection shape `{ nodes: [T!]!, pageInfo: { hasNextPage: Boolean!, endCursor: String } }` is sufficient; full Relay Connection spec (`edges/node`) is optional.'
+    - 'Design mutation arguments as a single `input` object: `mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { ... } }`. Never spread individual scalars as top-level arguments — a single input type is versionable and tooling-friendly.'
+    - 'Return a Payload type from every mutation: `type CreateUserPayload { user: User, userErrors: [UserError!]! }`. Return HTTP 200 with application-level errors in `userErrors` rather than using top-level GraphQL errors, which are harder for clients to branch on.'
+    - 'Solve N+1 with DataLoader. Resolvers MUST NOT issue DB queries directly — delegate to a batch loader keyed by parent IDs. This is mandatory for any `@ResolveField`-equivalent that loads related data.'
+    - 'Follow schema naming conventions: `PascalCase` for types and enums, `camelCase` for fields and arguments, `SCREAMING_SNAKE_CASE` for enum values. Deviations break code generation tools (`@graphql-codegen`).'
+    - 'Mark deprecated fields with `@deprecated(reason: "Use newField instead. Removal planned in v3.")` rather than deleting them immediately. Verify client migration before removing in the next major version.'
+  decision_table:
+    - when: 'A field returns a collection'
+      then: 'Use cursor-based pagination (`first`/`after`, UUID v7 PK as cursor) — stable under concurrent writes, safe for infinite scroll. Offset pagination (`limit`/`offset`) is acceptable for admin tables with bounded, slow-changing data.'
+      avoid: 'Unbounded `[Node!]!` return — no limit means memory exhaustion and DoS risk at scale'
+    - when: 'A mutation needs to communicate failure to the client'
+      then: 'Return a Payload union type (`User | ValidationError`) and populate `userErrors: [UserError!]!` — clients can switch on `__typename` and handle errors as data'
+      avoid: 'Throwing top-level GraphQL errors for expected business failures — clients must catch exceptions instead of branching on typed data'
+    - when: 'A schema field needs to be removed or renamed'
+      then: 'Add `@deprecated(reason: "...")` first, confirm all clients have migrated, then remove in the next major schema version'
+      avoid: 'Removing a field immediately without deprecation — causes runtime errors in deployed clients that have not yet updated their queries'
+    - when: 'A query needs complex filtering or sorting'
+      then: 'Define dedicated `FilterInput` / `OrderByInput` input types with typed fields for each filter criterion'
+      avoid: 'Accepting a JSON string or raw scalar as a filter parameter — loses type safety, IDE auto-complete, and validation at the schema level'

package/data/rules/libs-backend-python.yaml

@@ -0,0 +1,36 @@
+id: libs-backend-python
+category: tooling
+tags:
+  - python
+  - backend
+priority: 22
+content:
+  constraints:
+    - 'DO NOT use requirements.txt. Use uv (preferred) or Poetry with pyproject.toml. Lock file (uv.lock or poetry.lock) must be committed.'
+    - 'DO NOT use print() for logging. Use structlog with JSON output.'
+    - 'DO NOT use unittest.TestCase. Use pytest with function-based tests and fixtures.'
+    - 'DO NOT use bare assert in production code. The -O flag strips assert statements. Use explicit if/raise instead.'
+  guidelines:
+    - 'uv 0.5+ — package management. uv sync, uv run. Commit uv.lock.'
+    - 'pytest 8+ / pytest-asyncio / pytest-cov — testing. Use fixtures, parametrize, and coverage reports.'
+    - 'httpx 0.28+ — sync/async HTTP client. Use ASGITransport for FastAPI integration tests.'
+    - 'structlog 24+ — structured JSON logging. Bind request_id and user_id to the context.'
+    - 'ruff — lint and format (replaces flake8, black, isort). Configure in pyproject.toml [tool.ruff].'
+    - 'mypy 1.10+ or pyright — static type checking in strict mode. Enforce as a CI gate.'
+    - 'pydantic-settings 2+ — environment variable loading and validation. Single source of truth for config.'
+    - 'tenacity 9+ — retry logic with exponential backoff. Use for external API calls and transient failure recovery.'
+    - 'Great Expectations 1+ or pandera — pipeline input/output data quality validation.'
+    - 'polars 1+ / duckdb 1+ — core data processing stack. Works in conjunction with data-pipeline-python rule.'
+  decision_table:
+    - when: 'Package management is needed'
+      then: 'Use uv + pyproject.toml + uv.lock'
+      avoid: 'pip + requirements.txt (no lock file guarantees), conda (heavy, slow CI)'
+    - when: 'Lint and format tooling is needed'
+      then: 'Use ruff as the single tool for lint and format'
+      avoid: 'flake8 + black + isort (fragmented config, slower CI)'
+    - when: 'Data quality validation is needed'
+      then: 'Great Expectations (batch pipeline) or pandera (DataFrame schema)'
+      avoid: 'Scattered manual assert statements inside pipeline code (untestable, no reporting)'
+    - when: 'HTTP client is needed'
+      then: 'Use httpx (supports both sync and async with a single API)'
+      avoid: 'requests (no async support), aiohttp (complex low-level API)'

package/data/rules/libs-backend-ts.yaml

@@ -0,0 +1,43 @@
+id: libs-backend-ts
+category: tooling
+tags:
+  - typescript
+  - nestjs
+  - backend
+priority: 25
+content:
+  constraints:
+    - 'DO NOT use moment.js or dayjs. Use date-fns 4+ (tree-shakeable, immutable, functional API) — import individual functions only.'
+    - 'DO NOT use jsonwebtoken. Use jose 6+ (Web Crypto API, edge-compatible, no native binary dependencies).'
+    - 'DO NOT use Express APIs (req/res) directly in NestJS handlers. Route through the NestJS platform adapter layer.'
+    - 'DO NOT import lodash as a full bundle (import _ from "lodash"). Prefer native JS (structuredClone, Object.groupBy, Array.at) first; only then use individual lodash imports.'
+    - 'DO NOT use node-fetch or got for HTTP calls inside NestJS. Use @nestjs/axios (HttpModule) or native fetch().'
+    - 'DO NOT use winston, morgan, or console.log for application logging. Use pino 9+ via nestjs-pino 4+ — it fully replaces the NestJS Logger and provides best-in-class JSON serialization performance.'
+  guidelines:
+    - 'class-validator 0.14+ / class-transformer 0.5+ — DTO validation and serialization. Always enable whitelist: true in ValidationPipe.'
+    - '@nestjs/graphql 13+ / @nestjs/apollo 13+ / @apollo/server 5+ — GraphQL API layer. Use code-first approach with TypeScript decorators.'
+    - '@graphql-codegen/cli 6+ / client-preset 5+ — generate type-safe GraphQL operation types from the SDL at build time.'
+    - 'date-fns 4+ / date-fns-tz 3+ — date manipulation and timezone handling. Always import individual functions (e.g., import { format } from "date-fns").'
+    - 'jose 6+ — JWT signing, verification, JWK/JWKS handling. Use SignJWT / jwtVerify / createRemoteJWKSet.'
+    - 'pino 9+ / nestjs-pino 4+ — structured JSON logging. Bootstrap with LoggerModule.forRoot() to replace the NestJS Logger across all modules automatically.'
+    - 'rxjs 7+ — reactive patterns for NestJS interceptors, guards, and event streams. Prefer operators over manual Promise chains.'
+    - 'vitest 4+ / @nestjs/testing / supertest 7+ — unit and e2e testing. ESM-native; no ts-jest or @swc/jest configuration required.'
+    - 'pg 8+ / @prisma/adapter-pg 7+ — Prisma driver adapter. Configure connection pool size (max, idleTimeoutMillis) explicitly.'
+    - 'typescript 5+ with strict: true / @swc/core — type checking and fast transpilation in development and CI.'
+    - 'axios via @nestjs/axios HttpModule — outbound HTTP calls that require interceptors, retry logic, or request/response transformation.'
+  decision_table:
+    - when: 'JWT authentication is needed'
+      then: 'Use jose 6+ (SignJWT, jwtVerify, createRemoteJWKSet)'
+      avoid: 'jsonwebtoken — not Web Crypto compatible, not edge-runtime safe'
+    - when: 'Date manipulation or formatting is needed'
+      then: 'Use date-fns 4+ with individual function imports'
+      avoid: 'moment.js (mutable, large bundle), dayjs (non-standard plugin model)'
+    - when: 'A utility function is needed (e.g., deep clone, groupBy)'
+      then: 'Use native JS first (structuredClone, Object.groupBy); only fall back to individual lodash imports'
+      avoid: "lodash full bundle import (import _ from 'lodash')"
+    - when: 'Schema validation outside of DTOs is needed (e.g., env vars, external payloads)'
+      then: 'Use zod with parse/safeParse'
+      avoid: 'joi (CommonJS-only API), manual type guards (brittle, untestable)'
+    - when: 'Structured application logging is needed'
+      then: 'Use pino 9+ via nestjs-pino 4+ (LoggerModule.forRoot)'
+      avoid: 'winston (slow JSON serialization), morgan (HTTP-only), console.log (unstructured)'

package/data/rules/libs-frontend-app.yaml

@@ -0,0 +1,42 @@
+id: libs-frontend-app
+category: tooling
+tags:
+  - dart
+  - flutter
+  - frontend
+priority: 15
+content:
+  constraints:
+    - 'DO NOT use the http package for API calls. Use dio 5+ — it provides interceptors, retry, cancellation, and multipart support.'
+    - 'DO NOT use Provider or Bloc for state management. Use flutter_riverpod 2+ with riverpod_annotation and riverpod_generator for code-gen-based providers.'
+    - 'DO NOT write data classes manually (==, hashCode, copyWith, toJson). Use freezed 2+ with build_runner to generate them.'
+    - 'DO NOT use Navigator 1.0 (push/pop). Use go_router 14+ for declarative, deep-link-ready routing.'
+    - 'DO NOT manually implement JSON serialization with dart:convert. Use json_annotation 4+ / json_serializable 6+ (or freezed fromJson/toJson) with build_runner.'
+  guidelines:
+    - 'flutter_riverpod 2+ / riverpod_annotation 2+ / riverpod_generator 2+ — state management. Use @riverpod annotation; run build_runner to generate provider code.'
+    - 'freezed 2+ / freezed_annotation 2+ — immutable data models with union types. Annotate with @freezed and generate via build_runner.'
+    - 'go_router 14+ — declarative routing. Use context.go() for replacement and context.push() for stack navigation. Define all routes in a central GoRouter instance.'
+    - 'dio 5+ — HTTP networking. Create a single central Dio instance (registered via Riverpod) with baseUrl, headers, and interceptors configured.'
+    - 'shared_preferences 2+ — non-sensitive key-value storage (settings, flags). flutter_secure_storage 9+ — sensitive data (tokens, credentials).'
+    - 'cached_network_image 3+ — network image display with automatic disk and memory caching, placeholder, and errorWidget support. Prefer over Image.network to avoid memory waste and lack of offline cache.'
+    - 'json_annotation 4+ / json_serializable 6+ — JSON code generation for models not using freezed.'
+    - 'build_runner 2+ — code generation orchestrator. Use dart run build_runner watch in development and dart run build_runner build --delete-conflicting-outputs in CI.'
+    - 'mocktail 1+ — test mocking without code generation. Uses Dart-native class extension syntax; no annotation required.'
+    - 'very_good_analysis 7+ — strict lint ruleset. Treat warnings as errors in CI (--fatal-warnings flag).'
+    - 'intl 0.19+ or easy_localization 3+ — i18n based on ARB files. Use intl for minimal dependencies; use easy_localization for runtime locale switching with context.tr().'
+  decision_table:
+    - when: 'HTTP API call is needed'
+      then: 'Use a central dio 5+ instance injected via Riverpod (ref.watch(dioProvider))'
+      avoid: 'http package (no interceptors), raw HttpClient (verbose, no retry support)'
+    - when: 'Local data persistence is needed'
+      then: 'Use shared_preferences for non-sensitive KV data; use flutter_secure_storage for tokens and credentials'
+      avoid: 'SQLite or Hive for simple key-value needs — overkill with unnecessary schema overhead'
+    - when: 'Network image needs to be displayed'
+      then: 'Use cached_network_image 3+ with placeholder and errorWidget configured'
+      avoid: 'Image.network — no disk cache, no memory management, no offline support'
+    - when: 'Test mocking is needed'
+      then: 'Use mocktail 1+ (class-based mocking, no code generation)'
+      avoid: 'mockito — requires code generation (@GenerateMocks), higher boilerplate'
+    - when: 'Code generation is required (freezed, riverpod_generator, json_serializable)'
+      then: 'Run build_runner 2+ (watch in dev, build --delete-conflicting-outputs in CI)'
+      avoid: 'Manually writing generated code — error-prone and breaks on regeneration'

package/data/rules/libs-frontend-web.yaml

@@ -0,0 +1,49 @@
+id: libs-frontend-web
+category: tooling
+tags:
+  - typescript
+  - react
+  - nextjs
+  - frontend
+priority: 20
+content:
+  constraints:
+    - 'DO NOT use moment.js or dayjs. Use date-fns 4+ as the single standard — import individual functions only.'
+    - 'DO NOT use react-icons. Use lucide-react with named imports for a consistent design language and tree-shakeability.'
+    - 'DO NOT use axios on the client side. Use native fetch() to integrate with Next.js caching and revalidation mechanisms.'
+    - 'DO NOT write conditional className strings manually. Use the cn() utility (clsx + tailwind-merge) and cva for variant-based styling.'
+    - 'DO NOT install additional UI component libraries (MUI, Ant Design, Chakra UI) alongside shadcn/ui. Extend shadcn/ui primitives instead.'
+    - 'DO NOT use Redux, Recoil, or MobX for UI state. Use zustand 4+ for client UI state; delegate server/remote state to Apollo Client.'
+  guidelines:
+    - '@apollo/client 4+ / @apollo/experimental-nextjs-app-support 0.13+ — GraphQL data fetching in App Router. Use ApolloNextAppProvider in the root layout.'
+    - '@graphql-codegen/cli 6+ / client-preset 5+ — generate type-safe operation types (TypedDocumentNode) from the GraphQL schema at build time.'
+    - 'tailwindcss 4+ — utility-first styling with CSS variable design tokens. Define semantic tokens in globals.css.'
+    - 'clsx 2+ / tailwind-merge 3+ — compose the cn() utility for conflict-free class merging.'
+    - 'class-variance-authority 0.7+ — multi-variant component styling (e.g., Button with size and intent variants).'
+    - 'zustand 4+ — client UI state (modals, multi-step forms, sidebars). Keep server/remote state in Apollo Client cache; do not duplicate it in zustand.'
+    - 'next-intl 4+ — i18n with server component message loading and the useTranslations hook in client components.'
+    - 'next-themes — dark/light mode theming. Wrap the root layout with ThemeProvider; read the theme via useTheme.'
+    - 'recharts 2+ — data visualization. Always render inside a "use client" boundary component to avoid hydration errors.'
+    - 'sonner — toast notifications. Mount a single <Toaster /> in the root layout; call toast() anywhere.'
+    - 'date-fns 4+ — date formatting and manipulation. Import individual functions (e.g., import { format, parseISO } from "date-fns").'
+    - 'isomorphic-dompurify — sanitize UGC HTML before rendering with dangerouslySetInnerHTML. Never skip sanitization.'
+    - 'vitest 4+ / @testing-library/react — unit and component testing. Use userEvent over fireEvent; ESM-native, no separate transpiler needed.'
+  decision_table:
+    - when: 'GraphQL data fetching is needed in App Router'
+      then: 'Use @apollo/client 4+ with @apollo/experimental-nextjs-app-support (ApolloNextAppProvider)'
+      avoid: 'urql (less Next.js integration), raw fetch with manual cache keys'
+    - when: 'Date manipulation or formatting is needed'
+      then: 'Use date-fns 4+ with individual function imports'
+      avoid: 'dayjs (removed from this project — migrate to date-fns)'
+    - when: 'Icons are needed in the UI'
+      then: 'Use lucide-react with named imports (e.g., import { ChevronRight } from "lucide-react")'
+      avoid: 'react-icons (inconsistent design, large bundle), inline SVG (hard to maintain)'
+    - when: 'Form input validation is needed'
+      then: 'Use zod schema + react-hook-form with @hookform/resolvers/zod'
+      avoid: 'yup (larger API surface), manual validation logic in onChange handlers'
+    - when: 'User-generated HTML content must be rendered'
+      then: 'Sanitize with isomorphic-dompurify first, then render with dangerouslySetInnerHTML'
+      avoid: 'Rendering unsanitized HTML — XSS risk'
+    - when: 'Client UI state is needed (modal open, wizard step, sidebar)'
+      then: 'Use a zustand store slice'
+      avoid: 'Redux or Recoil (overkill); useState is sufficient for single-component-scoped state only'

package/data/rules/naming-convention.yaml

@@ -0,0 +1,10 @@
+id: naming-convention
+category: convention
+tags:
+  - general
+  - naming
+priority: 75
+content:
+  constraints: []
+  guidelines:
+    - 'Use kebab-case for directory names.'

package/data/rules/nestjs-graphql.yaml

@@ -0,0 +1,31 @@
+id: nestjs-graphql
+category: framework
+tags:
+  - typescript
+  - nestjs
+  - graphql
+priority: 43
+content:
+  constraints:
+    - 'DO NOT put business logic in Resolvers. Resolvers are thin orchestrators — delegate all domain logic to Services, identical to the Controller rule in nestjs.yaml.'
+    - "DO NOT access raw GraphQL context directly. Use typed `@Args('input') input: CreateUserInput` decorators for argument extraction. Direct `context.args` access bypasses NestJS type safety and validation pipe integration."
+    - 'DO NOT issue DB queries inside `@ResolveField()` methods. Inject and call a DataLoader instead — direct repository calls in field resolvers cause N+1 queries at runtime.'
+    - 'DO NOT expose unauthenticated `@Subscription()` endpoints. Apply `@UseGuards(GqlAuthGuard)` or implement a `filter` function that validates subscriber identity before yielding events.'
+    - 'DO NOT write manual SDL files in a code-first NestJS GraphQL project. TypeScript decorators (`@ObjectType`, `@Field`, `@InputType`) are the single source of truth — the schema is auto-generated from them.'
+  guidelines:
+    - 'Structure resolvers with `@Resolver(() => Entity)` at the class level, `@Query()` / `@Mutation()` for top-level operations, and `@ResolveField()` for field-level data loading. One resolver file per domain entity.'
+    - 'Register DataLoaders as request-scoped NestJS providers. Use `@nestjs/dataloader` or a custom `DataLoaderFactory` — request scoping ensures per-request batching without cross-request data leakage.'
+    - "Add `{ description: '...' }` to every `@ObjectType()`, `@InputType()`, `@ArgsType()`, and `@Field()` decorator. Descriptions are emitted into the auto-generated SDL and serve as living API documentation."
+    - 'Apply query complexity and depth limiting via `graphql-query-complexity` + the NestJS GraphQL complexity plugin. Set a maximum complexity budget per request to prevent DoS through deeply nested or highly multiplied queries.'
+    - 'Define custom scalars (`DateTime`, `JSON`, `UUID`) with `@Scalar()` decorator classes and register them globally in the GraphQL module config. Consistent scalar handling prevents serialization mismatches between the schema and runtime values.'
+    - 'Apply `@UseGuards()` and `@UseInterceptors()` at the resolver or method level using `GqlExecutionContext.create(context)` to extract the GraphQL-specific context. Reuse the same Guard and Interceptor classes as REST controllers — `ExecutionContext` switching is the only adapter needed.'
+  decision_table:
+    - when: 'A field resolver needs to load related entity data (e.g., user.posts)'
+      then: 'Use `@ResolveField()` backed by a request-scoped DataLoader that batches IDs and issues a single DB query per request cycle'
+      avoid: 'Calling the repository directly inside `@ResolveField()` — each parent node triggers a separate query (N+1)'
+    - when: 'Real-time data push is required (e.g., live notifications, order status updates)'
+      then: 'Use `@Subscription()` with Redis PubSub (`graphql-redis-subscriptions`) — horizontally scalable across multiple server instances'
+      avoid: 'In-memory PubSub (`new PubSub()`) — events are not shared across instances, causing silent message loss in multi-pod deployments'
+    - when: 'Authentication or authorization is required on a resolver'
+      then: 'Apply `@UseGuards(GqlAuthGuard)` at the class or method level; extract user from `GqlExecutionContext.create(ctx).getContext().req.user`'
+      avoid: 'Manual JWT parsing inside the resolver function body — authentication is a cross-cutting concern and must not bleed into business logic'

package/data/rules/nestjs.yaml

@@ -0,0 +1,26 @@
+id: nestjs
+category: framework
+tags:
+  - typescript
+  - nestjs
+priority: 45
+content:
+  constraints:
+    - 'DO NOT use @Res() or @Response() decorator to send responses directly. It bypasses Interceptors, Exception Filters, and built-in serialization. Return values from the handler instead.'
+    - 'DO NOT put business logic in Controllers. Controllers are thin orchestrators — delegate all logic to Services.'
+    - 'DO NOT use forwardRef() to work around circular dependencies. Redesign the module boundary or extract a shared module instead.'
+    - 'DO NOT access process.env directly in service or controller classes. Inject ConfigService from @nestjs/config and validate the env schema at application startup.'
+    - 'DO NOT use console.log for application logging. Inject NestJS Logger or a custom logger (e.g., pino, Winston) through the DI system.'
+  guidelines:
+    - 'Organize by feature module: one module per domain (e.g., users/users.module.ts) co-locating its controller, service, and DTOs.'
+    - 'Define request/response DTOs with class-validator decorators. Never expose entities directly as API responses.'
+    - 'Register global pipes, filters, and guards in main.ts bootstrap (e.g., app.useGlobalPipes(new ValidationPipe({ whitelist: true }))).'
+    - 'Extend HttpException for custom business exceptions to integrate with the built-in exception filter layer.'
+    - 'For REST APIs, annotate controllers with @ApiOperation and DTOs with @ApiProperty via @nestjs/swagger. Omit for GraphQL — the SDL schema is the contract.'
+  decision_table:
+    - when: 'Cross-cutting concern needs access to ExecutionContext (e.g., role check, auth)'
+      then: 'Use a Guard (@CanActivate) — it runs after middleware, before interceptors, and has access to the handler metadata'
+      avoid: 'Using middleware for auth — middleware lacks ExecutionContext and @SetMetadata access'
+    - when: 'Need to transform, wrap, or cache the response, or measure execution time'
+      then: 'Use an Interceptor — it wraps the handler execution with RxJS Observable'
+      avoid: 'Using middleware for response transformation — middleware runs before the route handler'

package/data/rules/nextjs.yaml

@@ -0,0 +1,34 @@
+id: nextjs
+category: framework
+tags:
+  - typescript
+  - react
+  - nextjs
+  - app-router
+priority: 50
+content:
+  constraints:
+    - "DO NOT import server-only code (db clients, secrets, internal APIs) in Client Components. Use the 'server-only' package to enforce the boundary."
+    - 'DO NOT store secrets in NEXT_PUBLIC_ environment variables. Only NEXT_PUBLIC_ vars are exposed to the browser.'
+    - 'DO NOT use next/router. Use next/navigation (useRouter, usePathname, useSearchParams) in App Router.'
+  guidelines:
+    - 'Use the Next.js file conventions: page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx.'
+    - "Co-locate Server Actions in a dedicated file (e.g., actions.ts) with 'use server' at the top."
+    - 'Use next/image for all images with explicit width/height or fill+sizes.'
+    - 'Use next/font in root layout, apply via CSS variable.'
+    - 'Use middleware.ts only for cross-cutting concerns: auth redirects, locale detection, header injection.'
+    - 'Export generateMetadata or a static metadata object from every public-facing page.tsx. Include title, description, and Open Graph fields for SEO crawlers and social sharing.'
+    - 'Apply JSON-LD structured data markup for GEO (Generative Engine Optimization). Inject <script type="application/ld+json"> with schema.org-based structured data in public pages to optimize for AI search engines (SGE, Perplexity) and traditional search engines.'
+  decision_table:
+    - when: 'Component needs event handlers, useState, useEffect, or browser APIs'
+      then: "Add 'use client' to that component only"
+      avoid: "Adding 'use client' to a parent — push it to the smallest leaf"
+    - when: 'Data needs to be fetched for a page'
+      then: 'Fetch in Server Component (page.tsx, layout.tsx) with async/await'
+      avoid: 'useEffect + fetch in Client Component for initial page data'
+    - when: 'Form submission or data mutation'
+      then: 'Server Action via form action or startTransition'
+      avoid: 'POST route.ts for simple mutations'
+    - when: 'API endpoint for external consumers or webhooks'
+      then: 'route.ts with explicit HTTP method exports (GET, POST)'
+      avoid: 'Server Actions for external API endpoints'

package/data/rules/prisma-postgresql.yaml

@@ -0,0 +1,30 @@
+id: prisma-postgresql
+category: database
+tags:
+  - typescript
+  - prisma
+  - postgresql
+priority: 40
+content:
+  constraints:
+    - 'DO NOT use $queryRawUnsafe with string interpolation or concatenation. It creates SQL injection vulnerabilities. Use tagged template $queryRaw`...${variable}` which auto-escapes, or use positional parameters ($1, $2) with $queryRawUnsafe.'
+    - 'DO NOT return Prisma model objects directly as API responses. Models may contain sensitive fields (password, tokens, deletedAt). Use select to pick specific fields or map to a response DTO.'
+    - 'DO NOT define mutable models without an updatedAt field. Add `updatedAt DateTime @updatedAt` to every model that can be modified after creation.'
+    - 'DO NOT use $use() middleware — it is removed in Prisma v7. Use Client Extensions ($extends) with query hooks instead.'
+    - 'DO NOT use prisma db push in production. It can cause data loss and has no migration history. Use prisma migrate deploy with versioned migration files only.'
+  guidelines:
+    - 'Use the prisma-client generator with an explicit output path: generator client { provider = "prisma-client"; output = "./generated/prisma/client" }. The legacy prisma-client-js provider is deprecated in v7.'
+    - 'Configure a driver adapter explicitly. For PostgreSQL, use @prisma/adapter-pg with pool settings (max connections, idleTimeoutMillis, connectionTimeoutMillis) tuned to your environment.'
+    - 'Add @@index on fields used in where, orderBy, and relation foreign keys. Use composite indexes @@index([fieldA, fieldB]) for multi-column filter patterns.'
+    - 'Set explicit timeout and maxWait on interactive transactions to match your business requirements — the defaults (timeout: 5000ms, maxWait: 2000ms) may be too short for complex operations.'
+    - 'Centralize configuration in prisma.config.ts (datasource URL, migration path, seed script). The url and directUrl fields in the schema.prisma datasource block are deprecated in v7.'
+    - 'Implement soft delete via Client Extension ($extends query hook) that injects where: { deletedAt: null } into find queries automatically — not via the removed $use() middleware.'
+    - 'Prefer cursor-based pagination (cursor + take) over offset-based (skip + take) for large tables. Offset pagination degrades as page depth increases; cursor pagination leverages indexes consistently.'
+    - 'In serverless or containerized environments, configure an external connection pooler (e.g., PgBouncer) or set an explicit connection_limit on @prisma/adapter-pg to prevent database max connection exhaustion.'
+  decision_table:
+    - when: 'Query requires window functions, CTEs, complex aggregations, or PostgreSQL-specific syntax not supported by Prisma Client API'
+      then: 'Use $queryRaw with tagged template literals for automatic escaping and type safety'
+      avoid: 'Overusing raw SQL for queries that Prisma Client API can express — lose type safety and query validation'
+    - when: 'Transaction involves multiple writes where later queries depend on earlier results'
+      then: 'Use interactive transaction ($transaction(async (tx) => { ... })) with explicit timeout/maxWait'
+      avoid: 'Using batch transaction ($transaction([...])) when queries are interdependent — batch does not guarantee execution order access'

package/data/rules/python.yaml

@@ -0,0 +1,31 @@
+id: python
+category: language
+tags:
+  - python
+priority: 55
+content:
+  constraints:
+    - 'DO NOT use Any type hint. Use object or concrete generics instead.'
+    - 'DO NOT use mutable default arguments (def f(items: list = [])). Use None sentinel + factory pattern inside the function body.'
+    - 'DO NOT use bare except: or except Exception:. Catch specific exception types.'
+    - 'DO NOT use from module import *. Always use explicit imports.'
+    - 'DO NOT use string-based type checking (type(x) == str). Use isinstance() or Protocol.'
+    - 'DO NOT use # type: ignore without an error code. Always specify the code (e.g., # type: ignore[arg-type]).'
+  guidelines:
+    - 'Annotate all function parameters and return types, including -> None.'
+    - 'Use Pydantic V2 BaseModel for DTOs, config, and schemas. Use model_validator / field_validator (V1 deprecated validator is forbidden).'
+    - 'Leverage TypeAlias, TypeVar, ParamSpec, TypedDict, and Literal for expressive type annotations.'
+    - 'Isolate business logic in *_logic.py (pure functions). Keep services and routers as thin orchestrators.'
+    - 'Use @dataclass(frozen=True) for immutable value objects that do not require runtime validation.'
+    - 'Use pathlib.Path instead of os.path for all filesystem operations.'
+    - 'Use f-strings only. Avoid % formatting and .format().'
+  decision_table:
+    - when: 'Structured data requires validation or serialization'
+      then: 'Use Pydantic V2 BaseModel'
+      avoid: 'plain dict, TypedDict (no runtime validation)'
+    - when: 'Immutable value object without runtime validation is needed'
+      then: 'Use @dataclass(frozen=True)'
+      avoid: 'Pydantic (unnecessary overhead for pure value objects)'
+    - when: 'Runtime type narrowing is needed'
+      then: 'Use isinstance() or model_validate()'
+      avoid: 'type() comparison, hasattr() (fragile and non-idiomatic)'

package/data/rules/react-typescript.yaml

@@ -0,0 +1,11 @@
+id: react-typescript
+category: framework
+tags:
+  - typescript
+  - react
+priority: 60
+content:
+  constraints:
+    - 'DO NOT use React.FC or FC. Type props directly and destructure them.'
+  guidelines:
+    - 'Use readonly for array and object props.'

package/data/rules/role-persona.yaml

@@ -0,0 +1,14 @@
+id: role-persona
+category: persona
+tags:
+  - general
+  - persona
+priority: 90
+content:
+  constraints:
+    - "DO NOT write patronizing tutorials (e.g., 'First, let me explain what React is...')."
+  guidelines:
+    - 'You are an expert Senior Full-Stack Developer.'
+    - 'Assume the user is a senior developer, but may be unfamiliar with specific domains or patterns.'
+    - 'When choosing a pattern, library, or architectural approach, briefly explain WHY it was chosen over alternatives.'
+    - 'Focus on high-level architecture, edge cases, performance optimization, and maintainability.'

package/data/rules/shadcn-ui.yaml

@@ -0,0 +1,36 @@
+id: shadcn-ui
+category: ui
+tags:
+  - typescript
+  - react
+  - shadcn-ui
+  - tailwind
+priority: 35
+content:
+  constraints:
+    - "DO NOT reimplement components already provided by Shadcn (Dialog, Sheet, Select, Toast, etc.). Use 'npx shadcn@latest add <component>' instead."
+    - 'DO NOT directly edit Shadcn source files (components/ui/*.tsx). Extend via wrapper components or customize via className.'
+    - 'DO NOT abuse Tailwind arbitrary values (e.g., w-[327px]). Define design tokens (spacing, color) in tailwind.config.ts and reference them.'
+    - 'DO NOT use inline styles (style={}) for static values. Only exception: runtime-computed dynamic values. Use Tailwind classes for all static styles.'
+  guidelines:
+    - 'Check the Shadcn component catalog first (https://ui.shadcn.com/docs/components) before implementing any new UI element.'
+    - 'Use the cn() utility (clsx + tailwind-merge) for conditional class merging. Prefer cn(base, condition && variant) over string templates or manual conditionals.'
+    - 'Follow Shadcn composition patterns. Compose complex components from sub-components (e.g., Dialog = DialogTrigger + DialogContent + DialogHeader + DialogTitle + DialogDescription).'
+    - 'Use cva (class-variance-authority) for components with multiple variants. Do not branch classes with prop conditionals.'
+    - 'Maintain CSS variable-based theme system. Use hsl(var(--primary)) color format. Map CSS variables to Tailwind tokens in tailwind.config.ts.'
+    - 'Apply responsive styles mobile-first. Use sm:, md:, lg: breakpoint prefixes in order. Avoid desktop-first (max-*:) patterns.'
+    - 'Preserve built-in accessibility from Shadcn (Radix UI). For icon-only buttons or visual-only elements, always add aria-label or <span className="sr-only"> for screen reader text.'
+    - "Use named imports for individual icons (e.g., import { ChevronDown } from 'lucide-react'). Never import the entire icon namespace."
+  decision_table:
+    - when: 'UI element exists in Shadcn catalog or can be composed from Radix primitives'
+      then: 'Use Shadcn component'
+      avoid: 'Custom implementation from scratch'
+    - when: 'Shadcn has no matching component and domain-specific complex interaction is needed'
+      then: 'Write a custom component'
+      avoid: 'Forcing Shadcn usage or wrapping unrelated primitives'
+    - when: 'Component needs conditional styling or multiple visual variants'
+      then: 'Define variant map with cva'
+      avoid: 'Branching className strings with if/ternary in JSX'
+    - when: 'Styling approach is needed'
+      then: 'Tailwind classes by default'
+      avoid: 'CSS Modules (only for complex animations/keyframes or third-party style overrides)'

package/data/rules/sqlalchemy.yaml

@@ -0,0 +1,32 @@
+id: sqlalchemy
+category: database
+tags:
+  - python
+  - sqlalchemy
+  - postgresql
+priority: 38
+content:
+  constraints:
+    - 'DO NOT use legacy 1.x style session.query(). Use 2.0 style select() / insert() / update() statements.'
+    - 'DO NOT execute raw SQL strings directly (except in Alembic migrations). Use ORM or text() with bound parameters to prevent SQL injection.'
+    - 'DO NOT call session.commit() in multiple scattered places. Use Unit of Work pattern — commit once at the service layer boundary.'
+    - 'DO NOT omit created_at / updated_at on models. Use server_default=func.now() and onupdate=func.now().'
+    - 'DO NOT modify the schema without Alembic. Use alembic revision --autogenerate and manually review the generated migration.'
+  guidelines:
+    - 'Use Mapped[T] / mapped_column() declarative mapping (SQLAlchemy 2.0 type-safe style).'
+    - 'Declare relationships as Mapped[list["Child"]] with relationship(back_populates=...) explicitly set.'
+    - 'Use AsyncSession + async_sessionmaker to match the FastAPI async stack.'
+    - 'Implement soft delete with deleted_at: Mapped[datetime | None] and apply the filter by default in all queries.'
+    - 'Use Python StrEnum + Mapped[MyEnum] for enum columns (stored as strings, migration-safe).'
+    - 'Declare indexes and constraints explicitly in __table_args__: composite indexes, unique constraints.'
+    - 'Prevent N+1: always specify eager loading strategy when accessing relationships — selectinload() for 1:N (separate IN query), joinedload() for N:1/1:1 (JOIN). Never rely on lazy="select" default.'
+  decision_table:
+    - when: 'Simple CRUD operations are needed'
+      then: 'Use SQLAlchemy ORM (select, insert, update)'
+      avoid: 'Raw SQL strings (no type safety, SQL injection risk)'
+    - when: 'Complex analytical query with window functions is needed'
+      then: 'Use DuckDB or raw SQL via text() with bound parameters'
+      avoid: 'Forcing complex window functions through the ORM (verbose and unreadable)'
+    - when: 'Schema change is required'
+      then: 'Use Alembic --autogenerate + manual review'
+      avoid: 'Manual SQL DDL (untracked, causes environment drift)'

package/data/rules/typescript.yaml

@@ -0,0 +1,22 @@
+id: typescript
+category: language
+tags:
+  - typescript
+priority: 65
+content:
+  constraints:
+    - 'DO NOT use interface. Use type only.'
+    - 'DO NOT use enum. Use as const objects instead.'
+    - 'DO NOT use any. Use unknown with type narrowing (Zod / type guards).'
+    - 'DO NOT use non-null assertion (!). Use optional chaining (?.) and nullish coalescing (??) instead.'
+    - 'DO NOT use .then() chains. Use async/await.'
+    - 'DO NOT throw raw strings. Use throw new Error(...) only. Type catch errors as unknown and narrow.'
+  guidelines:
+    - 'Use arrow functions only. Explicitly annotate return types for exported functions.'
+    - 'Use import type { ... } for type-only imports. Use absolute paths (@/...) only.'
+    - 'Use as const for static configuration objects.'
+    - 'Separate business logic into *.logic.ts files (pure functions). Keep stateless helpers in *.util.ts files (parsers, formatters).'
+  decision_table:
+    - when: 'Type assertion (as) seems necessary'
+      then: 'Prefer Zod .parse() or type guards to narrow the type safely'
+      avoid: 'Using as to bypass the type system without runtime validation'