@jetrabbits/agentic 0.0.1

package/areas/devops/sre/skills/slo-sli-design/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: slo-sli-design
+type: skill
+description: Define SLIs, SLOs, and error budgets; implement burn rate alerts; integrate with Prometheus.
+related-rules:
+  - slo-policy.md
+  - error-budget-policy.md
+allowed-tools: Read, Write, Edit
+---
+
+# Skill: SLO/SLI Design
+
+> **Expertise:** SLI selection, SLO target setting, error budget calculation, burn rate alerting, Sloth/pyrra integration.
+
+## When to load
+
+When defining SLOs for a new service, setting up error budget tracking, or reviewing existing SLOs after an incident.
+
+## SLI Selection Framework
+
+```
+Step 1: What does the user care about?
+  → "The checkout completes successfully and quickly"
+
+Step 2: What CAN we measure?
+  → HTTP 2xx responses, p99 latency
+
+Step 3: Define the SLI formula
+  → Availability SLI: good_requests / total_requests
+     where good = status < 500 AND latency < 500ms
+
+Step 4: Pick SLO target (start conservative, tighten later)
+  → 99.5% (don't chase 99.99% without data — high budget wasted on caution)
+
+Step 5: Calculate error budget
+  → 100% - 99.5% = 0.5% over 28 days = 0.5% × 28 × 24 × 60 = 201.6 minutes
+```
+
+## Prometheus SLO Implementation (manual)
+
+```yaml
+# Recording rules for SLO tracking
+groups:
+  - name: slo.checkout-service
+    interval: 30s
+    rules:
+      # Good requests (2xx, latency < 500ms)
+      - record: slo:http_requests_good:rate5m
+        expr: |
+          sum(rate(http_requests_total{
+            service="checkout-service",
+            status=~"2..",
+            duration_bucket="0.5"
+          }[5m]))
+
+      # Total requests
+      - record: slo:http_requests_total:rate5m
+        expr: |
+          sum(rate(http_requests_total{service="checkout-service"}[5m]))
+
+      # SLI = good / total
+      - record: slo:http_availability:ratio_rate5m
+        expr: slo:http_requests_good:rate5m / slo:http_requests_total:rate5m
+
+      # 28-day rolling availability
+      - record: slo:http_availability:ratio_rate28d
+        expr: |
+          sum_over_time(slo:http_availability:ratio_rate5m[28d]) / (28 * 24 * 12)
+```
+
+## Burn Rate Alerts (multiwindow)
+
+```yaml
+# Multi-window, multi-burn-rate alerting (Google SRE Workbook pattern)
+groups:
+  - name: slo.checkout-service.burn-rate
+    rules:
+      # Fast burn: 14.4× rate (burns 1h of budget in 5 min)
+      - alert: SLOFastBurn
+        expr: |
+          (
+            slo:http_availability:ratio_rate1h{service="checkout-service"} < (1 - 14.4 * 0.005)
+          ) and (
+            slo:http_availability:ratio_rate5m{service="checkout-service"} < (1 - 14.4 * 0.005)
+          )
+        labels:
+          severity: critical
+          slo: checkout-service-availability
+        annotations:
+          summary: "Fast error budget burn — checkout-service (> 14.4× rate)"
+          runbook_url: "https://runbooks.internal/slo-fast-burn"
+
+      # Slow burn: 3× rate (burns 10% of budget in 6h)
+      - alert: SLOSlowBurn
+        expr: |
+          (
+            slo:http_availability:ratio_rate6h{service="checkout-service"} < (1 - 3 * 0.005)
+          ) and (
+            slo:http_availability:ratio_rate30m{service="checkout-service"} < (1 - 3 * 0.005)
+          )
+        labels:
+          severity: warning
+          slo: checkout-service-availability
+        annotations:
+          summary: "Slow error budget burn — checkout-service (> 3× rate)"
+```
+
+## Sloth (SLO as Code)
+
+```yaml
+# slo/checkout-service.yaml — Sloth generates all recording rules + alerts
+version: "prometheus/v1"
+service: checkout-service
+labels:
+  team: backend
+slos:
+  - name: requests-availability
+    objective: 99.5
+    description: "99.5% of checkout requests succeed with latency < 500ms"
+    sli:
+      events:
+        error_query: |
+          sum(rate(http_requests_total{service="checkout-service", status=~"5.."}[{{.window}}]))
+        total_query: |
+          sum(rate(http_requests_total{service="checkout-service"}[{{.window}}]))
+    alerting:
+      name: CheckoutServiceSLO
+      page_alert:
+        labels: { severity: critical }
+      ticket_alert:
+        labels: { severity: warning }
+```
+
+```bash
+# Generate Prometheus rules from Sloth definition
+sloth generate -i slo/checkout-service.yaml -o prometheus-rules/slo-checkout.yaml
+```
+
+## Error Budget Dashboard (Grafana)
+
+Key panels:
+1. **SLI over 28 days** — current ratio vs SLO target line
+2. **Error budget remaining** — percentage + time remaining (burn at current rate)
+3. **Burn rate** — 1h, 6h, 1d, 7d windows
+4. **Events causing budget consumption** — top error causes by count

