ai-ops-cli 0.1.8 → 0.1.10

package/README.md

@@ -2,6 +2,56 @@
 
 CLI for managing AI tool rules and presets across projects.
 
+## Why this exists
+
+`ai-ops-cli` was created to reduce configuration drift across AI coding tools in a team.
+
+- Different tools (Claude Code, Codex, Gemini CLI) require different file locations and prompt layouts.
+- Tool conventions evolve over time, so manually maintained setup files become inconsistent quickly.
+- Teams need a single, repeatable way to install and maintain AI rule scaffolding.
+
+This project uses a centralized rule source (SSOT) and scaffolds tool-native files into the current project.
+For the full product background and architecture intent, see [`docs/plan.md`](../../docs/plan.md).
+
+### What this library provides
+
+- Interactive installation flow for supported AI tools (`ai-ops init`)
+- Managed updates based on installed manifest (`ai-ops update`)
+- Drift detection against current source hash (`ai-ops diff`)
+- Safe cleanup of installed managed files + manifest (`ai-ops uninstall`)
+- Project-local installation and management
+
+### What this library does not provide
+
+- A hosted backend or remote state service
+- Rule authoring workflow inside the CLI itself
+- IDE-specific plugin management
+
+## Supported AI tools and installation model
+
+`ai-ops-cli` currently supports:
+
+- Claude Code (`claude-code`)
+- Codex (`codex`)
+- Gemini CLI (`gemini`)
+
+### Tool-specific installation layout
+
+| Tool        | Single project                        | Monorepo                                                                      | Why this layout (JIT rationale)                                                                      |
+| ----------- | ------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Claude Code | `.claude/rules/<rule-id>.md` per rule | Shared rules in `.claude/rules/*.md`, domain rules in `<workspace>/CLAUDE.md` | Keeps always-on rules stable while loading domain rules only for matching paths/workspaces.          |
+| Codex       | `AGENTS.md` + `AGENTS.override.md`    | Root `AGENTS.md` + `<workspace>/AGENTS.override.md`                           | Uses root baseline + local override so only relevant workspace context is applied at execution time. |
+| Gemini CLI  | `.gemini/GEMINI.md`                   | Root `.gemini/GEMINI.md` + `<workspace>/GEMINI.md`                            | Splits shared defaults and workspace-local context to reduce irrelevant prompt context.              |
+
+Gemini CLI can also install optional runtime settings to `.gemini/settings.json`.
+
+### Installation behavior details
+
+- Rules are split into shared and domain categories and rendered per tool with tool-native file shapes.
+- Existing managed files are replaced safely using ai-ops metadata headers.
+- Existing non-managed files are preserved and receive an `ai-ops` managed section block instead of full overwrite.
+- `update`, `diff`, and `uninstall` operate from the manifest to keep changes deterministic and idempotent.
+
 ## Install
 
 ```bash
@@ -19,6 +69,9 @@ ai-ops diff
 
 # Apply updates
 ai-ops update
+
+# Remove installed managed files and manifest
+ai-ops uninstall
 ```
 
 ## Options
@@ -30,9 +83,9 @@ Commands:
   init     Initialize AI tool rules for a project
   update   Update installed rules
   diff     Show diff between installed and current rules
+  uninstall Remove installed rules and manifest
 
 Options:
-  --scope <scope>  Target scope: project (default) or global
   --force          Force update even when no changes detected
   -V, --version    Output the version number
   -h, --help       Display help

package/data/presets.yaml

@@ -0,0 +1,56 @@
+frontend-web:
+  description: '웹 프론트엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - plan-mode
+    - naming-convention
+    - engineering-standards
+    - typescript
+    - react-typescript
+    - shadcn-ui
+    - nextjs
+    - libs-frontend-web
+
+frontend-app:
+  description: '앱 프론트엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - plan-mode
+    - naming-convention
+    - engineering-standards
+    - flutter
+    - libs-frontend-app
+
+backend-ts:
+  description: 'TypeScript 백엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - plan-mode
+    - naming-convention
+    - engineering-standards
+    - typescript
+    - nestjs
+    - prisma-postgresql
+    - graphql
+    - nestjs-graphql
+    - libs-backend-ts
+
+backend-python:
+  description: 'Python 백엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - plan-mode
+    - naming-convention
+    - engineering-standards
+    - python
+    - fastapi
+    - sqlalchemy
+    - libs-backend-python

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

@@ -0,0 +1,35 @@
+id: ai-llm-python
+category: domain
+tags:
+  - python
+  - llm
+  - ai
+priority: 28
+content:
+  constraints:
+    - '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 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: '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

@@ -0,0 +1,30 @@
+id: code-philosophy
+category: philosophy
+tags:
+  - general
+  - philosophy
+  - tdd
+  - functional
+  - immutability
+priority: 80
+content:
+  constraints:
+    - '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:
+    - '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: '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/communication.yaml

