@jetrabbits/agentic 0.0.1

package/areas/software/full-stack/prompts/debug-issue.md

@@ -0,0 +1,115 @@
+---
+workflow: debug-issue
+---
+
+# Prompt: `/debug-issue`
+
+Use when: diagnosing a bug in a FastAPI / SQLAlchemy service — from stack trace or symptom through to root cause, fix, and regression test.
+
+---
+
+## Example 1 — Production error with stack trace
+
+**EN:**
+```
+/debug-issue
+
+Service: order-service (FastAPI + SQLAlchemy async)
+Error: 500 Internal Server Error on POST /api/v1/orders
+Affected users: 100% of users who apply a discount code; 0% for regular checkout
+First seen: 2024-09-13 14:30 UTC (correlates with v2.4.1 deploy at 14:22 UTC)
+Stack trace:
+  File "src/services/order_service.py", line 147, in create_order
+    total = subtotal - order_data['discount_amount']
+  KeyError: 'discount_amount'
+Logs (request_id=req_abc123):
+  INFO  order.validation_passed user_id=42 discount_code=SUMMER20
+  INFO  discount.applied code=SUMMER20 amount=15.00
+  ERROR order.creation_failed KeyError: 'discount_amount'
+Suspected cause: discount service returns Decimal amount but order_service expects field 'discount_amount';
+  PR #204 renamed field from 'discount' to 'discount_amount' in discount-service but order-service not updated
+```
+
+**RU:**
+```
+/debug-issue
+
+Сервис: order-service (FastAPI + SQLAlchemy async)
+Ошибка: 500 Internal Server Error на POST /api/v1/orders
+Затронутые пользователи: 100% пользователей применяющих код скидки; 0% при обычном оформлении
+Первое появление: 2024-09-13 14:30 UTC (совпадает с деплоем v2.4.1 в 14:22 UTC)
+Stack trace:
+  File "src/services/order_service.py", line 147, in create_order
+    total = subtotal - order_data['discount_amount']
+  KeyError: 'discount_amount'
+Логи (request_id=req_abc123):
+  INFO  order.validation_passed user_id=42 discount_code=SUMMER20
+  INFO  discount.applied code=SUMMER20 amount=15.00
+  ERROR order.creation_failed KeyError: 'discount_amount'
+Предполагаемая причина: discount сервис возвращает Decimal сумму но order-service ожидает поле 'discount_amount';
+  PR #204 переименовал поле с 'discount' на 'discount_amount' в discount-service но order-service не обновлён
+```
+
+---
+
+## Example 2 — Performance regression (no error)
+
+**EN:**
+```
+/debug-issue
+
+Service: product-service
+Symptom: GET /api/v1/products p99 latency went from 85ms to 4 200ms after migration PR #198
+No errors in logs — just extreme latency
+Migration PR #198 added: products_tags junction table (many-to-many between products and tags)
+Observed: slow queries only when tags are present; products without tags still fast (85ms)
+DB metrics: PostgreSQL CPU 8% (not saturated); query count per request jumped from 3 to ~47
+Diagnosis direction: N+1 query — each product loads its tags in a separate query; need joinedload()
+Reproduce: run EXPLAIN ANALYZE on GET /products with tags; count SELECT statements in a single request
+```
+
+**RU:**
+```
+/debug-issue
+
+Сервис: product-service
+Симптом: p99 задержка GET /api/v1/products выросла с 85ms до 4 200ms после миграции PR #198
+Ошибок в логах нет — только экстремальная задержка
+Миграция PR #198 добавила: junction таблицу products_tags (many-to-many между products и tags)
+Наблюдение: медленные запросы только когда есть теги; продукты без тегов по-прежнему быстрые (85ms)
+Метрики БД: PostgreSQL CPU 8% (не насыщен); количество запросов на запрос выросло с 3 до ~47
+Направление диагностики: N+1 запрос — каждый продукт загружает теги отдельным запросом; нужен joinedload()
+Воспроизвести: запустить EXPLAIN ANALYZE на GET /products с тегами; подсчитать SELECT операторы в одном запросе
+```
+
+---
+
+## Example 3 — Intermittent / Race condition
+
+**EN:**
+```
+/debug-issue
+
+Service: payment-service
+Symptom: ~2% of payments marked as FAILED despite Stripe confirming payment succeeded
+Pattern: only happens when user clicks "Pay" twice quickly (double-submit)
+Error log: "IntegrityError: duplicate key value violates unique constraint payments_idempotency_key"
+The payment actually succeeds on first attempt; second attempt raises IntegrityError which is propagated as 500
+Root issue: IntegrityError not caught — should return 200 with existing payment, not 500
+Fix direction: catch IntegrityError on idempotency key collision → query existing payment → return it
+Test: write test that sends two concurrent requests with same idempotency key; verify both return 200 with same payment_id
+```
+
+**RU:**
+```
+/debug-issue
+
+Сервис: payment-service
+Симптом: ~2% платежей помечаются как FAILED несмотря на то что Stripe подтверждает успешную оплату
+Паттерн: происходит только когда пользователь быстро дважды нажимает "Оплатить" (двойная отправка)
+Лог ошибки: "IntegrityError: duplicate key value violates unique constraint payments_idempotency_key"
+Платёж фактически проходит с первой попытки; вторая попытка вызывает IntegrityError которая возвращается как 500
+Корневая проблема: IntegrityError не перехватывается — должен возвращать 200 с существующим платежом, не 500
+Направление исправления: перехватить IntegrityError при коллизии idempotency key → запросить существующий платёж → вернуть его
+Тест: написать тест отправляющий два одновременных запроса с одинаковым idempotency key; убедиться что оба возвращают 200 с одинаковым payment_id
+```