package/areas/devops/sre/workflows/incident-response.md

@@ -0,0 +1,66 @@
+---
+name: incident-response
+type: workflow
+trigger: /incident-response
+description: Structured P0/P1 incident response — acknowledge, scope, mitigate, communicate, resolve, document.
+inputs:
+  - incident_summary
+  - severity (P0|P1)
+  - affected_service
+outputs:
+  - incident_resolved
+  - preliminary_postmortem
+roles:
+  - devops-engineer (IC)
+  - developer (technical lead)
+  - pm (comms)
+execution:
+  initiator: developer
+related-rules:
+  - on-call-standards.md
+  - error-budget-policy.md
+uses-skills:
+  - incident-command
+  - postmortem-analysis
+quality-gates:
+  - status page updated within 10 min of P0 declaration
+  - mitigation applied before root cause fully known (if available)
+  - timeline captured in real-time (not reconstructed after)
+---
+
+## Steps
+
+### T+0–5: Acknowledge & Scope — `@devops-engineer`
+- Post to #incidents: "I'm on this. War room: [link]"
+- Scope: `kubectl get pods -A | grep -v Running`; check Grafana golden signals
+- Declare severity; page secondary if P0
+
+### T+5–15: Mitigate — `@developer` + `@devops-engineer`
+- **First: try rollback** — `helm rollback <release> -n <ns>`
+- If rollback not applicable: feature flag off → scale up → restart
+- Start scribe doc: copy timeline template, log every action with timestamp
+
+### T+10: Communicate — `@pm`
+- Status page update: "Investigating [symptom] affecting [service]"
+- Stakeholder Slack message in #incidents + product channel
+
+### T+15–30: Stabilize — `@devops-engineer`
+- Watch error rate for 10 min post-mitigation
+- Confirm P95 and P99 latency returning to baseline
+- If not stabilized: re-escalate; try next mitigation step
+
+### T+30: Resolve or Escalate
+- If resolved: status page "Monitoring"; all-clear in #incidents
+- If not: loop mitigation; escalate to on-call lead
+
+### T+60: Preliminary Postmortem
+- Create postmortem doc with timeline (while fresh)
+- Mark as Draft; schedule 5-whys session within 48h
+
+### T+24h: Full Postmortem
+- Complete 5-whys RCA
+- Define action items with owners and due dates
+- Publish to team wiki; announce in #postmortems
+
+## Exit
+Service healthy + stakeholders informed + postmortem published = incident closed.

package/areas/devops/sre/workflows/postmortem.md