@@ -0,0 +1,11 @@
+id: communication
+category: communication
+tags:
+  - general
+  - communication
+priority: 85
+content:
+  constraints:
+    - "DO NOT use filler phrases like 'Certainly,' 'Of course,' 'Here is the code,' 'I understand,' 'Great question.' Just output the solution."
+  guidelines:
+    - 'Think and explain in Korean. Write code and comments in English.'

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

@@ -0,0 +1,34 @@
+id: data-pipeline-python
+category: domain
+tags:
+  - python
+  - data-engineering
+  - polars
+  - duckdb
+priority: 33
+content:
+  constraints:
+    - '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, 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: '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: '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

@@ -0,0 +1,39 @@
+id: engineering-standards
+category: standard
+tags:
+  - general
+  - api
+  - data-format
+  - cross-cutting
+priority: 70
+content:
+  constraints:
+    - '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:
+    - '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'
+      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

@@ -0,0 +1,34 @@
+id: fastapi
+category: framework
+tags:
+  - python
+  - fastapi
+  - backend
+priority: 42
+content:
+  constraints:
+    - '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 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 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, 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 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

@@ -0,0 +1,40 @@
+id: flutter
+category: framework
+tags:
+  - dart
+  - flutter
+  - riverpod
+  - mobile
+priority: 30
+content:
+  constraints:
+    - '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 @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 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

@@ -0,0 +1,34 @@
+id: graphql
+category: api
+tags:
+  - graphql
+  - api
+  - schema-design
+priority: 48
+content:
+  constraints:
+    - '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 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 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

@@ -0,0 +1,35 @@
+id: libs-backend-python
+category: tooling
+tags:
+  - python
+  - backend
+priority: 22
+content:
+  constraints:
+    - '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:
+    - '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 + 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'
+      avoid: 'Mixing requests/aiohttp across services'

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

@@ -0,0 +1,38 @@
+id: libs-backend-ts
+category: tooling
+tags:
+  - typescript
+  - nestjs
+  - backend
+priority: 25
+content:
+  constraints:
+    - '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:
+    - '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 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'

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

@@ -0,0 +1,39 @@
+id: libs-frontend-app
+category: tooling
+tags:
+  - dart
+  - flutter
+  - frontend
+priority: 15
+content:
+  constraints:
+    - 'DO NOT use http for API calls. Standardize on dio 5+.'
+    - 'DO NOT use Provider or Bloc. Standardize on flutter_riverpod with code generation.'
+    - 'DO NOT handwrite data classes (==, hashCode, copyWith, toJson). Use freezed.'
+    - 'DO NOT use Navigator 1.0 push/pop APIs for app routing. Use go_router.'
+    - 'DO NOT manually implement JSON serialization for models. Use json_serializable/freezed generation.'
+  guidelines:
+    - 'Use @riverpod with riverpod_generator and build_runner for provider generation.'
+    - 'Use freezed for immutable models and unions.'
+    - 'Define routes in a central GoRouter config and navigate with context.go()/push().'
+    - 'Create one shared Dio instance via Riverpod DI with interceptors and auth headers.'
+    - 'Use shared_preferences for non-sensitive keys and flutter_secure_storage for secrets.'
+    - 'Use cached_network_image for network image caching and placeholders.'
+    - 'Use very_good_analysis and treat warnings as CI failures.'
+    - 'Use intl/easy_localization with ARB-based translations.'
+  decision_table:
+    - when: 'HTTP API calls are needed'
+      then: 'Use DI-injected central Dio client'
+      avoid: 'Per-feature ad-hoc http clients'
+    - when: 'Simple local persistence is needed'
+      then: 'Use shared_preferences or flutter_secure_storage by data sensitivity'
+      avoid: 'SQLite/Hive for plain key-value settings'
+    - when: 'Network images are rendered'
+      then: 'Use cached_network_image with placeholder/error states'
+      avoid: 'Bare Image.network everywhere'
+    - when: 'Test mocking is needed'
+      then: 'Use mocktail (class-based, no code generation required)'
+      avoid: 'mockito with @GenerateMocks annotation boilerplate'
+    - when: 'Code generation is required'
+      then: 'Run build_runner watch in dev and build in CI'
+      avoid: 'Manually editing generated files'

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