package/areas/software/full-stack/prompts/develop-feature.md

@@ -0,0 +1,119 @@
+---
+workflow: develop-feature
+---
+
+# Prompt: `/develop-feature`
+
+Use when: implementing a feature end-to-end in an existing full-stack Python/FastAPI + Next.js project — DB model through API to UI.
+
+---
+
+## Example 1 — Full-stack feature with DB and UI
+
+**EN:**
+```
+/develop-feature
+
+Feature: "Product wishlists"
+Stack: FastAPI (Python 3.12) + SQLAlchemy async + Next.js (App Router) + Tailwind
+Acceptance criteria:
+  - Users can add / remove products from their wishlist (POST/DELETE /api/v1/wishlist/{product_id})
+  - GET /api/v1/wishlist returns user's wishlist (paginated, cursor-based)
+  - Product detail page shows "Add to wishlist" / "Remove" button (heart icon) — auth required to use
+  - Wishlist page (/wishlist) lists all saved products with thumbnail, name, price
+  - Wishlist count shown in navigation header (badge)
+DB changes: create wishlist_items table (user_id, product_id, created_at); unique constraint
+Constraints: wishlist is user-scoped (cannot see others'); limit 500 items per user
+Tests: service unit tests (add duplicate = 409, over limit = 400) + API integration + E2E (add → see on page)
+```
+
+**RU:**
+```
+/develop-feature
+
+Фича: "Списки желаний продуктов"
+Стек: FastAPI (Python 3.12) + SQLAlchemy async + Next.js (App Router) + Tailwind
+Критерии приёмки:
+  - Пользователи могут добавлять / удалять продукты из списка желаний (POST/DELETE /api/v1/wishlist/{product_id})
+  - GET /api/v1/wishlist возвращает список желаний пользователя (пагинация, cursor-based)
+  - Страница продукта показывает кнопку "Добавить в список желаний" / "Убрать" (иконка сердца) — для использования требуется auth
+  - Страница /wishlist перечисляет все сохранённые продукты с миниатюрой, названием, ценой
+  - Количество в списке желаний отображается в навигационном заголовке (badge)
+Изменения БД: создать таблицу wishlist_items (user_id, product_id, created_at); уникальное ограничение
+Ограничения: список желаний привязан к пользователю (нельзя видеть чужие); лимит 500 позиций на пользователя
+Тесты: unit тесты сервиса (добавить дубликат = 409, превышение лимита = 400) + API интеграция + E2E (добавить → увидеть на странице)
+```
+
+---
+
+## Example 2 — API-only feature (no frontend)
+
+**EN:**
+```
+/develop-feature
+
+Feature: "Bulk order status update (admin API)"
+Stack: FastAPI + SQLAlchemy async (no UI changes)
+Endpoint: PATCH /api/v1/admin/orders/bulk-status
+Auth: admin role required (scope: admin:orders:write)
+Request: { order_ids: list[int] (max 100), status: OrderStatus, reason: str }
+Business rules:
+  - All order_ids must belong to the same tenant (400 if mixed tenants)
+  - Only allowed transitions: PENDING → PROCESSING, PROCESSING → SHIPPED
+  - Invalid transition returns 422 with per-order error detail
+  - Successful updates emit OrderStatusChanged event per order
+  - Returns: { updated: int, failed: list[{order_id, error}] } (partial success allowed)
+DB: bulk UPDATE with RETURNING; wrap in single transaction (all-or-nothing if any fail: configurable)
+Tests: test partial failure scenario; test tenant isolation; test unauthorised access (403)
+```
+
+**RU:**
+```
+/develop-feature
+
+Фича: "Массовое обновление статуса заказов (admin API)"
+Стек: FastAPI + SQLAlchemy async (без изменений UI)
+Эндпоинт: PATCH /api/v1/admin/orders/bulk-status
+Auth: требуется роль admin (scope: admin:orders:write)
+Запрос: { order_ids: list[int] (макс 100), status: OrderStatus, reason: str }
+Бизнес правила:
+  - Все order_ids должны принадлежать одному tenant (400 если смешанные tenants)
+  - Разрешённые переходы только: PENDING → PROCESSING, PROCESSING → SHIPPED
+  - Недопустимый переход возвращает 422 с детализацией ошибок по заказу
+  - Успешные обновления отправляют событие OrderStatusChanged на каждый заказ
+  - Возвращает: { updated: int, failed: list[{order_id, error}] } (частичный успех допускается)
+БД: массовый UPDATE с RETURNING; обернуть в одну транзакцию (всё или ничего при любом сбое: настраивается)
+Тесты: тест сценария частичного сбоя; тест изоляции tenant; тест несанкционированного доступа (403)
+```
+
+---
+
+## Example 3 — Quick / Small change
+
+**EN:**
+```
+/develop-feature
+
+Feature: "Archive products (soft-delete)"
+Change scope: small — adds 'archived' status and filters
+Endpoints affected:
+  - PATCH /api/v1/products/{id}: add {"status": "archived"} as valid transition (admin only)
+  - GET /api/v1/products: exclude archived by default; add ?include_archived=true param for admin
+DB: add archived_at TIMESTAMP column to products (nullable; non-breaking migration)
+No frontend changes needed (admin uses API directly)
+Tests: verify archived products hidden from public listing; visible to admin with param
+```
+
+**RU:**
+```
+/develop-feature
+
+Фича: "Архивирование продуктов (soft-delete)"
+Скоуп изменения: небольшой — добавляет статус 'archived' и фильтры
+Затронутые эндпоинты:
+  - PATCH /api/v1/products/{id}: добавить {"status": "archived"} как допустимый переход (только admin)
+  - GET /api/v1/products: исключать archived по умолчанию; добавить параметр ?include_archived=true для admin
+БД: добавить столбец archived_at TIMESTAMP в products (nullable; non-breaking миграция)
+Изменений frontend не нужно (admin использует API напрямую)
+Тесты: убедиться что архивированные продукты скрыты из публичного листинга; видны admin с параметром
+```

