@jetrabbits/agentic 0.0.1

package/areas/devops/ci-cd/AGENTS.md

@@ -0,0 +1,48 @@
+# CI/CD — guidance index
+
+## What this area covers
+
+Continuous integration and delivery pipelines: GitHub Actions, GitLab CI, quality gates, artifact management, build optimization, supply-chain security, and pipeline security hardening.
+
+## Guidance chain
+
+1. Project `.agent/` baseline
+2. `ci-cd/rules/*` — load all
+3. `ci-cd/skills/*/SKILL.md` — load only the skill matching the current task
+4. `ci-cd/workflows/*` — load the workflow matching the triggered command
+
+## Cross-cutting constraints
+
+- **No secrets in pipeline YAML** — all credentials via vault / environment secrets, never inline.
+- **Quality gates are non-negotiable** — pipelines must not merge on test failure, ever.
+- **Supply-chain integrity** — pin all external actions to a full commit SHA, not a tag.
+- **Artifact immutability** — built artifacts are never modified after creation; re-build instead.
+
+## Spec map
+
+```text
+ci-cd/
+├── rules/
+│   ├── pipeline-standards.md         ← stage order, naming, timeout policies
+│   ├── quality-gates.md              ← required checks, merge block conditions
+│   └── supply-chain-security.md      ← action pinning, SBOM, provenance attestation
+├── skills/
+│   ├── github-actions-patterns/SKILL.md  ← reusable workflows, matrix, caching strategies
+│   ├── gitlab-ci-patterns/SKILL.md       ← DAG pipelines, include templates, runners
+│   ├── artifact-management/SKILL.md      ← registry push, versioning, retention policy
+│   ├── build-optimization/SKILL.md       ← layer caching, parallelism, incremental builds
+│   └── pipeline-security/SKILL.md        ← OIDC auth, secret scanning, SAST integration
+├── workflows/
+│   ├── onboard-repo.md        ← /onboard-repo
+│   ├── pipeline-debug.md      ← /pipeline-debug
+│   └── release-pipeline.md   ← /release-pipeline
+└── prompts/
+    └── *.md
+```
+
+## Discovery patterns
+
+- `rules/*.md`
+- `skills/*/SKILL.md`
+- `workflows/*.md`
+- `prompts/*.md`

package/areas/devops/ci-cd/PROMPTS.md

@@ -0,0 +1,7 @@
+# PROMPTS: ci-cd
+
+| Prompt | Use when |
+|:---|:---|
+| `/onboard-repo` | Setting up CI/CD pipeline for new repository |
+| `/pipeline-debug` | Diagnosing failing CI/CD pipeline |
+| `/release-pipeline` | Running or designing a production release with gates |

package/areas/devops/ci-cd/prompts/onboard-repo.md

