ai-ops-compiler 0.1.4 → 0.1.6

package/data/presets.yaml

@@ -4,6 +4,7 @@ frontend-web:
     - role-persona
     - communication
     - code-philosophy
+    - plan-mode
     - naming-convention
     - engineering-standards
     - typescript
@@ -18,6 +19,7 @@ frontend-app:
     - role-persona
     - communication
     - code-philosophy
+    - plan-mode
     - naming-convention
     - engineering-standards
     - flutter
@@ -29,6 +31,7 @@ backend-ts:
     - role-persona
     - communication
     - code-philosophy
+    - plan-mode
     - naming-convention
     - engineering-standards
     - typescript
@@ -44,6 +47,7 @@ backend-python:
     - role-persona
     - communication
     - code-philosophy
+    - plan-mode
     - naming-convention
     - engineering-standards
     - python

package/data/rules/ai-llm-python.yaml

@@ -7,29 +7,29 @@ tags:
 priority: 28
 content:
   constraints:
-    - 'DO NOT parse LLM text responses with regex or string splitting. Use structured output via Pydantic + response_format / instructor / function calling.'
-    - 'DO NOT hardcode prompts inline. Externalize to version-controlled templates (files or DB) that are diffable and reviewable.'
-    - 'DO NOT call synchronous SDK methods inside async applications. Use AsyncOpenAI, AsyncAnthropic, or equivalent async clients.'
-    - 'DO NOT ignore token limits. Count input tokens and truncate or chunk before sending when context window would be exceeded.'
-    - 'DO NOT log or persist raw API responses that contain PII. Mask sensitive fields before logging.'
+    - 'DO NOT parse model outputs with regex/split when schema output is required. Use structured output (Pydantic + response_format/function calling/instructor).'
+    - 'DO NOT hardcode prompts inline. Keep prompts versioned in files or managed storage.'
+    - 'DO NOT call sync SDK methods from async app paths.'
+    - 'DO NOT ignore token limits. Estimate and chunk/truncate input before requests.'
+    - 'DO NOT log raw responses containing PII.'
   guidelines:
-    - 'Use instructor or native SDK response_format + Pydantic model to extract structured output from LLM responses.'
-    - 'Apply exponential backoff retry on LLM API calls via tenacity. Handle 429, 500, and 503 explicitly.'
-    - 'Abstract provider selection with LiteLLM. Avoid scattering provider-specific SDK calls across the codebase.'
-    - 'Track per-request token usage (input tokens, output tokens, model name, latency) for cost monitoring.'
-    - 'Apply semantic versioning to prompt templates. Include the version in LLM call logs for reproducibility.'
-    - 'Use stream=True for user-facing LLM calls to stream progressive responses (improves TTFB). Reserve non-streaming for internal pipelines that require structured output extraction.'
-    - 'Define a fallback model chain for primary model failures or rate limits. Use LiteLLM fallbacks config or implement retry-with-downgrade logic.'
+    - 'Use Pydantic models with instructor or native response_format JSON schema mode.'
+    - 'Apply retry with exponential backoff for 429/5xx transient errors.'
+    - 'Centralize provider routing via LiteLLM (or equivalent abstraction).'
+    - 'Track model, input/output tokens, and latency per call for cost/perf monitoring.'
+    - 'Version prompts and include prompt version in request logs.'
+    - 'Stream user-facing responses when possible; keep non-streaming for strict structured extraction flows.'
+    - 'Define fallback model chains for rate limits or provider outages.'
   decision_table:
