@jetrabbits/agentic 0.0.1

package/areas/software/backend/prompts/create-endpoint.md

@@ -0,0 +1,97 @@
+---
+workflow: create-endpoint
+---
+
+# Prompt: `/create-endpoint`
+
+Use when: adding a single new API endpoint to an existing backend service.
+
+---
+
+## Example 1 — Domain Action Endpoint
+
+**EN:**
+```
+/create-endpoint "Refund Order"
+
+Method: POST /orders/{order_id}/refund
+Auth: Bearer token, scope: orders:write
+Request body: { reason: string (max 500 chars), amount?: number (partial refund, optional) }
+Business rules:
+- Order must be in PAID status, else return 400 with error code ORDER_NOT_REFUNDABLE
+- If amount not provided: full refund
+- If amount > original: return 400 REFUND_EXCEEDS_ORIGINAL
+- On success: create refund_transaction, update order status to REFUNDED (or PARTIALLY_REFUNDED), emit order.refunded event
+Response: 200 { refund_id, status, amount, processed_at }
+Non-functional: idempotency key support via X-Idempotency-Key header
+```
+
+**RU:**
+```
+/create-endpoint "Возврат средств по заказу"
+
+Метод: POST /orders/{order_id}/refund
+Auth: Bearer token, scope: orders:write
+Тело запроса: { reason: string (макс 500 символов), amount?: number (частичный возврат, опционально) }
+Бизнес-правила:
+- Заказ должен быть в статусе PAID, иначе 400 с кодом ORDER_NOT_REFUNDABLE
+- Если amount не указан: полный возврат
+- Если amount > оригинального: 400 REFUND_EXCEEDS_ORIGINAL
+- Успех: создать refund_transaction, обновить статус (REFUNDED или PARTIALLY_REFUNDED), emit order.refunded
+Ответ: 200 { refund_id, status, amount, processed_at }
+Нефункциональное: поддержка idempotency key через заголовок X-Idempotency-Key
+```
+
+---
+
+## Example 2 — Read / Query Endpoint
+
+**EN:**
+```
+/create-endpoint "List User Activity Feed"
+
+Method: GET /users/{user_id}/feed
+Auth: Bearer token; user can only access own feed unless admin scope
+Query params: limit (default 20, max 100), cursor (pagination), type? (filter by event type)
+Response: { items: ActivityEvent[], next_cursor?: string, total_count: int }
+ActivityEvent: { id, type, payload, created_at }
+Performance: response time p99 < 200ms; use cursor-based pagination, not offset
+Constraints: do not expose other users' PII in feed items
+```
+
+**RU:**
+```
+/create-endpoint "Лента активности пользователя"
+
+Метод: GET /users/{user_id}/feed
+Auth: Bearer token; пользователь видит только свою ленту, если нет admin scope
+Query params: limit (default 20, max 100), cursor (пагинация), type? (фильтр по типу события)
+Ответ: { items: ActivityEvent[], next_cursor?: string, total_count: int }
+ActivityEvent: { id, type, payload, created_at }
+Производительность: p99 < 200ms; cursor-based пагинация, не offset
+Ограничения: не раскрывать PII других пользователей в элементах ленты
+```
+
+---
+
+## Example 3 — Quick / Minimal
+
+**EN:**
+```
+/create-endpoint "Health Check"
+
+Method: GET /health
+Auth: none
+Response: 200 { status: "ok", version: string, uptime_seconds: int }
+Must respond in < 50ms; must not trigger DB queries.
+```
+
+**RU:**
+```
+/create-endpoint "Health Check"
+
+Метод: GET /health
+Auth: нет
+Ответ: 200 { status: "ok", version: string, uptime_seconds: int }
+Ответ < 50ms; запросы к БД не допускаются.
+```

package/areas/software/backend/prompts/debug-issue.md

