From d6b13fa58d04b5b5a7693f3c798dc1be24dc70e8 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Wed, 27 May 2026 15:31:54 -0400 Subject: [PATCH] Split devops and sdlc skills by scope; dedupe shared content devops/SKILL.md is now the canonical home for infrastructure lifecycle (groombook/infra, single-branch main, Flux + OpenTofu controller, cluster topology). sdlc/SKILL.md is scoped to application code (3-branch dev/uat/main, Phases 1-5, Stage 1 CI image build, app-tool policy). Each skill cross-refs the other and defers to coding-standards/safety for cross-cutting rules rather than restating them. Fixes in devops/SKILL.md: - Rewrote frontmatter description (was a copy of sdlc, referenced phases and dev/uat/prod that do not apply). - Hoisted "applies to groombook/infra" to a top-level scope statement. - Renumbered the pipeline (was 1,2,3,4,4,5,4,5,5) and fixed --base dev -> --base main in the tea example. - Closed an unterminated bold marker. - Removed Authentication framework, Stage 1 image build, and the "never tofu / never kubectl apply" lines (now cited from sdlc / safety). - Trimmed the tools list to infra-only operators and controllers. Trims in sdlc/SKILL.md: - Removed Infrastructure topology, IaC, Stage 2 GitOps detail, the Flux Image Automation DENIED policy, the "never tofu / never kubectl apply" lines, and the External communication section (cited from devops / safety / coding-standards instead). - Trimmed the tools list to application-level dependency choices. - Added a pointer from Phase 5 into the devops pipeline. cc @cpfarhood Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/devops/SKILL.md | 76 ++++++++++++++++++++++++++++++++++++++++++ skills/sdlc/SKILL.md | 70 +++++++++++++------------------------- 2 files changed, 99 insertions(+), 47 deletions(-) create mode 100644 skills/devops/SKILL.md diff --git a/skills/devops/SKILL.md b/skills/devops/SKILL.md new file mode 100644 index 0000000..5a47cdc --- /dev/null +++ b/skills/devops/SKILL.md @@ -0,0 +1,76 @@ +--- +name: devops +description: > + Infrastructure lifecycle for GroomBook. Governs work on the + groombook/infra repo: single-branch main strategy, the infra PR review + pipeline, Flux GitOps reconciliation, OpenTofu controller workflow, + cluster topology, and the Flux image-automation policy. For application + code, see the sdlc skill. +--- + +# DevOps Practices + +This skill governs work on **`groombook/infra`**. For application code lifecycle, see the `sdlc` skill. For PR/test discipline and the `cc @cpfarhood` visibility rule, see `coding-standards`. For non-negotiable safety rules (no direct `tofu`, no `kubectl apply` to production, SealedSecrets), see `safety`. + +## Gitea authentication + +Use the `GITEA_TOKEN` environment variable for all Gitea operations — it is already set in the agent environment. Use the **`tea`** CLI for all Gitea/Git operations (e.g., `tea issue list`, `tea pr create`). Gitea is the primary source of truth. + +## Branch strategy + +`groombook/infra` uses a single long-lived branch: **`main`**. Engineers target `main` directly via feature branches named `/`. + +## Pipeline + +1. **Engineer** branches from `main`, writes code. +2. **Engineer** opens a PR against `main`. +3. **CI** fail → back to **Engineer**. +4. **CI** pass → **QA** performs code review. +5. **QA** rejected → back to **Engineer**. +6. **QA** approved → **CTO** performs code review. +7. **CTO** rejected → back to **Engineer**. +8. **CTO** approved → **Engineer** merges PR → **Flux** reconciles automatically. + +```bash +tea pr create --base main --title "..." --body "... cc @cpfarhood" +``` + +Gitea branch protection requires CI checks to pass. See `coding-standards` for the no-self-merge contract and the `cc @cpfarhood` rule. + +## Infrastructure topology + +* **Production:** namespace `groombook`, FQDN `demo.groombook.dev` +* **UAT:** namespace `groombook-uat`, FQDN `uat.groombook.dev` +* **Dev:** namespace `groombook-dev`, FQDN `dev.groombook.dev` +* **Cluster:** Kubernetes — cluster-wide read; read/write on `groombook-dev` and `groombook-uat`; read-only on `groombook` (production). +* **Gateways:** `istio-external` (public) and `istio-internal` (internal) in `gateway-system`. +* **Container registry:** `git.farh.net/groombook/` only. + +## GitOps (Flux) + +Flux watches `groombook/infra` as the **target** GitRepository — it is **not** a Flux bootstrap/cluster repo and must never be treated as one. + +Reconciles Kustomize overlays: +- `apps/overlays/dev` → `groombook-dev` +- `apps/overlays/uat` → `groombook-uat` +- `apps/overlays/prod` → `groombook` + +Images currently use `:latest` with `imagePullPolicy: Always`; pin to a CalVer tag in the infra overlay when stabilizing a release. + +**Policy — Flux Image Tag Automation is DENIED.** Do NOT use `ImageRepository`, `ImagePolicy`, or `ImageUpdateAutomation` Flux resources. Image tag updates must be made intentionally via a PR to `groombook/infra` — typically as the final step of the `sdlc` application pipeline (Phase 5). + +## Infrastructure as Code + +Terraform (OpenTofu) is deployed via the **Flux OpenTofu Controller** in a GitOps fashion. Submit Terraform configurations via a PR to `groombook/infra` — the tofu controller reconciles them on merge. See `safety` for the prohibition on running `tofu` directly and on `kubectl apply` against production. + +## Infra-only tools + +These are the operators and controllers the infra repo installs and manages. Alternatives are policy violations: + +* **GitOps:** Flux CD (managed externally; reconciles `groombook/infra`). +* **IaC:** Flux OpenTofu Controller. +* **Secret management:** Bitnami Sealed Secrets Controller — encrypt with `kubeseal`, commit `SealedSecret` resources to `groombook/infra`. No plain Kubernetes secrets. +* **Database operator:** CloudNativePG (Postgres). +* **Cache / pub-sub operator:** DragonflyDB. + +For application-level tool policy (Renovate, Playwright, registry, CalVer) see `coding-standards` and `sdlc`. diff --git a/skills/sdlc/SKILL.md b/skills/sdlc/SKILL.md index 27526d2..aec8696 100644 --- a/skills/sdlc/SKILL.md +++ b/skills/sdlc/SKILL.md @@ -1,22 +1,23 @@ --- name: sdlc description: > - Software development lifecycle for GroomBook. Covers Gitea authentication, - branch strategy across Dev/UAT/Prod, the SDLC pipeline phases, - PR review and merge policy, infrastructure layout, the Gitea-origin issue - board-approval gate, the cc-cpfarhood visibility rule, - and delegation model tier policy. + Software development lifecycle for GroomBook application repos. Covers + Gitea authentication, the 3-branch dev/uat/main strategy, the SDLC + pipeline phases 1-5, the Stage 1 CI image build, the authentication + framework, and application-tool policy. For infrastructure + (groombook/infra), see the devops skill. --- # Software Development Lifecycle +This skill governs **application code repos**. For infrastructure (`groombook/infra`), see the `devops` skill. For PR/test discipline and the `cc @cpfarhood` visibility rule, see `coding-standards`. For non-negotiable safety rules, see `safety`. + ## Gitea authentication **Use the `GITEA_TOKEN`** environment variable for all Gitea operations. It is already set in the agent environment. Use the **`tea`** CLI for all Gitea/Git operations (e.g., `tea issue list`, `tea pr create`). The token expires when the environment variable is rotated — re-invoke any Gitea operation if you get a 401. Gitea is the **primary source of truth**. Every Paperclip issue must have a corresponding Gitea issue (create one if missing). Both stay open until the work is completed, reviewed, approved, merged, and QA-verified. - ## Branch strategy Three long-lived branches map to the three deployment environments: @@ -32,14 +33,12 @@ Three long-lived branches map to the three deployment environments: ## Pull requests -All changes happen via pull request. Always include `cc @cpfarhood` at the bottom of the PR body for visibility — never as a reviewer. +All changes happen via pull request. Gitea branch protection requires CI checks to pass. See `coding-standards` for the no-self-merge contract and the `cc @cpfarhood` visibility rule. ```bash tea pr create --base dev --title "..." --body "... cc @cpfarhood" ``` -Gitea branch protection requires CI checks to pass. - ## SDLC pipeline ### Phase 1 — Dev @@ -86,14 +85,16 @@ Gitea branch protection requires CI checks to pass. 5. **QA** approved → **Engineer** merges PR. 6. **Flux** reconciles `groombook/infra` on merge and rolls out the updated pods to production (`https://demo.groombook.dev`). -## Infrastructure +See the `devops` skill for the infrastructure pipeline that governs the `groombook/infra` PR in this phase, and for Flux reconciliation behavior. -* **Production:** namespace `groombook`, FQDN `demo.groombook.dev` -* **UAT:** namespace `groombook-uat`, FQDN `uat.groombook.dev` -* **Dev:** namespace `groombook-dev`, FQDN `dev.groombook.dev` -* **Cluster:** Kubernetes — cluster-wide read; read/write on `groombook-dev` and `groombook-uat`; read-only on `groombook` (production). -* **Gateways:** `istio-external` (public) and `istio-internal` (internal) in `gateway-system`. -* **Container registry:** `git.farh.net/groombook/` only. +## Stage 1 CI — Image build + +Triggered automatically on every merge to `main` in an application repo: +- Builds and tags the Docker image: CalVer (`YYYY.MM.DD[.N]`), `latest`, and `sha-` +- Pushes tagged images to `git.farh.net/groombook/` (see `coding-standards` for the registry and CalVer policy) +- Creates a CalVer git tag in the source repo + +Stage 2 (Flux GitOps deployment) is owned by `devops`. ## Authentication @@ -102,39 +103,14 @@ Gitea branch protection requires CI checks to pass. * **SSO:** Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret). * **Never build custom authentication.** -## Continuous Integration & Deployment +## Application tools (canonical, not alternatives) -**Stage 1 — CI (runs in each application repo):** -- Triggered automatically on every merge to `main` -- Builds and tags the Docker image: CalVer (`YYYY.MM.DD[.N]`), `latest`, and `sha-` -- Pushes tagged images to `git.farh.net/groombook/` -- Creates a CalVer git tag in the source repo +These are application-level dependency choices. Alternatives are policy violations: -**Stage 2 — GitOps (Flux, managed externally):** -- Flux watches `groombook/infra` as the **target** GitRepository — it is **not** a Flux bootstrap/cluster repo and must never be treated as one. -- Reconciles Kustomize overlays: `apps/overlays/dev` → `groombook-dev`, `apps/overlays/uat` → `groombook-uat`, `apps/overlays/prod` → `groombook`. -- Images currently use `:latest` with `imagePullPolicy: Always`; pin to a CalVer tag in the infra overlay when stabilizing a release. - -**Policy — Flux Image Tag Automation is DENIED.** Do NOT use `ImageRepository`, `ImagePolicy`, or `ImageUpdateAutomation` Flux resources. Image tag updates must be made intentionally via a PR to `groombook/infra`. - -## Infrastructure as Code - -Terraform (OpenTofu) is deployed via the **Flux OpenTofu Controller** in a GitOps fashion. Submit Terraform configurations via a PR to `groombook/infra` — the tofu controller reconciles them on merge. - -**Never run `tofu` directly.** Never `kubectl apply` against production. Production changes go through Flux only. The `groombook-dev` and `groombook-uat` namespaces permit direct kubectl use for troubleshooting and iteration. - -## Tools (canonical, not alternatives) - -These are the only acceptable choices — alternatives are policy violations: - -* **Secret management:** Bitnami Sealed Secrets Controller — no plain Kubernetes secrets. -* **Database:** CloudNativePG Operator (Postgres) — no SQLite, MariaDB, or MySQL. -* **Cache / pub-sub:** DragonflyDB Operator — no Redis. -* **Authentication:** Better-Auth + Google + Apple + Authentik (see Authentication section). Never build custom auth. +* **Database:** CloudNativePG-managed Postgres — no SQLite, MariaDB, or MySQL. +* **Cache / pub-sub:** DragonflyDB — no Redis. +* **Authentication:** Better-Auth + Google + Apple + Authentik (see Authentication above). * **Dependency updates:** Mend Renovate. **Dependabot is not used and will not be used.** Do not configure it. -* **Container registry:** `git.farh.net/groombook/` — no Docker Hub for first-party images. * **Browser automation:** the `playwright` MCP server (`http://playwright:8931/mcp`). Target dev only — never test production. -## External communication - -When communicating in any context visible outside the GroomBook agent team (external users, human reviewers, non-agent entities), include `cc @cpfarhood` for visibility — never as a reviewer. +For the container registry, CalVer versioning, and general PR/test discipline, see `coding-standards`. For the operator install side (CNPG, Dragonfly, Sealed Secrets), see `devops`.