@@ -0,0 +1,97 @@
+---
+workflow: onboard-repo
+---
+
+# Prompt: `/onboard-repo`
+
+Use when: setting up CI/CD pipeline for a new repository from scratch.
+
+---
+
+## Example 1 — Python service on GitHub Actions
+
+**EN:**
+```
+/onboard-repo
+
+Repo: github.com/myorg/payment-service / Language: Python 3.12 / Framework: FastAPI
+CI platform: GitHub Actions
+Tests: pytest + coverage / Lint: ruff + mypy
+Registry: ghcr.io (OIDC auth — no long-lived keys)
+Deploy: Kubernetes (bare-metal, ArgoCD GitOps)
+Environments: staging (auto on main merge) + production (manual approval, team-lead required)
+Image signing: cosign + SBOM via Syft
+Quality gates: coverage >= 80%, no Critical/High CVEs in Trivy scan
+```
+
+**RU:**
+```
+/onboard-repo
+
+Репо: github.com/myorg/payment-service / Язык: Python 3.12 / Фреймворк: FastAPI
+CI платформа: GitHub Actions
+Тесты: pytest + coverage / Линтер: ruff + mypy
+Реестр: ghcr.io (OIDC auth — без долгоживущих ключей)
+Деплой: Kubernetes (bare-metal, ArgoCD GitOps)
+Окружения: staging (авто при merge в main) + production (ручное подтверждение, team-lead)
+Подпись образов: cosign + SBOM через Syft
+Quality gates: coverage >= 80%, нет Critical/High CVE в Trivy scan
+```
+
+---
+
+## Example 2 — Go service on self-hosted GitLab CI
+
+**EN:**
+```
+/onboard-repo
+
+Repo: gitlab.internal/backend/order-service / Language: Go 1.23
+CI platform: GitLab CI (self-hosted, bare-metal runner tagged: [self-hosted, docker])
+Tests: go test ./... / Lint: golangci-lint
+Registry: registry.internal (authenticated, no OIDC — use GitLab CI_JOB_TOKEN)
+Deploy: Helm to K8s staging namespace; production requires manual approval gate
+Special: internal module proxy (GOPROXY=https://proxy.internal); runner has no public internet
+SAST: GitLab built-in SAST template
+```
+
+**RU:**
+```
+/onboard-repo
+
+Репо: gitlab.internal/backend/order-service / Язык: Go 1.23
+CI платформа: GitLab CI (self-hosted, bare-metal runner с тегами: [self-hosted, docker])
+Тесты: go test ./... / Линтер: golangci-lint
+Реестр: registry.internal (аутентификация через CI_JOB_TOKEN, без OIDC)
+Деплой: Helm в K8s staging namespace; production требует ручного подтверждения
+Особенность: внутренний module proxy (GOPROXY=https://proxy.internal); runner без публичного интернета
+SAST: встроенный GitLab SAST шаблон
+```
+
+---
+
+## Example 3 — Quick: add missing security scan stage
+
+**EN:**
+```
+/onboard-repo
+
+Task: add Trivy container scan to existing GitHub Actions pipeline
+Current stages: lint → test → build (already working)
+Missing: image scan between build and deploy
+Threshold: block on Critical/High; warn on Medium
+Upload results to GitHub Security tab (SARIF format)
+Platform: GitHub Actions / Image: ghcr.io/myorg/api:${{ github.sha }}
+```
+
+**RU:**
+```
+/onboard-repo
+
+Задача: добавить Trivy сканирование контейнера в существующий GitHub Actions pipeline
+Текущие стадии: lint → test → build (уже работают)
+Отсутствует: сканирование образа между build и deploy
+Порог: блокировать при Critical/High; предупреждать при Medium
+Загрузить результаты в GitHub Security tab (формат SARIF)
+Платформа: GitHub Actions / Образ: ghcr.io/myorg/api:${{ github.sha }}
+```

package/areas/devops/ci-cd/prompts/pipeline-debug.md