package/areas/software/full-stack/prompts/feature-implementation-flow.md

@@ -0,0 +1,137 @@
+---
+workflow: feature-implementation-flow
+---
+
+# Prompt: `/feature-implementation-flow`
+
+Use when: implementing a single feature in an existing FastAPI/SQLAlchemy service — following the layered architecture (model → repo → service → endpoint).
+
+---
+
+## Example 1 — State transition with business rules
+
+**EN:**
+```
+/feature-implementation-flow
+
+Feature: "Refund order"
+Existing codebase: src/ (FastAPI + SQLAlchemy async, layered architecture)
+Endpoint: POST /api/v1/orders/{order_id}/refund
+Request body: { reason: str, amount: Decimal (optional, defaults to full order total) }
+Business rules:
+  - Only orders with status PAID can be refunded
+  - Partial refund: amount must be > 0 and ≤ order total
+  - Full refund if amount not provided
+  - On refund: create RefundRecord, update order status → REFUNDED, emit OrderRefunded event
+  - Idempotency: same order_id + reason within 1 hour = return existing refund (no duplicate)
+Error responses:
+  - 404 if order not found
+  - 403 if order belongs to different user
+  - 400 if order not in PAID status (code: ORDER_NOT_REFUNDABLE)
+  - 400 if amount > total (code: REFUND_EXCEEDS_TOTAL)
+Tests required: service unit tests (all business rules) + API integration tests (all error codes)
+```
+
+**RU:**
+```
+/feature-implementation-flow
+
+Фича: "Возврат заказа"
+Существующий код: src/ (FastAPI + SQLAlchemy async, layered architecture)
+Эндпоинт: POST /api/v1/orders/{order_id}/refund
+Тело запроса: { reason: str, amount: Decimal (необязательно, по умолчанию полная сумма заказа) }
+Бизнес правила:
+  - Возврат возможен только для заказов со статусом PAID
+  - Частичный возврат: amount должен быть > 0 и ≤ итогу заказа
+  - Полный возврат если amount не указан
+  - При возврате: создать RefundRecord, обновить статус заказа → REFUNDED, отправить событие OrderRefunded
+  - Идемпотентность: одинаковые order_id + reason в течение 1 часа = вернуть существующий возврат (без дублирования)
+Ответы ошибок:
+  - 404 если заказ не найден
+  - 403 если заказ принадлежит другому пользователю
+  - 400 если заказ не в статусе PAID (code: ORDER_NOT_REFUNDABLE)
+  - 400 если amount > total (code: REFUND_EXCEEDS_TOTAL)
+Обязательные тесты: unit тесты сервиса (все бизнес правила) + API интеграционные тесты (все коды ошибок)
+```
+
+---
+
+## Example 2 — New resource with relationships
+
+**EN:**
+```
+/feature-implementation-flow
+
+Feature: "Product reviews"
+Existing codebase: src/ (order-service extended with product catalog)
+Endpoints:
+  POST /api/v1/products/{product_id}/reviews   → create review (auth required)
+  GET  /api/v1/products/{product_id}/reviews   → paginated list, newest first (no auth)
+  DELETE /api/v1/reviews/{review_id}           → delete own review (auth required)
+Business rules:
+  - One review per user per product (409 if already reviewed)
+  - Rating: integer 1–5 (validated)
+  - Text: 10–1000 characters
+  - User cannot review their own product
+  - Product average_rating and review_count cached on Product model (updated on create/delete)
+DB changes: create reviews table; add average_rating + review_count columns to products
+Performance: GET list uses cursor pagination; N+1 safeguard (eager-load author username)
+```
+
+**RU:**
+```
+/feature-implementation-flow
+
+Фича: "Отзывы на продукты"
+Существующий код: src/ (order-service расширенный каталогом продуктов)
+Эндпоинты:
+  POST /api/v1/products/{product_id}/reviews   → создать отзыв (требуется auth)
+  GET  /api/v1/products/{product_id}/reviews   → пагинированный список, сначала новые (без auth)
+  DELETE /api/v1/reviews/{review_id}           → удалить свой отзыв (требуется auth)
+Бизнес правила:
+  - Один отзыв от пользователя на продукт (409 если уже оставлен отзыв)
+  - Оценка: целое число 1–5 (валидируется)
+  - Текст: 10–1000 символов
+  - Пользователь не может оставить отзыв на свой продукт
+  - average_rating и review_count продукта кэшируются в модели Product (обновляются при создании/удалении)
+Изменения БД: создать таблицу reviews; добавить столбцы average_rating + review_count в products
+Производительность: GET список использует cursor пагинацию; защита от N+1 (eager-load имя автора)
+```
+
+---
+
+## Example 3 — Background / async job feature
+
+**EN:**
+```
+/feature-implementation-flow
+
+Feature: "Send order confirmation email (async)"
+Trigger: OrderPaid event consumed from RabbitMQ queue
+Implementation: ARQ worker task, not a FastAPI endpoint
+Task: send_order_confirmation_email(order_id: int)
+  - Load order + user email from DB
+  - Render email template (templates/order_confirmation.html)
+  - Send via SendGrid API (SENDGRID_API_KEY from env)
+  - Mark order.confirmation_sent = True
+Retry: 3 attempts, exponential backoff (30s, 90s, 270s)
+Dead-letter: after 3 failures → log error with order_id + push to failed_notifications queue
+Tests: mock SendGrid client; test retry logic; test dead-letter on repeated failure
+```
+
+**RU:**
+```
+/feature-implementation-flow
+
+Фича: "Отправка email подтверждения заказа (async)"
+Триггер: событие OrderPaid потребляемое из очереди RabbitMQ
+Реализация: ARQ worker задача, не FastAPI эндпоинт
+Задача: send_order_confirmation_email(order_id: int)
+  - Загрузить заказ + email пользователя из БД
+  - Отрисовать email шаблон (templates/order_confirmation.html)
+  - Отправить через SendGrid API (SENDGRID_API_KEY из env)
+  - Отметить order.confirmation_sent = True
+Повторные попытки: 3 попытки, exponential backoff (30s, 90s, 270s)
+Dead-letter: после 3 неудач → логировать ошибку с order_id + поместить в очередь failed_notifications
+Тесты: mock SendGrid клиент; тест логики повторных попыток; тест dead-letter при повторных сбоях
+```