@@ -0,0 +1,87 @@
+---
+workflow: debug-issue
+---
+
+# Prompt: `/debug-issue`
+
+Use when: investigating and resolving a backend defect, incident, or unexpected behavior.
+
+---
+
+## Example 1 — Production Incident
+
+**EN:**
+```
+/debug-issue "Orders API 500 errors spike — P1"
+
+Severity: P1
+Symptoms: 500 error rate on POST /orders jumped from 0.1% to 8% at 14:32 UTC
+Affected service: order-service (v2.4.1, deployed 14:15 UTC)
+Logs: attached — shows NullPointerException in OrderService.createOrder() line 142
+Metrics: error spike matches deployment time; CPU and memory normal
+Last change: added optional discount_code field to order creation
+Expected: reproduce and fix; write regression test; document root cause
+```
+
+**RU:**
+```
+/debug-issue "Спайк 500 ошибок в Orders API — P1"
+
+Severity: P1
+Симптомы: rate 500 ошибок на POST /orders вырос с 0.1% до 8% в 14:32 UTC
+Сервис: order-service (v2.4.1, задеплоен в 14:15 UTC)
+Логи: приложены — NullPointerException в OrderService.createOrder() строка 142
+Метрики: спайк совпадает со временем деплоя; CPU и memory в норме
+Последнее изменение: добавлено опциональное поле discount_code
+Ожидание: воспроизвести и исправить; написать regression test; задокументировать причину
+```
+
+---
+
+## Example 2 — Intermittent Bug
+
+**EN:**
+```
+/debug-issue "Duplicate order creation on payment webhook retry"
+
+Severity: P2
+Symptoms: ~0.3% of orders created twice when payment provider retries webhook
+Frequency: intermittent, only on webhook retry (payment provider retries 3x on timeout)
+Suspected cause: webhook handler is not idempotent — processes same payment_id twice
+Expected: implement idempotency check on payment_id; add regression test with concurrent request simulation
+```
+
+**RU:**
+```
+/debug-issue "Дублирование заказов при повторном вебхуке оплаты"
+
+Severity: P2
+Симптомы: ~0.3% заказов создаётся дважды при retry от платёжного провайдера
+Частота: intermittent, только при retry (провайдер делает 3 попытки при таймауте)
+Предполагаемая причина: обработчик вебхука не idempotent — обрабатывает один payment_id дважды
+Ожидание: добавить проверку идемпотентности по payment_id; тест с симуляцией конкурентных запросов
+```
+
+---
+
+## Example 3 — Quick / Minimal
+
+**EN:**
+```
+/debug-issue "GET /products returns 403 for service account token"
+
+Service account role: product-reader
+Expected: 200 with product list
+Actual: 403 Forbidden
+Started: after auth service upgrade to v3.1.0 yesterday
+```
+
+**RU:**
+```
+/debug-issue "GET /products возвращает 403 для service account токена"
+
+Роль service account: product-reader
+Ожидалось: 200 со списком продуктов
+Факт: 403 Forbidden
+Началось: после обновления auth service до v3.1.0 вчера
+```

package/areas/software/backend/prompts/develop-epic.md