@@ -0,0 +1,103 @@
+---
+workflow: pipeline-debug
+---
+
+# Prompt: `/pipeline-debug`
+
+Use when: a CI/CD pipeline is failing, a build is too slow, or a delivery job needs root-cause diagnosis and recovery.
+
+---
+
+## Example 1 — Auth failure: registry push rejected
+
+**EN:**
+```
+/pipeline-debug
+
+Pipeline: https://github.com/myorg/order-service/actions/runs/12345678
+Stage: build / Step: "Push image to ghcr.io"
+Error: "unauthorized: unauthenticated: User cannot be authenticated"
+Last successful run: 3 days ago (same workflow, no code changes)
+Hypothesis: GITHUB_TOKEN permissions changed, or OIDC trust policy expired
+Check: workflow permissions block, repository Settings → Actions → permissions
+```
+
+**RU:**
+```
+/pipeline-debug
+
+Pipeline: https://github.com/myorg/order-service/actions/runs/12345678
+Стадия: build / Шаг: "Push image to ghcr.io"
+Ошибка: "unauthorized: unauthenticated: User cannot be authenticated"
+Последний успешный запуск: 3 дня назад (тот же workflow, без изменений кода)
+Гипотеза: изменились разрешения GITHUB_TOKEN или истёк OIDC trust policy
+Проверить: блок permissions в workflow, Settings → Actions → permissions репозитория
+```
+
+---
+
+## Example 2 — Flaky test causing random failures
+
+**EN:**
+```
+/pipeline-debug
+
+Pipeline: GitLab CI / Project: backend/payment-service / Branch: main
+Stage: test / Failure rate: ~30% (same commit sometimes passes, sometimes fails)
+Error: "FAILED tests/test_settlement.py::test_daily_settlement - AssertionError: expected 3 records, got 2"
+Suspicion: test depends on datetime.now() — timezone or timing issue in CI runner
+Environment: GitLab shared runner (UTC) vs local dev (Europe/Moscow)
+Goal: identify root cause + fix test + add to flaky-test tracking
+```
+
+**RU:**
+```
+/pipeline-debug
+
+Pipeline: GitLab CI / Проект: backend/payment-service / Ветка: main
+Стадия: test / Частота отказов: ~30% (один и тот же коммит иногда проходит, иногда нет)
+Ошибка: "FAILED tests/test_settlement.py::test_daily_settlement - AssertionError: expected 3 records, got 2"
+Подозрение: тест зависит от datetime.now() — проблема с timezone или таймингом в CI runner
+Окружение: GitLab shared runner (UTC) vs локальная разработка (Europe/Moscow)
+Цель: определить корневую причину + исправить тест + добавить в flaky-test tracking
+```
+
+---
+
+## Example 3 — Reduce Docker build time from 12 min to < 3 min
+
+**EN:**
+```
+/pipeline-debug
+
+Service: order-service / Language: Python 3.12 + FastAPI
+Current build time: 12 min (GitHub Actions); cache hit rate: ~15%
+Problems observed:
+  - pip install runs from scratch every build (no layer caching)
+  - Test dependencies bundled into production image
+  - Base image pulled fresh every build (no registry mirror)
+Goals:
+  - Achieve < 3 min build on cache hit
+  - Separate build deps from runtime image (multi-stage)
+  - Use GitHub Actions cache for pip + Docker layer cache (type=gha)
+  - Produce minimal production image (target < 200MB)
+Show: before/after Dockerfile + updated GitHub Actions workflow
+```
+
+**RU:**
+```
+/pipeline-debug
+
+Сервис: order-service / Язык: Python 3.12 + FastAPI
+Текущее время сборки: 12 мин (GitHub Actions); cache hit rate: ~15%
+Наблюдаемые проблемы:
+  - pip install запускается с нуля при каждой сборке (нет layer caching)
+  - Зависимости для тестов входят в production образ
+  - Base image скачивается заново при каждой сборке (нет registry mirror)
+Цели:
+  - Достичь < 3 мин при попадании в кэш
+  - Разделить build и runtime зависимости (multi-stage)
+  - Использовать GitHub Actions cache для pip + Docker layer cache (type=gha)
+  - Минимальный production образ (цель < 200MB)
+Показать: Dockerfile до/после + обновлённый GitHub Actions workflow
+```

package/areas/devops/ci-cd/prompts/release-pipeline.md