package/areas/software/full-stack/prompts/testing-ci-pipeline.md

@@ -0,0 +1,119 @@
+---
+workflow: testing-ci-pipeline
+---
+
+# Prompt: `/testing-ci-pipeline`
+
+Use when: running the full CI validation pipeline — lint, type check, unit tests, integration tests, E2E — or diagnosing a CI failure.
+
+---
+
+## Example 1 — Full pipeline on PR
+
+**EN:**
+```
+/testing-ci-pipeline
+
+Project type: backend (Python / FastAPI)
+Test scope: all
+Trigger: PR #187 ready for review
+Pipeline stages (in order):
+  1. lint:  ruff check src/ tests/ — zero tolerance
+  2. types: mypy src/ --strict
+  3. unit:  pytest tests/unit/ -x --tb=short (fail fast)
+  4. integration: pytest tests/integration/ --cov=src --cov-report=term-missing
+  5. e2e:   pytest tests/e2e/ (Docker Compose stack: app + postgres + redis)
+Coverage threshold: 80% lines on src/ — fail CI if below
+Environment: GitHub Actions (ubuntu-latest); secrets from GitHub Secrets
+Artefacts to upload: coverage/html/, test-results/junit.xml
+Expected duration: < 8 minutes total
+```
+
+**RU:**
+```
+/testing-ci-pipeline
+
+Тип проекта: backend (Python / FastAPI)
+Скоуп тестов: все
+Триггер: PR #187 готов к ревью
+Этапы pipeline (по порядку):
+  1. lint:  ruff check src/ tests/ — нулевая терпимость
+  2. types: mypy src/ --strict
+  3. unit:  pytest tests/unit/ -x --tb=short (завершение при первом сбое)
+  4. integration: pytest tests/integration/ --cov=src --cov-report=term-missing
+  5. e2e:   pytest tests/e2e/ (Docker Compose стек: app + postgres + redis)
+Порог покрытия: 80% строк в src/ — не прохождение CI если ниже
+Окружение: GitHub Actions (ubuntu-latest); секреты из GitHub Secrets
+Артефакты для загрузки: coverage/html/, test-results/junit.xml
+Ожидаемая длительность: < 8 минут всего
+```
+
+---
+
+## Example 2 — CI failure investigation
+
+**EN:**
+```
+/testing-ci-pipeline
+
+Mode: diagnose failure
+Project type: frontend (TypeScript / React)
+Failed CI run: https://github.com/myorg/myapp/actions/runs/9876543210
+Failure stage: integration tests (unit passed)
+Error output (from CI log):
+  FAIL src/features/checkout/__tests__/CheckoutStepper.test.tsx
+  ● CheckoutStepper › step 3 payment › renders Stripe Elements
+    TypeError: Cannot read properties of undefined (reading 'create')
+    at Object.<anonymous> (src/features/checkout/CheckoutStepper.tsx:47:22)
+Context: Stripe mock was working yesterday; PR only changed styling (no logic changes)
+Hypothesis: Stripe mock not restored between tests — shared state pollution
+Investigate: check jest.mock() setup in test file; check if other test modified Stripe global
+Fix: ensure jest.resetAllMocks() in afterEach or use jest.isolateModules()
+```
+
+**RU:**
+```
+/testing-ci-pipeline
+
+Режим: диагностика сбоя
+Тип проекта: frontend (TypeScript / React)
+Неудачный CI запуск: https://github.com/myorg/myapp/actions/runs/9876543210
+Этап сбоя: integration тесты (unit прошли)
+Вывод ошибки (из CI лога):
+  FAIL src/features/checkout/__tests__/CheckoutStepper.test.tsx
+  ● CheckoutStepper › step 3 payment › renders Stripe Elements
+    TypeError: Cannot read properties of undefined (reading 'create')
+    at Object.<anonymous> (src/features/checkout/CheckoutStepper.tsx:47:22)
+Контекст: Stripe mock работал вчера; PR изменил только стили (без изменений логики)
+Гипотеза: Stripe mock не восстанавливается между тестами — загрязнение shared state
+Расследовать: проверить настройку jest.mock() в файле теста; проверить изменял ли другой тест Stripe global
+Исправление: обеспечить jest.resetAllMocks() в afterEach или использовать jest.isolateModules()
+```
+
+---
+
+## Example 3 — Scope: unit only (quick check)
+
+**EN:**
+```
+/testing-ci-pipeline
+
+Project type: backend
+Test scope: unit only (fast feedback during development)
+Command: pytest tests/unit/ -x -q --tb=short
+Target: verify that new OrderService.refund() method passes all unit tests before pushing
+Expected: < 60 seconds; no Docker, no DB, no network calls
+Coverage: skip (coverage only on full run)
+```
+
+**RU:**
+```
+/testing-ci-pipeline
+
+Тип проекта: backend
+Скоуп тестов: только unit (быстрая обратная связь при разработке)
+Команда: pytest tests/unit/ -x -q --tb=short
+Цель: убедиться что новый метод OrderService.refund() проходит все unit тесты перед push
+Ожидается: < 60 секунд; без Docker, без БД, без сетевых вызовов
+Покрытие: пропустить (покрытие только при полном запуске)
+```