-    - when: 'LLM output must conform to a specific schema'
-      then: 'Use instructor + Pydantic or response_format={"type": "json_schema"}'
-      avoid: 'Regex parsing of free-text LLM output (brittle, breaks on formatting changes)'
-    - when: 'Selecting a model for a task'
-      then: 'Use the smallest model sufficient for the task (Haiku/GPT-4o-mini for classification/extraction; large models for complex reasoning only)'
-      avoid: 'Defaulting to the largest/most expensive model for every task'
-    - when: 'Input document exceeds context window'
-      then: 'Chunk with overlap, process independently, then aggregate results'
-      avoid: 'Silent truncation at the SDK level (loses data without warning)'
-    - when: 'Multiple LLM providers must be supported'
-      then: 'Use LiteLLM unified interface with routing config'
-      avoid: 'Separate provider SDK call sites scattered across the codebase'
+    - when: 'Output must match a strict schema'
+      then: 'Use structured output with Pydantic schema validation'
+      avoid: 'Regex parsing on free-text responses'
+    - when: 'Selecting a model'
+      then: 'Use the smallest model that meets quality requirements'
+      avoid: 'Defaulting to the largest model for all tasks'
+    - when: 'Input exceeds context window'
+      then: 'Chunk with overlap and aggregate results'
+      avoid: 'Silent SDK truncation'
+    - when: 'Multiple providers are required'
+      then: 'Use a unified provider abstraction (e.g., LiteLLM)'
+      avoid: 'Scattered provider-specific call sites'

package/data/rules/code-philosophy.yaml

@@ -9,22 +9,22 @@ tags:
 priority: 80
 content:
   constraints:
-    - "DO NOT over-engineer or write 'clever' one-liners. Code must be explicit; magic is forbidden."
-    - 'DO NOT extract code into shared functions/utils unless it is repeated at least 3 times (Rule of Three).'
-    - 'DO NOT mutate state. Use const, readonly, and spread operators for immutability.'
-    - 'DO NOT create side effects in business logic functions. Keep them pure.'
+    - 'DO NOT write clever or opaque code. Prefer explicit intent over tricks.'
+    - 'DO NOT extract shared abstractions before the Rule of Three.'
+    - 'DO NOT mutate state. Use const/final and spread operators for immutability.'
+    - 'DO NOT mix side effects into core business functions.'
   guidelines:
-    - 'Favor readability over complexity (Simple Made Easy).'
-    - 'Prefer duplication over the wrong abstraction (WET > DRY).'
-    - 'For complex business logic, write the failing test case FIRST (TDD).'
-    - 'Apply Functional Core / Imperative Shell: keep business logic as pure functions, keep services as thin orchestrators.'
-    - 'Use const/final and spread operators (...) for all data transformations.'
+    - 'Optimize for readability and maintainability first.'
+    - 'Prefer temporary duplication over premature abstraction.'
+    - 'For non-trivial business rules, start with a failing test (TDD).'
+    - 'Use a functional-core / imperative-shell structure.'
+    - 'Use immutable updates (const/final, copy/spread patterns).'
   decision_table:
-    - when: 'Business logic needs to be implemented'
-      then: 'Write a failing test first, then implement as a pure function'
-      avoid: 'Writing implementation before tests, or mixing I/O with business logic'
-    - when: 'Similar code appears in 2 places'
-      then: 'Keep both copies as-is (WET)'
-      avoid: 'Premature extraction into a shared utility'
-    - when: 'Similar code appears in 3+ places'
-      then: 'Extract into a shared function with a clear, descriptive name'
+    - when: 'Implementing complex business logic'
+      then: 'Write failing tests first, then implement pure functions'
+      avoid: 'Implementation-first with mixed I/O'
+    - when: 'Similar code appears in two places'
+      then: 'Keep duplication temporarily'
+      avoid: 'Early shared abstraction'
+    - when: 'Similar code appears in three or more places'
+      then: 'Extract a clearly named shared function'

package/data/rules/data-pipeline-python.yaml

@@ -8,27 +8,27 @@ tags:
 priority: 33
 content:
   constraints:
-    - 'DO NOT iterate over DataFrame rows with a Python for-loop. Use vectorized operations.'
-    - 'DO NOT use Pandas .apply(axis=1). It runs at Python speed. Use vectorized column expressions or migrate to Polars.'
-    - 'DO NOT load an entire dataset that exceeds available RAM into memory. Use streaming or chunked reads (scan_parquet, read_csv_batched, DuckDB out-of-core).'
-    - 'DO NOT rely on automatic dtype inference (.infer_objects()). Specify explicit dtypes or schema at read time.'
-    - 'DO NOT mutate DataFrames in-place (inplace=True). Always reassign to a new variable.'
+    - 'DO NOT iterate DataFrame rows in Python loops for transformations.'
+    - 'DO NOT use Pandas .apply(axis=1). It runs at Python speed; use vectorized expressions or Polars.'
+    - 'DO NOT load datasets larger than memory in one shot.'
+    - 'DO NOT rely on implicit dtype inference for production pipelines.'
+    - 'DO NOT mutate DataFrames in-place.'
   guidelines:
-    - 'Prefer Polars for new pipelines: lazy evaluation, multi-threaded execution, no index confusion.'
-    - 'Use DuckDB for SQL-style analysis on local Parquet/CSV files. Zero-copy interop with Polars and Pandas DataFrames.'
-    - 'Use generators and itertools for record-level streaming transformations to avoid materializing large datasets.'
-    - 'Write large outputs as Hive-style partitioned Parquet (year=YYYY/month=MM/) for efficient downstream reads.'
-    - 'Enforce explicit schemas at all I/O boundaries: Polars Schema, Pandas dtype dict, or Pydantic model.'
+    - 'Prefer Polars for new pipelines, especially lazy mode for query pushdown and parallel execution.'
+    - 'Use DuckDB for local SQL analytics on Parquet/CSV and out-of-core workloads.'
+    - 'Use streaming/chunked reads for large sources (scan_*, batched readers, out-of-core SQL).'
+    - 'Write partitioned Parquet outputs for downstream pruning and faster reads.'
+    - 'Enforce explicit schemas at I/O boundaries.'
   decision_table:
-    - when: 'Table transformation under ~10 GB'
-      then: 'Polars lazy mode + .collect()'
-      avoid: 'Pandas (GIL-bound, single-threaded, slow for large frames)'
-    - when: 'Ad-hoc SQL analysis on local Parquet/CSV files'
-      then: 'DuckDB SQL directly on files'
-      avoid: 'Loading into Pandas then filtering in Python (slow, memory-hungry)'
+    - when: 'Transforming tables up to medium-large scale'
+      then: 'Use Polars lazy pipelines'
+      avoid: 'Row-wise pandas patterns'
+    - when: 'Ad-hoc SQL analysis on local files is needed'
+      then: 'Use DuckDB directly on source files'
+      avoid: 'Load-all-then-filter in pandas'
     - when: 'Data exceeds available memory'
-      then: 'Polars scan_* (lazy streaming) or DuckDB out-of-core execution'
-      avoid: 'pandas.read_csv full load (OOM risk)'
-    - when: 'Complex Python logic needed per row'
-      then: 'Polars .map_elements() or struct expressions'
-      avoid: '.iter_rows() for-loop (Python speed, loses vectorization benefits)'
+      then: 'Use Polars scan_* or DuckDB out-of-core execution'
+      avoid: 'Full-memory pandas reads'
+    - when: 'Custom per-row Python logic is unavoidable'
+      then: 'Use vectorized expressions or controlled map APIs'
+      avoid: 'General-purpose iter_rows for core pipelines'

package/data/rules/engineering-standards.yaml

@@ -8,33 +8,32 @@ tags:
 priority: 70
 content:
   constraints:
-    - 'DO NOT use floating-point numbers for monetary values. Represent money as an integer in the smallest currency unit (e.g., cents) with an ISO 4217 currency code — { amount: 1099, currency: "USD" } means $10.99. IEEE 754 rounding errors accumulate across arithmetic operations.'
-    - 'DO NOT expose sequential or auto-increment IDs in external APIs. Use UUIDs. Sequential IDs enable enumeration attacks and leak business volume (e.g., total order count).'
-    - 'DO NOT store or transmit timestamps without timezone information. Always use ISO 8601 UTC format (e.g., "2024-01-15T09:30:00Z"). Timezone-naive strings ("2024-01-15 09:30:00") are ambiguous and cause silent data corruption across regions.'
-    - 'DO NOT use magic numbers or magic strings inline. Extract to named constants or env config. Inline literals (e.g., if (retries > 3), setTimeout(fn, 5000)) make intent opaque and changes error-prone.'
-    - 'DO NOT return inconsistent error response shapes across endpoints. Every error response MUST follow a standard envelope: { code: string, message: string, requestId: string }. Arbitrary shapes (e.g., { success: false, msg }) break client error handling.'
-    - 'DO NOT accept unbounded input. Enforce Content-Length limits, request body size limits, array length limits, and string length limits at the API boundary. Missing bounds are a DoS vector and amplify downstream processing cost.'
+    - 'DO NOT use floating-point for money. Use minor-unit integers with ISO 4217 currency (e.g., { amount: 1099, currency: "USD" }).'
+    - 'DO NOT expose sequential IDs in external APIs. Use UUIDs (prefer UUID v7).'
+    - 'DO NOT store or transmit timezone-naive timestamps. Use ISO 8601 UTC (e.g., "2024-01-15T09:30:00Z").'
+    - 'DO NOT use magic numbers or strings inline. Extract constants or config.'
+    - 'DO NOT return inconsistent error shapes. Use { code: string, message: string, details?: unknown[] }.'
+    - 'DO NOT accept unbounded input. Enforce body, array, and string size limits at the API boundary.'
   guidelines:
-    - 'UTC everywhere: store all timestamps as UTC in the DB (TIMESTAMPTZ), transmit as ISO 8601 UTC in APIs and logs. Convert to local timezone only in the presentation layer.'
-    - 'Wrap all API responses in a consistent envelope: { data: T | null, error: ErrorEnvelope | null, meta: { requestId: string, timestamp: string } }. This makes client-side response handling uniform regardless of endpoint.'
-    - 'Propagate a correlation ID (X-Request-Id) through every layer: API gateway → service → DB query comment → log entry → outbound HTTP headers. This makes distributed tracing and log correlation possible without a full APM setup.'
-    - 'Validate environment variables at application startup using Zod parse. Print all missing or invalid variables before failing — fail fast with full context rather than a cryptic runtime error on first use.'
-    - 'Name domain error codes as DOMAIN_ACTION_REASON (e.g., PAYMENT_CHARGE_INSUFFICIENT_FUNDS, AUTH_TOKEN_EXPIRED). Generic codes (INVALID_INPUT, SERVER_ERROR) give clients no actionable information.'
-    - 'Accept an Idempotency-Key header on non-idempotent mutations (POST, PATCH). Cache the response for the key within a TTL and return the cached response for duplicate requests. This makes retries safe for clients.'
-    - 'Expose GET /health (liveness — process is alive) and GET /ready (readiness — dependent services reachable) endpoints. Kubernetes liveness and readiness probes require these to be separate.'
-    - 'Represent monetary amounts as { amount: number, currency: string } where amount is an integer in the minor unit (cents, pence, etc.) and currency is an ISO 4217 code. Divide by the minor unit factor only at the display layer.'
-    - 'Return empty collections as [] (or {}) instead of null. Returning null forces every client to null-check before calling .map(), .filter(), or Object.keys(). An empty collection is unambiguous and safe to iterate without guards.'
-    - 'Handle SIGTERM for graceful shutdown: (1) stop accepting new requests, (2) wait for in-flight requests to complete, (3) close DB connection pools and message queue connections before exiting. Align the shutdown timeout with Kubernetes terminationGracePeriodSeconds to avoid forceful pod kills.'
+    - 'Use UTC end-to-end: TIMESTAMPTZ in DB, ISO 8601 UTC in API/logs, local conversion only in the presentation layer.'
+    - 'Wrap API responses in a consistent envelope: { data: T | null, error: ErrorEnvelope | null, meta: { requestId: string, timestamp: string } }.'
+    - 'Propagate X-Request-Id across gateway, service, logs, DB comments, and outbound calls.'
+    - 'Validate environment variables at startup (e.g., Zod parse) and fail fast with all missing/invalid keys.'
+    - 'Use domain error codes in DOMAIN_ACTION_REASON format (e.g., PAYMENT_CHARGE_INSUFFICIENT_FUNDS).'
+    - 'Support Idempotency-Key for POST/PATCH and replay the cached response for duplicate keys within TTL.'
+    - 'Expose GET /health (liveness) and GET /ready (readiness) separately.'
+    - 'Return empty collections ([] or {}) instead of null.'
+    - 'Handle SIGTERM gracefully: stop intake, drain in-flight requests, close resources, then exit.'
   decision_table:
     - when: 'A new entity needs a primary key'