@@ -0,0 +1,83 @@
+---
+workflow: develop-epic
+---
+
+# Prompt: `/develop-epic`
+
+Use when: delivering a large multi-sprint epic that must be broken into independently deployable increments.
+
+---
+
+## Example 1 — New Domain Feature
+
+**EN:**
+```
+/develop-epic "Multi-currency Support"
+
+Epic goal: allow users to transact in USD, EUR, GBP, and JPY with real-time exchange rates
+Increments (suggested):
+  1. Currency model + exchange rate service integration (no UI)
+  2. Price display in user's preferred currency
+  3. Checkout and payment in selected currency
+  4. Historical transaction display with original and converted amounts
+Acceptance criteria (epic-level):
+  - User can set preferred currency in profile
+  - All price displays respect preferred currency
+  - Payments processed in selected currency via Stripe multi-currency
+  - Exchange rate updated every 15 minutes from provider
+Non-goals: crypto currencies; manual rate override by admins (future epic)
+Architecture risk: exchange rate service failure must not block checkout
+```
+
+**RU:**
+```
+/develop-epic "Поддержка нескольких валют"
+
+Цель эпика: пользователи могут работать в USD, EUR, GBP, JPY с курсами в реальном времени
+Инкременты (предложение):
+  1. Модель валюты + интеграция сервиса курсов (без UI)
+  2. Отображение цен в валюте пользователя
+  3. Оформление и оплата в выбранной валюте
+  4. История транзакций с оригинальной и конвертированной суммой
+Критерии приёмки (уровень эпика):
+  - Пользователь выбирает предпочтительную валюту в профиле
+  - Все цены учитывают валюту пользователя
+  - Платежи обрабатываются в выбранной валюте через Stripe multi-currency
+  - Курс обновляется каждые 15 минут
+Non-goals: криптовалюты; ручное управление курсами (следующий эпик)
+Архитектурный риск: сбой сервиса курсов не должен блокировать оформление заказа
+```
+
+---
+
+## Example 2 — Platform Improvement
+
+**EN:**
+```
+/develop-epic "Event-Driven Architecture Migration for Order Processing"
+
+Epic goal: migrate synchronous order processing chain to event-driven with Kafka
+Current: OrderService → PaymentService → NotificationService (synchronous, 3s p99)
+Target: OrderService emits events; Payment and Notification subscribe independently
+Increments:
+  1. Kafka infrastructure + event schema definitions
+  2. Order service emits events (dual-write: sync + async during migration)
+  3. Payment service migrated to consume events
+  4. Notification service migrated; sync chain removed
+Success metric: order creation p99 < 500ms; services independently deployable
+```
+
+**RU:**
+```
+/develop-epic "Миграция обработки заказов на Event-Driven Architecture"
+
+Цель: перевести синхронную цепочку обработки заказов на Kafka
+Текущее: OrderService → PaymentService → NotificationService (синхронно, p99 3s)
+Цель: OrderService публикует события; Payment и Notification независимо подписываются
+Инкременты:
+  1. Kafka инфраструктура + схемы событий
+  2. OrderService публикует события (dual-write во время миграции)
+  3. PaymentService переведён на события
+  4. NotificationService переведён; синхронная цепочка удалена
+Метрика успеха: создание заказа p99 < 500ms; сервисы деплоятся независимо
+```

package/areas/software/backend/prompts/develop-feature.md