package/areas/software/full-stack/rules/api-design-guide.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+glob: api-design-guide
+description: API contracts must be explicit, validated, and versioned
+---
+
+# API Design Rule
+
+**Rules:**
+
+- Use Pydantic for request/response validation; enforce strict types, no raw dicts.
+- Implement `/liveness` and `/readiness` for K8s probes.
+- Implement `/metrics` for FastAPI using PrometheusMiddleware.
+- Version APIs in path or headers (v1, v2…).
+- Sanitize input; output must be explicit.
+- Document all endpoints with OpenAPI/Swagger.
+- No side effects in GET requests.
+- Responses must include status codes and error details.
+
+**Violations:**
+
+- API schemas are implicit.
+- Validation is ad-hoc.
+- Endpoints mutate state unexpectedly.

package/areas/software/full-stack/rules/async-concurrency-guide.md

@@ -0,0 +1,21 @@
+---
+trigger: model_decision
+glob: async-concurrency-guide
+description: isolate async code, use tasks safely
+---
+
+# Async & Concurrency Rule
+
+**Rules:**
+
+- Isolate async/TaskGroup logic from sync code.
+- Do not block event loop with heavy computation.
+- Catch only expected exceptions in async tasks.
+- Ensure idempotency for retried tasks.
+- Implement logic to debug event loop delays.
+
+**Violations:**
+
+- Async tasks share mutable state.
+- Root Exception is caught.
+- Tasks are non-idempotent.