-      then: 'Use UUID v7 (RFC 9562) — time-sortable, B-tree friendly, no enumeration risk'
-      avoid: 'Auto-increment integers (enumeration attack, leaks volume); UUID v4 (non-sortable, causes B-tree page splits at scale)'
-    - when: 'An API endpoint needs to return an error'
-      then: 'Use a structured error envelope: { code: string, message: string, details?: unknown[] } following RFC 9457 (Problem Details for HTTP APIs)'
-      avoid: 'Arbitrary error shapes ({ success: false, msg: string }) — breaks uniform client error handling and logging'
-    - when: 'Timestamps are exchanged between systems (API, logs, DB)'
-      then: 'Use ISO 8601 UTC strings ("2024-01-15T09:30:00Z") for APIs and logs; TIMESTAMPTZ column type for DB'
-      avoid: 'Unix epoch milliseconds for human-readable interfaces (undebuggable without a converter); timezone-naive strings (ambiguous); ISO 8601 with local offset in storage (inconsistent sort order). Note: Unix epoch is acceptable in compact formats such as JWT exp/iat claims.'
-    - when: 'An API needs to support multiple versions'
-      then: 'Use URL path prefix versioning (/v1/, /v2/) — explicit, cacheable, and simple to route'
-      avoid: 'Header-based versioning (Accept-Version, X-API-Version) — invisible in browser/curl, complicates CDN caching and routing'
+      then: 'Use UUID v7'
+      avoid: 'Auto-increment IDs or UUID v4 by default'
+    - when: 'An endpoint returns an error'
+      then: 'Return the standard error envelope'
+      avoid: 'Ad-hoc error fields (e.g., { success: false, msg })'
+    - when: 'Systems exchange timestamps'
+      then: 'Use ISO 8601 UTC in API/logs and TIMESTAMPTZ in DB; Unix epoch is acceptable in compact token formats (e.g., JWT exp/iat)'
+      avoid: 'Timezone-naive strings or mixed local-time storage'
+    - when: 'An API needs versioning'
+      then: 'Use URL versioning (/v1, /v2)'
+      avoid: 'Header-only versioning by default'

package/data/rules/fastapi.yaml

@@ -7,31 +7,28 @@ tags:
 priority: 42
 content:
   constraints:
-    - 'DO NOT use plain dict or TypedDict as request/response models. Use Pydantic BaseModel with Field constraints.'
-    - 'DO NOT perform synchronous blocking I/O inside async def handlers (time.sleep, requests.get, open()). Use httpx.AsyncClient, aiofiles, or run_in_executor.'
-    - 'DO NOT return manual error dicts from route handlers. Use @app.exception_handler with HTTPException or custom exceptions.'
-    - 'DO NOT put business logic inside router functions. Inject services via Depends().'
-    - 'DO NOT hardcode CORS origins. Load them from Pydantic Settings.'
+    - 'DO NOT use plain dict/TypedDict as request or response models. Use Pydantic BaseModel with Field constraints.'
+    - 'DO NOT run blocking I/O in async handlers. Use async clients or offload to executors.'
+    - 'DO NOT return ad-hoc error dicts from handlers. Raise HTTPException/custom exceptions and centralize handlers.'
+    - 'DO NOT place business logic in routers. Keep routers thin and inject services via Depends().'
+    - 'DO NOT hardcode CORS origins. Load from validated settings.'
   guidelines:
-    - 'Use Depends() for DI: DB sessions, auth, services. Write reusable dependency functions.'
-    - 'Create one APIRouter per domain (prefix="/users", tags=["users"]) and mount on the main app.'
-    - 'Specify response_model on all endpoints for OpenAPI accuracy and response filtering.'
-    - 'Use Annotated[T, Depends(...)] pattern (PEP 593) for dependency injection.'
-    - 'Use Pydantic Settings with SettingsConfigDict(env_file=".env") for environment variable validation at startup.'
-    - 'Use lifespan async context manager for startup/shutdown. @app.on_event is deprecated and forbidden.'
+    - 'Use reusable Depends() providers for DB session, auth context, and services.'
+    - 'Use APIRouter per domain with clear prefixes/tags and mount in the main app.'
+    - 'Set response_model on endpoints for output filtering and OpenAPI correctness.'
+    - 'Use Annotated[T, Depends(...)] for typed dependency injection.'
+    - 'Use Pydantic Settings for startup-time environment validation.'
+    - 'Use lifespan context manager for startup/shutdown lifecycle management.'
   decision_table:
     - when: 'Endpoint is CPU-bound'
-      then: 'Use def (sync) — FastAPI automatically runs it in a threadpool'
-      avoid: 'async def with blocking code (starves the event loop)'
+      then: 'Use sync def and let FastAPI run it in the threadpool'
+      avoid: 'async def with blocking code'
     - when: 'Endpoint is I/O-bound'
-      then: 'Use async def with async drivers (asyncpg, httpx.AsyncClient, aiofiles)'
-      avoid: 'def with sync drivers (blocks the threadpool under load)'
-    - when: 'Shared resource needs setup/teardown (DB pool, HTTP client)'
+      then: 'Use async def with async drivers (asyncpg, httpx, aiofiles)'
+      avoid: 'Sync driver calls on hot paths'
+    - when: 'Shared resources need setup/teardown'
       then: 'Use lifespan async context manager'
-      avoid: '@app.on_event("startup"/"shutdown") — deprecated since FastAPI 0.93'
-    - when: 'Error response must be returned'
-      then: 'Raise HTTPException or a custom exception handled by @app.exception_handler. Sync with engineering-standards error envelope.'
-      avoid: 'Returning manual JSONResponse from the route handler'
-    - when: 'Fire-and-forget work is needed after responding'
-      then: 'Lightweight tasks: BackgroundTasks (FastAPI built-in). Heavy tasks or retry needed: Celery or TaskIQ (async-native).'
-      avoid: 'Awaiting the task synchronously inside the route handler (delays response)'
+      avoid: '@app.on_event startup/shutdown hooks'
+    - when: 'Post-response background work is required'
+      then: 'Use BackgroundTasks for light jobs, Celery/TaskIQ for heavy/retriable jobs'
+      avoid: 'Awaiting long tasks inside the request handler'

package/data/rules/flutter.yaml

@@ -8,33 +8,33 @@ tags:
 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.'