@@ -0,0 +1,91 @@
+---
+workflow: develop-feature
+---
+
+# Prompt: `/develop-feature`
+
+Use when: starting end-to-end backend feature delivery from a business request to an accepted, tested increment.
+
+---
+
+## Example 1 — New Business Feature
+
+**EN:**
+```
+/develop-feature "User Subscription Cancellation"
+
+Feature: allow users to cancel their active subscription immediately or at end of billing period.
+Acceptance criteria:
+- User can cancel via DELETE /subscriptions/{id}
+- Cancellation reason is recorded (enum: too_expensive, not_useful, switching_product, other)
+- Immediate cancellation: subscription status set to CANCELLED, refund_eligible flag computed
+- End-of-period: status set to CANCEL_PENDING, access retained until period end
+- Cancellation event emitted to event bus for billing and analytics consumers
+Constraints: backward-compatible with existing billing integrations; no downtime; rollback-safe
+```
+
+**RU:**
+```
+/develop-feature "Отмена подписки пользователем"
+
+Фича: пользователь может отменить активную подписку немедленно или по окончании платёжного периода.
+Критерии приёмки:
+- Отмена через DELETE /subscriptions/{id}
+- Причина отмены записывается (enum: too_expensive, not_useful, switching_product, other)
+- Немедленная отмена: статус CANCELLED, вычисляется флаг refund_eligible
+- Отмена в конце периода: статус CANCEL_PENDING, доступ сохраняется до конца периода
+- Событие cancellation публикуется в event bus для billing и analytics
+Ограничения: обратная совместимость с текущим billing; без даунтайма; безопасный rollback
+```
+
+---
+
+## Example 2 — Technical Feature / Platform Improvement
+
+**EN:**
+```
+/develop-feature "Rate Limiting on Public API"
+
+Feature: add per-client rate limiting to all public API endpoints.
+Acceptance criteria:
+- Limit: 100 requests/minute per API key (configurable)
+- Response on breach: 429 Too Many Requests with Retry-After header
+- Limits tracked in Redis with sliding window algorithm
+- Admin endpoint to view current usage per client: GET /admin/rate-limits/{api_key}
+- Rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
+Constraints: p99 latency increase < 5ms; Redis connection failure must degrade gracefully (fail open with logging)
+```
+
+**RU:**
+```
+/develop-feature "Rate Limiting на публичном API"
+
+Фича: per-client rate limiting для всех публичных эндпоинтов.
+Критерии приёмки:
+- Лимит: 100 запросов/минуту на API-ключ (конфигурируемо)
+- При превышении: 429 Too Many Requests с заголовком Retry-After
+- Лимиты хранятся в Redis, алгоритм sliding window
+- Эндпоинт для просмотра использования: GET /admin/rate-limits/{api_key}
+- Заголовки в каждом ответе: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
+Ограничения: рост p99 latency < 5ms; сбой Redis — fail open с логированием
+```
+
+---
+
+## Example 3 — Quick / Minimal
+
+**EN:**
+```
+/develop-feature "Add soft delete to orders"
+
+Feature: orders should not be hard-deleted; add deleted_at timestamp column and filter deleted orders from all default queries.
+Constraints: existing queries must not return deleted orders without explicit flag.
+```
+
+**RU:**
+```
+/develop-feature "Soft delete для заказов"
+
+Фича: заказы не удаляются физически; добавить колонку deleted_at и фильтровать удалённые из всех стандартных запросов.
+Ограничения: существующие запросы не должны возвращать удалённые заказы без явного флага.
+```

package/areas/software/backend/prompts/refactor-module.md

@@ -0,0 +1,79 @@
+---
+workflow: refactor-module
+---
+
+# Prompt: `/refactor-module`
+
+Use when: improving the structure, readability, or maintainability of existing backend code without changing behavior.
+
+---
+
+## Example 1 — Extract Service Layer
+
+**EN:**
+```
+/refactor-module "Extract business logic from OrderController into OrderService"
+
+Current state: OrderController has 400+ lines mixing HTTP handling, business rules, and DB queries
+Target: clean controller (HTTP only) + OrderService (business logic) + OrderRepository (data access)
+Baseline behavior: all existing integration tests for /orders/* must still pass
+Constraints: no behavior changes; no new features; one PR per logical extraction step
+Risk areas: transaction handling is currently in controller — must move to service layer correctly
+```
+
+**RU:**
+```
+/refactor-module "Вынести бизнес-логику из OrderController в OrderService"
+
+Текущее состояние: OrderController — 400+ строк, смешаны HTTP, бизнес-правила и запросы к БД
+Цель: чистый контроллер (только HTTP) + OrderService (бизнес-логика) + OrderRepository (доступ к данным)
+Базовое поведение: все существующие integration tests для /orders/* должны пройти после рефакторинга
+Ограничения: без изменений поведения; без новых фич; один PR на каждый логический шаг
+Риск: управление транзакциями сейчас в контроллере — перенести корректно в service layer
+```
+
+---
+
+## Example 2 — Eliminate Duplication
+
+**EN:**
+```
+/refactor-module "Deduplicate pagination logic across 12 repository methods"
+
+Current state: each repository method has its own copy of limit/offset/cursor pagination boilerplate (~30 lines each)
+Target: single PaginationHelper utility used by all repository methods
+Baseline: all repository unit tests pass; pagination behavior identical before/after
+Approach: strangler fig — introduce helper, migrate methods one at a time, delete old code
+```
+
+**RU:**
+```
+/refactor-module "Устранить дублирование логики пагинации в 12 методах репозитория"
+
+Текущее состояние: каждый метод репозитория содержит собственную копию boilerplate пагинации (~30 строк каждая)
+Цель: единый PaginationHelper, используемый всеми методами
+Базовое поведение: все unit tests репозитория проходят; поведение пагинации идентично до и после
+Подход: strangler fig — ввести helper, мигрировать методы по одному, удалить старый код
+```
+
+---
+
+## Example 3 — Quick / Minimal
+
+**EN:**
+```
+/refactor-module "Replace raw SQL strings with ORM queries in UserRepository"
+
+Scope: UserRepository only (5 methods)
+Target: replace string-concatenated SQL with SQLAlchemy ORM; improve readability and eliminate injection surface
+Behavior: identical query results; existing tests must pass
+```
+
+**RU:**
+```
+/refactor-module "Заменить raw SQL строки на ORM запросы в UserRepository"
+
+Скоуп: только UserRepository (5 методов)
+Цель: заменить конкатенацию SQL на SQLAlchemy ORM; улучшить читаемость, убрать injection surface
+Поведение: идентичные результаты; существующие тесты должны пройти
+```