@@ -0,0 +1,90 @@
+---
+name: postmortem
+type: workflow
+trigger: /postmortem
+description: Facilitate and write a blameless postmortem after a P0/P1 incident — 5-whys RCA, action items, and publication.
+inputs:
+  - incident_id
+  - severity
+  - timeline_raw (scribe notes)
+outputs:
+  - published_postmortem
+  - action_items_in_tracker
+roles:
+  - devops-engineer (facilitator)
+  - team-lead
+  - developer (technical lead for RCA)
+execution:
+  initiator: developer
+related-rules:
+  - on-call-standards.md
+  - error-budget-policy.md
+uses-skills:
+  - postmortem-analysis
+  - incident-command
+quality-gates:
+  - postmortem published within 48h of incident resolution
+  - every action item has an owner and a due date
+  - root cause reaches systemic level (not "human error")
+---
+
+## Steps
+
+### 1. Collect Data (within 2h of resolution) — `@devops-engineer`
+- Export timeline from scribe doc / Slack thread
+- Pull metrics from Prometheus: error rate, latency, pod events during incident window
+- Download relevant log excerpts from Loki
+- Note: who was involved, what actions were taken, what worked
+
+### 2. Draft Postmortem — `@devops-engineer`
+- Use `postmortem-analysis` skill template
+- Write timeline with precise UTC timestamps
+- Write preliminary 5-whys (iteration 1 — will be refined in meeting)
+- List initial action item candidates
+- Mark doc: **DRAFT — pending review meeting**
+
+### 3. 5-Whys Facilitation Meeting (within 48h) — `@devops-engineer` (facilitator)
+
+**Meeting format (45–60 min):**
+```
+5 min:  Ground rules — blameless; focus on systems, not people
+10 min: Walk through timeline (verify accuracy, fill gaps)
+20 min: 5-Whys analysis (stop when you reach a missing process/tooling/convention)
+15 min: Action items — specific, owned, dated; challenge vague items
+5 min:  What went well? (at least 3 items)
+```
+
+**Facilitation rules:**
+- If the answer is "human error" → ask why the system allowed the error
+- If the answer is "lack of monitoring" → that's an actionable system gap
+- If a "why" repeats a previous incident → high priority to fix
+- Stop at 5 whys or when you reach an organizational/process level
+
+### 4. Finalize Document — `@devops-engineer`
+- Incorporate all meeting feedback
+- Ensure every action item:
+  - Is specific (not "improve testing" but "add k6 load test for /checkout")
+  - Has a named owner
+  - Has a due date within 2–4 weeks
+- Remove any blame language ("Alice forgot to" → "the process did not require")
+- Calculate SLO impact: minutes of error budget consumed
+
+### 5. Publish & Track — `@devops-engineer` + `@team-lead`
+```bash
+# Create Jira/Linear tickets for each action item
+for item in action_items; do
+  create_ticket --title "$item.title" --assignee "$item.owner" --due "$item.due_date" \
+    --label "postmortem-followup" --link "postmortem_url"
+done
+```
+- Publish to team wiki (Confluence/Notion)
+- Announce in #postmortems Slack: "Postmortem for INC-XXXX published: [link]"
+- Add to monthly reliability review agenda
+
+### 6. Follow-Up (2 weeks later) — `@team-lead`
+- Check ticket status: are action items progressing?
+- Any blocked items? Need resource allocation?
+- If root cause not addressed: escalate to engineering lead
+
+## Exit
+Postmortem published + all action items in tracker + team notified = postmortem complete.

package/areas/devops/sre/workflows/slo-review.md

