---
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

## 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:

| Branch | Environment | Who merges | Prerequisites for merge |
|--------|-------------|-----------|-----------|
| `dev`  | Dev         | Engineer | None (self-merges after CI passes) |
| `uat`  | UAT         | Engineer | QA code review approval |
| `main` | Production  | Engineer | UAT validation & CTO code review |

**Engineers always target `dev` first** — never `uat` or `main` directly.
- Feature branches: `<agent-name>/<short-description>`.

## 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.

```bash
tea pr create --base dev --title "..." --body "... cc @cpfarhood"
```

Gitea branch protection requires CI checks to pass.

## SDLC pipeline

### Phase 1 — Dev

1. **Engineer** branches from `dev`, writes code.
2. **Engineer** opens a PR against `dev`.
3. **CI** fail → back to **Engineer**.
4. **CI** pass → **Engineer** merges PR.
5. **CI** builds and deploys automatically to Dev (`https://dev.groombook.dev`).

### Phase 2 — UAT promotion

1. **Engineer** opens a PR from `dev` to `uat`.
2. **CI** fail → back to **Engineer** (return to Phase 1).
3. **CI** pass → **QA** performs code review.
4. **QA** rejected → back to **Engineer** (return to Phase 1).
5. **QA** approved → **Engineer** merges PR.
6. **CI** builds and deploys automatically to UAT (`https://uat.groombook.dev`).

### Phase 3 — User Testing & Security Review

1. **UAT (Shedward Scissorhands)** runs full regression against UAT — every feature, old and new, no exceptions.
2. **UAT** fail → back to **Engineer** (return to Phase 1).
3. **UAT** pass → **Security Engineer** performs a security code review of the changes.
4. **Security** fail → back to **Engineer** (return to Phase 1).
5. **Security** pass → **Engineer** opens a PR from `uat` to `main`.
6. **CI** fail → back to **Engineer** (return to Phase 1).
7. **CI** pass → Begin Phase 4.

### Phase 4 — Production

1. **CTO** performs code review.
2. **CTO** approved → **Engineer** merges PR.
3. **CTO** rejected → back to **Engineer** (return to Phase 1).
4. **CI** deploys automatically to Production (`https://demo.groombook.dev`).

## Infrastructure

* **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/<service>` only.

## Authentication

* **Framework:** Better-Auth.
* **OAuth Providers:** GroomBook (Authentik), Google and Apple.
* **SSO:** Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret).
* **Never build custom authentication.**

## Deployment — 2-stage Flux GitOps

**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-<hash>`
- Pushes tagged images to `git.farh.net/groombook/<service>`
- Creates a CalVer git tag in the source repo

**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`.

**To deploy a change:**
1. Merge code to `main` in the app repo — CI builds and pushes a new image automatically.
2. Open a PR against `groombook/infra` to update the relevant overlay; merge after kustomize CI passes.
3. Flux reconciles `groombook/infra` on merge and rolls out the updated pods.

**To force a rollout without a manifest change:**
```bash
kubectl rollout restart deployment/<name> -n <namespace>
```

## 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.
* **Dependency updates:** Mend Renovate. **Dependabot is not used and will not be used.** Do not configure it.
* **Container registry:** `git.farh.net/groombook/<service>` — 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.