package/areas/software/backend/prompts/test-feature.md

@@ -0,0 +1,89 @@
+---
+workflow: test-feature
+---
+
+# Prompt: `/test-feature`
+
+Use when: expanding test coverage for an existing feature that is undertested or has known coverage gaps.
+
+---
+
+## Example 1 — Critical Business Flow
+
+**EN:**
+```
+/test-feature "Payment processing coverage gaps"
+
+Feature scope: payment-service — charge, refund, dispute flows
+Current coverage: 38% (only happy path unit tests)
+Critical gaps:
+- No tests for partial refund edge cases (amount > original, amount = 0)
+- No tests for payment provider timeout handling
+- No tests for idempotency key collision
+- No integration tests for charge → refund round-trip
+Acceptance: coverage ≥ 70% on payment domain; all failure paths have explicit assertions
+```
+
+**RU:**
+```
+/test-feature "Покрытие критических сценариев обработки платежей"
+
+Скоуп: payment-service — charge, refund, dispute flows
+Текущее покрытие: 38% (только happy path unit tests)
+Критические пробелы:
+- Нет тестов для edge cases частичного возврата (amount > оригинала, amount = 0)
+- Нет тестов для обработки таймаута от платёжного провайдера
+- Нет тестов для коллизии idempotency key
+- Нет integration tests для round-trip charge → refund
+Критерий: покрытие ≥ 70% на payment domain; для всех failure paths — явные assertions
+```
+
+---
+
+## Example 2 — API Contract Testing
+
+**EN:**
+```
+/test-feature "Contract tests for Orders API public endpoints"
+
+Endpoints: POST /orders, GET /orders/{id}, PATCH /orders/{id}/status, DELETE /orders/{id}
+Missing test scenarios:
+- 400 responses: invalid input shapes, missing required fields
+- 401/403: unauthenticated, wrong scope, other user's order
+- 404: non-existent order ID
+- 409: concurrent status update conflict
+Constraints: use existing test client; no new test infrastructure; stable in CI
+```
+
+**RU:**
+```
+/test-feature "Contract tests для публичных эндпоинтов Orders API"
+
+Эндпоинты: POST /orders, GET /orders/{id}, PATCH /orders/{id}/status, DELETE /orders/{id}
+Отсутствующие сценарии:
+- 400 ответы: невалидные данные, отсутствующие обязательные поля
+- 401/403: без аутентификации, неверный scope, чужой заказ
+- 404: несуществующий order ID
+- 409: конфликт при одновременном изменении статуса
+Ограничения: использовать существующий test client; без новой test infrastructure; стабильно в CI
+```
+
+---
+
+## Example 3 — Quick / Minimal
+
+**EN:**
+```
+/test-feature "Add unit tests for DiscountCalculator service"
+
+Current state: 0 tests; 3 methods: applyPercentage, applyFixed, applyCode
+Cover: valid inputs, zero discount, negative discount guard, code not found case.
+```
+
+**RU:**
+```
+/test-feature "Unit tests для DiscountCalculator service"
+
+Текущее состояние: 0 тестов; 3 метода: applyPercentage, applyFixed, applyCode
+Покрыть: валидные входные данные, нулевая скидка, защита от отрицательной скидки, case code not found.
+```