@@ -0,0 +1,115 @@
+---
+workflow: release-pipeline
+---
+
+# Prompt: `/release-pipeline`
+
+Use when: designing or running a production release pipeline with versioning, supply-chain controls, and deployment gates.
+
+---
+
+## Example 1 — Semantic versioning + automated changelog
+
+**EN:**
+```
+/release-pipeline
+
+Repo: github.com/myorg/api-service
+Release strategy: semantic versioning (semver) via git tags
+Changelog: auto-generated from conventional commits (feat/fix/breaking)
+Trigger: manual tag push (v1.2.3) → full release pipeline
+Pipeline steps:
+  1. Validate: all CI gates pass on tagged commit
+  2. Build: image with tag=v1.2.3 AND digest; push to ghcr.io
+  3. Sign: cosign sign + SBOM attach
+  4. Release: GitHub Release with changelog + image digest in description
+  5. Deploy staging: Helm upgrade --set image.tag=v1.2.3 --atomic
+  6. Smoke test staging: automated; gate before production
+  7. Deploy production: manual approval; canary 10% → 100%
+```
+
+**RU:**
+```
+/release-pipeline
+
+Репо: github.com/myorg/api-service
+Стратегия релизов: semantic versioning (semver) через git теги
+Changelog: авто-генерация из conventional commits (feat/fix/breaking)
+Триггер: ручной push тега (v1.2.3) → полный pipeline релиза
+Шаги pipeline:
+  1. Validate: все CI gates проходят на тегированном коммите
+  2. Build: образ с tag=v1.2.3 И digest; push в ghcr.io
+  3. Sign: cosign sign + SBOM attach
+  4. Release: GitHub Release с changelog + image digest в описании
+  5. Deploy staging: Helm upgrade --set image.tag=v1.2.3 --atomic
+  6. Smoke test staging: автоматический; gate перед production
+  7. Deploy production: ручное подтверждение; canary 10% → 100%
+```
+
+---
+
+## Example 2 — Emergency hotfix release
+
+**EN:**
+```
+/release-pipeline
+
+Context: critical bug in v2.1.0 (CVE exploited in production); hotfix needed in < 2 hours
+Branch: hotfix/cve-2024-payment from tag v2.1.0 (NOT from main — main has unreleased features)
+Version: v2.1.1
+Speed optimizations allowed:
+  - Skip: integration tests (replace with targeted regression test for the fix)
+  - Skip: changelog automation (write manually)
+  - Keep: security scan (mandatory), smoke test (mandatory), canary deploy (mandatory)
+Rollback plan: v2.1.0 image already in registry — Helm rollback in < 2 min if needed
+```
+
+**RU:**
+```
+/release-pipeline
+
+Контекст: критический баг в v2.1.0 (CVE эксплуатируется в production); hotfix нужен за < 2 часа
+Ветка: hotfix/cve-2024-payment от тега v2.1.0 (НЕ от main — там незарелиженные фичи)
+Версия: v2.1.1
+Допустимые оптимизации скорости:
+  - Пропустить: интеграционные тесты (заменить целевым регрессионным тестом для исправления)
+  - Пропустить: автоматизацию changelog (написать вручную)
+  - Оставить: security scan (обязательно), smoke test (обязательно), canary deploy (обязательно)
+План отката: образ v2.1.0 уже в реестре — Helm rollback за < 2 мин при необходимости
+```
+
+---
+
+## Example 3 — Add full supply chain to existing pipeline
+
+**EN:**
+```
+/release-pipeline
+
+Service: checkout-service / CI: GitHub Actions
+Current state: images built and pushed, no signing, no SBOM
+Required:
+  1. SBOM: generate CycloneDX SBOM with Syft during build; attach to image with cosign
+  2. Signing: sign image with cosign using GitHub OIDC (keyless) after push
+  3. Provenance: enable SLSA level 2 via docker/build-push-action (provenance: true)
+  4. Verification: add cosign verify step in CD pipeline before every deploy
+  5. Policy: Kyverno ClusterPolicy — block unsigned images in production namespace
+  6. Dependency pinning: base image must reference @sha256 digest, not tag
+Show full updated GitHub Actions workflow + Kyverno policy
+```
+
+**RU:**
+```
+/release-pipeline
+
+Сервис: checkout-service / CI: GitHub Actions
+Текущее состояние: образы собираются и пушатся, без подписи, без SBOM
+Требуется:
+  1. SBOM: генерация CycloneDX SBOM через Syft при сборке; прикрепление к образу через cosign
+  2. Подпись: подпись образа через cosign с GitHub OIDC (keyless) после push
+  3. Provenance: SLSA level 2 через docker/build-push-action (provenance: true)
+  4. Верификация: добавить шаг cosign verify в CD pipeline перед каждым деплоем
+  5. Политика: Kyverno ClusterPolicy — блокировка неподписанных образов в production namespace
+  6. Pinning зависимостей: base image должен ссылаться на @sha256 digest, не тег
+Показать полный обновлённый workflow GitHub Actions + Kyverno политику
+```

package/areas/devops/ci-cd/rules/pipeline-standards.md

@@ -0,0 +1,33 @@
+# Rule: Pipeline Standards
+
+**Priority**: P0 — Pipelines without quality gates do not deploy to production.
+
+## Mandatory Pipeline Stages (in order)
+
+1. **lint** — static analysis, formatting check; zero tolerance for errors
+2. **test** — unit + integration; coverage gate ≥ 80% on critical paths
+3. **build** — reproducible image/artifact with content-addressable tag (digest)
+4. **scan** — SAST + dependency CVE audit + secrets detection; blocks on Critical/High
+5. **deploy-staging** — deploy to staging; auto-triggered on main branch merge
+6. **smoke-test** — automated health check against staging post-deploy
+7. **deploy-production** — manual approval gate + canary rollout
+
+## Image Tagging
+
+```
+❌ :latest, :main, :branch-name  (mutable — untraceable)
+✅ :<git-sha>                     (immutable, traceable)
+✅ image@sha256:<digest>          (preferred in K8s manifests)
+```
+
+## Secrets in CI
+
+- CI secrets stored in vault (GitHub Actions Secrets, GitLab Variables masked+protected).
+- OIDC-based cloud auth preferred over long-lived access keys.
+- No `echo $SECRET` or `env` dump in logs — mask all sensitive values.
+
+## Pipeline as Code
+
+- All pipeline config lives in the repo alongside the code it builds.
+- No pipeline configuration via UI — Git is the only source of truth.
+- Pipeline changes require peer review (same PR as code changes when possible).