package/areas/software/full-stack/rules/backend-architecture-rule.md

@@ -0,0 +1,41 @@
+---
+trigger: always_on
+glob: backend-architecture-rule
+description: enforce layered architecture and dependency rules for backend services
+---
+
+# Backend Architecture Rule
+
+**Goal:** Maintain clean separation of concerns and testability.
+
+**Layers:**
+
+1.  **API Layer (Entry Points):**
+    - Handles HTTP requests, websocket events, or CLI commands.
+    - Validates input using Pydantic schemas.
+    - Calls Service Layer.
+    - **Allowed Imports:** Service Layer, Schemas.
+    - **Forbidden Imports:** Repository Layer, direct DB access.
+
+2.  **Service Layer (Business Logic):**
+    - Contains pure business logic and orchestration.
+    - Transaction boundaries are defined here.
+    - **Allowed Imports:** Repository Layer, Schemas, Domain Models.
+    - **Forbidden Imports:** API Layer, frameworks (FastAPI/Flask) specific objects.
+
+3.  **Repository Layer (Data Access):**
+    - Abstracts database queries and external service calls.
+    - Returns Domain Models or Pydantic Schemas.
+    - **Allowed Imports:** Domain Models, Database Drivers (SQLAlchemy/AsyncPG).
+    - **Forbidden Imports:** API/Service Layers.
+
+4.  **Domain Models / Schemas:**
+    - Pure data structures.
+    - **Allowed Imports:** None (should be dependency-free).
+
+**Violations:**
+
+- API layer directly accessing database.
+- Service layer returning SQLAlchemy models directly (leaking implementation details).
+- Circular dependencies between layers.
+- Business logic inside API handlers.

