---
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, and the canonical tools list.
---

# Software Development Lifecycle

## Gitea authentication

**Use the `tea` CLI** with the `GITEA_TOKEN` environment variable for all Gitea operations. Configure it once:

```bash
tea login add --url https://git.farh.net --token $GITEA_TOKEN --name groombook
```

Gitea is the **primary source of truth**. Every Paperclip issue should have a corresponding Gitea issue (create one if missing). Both stay open until the work is completed, reviewed, approved, merged, and QA-verified.

## Gitea-origin issue policy — board approval required

If a task originated from Gitea (`originKind: "gitea"`), **do not begin work**. Immediately create a board approval:

```
POST /api/companies/{companyId}/approvals
{
  "type": "request_board_approval",
  "requestedByAgentId": "{your-agent-id}",
  "issueIds": ["{issueId}"],
  "payload": {
    "title": "Board approval required: Gitea issue",
    "summary": "Summarize what the Gitea issue requests.",
    "recommendedAction": "Approve to begin work.",
    "risks": ["Work begins without board review if approved."]
  }
}
```

Set the issue to `blocked` with a comment linking to the approval. Only proceed once `PAPERCLIP_APPROVAL_ID` is set and `PAPERCLIP_APPROVAL_STATUS` indicates approval.

## Branch strategy

Three long-lived branches map to the three deployment environments:

| Branch | Environment | Who merges |
|--------|-------------|-----------|
| `dev`  | Dev         | Engineer (self-merges after CI passes)            |
| `uat`  | UAT         | QA (merges after code review)        |
| `main` | Production  | UAT (validates browser, then merges)       |

**Engineers always target `dev`** — 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"
```

## PR review & merge policy

### Dev branch (`dev`)

- **Engineer** self-merges after CI passes. No review required. Dev is for validation, not quality gates.
- **QA (Lint Roller `525c2c39-1196-4682-9cd1-0bcfcb0d0f31`)** reviews the PR. Fail → back to engineer directly with exact details.

### UAT branch (`uat`)

- **QA (Lint Roller)** merges `dev → uat` after approval.
- **CI** builds and deploys automatically to UAT (`https://uat.groombook.dev`).

### Main branch (`main`)

- **UAT (Shedward Scissorhands `c24bab42-4a3c-4a80-b4df-425eeb77088f`)** validates the deployed application via Playwright browser testing.
- **UAT** merges `uat → main` after validation passes.
- **CI** deploys automatically to Production (`https://demo.groombook.dev`).

`@cpfarhood` is cc'd for visibility on all PRs — never as a reviewer.

## SDLC pipeline

### Phase 1 — Dev

1. **Engineer** (Flea Flicker `ccfa5281-2076-40c2-87a9-bf2dbcf98d22`) branches from `dev`, writes code. GitOps deploys to dev on demand.
2. **Engineer** opens a PR against `dev`. CI must pass.
3. **Engineer** self-merges after CI passes.
4. **CI** builds and deploys automatically to Dev (`https://dev.groombook.dev`).
5. **QA (Lint Roller `525c2c39-1196-4682-9cd1-0bcfcb0d0f31`)** reviews the PR. Fail → back to engineer.
6. QA approves and hands off to CTO.
7. **CTO (The Dogfather `c370d244-3c3b-4f21-a403-4cdc9dbdbf96`)** reviews the PR. Fail → back to engineer.
8. **CTO** merges the dev PR.

### Phase 2 — UAT promotion

9. **QA (Lint Roller)** merges `dev → uat` after CTO approval.
10. **CI** builds and deploys automatically to UAT (`https://uat.groombook.dev`).
11. **CTO** creates a UAT regression task for **Shedward Scissorhands (`c24bab42-4a3c-4a80-b4df-425eeb77088f`)** immediately after promoting.

### Phase 3 — UAT testing

12. **UAT (Shedward Scissorhands `c24bab42-4a3c-4a80-b4df-425eeb77088f`)** runs full regression against UAT — every feature, no exceptions.
13. UAT fail → CTO redistributes to engineer (return to Phase 1).
14. UAT pass → **Security Engineer (Barkley Trimsworth `622a69bf-ec37-4a5c-b385-bef7219191b1`)** performs a security code review of the changes.
15. Security fail → CTO redistributes to engineer (return to Phase 1).

### Phase 4 — Production

16. Security pass → **UAT (Shedward Scissorhands)** merges `uat → main`.
17. **CI** deploys automatically to Production (`https://demo.groombook.dev`).

### Hierarchy rules

* CTO rejections at Dev go directly to the engineer (not back through QA).
* UAT failures (Shedward Scissorhands `c24bab42-4a3c-4a80-b4df-425eeb77088f`) go to CTO — CTO cascades to engineer.
* Security failures (Barkley Trimsworth `622a69bf-ec37-4a5c-b385-bef7219191b1`) go to CTO — CTO cascades to engineer.
* UAT rejections at Prod go to CTO.

> **Penetration testing.** Barkley performs scheduled penetration testing against Production (`demo.groombook.dev`) and Demo independently of the PR workflow. Board-authorized; not triggered per-PR. Findings get filed as Paperclip issues with severity (`CRITICAL` / `HIGH` / `MEDIUM` / `LOW`) and routed to CTO for engineer redistribution.


## Infrastructure

* **Production / Demo:** 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` (publicly accessible) and `istio-internal` (internal only) in `gateway-system`.
* **Container registry:** `ghcr.io/groombook/<service>` only.

## Authentication

* **Framework:** Better-Auth.
* **Social login:** Google and Apple OAuth.
* **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 (Gitea Actions, uses GitHub Actions-compatible YAML syntax, runs in each application repo):**
- Triggered automatically on every merge to `main`
- Builds and tags the Docker image
- Pushes tagged images to `ghcr.io/groombook/<service>`

**Stage 2 — GitOps (Flux, managed externally):**
- Flux watches `groombook/infra` as the **target** GitRepository — it is **not** a Flux bootstrap/cluster repo.
- Reconciles Kustomize overlays: `apps/overlays/dev` → `groombook-dev`, `apps/overlays/uat` → `groombook-uat`, `apps/overlays/prod` → `groombook`.

**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** (pick up new `:latest` on stuck pods):
```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 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.

## 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.**
* **Container registry:** `ghcr.io/groombook/<service>` — no Docker Hub for first-party images.

If a task requires deviating from any of the above, treat it as a destructive action: stop, file an issue with rationale, request board approval.

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