@@ -0,0 +1,95 @@
+---
+name: slo-review
+type: workflow
+trigger: /slo-review
+description: Conduct quarterly SLO review — evaluate current SLOs against reliability data, adjust targets, and plan error budget policy changes.
+inputs:
+  - quarter (e.g. Q4-2024)
+  - services_to_review
+outputs:
+  - slo_review_report
+  - updated_slo_definitions
+  - error_budget_policy_changes
+roles:
+  - devops-engineer (SRE)
+  - team-lead
+  - product-owner
+execution:
+  initiator: developer
+related-rules:
+  - slo-policy.md
+  - error-budget-policy.md
+uses-skills:
+  - slo-sli-design
+  - slo-implementation
+  - capacity-planning
+quality-gates:
+  - SLO targets grounded in actual reliability data (not aspirational)
+  - every changed SLO has product-owner sign-off
+  - error budget policy reviewed for services that hit freeze state
+---
+
+## Steps
+
+### 1. Pull Reliability Data — `@devops-engineer`
+```promql
+-- 90-day availability per service
+avg_over_time(
+  slo:http_availability:ratio_rate5m{service="$svc"}[90d]
+) * 100
+
+-- Total error budget consumed this quarter
+(
+  1 - avg_over_time(
+    slo:http_availability:ratio_rate5m{service="$svc"}[90d]
+  )
+) / (1 - 0.995) * 100   -- as % of total budget
+```
+- For each service: actual availability, error budget consumed, number of incidents
+
+### 2. Classify Services — `@devops-engineer`
+
+| Category | Criteria | Action |
+|:---|:---|:---|
+| **Overperforming** | Actual > SLO + 0.5% | Tighten SLO (stop "saving" budget by over-engineering) |
+| **Meeting SLO** | Within ±0.2% | No change required |
+| **Underperforming** | Budget < 25% remaining | Investigate root cause; adjust target or invest in reliability |
+| **New service** | < 1 month of data | Set conservative target; review in 30 days |
+
+### 3. SLO Adjustment Workshop — `@devops-engineer` + `@team-lead` + `@product-owner`
+
+For each flagged service:
+- **Tightening:** "We maintained 99.92% — can we commit to 99.9% and remove over-engineering?"
+- **Loosening:** "We hit 99.3% but committed to 99.5% — is the gap a reliability problem or wrong target?"
+- **New SLIs:** any new customer-visible behavior not yet covered by an SLI?
+
+### 4. Update SLO Definitions — `@devops-engineer`
+```yaml
+# Update slo/<service>.yaml (Sloth)
+# Re-generate Prometheus rules
+sloth generate -i slo/${SERVICE}.yaml -o rules/slo-${SERVICE}-generated.yaml
+kubectl apply -f rules/slo-${SERVICE}-generated.yaml -n monitoring
+```
+
+### 5. Error Budget Policy Review — `@team-lead` + `@product-owner`
+- Did any service exhaust budget? → Was feature freeze enforced? Did it work?
+- Any services that needed freeze but policy wasn't triggered? → Fix thresholds
+- Review next quarter's reliability investment vs feature work ratio
+
+### 6. Publish SLO Review Report — `@devops-engineer`
+```markdown
+# SLO Review Report — Q4 2024
+
+| Service   | SLO Target | Actual Q4 | Budget Used | Action |
+|:----------|:-----------|:----------|:------------|:-------|
+| checkout  | 99.5%      | 99.71%    | 42%         | None   |
+| payments  | 99.9%      | 99.82%    | 80%         | Invest |
+| notify    | 99.0%      | 99.43%    | 0%          | Tighten to 99.3% |
+
+## Decisions
+- payments: allocate 20% of Q1 sprint capacity to reliability work
+- notify: tighten SLO to 99.3%; generates meaningful error budget
+```
+
+## Exit
+Report published + SLO changes applied + action items in tracker = review complete.

package/areas/software/backend/AGENTS.md

@@ -0,0 +1,59 @@
+# Backend — guidance index
+
+## What this area covers
+
+Server-side service development: REST / GraphQL API design, domain modeling, database access patterns, async processing, observability, and security. Load after `software/general/` baseline.
+
+## Guidance chain
+
+1. Project `.agent/` baseline (`AGENTS.md` + `.agent/*`)
+2. `software/general/rules/*` — always active
+3. `backend/rules/*` — load all for this spec
+4. `backend/skills/*/SKILL.md` — load only the skill matching the current task
+5. `backend/workflows/*` — load the workflow matching the triggered command
+
+## Inherited from general
+
+- SDLC methodology and role responsibilities
+- Git / CI / lint / format and code style baselines
+- General development and code review workflows
+
+## Backend-specific overrides
+
+- All endpoints must include authZ check, input validation, and structured error response.
+- Database changes require a migration file — no schema drift via ORM sync in production.
+- Every new module requires observability: at minimum, structured logs and a latency metric.
+
+## Spec map
+
+```text
+backend/
+├── rules/
+│   ├── architecture.md       ← layering, module boundaries, dependency direction
+│   ├── data_access.md        ← ORM usage, query patterns, N+1 prevention
+│   ├── security.md           ← authN/authZ, input validation, secret handling
+│   └── testing.md            ← test pyramid targets, mock boundaries, contract tests
+├── skills/
+│   ├── api-design/SKILL.md           ← REST / GraphQL conventions, versioning, contracts
+│   ├── async-processing/SKILL.md     ← queues, workers, retry/DLQ patterns
+│   ├── database-modeling/SKILL.md    ← schema design, indexes, migration safety
+│   ├── observability/SKILL.md        ← structured logging, metrics, distributed tracing
+│   └── troubleshooting/SKILL.md      ← systematic debugging, profiling, root-cause analysis
+├── workflows/
+│   ├── add-migration.md       ← /add-migration
+│   ├── create-endpoint.md     ← /create-endpoint
+│   ├── debug-issue.md         ← /debug-issue
+│   ├── develop-epic.md        ← /develop-epic
+│   ├── develop-feature.md     ← /develop-feature
+│   ├── refactor-module.md     ← /refactor-module
+│   └── test-feature.md        ← /test-feature
+└── prompts/
+    └── *.md
+```
+
+## Discovery patterns
+
+- `rules/*.md`
+- `skills/*/SKILL.md`
+- `workflows/*.md`
+- `prompts/*.md`