package/areas/software/full-stack/rules/background-jobs-guide.md

@@ -0,0 +1,20 @@
+---
+trigger: model_decision
+glob: background-jobs-guide
+description: manage background tasks safely and reliably
+---
+
+# Background Jobs Rule
+
+**Rules:**
+
+- Use queues for async jobs (Celery, RQ, etc.).
+- Ensure idempotency for retried jobs.
+- Log errors and metrics for each task.
+- Limit concurrency and handle exceptions explicitly.
+
+**Violations:**
+
+- Jobs are non-idempotent.
+- Exceptions crash the worker.
+- No logging/metrics for task execution.

package/areas/software/full-stack/rules/code-quality-guide.md

@@ -0,0 +1,22 @@
+---
+trigger: always_on
+glob: code-quality-guide
+description: enforce code formatting, linting, and static typing after code changes
+---
+
+# Code Quality Rule
+
+**Rules:**
+
+- After writing or modifying code, always run formatters and linters.
+- Execute formatting tools and fix all formatting issues.
+- Execute linting tools and fix all lint/type errors until passed.
+- For Python projects, use standard tools (e.g. `ruff`, `black`, `mypy`) via the project's dependency manager.
+- All tools must be installed and run inside the project's virtual environment.
+
+**Violations:**
+
+- Skipping formatting or linting.
+- Ignoring formatter or linter errors.
+- Running tools outside the virtual environment.
+- Missing standard quality tools in dependencies.

package/areas/software/full-stack/rules/database-access-guide.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+glob: database-access-guide
+description: safe, efficient, maintainable DB access.
+---
+
+# Database Access Rule
+
+**Purpose:** Safe, efficient, maintainable DB access.
+
+**Rules:**
+
+- Use repository/DAO layer; no direct DB calls in business logic.
+- Prefer ORM; raw SQL only if necessary, always parameterized.
+- Batch queries; avoid N+1 problems.
+- Use caching carefully; keep invalidation consistent.
+- Use separate schema per project.
+- Run `EXPLAIN` for complex queries; save in `sqlplans`.
+
+**Violations:**
+
+- Unsafe SQL or in business logic.
+- Repeated queries/N+1 issues.
+- Mutable DB state leaks outside DAL.