package/areas/devops/ci-cd/rules/quality-gates.md

@@ -0,0 +1,24 @@
+# Rule: Quality Gates
+
+**Priority**: P1 — Gates below minimum thresholds block promotion to production.
+
+## Gate Thresholds
+
+| Gate | Minimum | Block on |
+|:---|:---|:---|
+| Unit test coverage (critical paths) | 80% | < 70% |
+| Integration tests | all pass | any failure |
+| SAST findings | 0 Critical/High unresolved | any Critical/High |
+| Dependency CVE | 0 Critical/High unresolved | any Critical/High |
+| Secrets scan | 0 findings | any finding |
+| Image scan | 0 Critical/High CVEs | any Critical/High |
+| Smoke tests (staging) | 100% pass | any failure |
+
+## Promotion Rules
+
+1. Code merges to `main` only after all CI gates pass.
+2. Staging deployment is automatic on `main` merge.
+3. Production deployment requires:
+   - Staging deployment healthy for ≥ 15 minutes
+   - Manual approval from team-lead or on-call
+   - No active P0/P1 incidents

package/areas/devops/ci-cd/rules/supply-chain-security.md

@@ -0,0 +1,34 @@
+# Rule: Supply Chain Security
+
+**Priority**: P0 — Unsigned or unverified artifacts are blocked from production.
+
+## SBOM (Software Bill of Materials)
+
+1. Every container image build generates an SBOM (Syft / Trivy).
+2. SBOM attached to image in OCI registry (cosign attach sbom).
+3. SBOM stored for minimum 1 year per compliance requirements.
+
+## Image Signing (Sigstore/cosign)
+
+```bash
+# Sign image after build
+cosign sign --key env://COSIGN_PRIVATE_KEY \
+  registry.example.com/my-service@sha256:<digest>
+
+# Verify before deploy (in CD pipeline)
+cosign verify --key env://COSIGN_PUBLIC_KEY \
+  registry.example.com/my-service@sha256:<digest>
+```
+
+4. Unsigned images are blocked from production namespaces via OPA/Kyverno policy.
+
+## Dependency Pinning
+
+5. All `package.json`, `requirements.txt`, `go.sum` must pin exact versions.
+6. `pip install requests` (unpinned) is forbidden in CI — use `requirements.txt` with hashes.
+7. Base images pinned to digest in Dockerfile: `FROM python:3.12-slim@sha256:...`
+
+## Audit Trail
+
+8. Every build records: git commit, build timestamp, base image digest, all dependency versions.
+9. Provenance attestation (SLSA level 2+) generated for production releases.