package/areas/software/backend/PROMPTS.md

@@ -0,0 +1,50 @@
+# PROMPTS: backend
+
+Use these prompts with `backend/AGENTS.md` from the same directory.
+
+## 1) Initialize backend agent behavior
+
+```text
+Read `backend/AGENTS.md` and apply all backend rules as hard constraints.
+Before implementation, return:
+1) selected workflow,
+2) loaded skills,
+3) implementation plan,
+4) risk list.
+```
+
+## 2) Develop backend feature
+
+```text
+Using `backend/AGENTS.md`, implement: <feature description>.
+Mandatory pre-coding output:
+- architecture notes,
+- data model/query impact,
+- security checks,
+- test plan.
+After coding: run checks and report exact commands and results.
+```
+
+## 3) Create endpoint
+
+```text
+Using `backend/AGENTS.md`, create endpoint: <method + path + contract>.
+Include request/response DTOs, validation, authZ, error mapping, tests,
+and observability (metrics/logs/tracing) updates.
+```
+
+## 4) Incident / debug mode
+
+```text
+Using `backend/AGENTS.md`, triage incident: <incident summary>.
+Return root-cause hypotheses, validation steps, minimal fix,
+regression tests, and rollback plan.
+```
+
+## 5) Safe migration
+
+```text
+Using `backend/AGENTS.md`, implement migration: <schema change>.
+Produce backward-compatible rollout plan, migration SQL/code,
+verification queries, and rollback strategy.
+```

package/areas/software/backend/README.md

@@ -0,0 +1,48 @@
+# .agent-os Backend Module
+
+This directory contains the deep specialization rules, skills, workflows, and prompts for the **Backend Engineering** domain.
+
+This specialization is engineered for modern, robust backend systems that rely on:
+- **Architecture**: Microservices, Clean/Hexagonal Architecture.
+- **Security**: Zero Trust Architecture, OWASP standards, RBAC/ABAC.
+- **Tech Agnosticism**: Deep principles applicable across Python/FastAPI, Go, Node.js/NestJS, Java, Rust.
+- **Databases**: PostgreSQL (OLTP), Redis (Caching/Locks), ClickHouse (OLAP/Analytics).
+- **Asynchronous Processing**: NATS, Kafka, RabbitMQ, Celery, BullMQ.
+- **Telemetry**: Prometheus, OpenTelemetry, Structured JSON Logging.
+- **Quality**: Unit, Integration (Testcontainers), E2E, SVT tests.
+
+## Ecosystem Content
+
+### 1. Rules (`/rules`)
+The immutable constraints of the backend world. Agent will strictly abide by these.
+- `architecture.md` - Service boundaries, ZTA, Clean Arch.
+- `data_access.md` - Polyglot Persistence, No N+1, Safe Migrations.
+- `security.md` - OWASP Top 10 mitigations.
+- `testing.md` - Testing Pyramid strategy.
+
+### 2. Skills (`/skills`)
+Active knowledge to execute specialized tasks.
+- `api-design.md` - RESTful semantics and gRPC contracts.
+- `database-modeling.md` - Indices, scaling, ClickHouse patterns.
+- `async-processing.md` - Event-Driven Architecture, Outbox, DLQ.
+- `observability.md` - RED/USE methodology and distributed tracing.
+- `troubleshooting.md` - RCA, categorizing HTTP errors, fixing N+1 and OOMs.
+
+### 3. Workflows (`/workflows`)
+Step-by-step algorithms for repetitive backend chores.
+- `develop-epic.md` - High-level system design and task decomposition for large features.
+- `develop-feature.md` - Developing a single vertical slice from DB to API.
+- `test-feature.md` - Applying the testing pyramid to existing code.
+- `debug-issue.md` - Root Cause Analysis and bug fixing strategy.
+- `create-endpoint.md` - From DTO validation to presentation.
+- `add-migration.md` - Safe backward-compatible schema changes.
+- `refactor-module.md` - Strangler fig extraction from legacy.
+
+### 4. Prompts (`/prompts`)
+System instructions configuring the Agent's persona and context.
+- `system-prompt.md` - Base instruction for the Senior Backend Agent.
+- `code-review.md` - Uncompromising code review checklist.
+- `develop-epic.md` - Prompt to kick off an epic structure.
+- `develop-feature.md` - Prompt to build a standalone feature.
+- `test-feature.md` - Prompt to generate comprehensive tests.
+- `debug-issue.md` - Prompt to find the exact root cause of an incident.