package/areas/software/backend/rules/architecture.md

@@ -0,0 +1,20 @@
+# Rule: Backend Architecture (Microservices & Zero Trust)
+
+**Priority**: P0 — Architectural violations block deployment.
+
+## Core principles
+
+1. **Microservices First**
+   - Each service owns one bounded context.
+   - Shared databases across microservices are forbidden (except read-only analytical replicas).
+   - Services must support independent deployment.
+
+2. **Zero Trust Architecture**
+   - No request is trusted by default, including internal traffic.
+   - Inter-service communication must use mTLS or signed service tokens.
+   - Enforce least privilege for every service identity.
+
+3. **API and communication strategy**
+   - Use synchronous calls (REST/gRPC) only when immediate responses are required.
+   - Prefer asynchronous event-driven communication (Kafka/NATS/RabbitMQ) for service-to-service flows.
+   - Use circuit breakers and retries with exponential backoff for external dependencies.

package/areas/software/backend/rules/data_access.md

@@ -0,0 +1,20 @@
+# Rule: Data Access & State Management
+
+**Priority**: P0 — Data integrity violations are critical.
+
+## Constraints
+
+1. **Polyglot persistence roles**
+   - **PostgreSQL**: primary source of truth for OLTP transactions.
+   - **Redis**: cache, rate-limiting, distributed locks, and transient Pub/Sub only.
+   - **ClickHouse**: analytics/time-series/high-volume OLAP workloads.
+
+2. **Migration protocol**
+   - All schema migrations must be versioned.
+   - Migrations must remain backward compatible.
+   - Breaking changes follow Expand-and-Contract: add new -> dual write/read -> remove old.
+
+3. **Performance and query hygiene**
+   - N+1 queries are forbidden; use joins, eager loading, or DataLoader patterns.
+   - `SELECT *` is disallowed.
+   - Avoid long-running transactions; external I/O must not run inside DB transactions.

package/areas/software/backend/rules/security.md

@@ -0,0 +1,20 @@
+# Rule: Backend Security & OWASP Standards
+
+**Priority**: P0 — Security vulnerabilities are release blockers.
+
+## OWASP-aligned baseline
+
+1. **Access control**
+   - Protect all endpoints with a default-deny posture.
+   - Use RBAC or ABAC and enforce resource-level authorization.
+
+2. **Cryptography and secrets**
+   - Use Argon2id or bcrypt for password hashing.
+   - Store secrets in a dedicated secret manager (Vault/AWS Secrets Manager/etc.).
+
+3. **Injection prevention**
+   - Never build SQL via string concatenation; use parameterized queries only.
+   - Validate input at system boundaries with typed DTO/schema validation.
+
+4. **Authentication hardening**
+   - Implement strong token/session validation, rotation, and auditability.

package/areas/software/backend/rules/testing.md

@@ -0,0 +1,19 @@
+# Rule: Backend Testing Pyramid
+
+**Priority**: P1 — Missing critical-path coverage fails review.
+
+## Testing layers
+
+1. **Unit tests**
+   - Isolated domain/application logic tests.
+   - External dependencies must be mocked.
+
+2. **Integration tests**
+   - Validate real integration with databases/message systems.
+   - Use realistic infrastructure (for example, Testcontainers).
+
+3. **E2E/API tests**
+   - Verify critical user and system flows through service interfaces.
+
+4. **SVT/chaos (when relevant)**
+   - Validate resilience under partial failure and degraded conditions.