package/areas/devops/ci-cd/skills/artifact-management/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: artifact-management
+type: skill
+description: Manage container images, Helm charts, and build artifacts — registry organization, retention, promotion between environments.
+related-rules:
+  - pipeline-standards.md
+  - supply-chain-security.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Skill: Artifact Management
+
+> **Expertise:** OCI registry organization, image tagging strategy, Helm chart registry, artifact promotion, retention policies.
+
+## When to load
+
+When designing artifact storage, setting up Helm chart publishing, configuring image retention, or promoting artifacts between environments.
+
+## Image Tagging Strategy
+
+```
+Registry: registry.example.com / myorg/<service>
+
+Development (PR):
+  registry.example.com/myorg/order-service:pr-123-abc1234   ← per-PR, short-lived
+
+Staging (main branch merge):
+  registry.example.com/myorg/order-service:main-abc1234def   ← branch + sha
+
+Release (git tag):
+  registry.example.com/myorg/order-service:v2.3.1            ← semver tag
+  registry.example.com/myorg/order-service:v2.3              ← minor floating (optional)
+  registry.example.com/myorg/order-service@sha256:abc...     ← digest (use in K8s manifests)
+
+❌ NEVER in production:
+  :latest / :main / :develop   ← mutable, untraceable
+```
+
+## Build + Push with Digest Output
+
+```yaml
+# GitHub Actions — capture digest for downstream jobs
+- name: Build and push
+  id: build
+  uses: docker/build-push-action@v6
+  with:
+    tags: |
+      registry.example.com/myorg/order-service:${{ github.sha }}
+      registry.example.com/myorg/order-service:v${{ steps.version.outputs.tag }}
+    outputs: type=image,push=true
+
+- name: Export digest
+  run: echo "${{ steps.build.outputs.digest }}" > /tmp/digest.txt
+
+# Use digest in deploy job (pinned, immutable)
+- name: Deploy
+  run: |
+    helm upgrade --install order-service charts/order-service \
+      --set image.digest=${{ steps.build.outputs.digest }}
+```
+
+## Helm Chart Registry (OCI)
+
+```bash
+# Push chart to OCI registry (Helm 3.8+)
+helm package charts/order-service --version 1.2.3
+helm push order-service-1.2.3.tgz oci://registry.example.com/myorg/charts
+
+# Pull and use in CI/CD
+helm upgrade --install order-service \
+  oci://registry.example.com/myorg/charts/order-service \
+  --version 1.2.3
+
+# GitLab registry (built-in Helm registry)
+helm push order-service-1.2.3.tgz oci://registry.gitlab.com/myorg/helm-charts
+```
+
+## Artifact Promotion Pattern (staging → production)
+
+```bash
+# Promote: re-tag staging image as release candidate (no rebuild)
+# Using crane (OCI tool) — copy image without pulling/pushing layers
+crane copy \
+  registry.example.com/myorg/order-service:main-abc1234 \
+  registry.example.com/myorg/order-service:v2.3.1
+
+# Verify digest is same (promotion = same bytes, different tag)
+crane digest registry.example.com/myorg/order-service:main-abc1234
+crane digest registry.example.com/myorg/order-service:v2.3.1
+# Must match ✅
+```
+
+## Registry Organization (Harbor / internal)
+
+```
+registry.example.com/
+├── dev/        ← PR images; retain 7 days; no signing required
+│   └── myorg/<service>:<pr-tag>
+├── staging/    ← main branch images; retain 30 days; scan required
+│   └── myorg/<service>:<sha-tag>
+├── releases/   ← versioned releases; retain 1 year; signed + SBOM attached
+│   └── myorg/<service>:v<semver>
+└── base/       ← internal base images; curated, patched, signed
+    ├── python:3.12-slim
+    └── golang:1.23-alpine
+```
+
+## Retention Policy (Harbor / ECR)
+
+```yaml
+# Harbor retention policy (UI or API)
+rules:
+  - tag_selectors:
+      - kind: doublestar
+        pattern: "pr-*"
+    action: retain
+    params:
+      latestPushedK: 5        # keep only 5 latest per PR branch
+    scope_selectors:
+      - kind: daysAgo
+        params: { daysAgo: "7" }  # and delete after 7 days regardless
+
+  - tag_selectors:
+      - kind: doublestar
+        pattern: "v[0-9]*"    # semver tags
+    action: retain            # retain all versioned releases
+```
+
+```bash
+# ECR lifecycle policy
+aws ecr put-lifecycle-policy \
+  --repository-name myorg/order-service \
+  --lifecycle-policy '{
+    "rules": [{
+      "rulePriority": 1,
+      "selection": {
+        "tagStatus": "tagged",
+        "tagPrefixList": ["pr-"],
+        "countType": "sinceImagePushed",
+        "countUnit": "days",
+        "countNumber": 7
+      },
+      "action": {"type": "expire"}
+    }]
+  }'
+```
+
+## Vulnerability Database Refresh
+
+```bash
+# Trivy: update vuln DB before scanning (don't use stale DB in CI)
+trivy image --download-db-only
+# Or in GitHub Actions:
+- uses: aquasecurity/trivy-action@master
+  with:
+    update-db: true
+```