package/areas/software/backend/prompts/add-migration.md

@@ -0,0 +1,93 @@
+---
+workflow: add-migration
+---
+
+# Prompt: `/add-migration`
+
+Use when: adding or modifying database schema — columns, tables, indexes, constraints.
+
+---
+
+## Example 1 — Breaking Change (Expand/Contract)
+
+**EN:**
+```
+/add-migration "Rename users.full_name to users.display_name"
+
+Change type: breaking — column rename
+Affected services: user-service (writes), profile-service (reads), search-service (reads)
+Current column: users.full_name VARCHAR(255) NOT NULL
+Target column: users.display_name VARCHAR(255) NOT NULL
+Strategy: expand/contract
+  Phase 1: add display_name column, backfill from full_name, write to both
+  Phase 2: migrate all reader services to display_name
+  Phase 3: mark full_name deprecated
+  Phase 4 (30 days): drop full_name
+Rollback: Phase 1 is reversible; document downgrade migration
+```
+
+**RU:**
+```
+/add-migration "Переименование users.full_name в users.display_name"
+
+Тип изменения: breaking — переименование колонки
+Затронутые сервисы: user-service (запись), profile-service (чтение), search-service (чтение)
+Текущая колонка: users.full_name VARCHAR(255) NOT NULL
+Целевая колонка: users.display_name VARCHAR(255) NOT NULL
+Стратегия: expand/contract
+  Фаза 1: добавить display_name, бэкфилл из full_name, писать в обе
+  Фаза 2: перевести все читающие сервисы на display_name
+  Фаза 3: пометить full_name как deprecated
+  Фаза 4 (через 30 дней): удалить full_name
+Rollback: Фаза 1 обратима; написать downgrade миграцию
+```
+
+---
+
+## Example 2 — Non-Breaking Change
+
+**EN:**
+```
+/add-migration "Add index on orders.created_at for date-range queries"
+
+Change type: non-breaking — add index
+Table: orders
+New index: idx_orders_created_at ON orders(created_at DESC)
+Reason: query GET /orders?from=&to= does full table scan; table has 50M rows
+Validate: EXPLAIN ANALYZE on the query before and after
+Deployment: can be applied with CONCURRENTLY in Postgres — no table lock
+```
+
+**RU:**
+```
+/add-migration "Добавить индекс на orders.created_at для range-запросов"
+
+Тип изменения: non-breaking — добавление индекса
+Таблица: orders
+Новый индекс: idx_orders_created_at ON orders(created_at DESC)
+Причина: запрос GET /orders?from=&to= делает full table scan; в таблице 50M строк
+Валидация: EXPLAIN ANALYZE на запрос до и после
+Деплой: применить с CONCURRENTLY в Postgres — без блокировки таблицы
+```
+
+---
+
+## Example 3 — Quick / Minimal
+
+**EN:**
+```
+/add-migration "Add archived_at nullable column to projects"
+
+Table: projects
+Change: add column archived_at TIMESTAMP WITH TIME ZONE NULL DEFAULT NULL
+Non-breaking; no existing queries affected; no data backfill needed.
+```
+
+**RU:**
+```
+/add-migration "Добавить nullable колонку archived_at в projects"
+
+Таблица: projects
+Изменение: добавить archived_at TIMESTAMP WITH TIME ZONE NULL DEFAULT NULL
+Non-breaking; существующие запросы не затронуты; бэкфилл не нужен.
+```