+    - 'DO NOT use dynamic as a default type. Prefer concrete types, Object, or sealed unions.'
+    - 'DO NOT put business logic in Widget build(). Keep widgets declarative.'
+    - 'DO NOT use StatefulWidget for shared or long-lived state. Use Riverpod providers.'
+    - 'DO NOT use GlobalKey to reach into child state for app data flow.'
+    - 'DO NOT keep mutable model fields. Prefer immutable classes with copyWith/freezed.'
+    - 'DO NOT run heavy synchronous work on the UI thread. Use compute or 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.'
+    - 'Use Riverpod with @riverpod code generation and feature-local providers.'
+    - 'Use feature-first directories: lib/features/<feature>/{view,model,provider,logic} and shared code in lib/core.'
+    - 'Use sealed classes and pattern matching for Result/Async state handling.'
+    - 'Prefer const constructors where possible for rebuild efficiency.'
+    - 'Use go_router for declarative routes and deep-link handling.'
+    - 'Use freezed for immutable models and generated equality/copy/JSON methods.'
+    - 'Write widget tests with ProviderScope.overrides and unit-test pure logic separately.'
+    - 'Profile with DevTools before optimization; use RepaintBoundary where repaint isolation is needed.'
+    - 'Handle async states explicitly with AsyncValue or a Result type (loading/success/failure). Set a global error boundary to catch unhandled exceptions before they reach the UI.'
+    - 'Access external APIs/storage via repositories; providers should depend on repository interfaces.'
   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()'
+    - when: 'State is local and ephemeral (focus, small toggle)'
+      then: 'Use StatefulWidget or flutter_hooks state'
+      avoid: 'Creating global/shared providers for trivial local state'
+    - when: 'State is shared or must outlive a widget'
+      then: 'Use Riverpod Notifier/AsyncNotifier'
+      avoid: 'Prop-drilling callback chains'
+    - when: 'A model needs equality/copy/JSON generation'
+      then: 'Use @freezed + build_runner'
+      avoid: 'Manual ==/hashCode/copyWith implementations'
+    - when: 'Navigation and deep links are needed'
+      then: 'Use GoRouter route configuration'
+      avoid: 'Imperative Navigator-only architecture'

package/data/rules/graphql.yaml

@@ -7,28 +7,28 @@ tags:
 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.'
+    - 'DO NOT rely on implicit nullability. Mark every field intentionally (prefer non-null by default).'
+    - 'DO NOT perform mutations in Query resolvers. Reads belong to Query, writes belong to Mutation.'
+    - 'DO NOT return a generic Error type. Use operation-specific typed errors (union or payload errors).'
+    - 'DO NOT return unbounded lists. Every collection must support pagination.'
+    - 'DO NOT expose internal implementation details in enum values. Use semantic SCREAMING_SNAKE_CASE names.'
   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.'
+    - 'Prefer cursor pagination (first/after) for user-facing lists; use offset pagination only for bounded admin tables.'
+    - 'Use a single input object for every mutation: mutation X($input: XInput!).'
+    - 'Return mutation payload types that can carry both result data and structured errors.'
+    - 'Use DataLoader for related entity resolution; field resolvers must not issue per-parent DB queries.'
+    - 'Follow naming conventions: PascalCase types/enums, camelCase fields/args, SCREAMING_SNAKE_CASE enum values.'
+    - 'Deprecate fields first with @deprecated(reason: "...") and remove only 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'
+      then: 'Use cursor pagination with a stable cursor'
+      avoid: 'Returning unbounded [Node!]! lists'
+    - when: 'A mutation must report business failure'
+      then: 'Use both a Payload wrapper type AND typed union errors together — Payload carries partial success data, union enables __typename switching; they are complementary, not alternatives'
+      avoid: 'Throwing top-level GraphQL errors for expected failures, or using only a bare union without a Payload'
+    - when: 'A field is removed or renamed'
+      then: 'Deprecate first, migrate clients, then remove in next major'
+      avoid: 'Immediate schema removal'
+    - when: 'Filtering or sorting is complex'
+      then: 'Define typed FilterInput/OrderByInput types'
+      avoid: 'Accepting raw JSON or string filters'

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