@@ -0,0 +1,44 @@
+id: libs-frontend-web
+category: tooling
+tags:
+  - typescript
+  - react
+  - nextjs
+  - frontend
+priority: 20
+content:
+  constraints:
+    - 'DO NOT use moment.js or dayjs. Standardize on date-fns with named imports.'
+    - 'DO NOT use react-icons. Use lucide-react named imports only.'
+    - 'DO NOT use axios in browser code. Use native fetch() for Next.js cache/revalidate integration.'
+    - 'DO NOT build conditional className strings manually. Use cn() and cva().'
+    - 'DO NOT install parallel UI kits (MUI, Ant, Chakra) alongside shadcn/ui.'
+    - 'DO NOT use Redux/Recoil/MobX for local UI state. Use zustand for client UI state.'
+  guidelines:
+    - 'Use @apollo/client with @apollo/experimental-nextjs-app-support for GraphQL in App Router.'
+    - 'Use GraphQL Codegen client-preset to generate TypedDocumentNode types at build time.'
+    - 'Keep styling on Tailwind + design tokens (CSS variables) and cva variants.'
+    - 'Use next-intl for i18n and next-themes for theme switching.'
+    - 'Render Recharts inside client components only.'
+    - 'Mount one Sonner <Toaster /> at the app root and call toast() from features.'
+    - 'Sanitize user HTML with isomorphic-dompurify before dangerouslySetInnerHTML.'
+    - 'Use Vitest + Testing Library; prefer userEvent over fireEvent.'
+  decision_table:
+    - when: 'GraphQL data fetching is needed in App Router'
+      then: 'Use ApolloNextAppProvider with @apollo/client'
+      avoid: 'Ad-hoc raw fetch cache wiring'
+    - when: 'Date handling is needed'
+      then: 'Use date-fns named imports'
+      avoid: 'moment/dayjs'
+    - when: 'Icons are needed'
+      then: 'Use lucide-react named imports'
+      avoid: 'react-icons or inline SVG'
+    - when: 'Form validation is needed'
+      then: 'Use zod + react-hook-form + zod resolver'
+      avoid: 'Manual validation in component event handlers'
+    - when: 'User-generated HTML must be rendered'
+      then: 'Sanitize with isomorphic-dompurify first, then dangerouslySetInnerHTML'
+      avoid: 'Rendering unsanitized HTML (XSS risk)'
+    - when: 'Client UI state is needed (modals, wizard step, sidebar)'
+      then: 'Use a zustand slice'
+      avoid: 'Global Redux/Recoil for simple UI state'

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. Keep resolvers thin and delegate to Services.'
+    - 'DO NOT access raw GraphQL args/context manually when typed decorators are available. Use @Args() with typed DTOs.'
+    - 'DO NOT query the DB directly inside @ResolveField(). Use request-scoped DataLoaders.'
+    - 'DO NOT expose unauthenticated @Subscription() endpoints. Protect with guards and subscriber checks.'
+    - 'DO NOT maintain manual SDL in code-first projects. TypeScript decorators are the source of truth.'
+  guidelines:
+    - 'Use one resolver per domain entity with @Resolver(), @Query(), @Mutation(), and @ResolveField() responsibilities clearly separated.'
+    - 'Register DataLoaders as request-scoped providers to enable per-request batching without cross-request leakage.'
+    - 'Add decorator descriptions for public schema types and fields to keep generated SDL self-documenting.'
+    - 'Enforce query depth/complexity limits to prevent expensive nested query abuse.'
+    - 'Define and register custom scalars (DateTime, UUID, JSON) consistently in GraphQL module config.'
+    - 'Reuse Guards/Interceptors from REST and adapt context via GqlExecutionContext.'
+  decision_table:
+    - when: 'A field resolver loads related data (e.g., user.posts)'
+      then: 'Use @ResolveField() + request-scoped DataLoader batching'
+      avoid: 'Repository call per parent row (N+1)'
+    - when: 'Real-time push is required'
+      then: 'Use @Subscription() with Redis PubSub for multi-instance deployments'
+      avoid: 'In-memory PubSub in production'
+    - when: 'Resolver auth is required'
+      then: 'Apply @UseGuards(GqlAuthGuard) and read user from GqlExecutionContext'
+      avoid: 'Manual JWT parsing inside resolver methods'

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() for manual response handling in normal routes. Return values and let Nest handle serialization/interceptors.'
+    - 'DO NOT put business logic in Controllers. Delegate to Services.'
+    - 'DO NOT use forwardRef() as a default fix for circular dependencies. Refactor module boundaries.'
+    - 'DO NOT read process.env directly in services/controllers. Use ConfigService with validated schema.'
+    - 'DO NOT use console.log for app logging. Use Nest Logger or a DI-managed logger (e.g., pino).'
+  guidelines:
+    - 'Organize by feature module and co-locate controller/service/DTO files by domain.'
+    - 'Use class-validator DTOs for request boundaries and avoid exposing persistence entities directly.'
+    - 'Register global ValidationPipe, filters, and guards in main.ts bootstrap.'
+    - 'Use custom HttpException types for domain/business failures.'
+    - 'Use @nestjs/swagger decorators for REST APIs; GraphQL schema serves as contract for GraphQL APIs.'
+  decision_table:
+    - when: 'A cross-cutting check needs handler metadata (auth/roles)'
+      then: 'Use Guards'
+      avoid: 'Middleware for authorization logic'
+    - when: 'You need response transform/caching/timing'
+      then: 'Use Interceptors'
+      avoid: 'Middleware for response-layer behavior'