@@ -6,31 +6,30 @@ tags:
 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.'
+    - 'DO NOT use requirements.txt as the primary dependency spec. Use pyproject.toml with uv (preferred) or Poetry, and commit the lock file.'
+    - 'DO NOT use print() for logging. Use structured JSON logging (structlog).'
+    - 'DO NOT use unittest.TestCase. Use pytest with fixtures.'
+    - 'DO NOT rely on bare assert in production code. Raise explicit exceptions.'
   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.'
+    - 'Use uv for environment and dependency management (uv sync, uv run).'
+    - 'Use pytest + pytest-asyncio + pytest-cov for tests.'
+    - 'Use httpx for sync/async HTTP and ASGITransport for FastAPI integration tests.'
+    - 'Use structlog and bind request_id/user_id in context.'
+    - 'Use ruff for lint + format and enforce it in CI.'
+    - 'Use mypy or pyright in strict mode.'
+    - 'Use pydantic-settings for env loading/validation.'
+    - 'Use tenacity for retry/backoff around transient external calls.'
+    - 'Use pandera or Great Expectations for data quality validation in pipelines.'
   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)'
+      then: 'Use uv + pyproject.toml + lock file'
+      avoid: 'pip-only requirements.txt workflows'
+    - when: 'Lint/format tooling is needed'
+      then: 'Use ruff as the default toolchain'
+      avoid: 'Split flake8/black/isort stacks'
+    - when: 'Data quality checks are needed'
+      then: 'Use pandera or Great Expectations with explicit checks'
+      avoid: 'Scattered inline asserts with 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)'
+      then: 'Use httpx'
+      avoid: 'Mixing requests/aiohttp across services'

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

@@ -7,37 +7,32 @@ tags:
 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.'
+    - 'DO NOT use moment/dayjs. Standardize on date-fns with named imports.'
+    - 'DO NOT use jsonwebtoken. Use jose 6+.'
+    - 'DO NOT handle Express req/res directly in NestJS handlers.'
+    - 'DO NOT import lodash as a full bundle. Prefer native APIs or per-function imports.'
+    - 'DO NOT use node-fetch/got in NestJS services. Use @nestjs/axios HttpModule or native fetch().'
+    - 'DO NOT use winston/morgan/console.log for app logs. Use pino via nestjs-pino.'
   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.'
+    - 'Use class-validator + class-transformer DTO validation with ValidationPipe({ whitelist: true }).'
+    - 'Use @nestjs/graphql + @nestjs/apollo code-first for GraphQL APIs.'
+    - 'Use GraphQL Codegen for operation/result type generation.'
+    - 'Use jose for JWT sign/verify and JWKS workflows.'
+    - 'Use pino + nestjs-pino as the default structured logger.'
+    - 'Use rxjs operators for NestJS interceptors, guards, and event streams.'
+    - 'Use Vitest + @nestjs/testing + supertest for unit/e2e tests.'
+    - 'Use zod for schema validation outside DTOs (env, external payloads).'
+    - 'Keep TypeScript strict mode enabled.'
   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)'
+    - when: 'JWT auth is needed'
+      then: 'Use jose (SignJWT, jwtVerify, createRemoteJWKSet)'
+      avoid: 'jsonwebtoken'
+    - when: 'Date handling is needed'
+      then: 'Use date-fns named imports'
+      avoid: 'moment/dayjs'
+    - when: 'Utility helpers are needed (clone/groupBy)'
+      then: 'Use native JS first; fallback to scoped lodash imports only'
+      avoid: 'import _ from "lodash"'
+    - when: 'Structured logging is needed'
+      then: 'Use pino via nestjs-pino LoggerModule.forRoot()'
+      avoid: 'console.log or mixed logging stacks'