org/skills/sdlc/SKILL.md

---
name: sdlc
description: >
  Software development lifecycle for GroomBook application repos. Covers
  Gitea authentication, the 3-branch dev/uat/main strategy, the SDLC
  pipeline phases 1-5, the uat→main merge-gate policy (engineer
  self-merge when pre-gates are green; CTO Gitea Approve only for
  novel auth, infra/prod-affecting, and risk-flagged merges),
  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`. The **uat→main merge-gate policy** (which uat→main PRs need a CTO Gitea Approve click vs. engineer self-merge) is defined in this skill — see "uat→main merge-gate policy" below.

## 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 | CI passes |
| `uat`  | UAT         | Engineer | QA code review approval |
| `main` | Production  | Engineer | UAT validation, security review, and the uat→main merge-gate policy (below) |

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

## Pull requests

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

## 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 → Begin Phase 4.

### Phase 4 — Production Promotion

1. **Engineer** opens a PR from `uat` to `main`.
2. **CI** fail → back to **Engineer** (return to Phase 1).
3. **CI** pass → **Engineer** classifies the PR against the **uat→main merge-gate policy** (below):
   * **In a category that requires CTO Gitea Approve** (novel auth / session paths, infra / prod-affecting merges, `risk:cto-approve` label or explicit CTO/CEO sign-off request) → Engineer pings the CTO for a Gitea Approve click.
     * **CTO** rejected → back to **Engineer** (return to Phase 1).
     * **CTO** approved → continue to step 4.
   * **Outside all three categories** → no CTO click needed; jump to step 4 once the four pre-gates (QA, UAT deploy, UAT regression, security) are green.
4. **Engineer** merges the PR.
5. **CI** fail → back to **Engineer** (return to Phase 1).
6. **CI** pass → Begin Phase 5.

### Phase 5 — Production Deployment

The **Engineer** opens a PR against `groombook/infra` to update the relevant Kustomize overlay with the new image tag. From this point the work follows the **`devops` skill pipeline** end-to-end — review, merge, and Flux reconciliation are all owned there. On merge, Flux rolls out the updated pods to production (`https://demo.groombook.dev`).

## uat→main merge-gate policy

This is the process policy that governs which `uat → main` PRs need a CTO Gitea Approve click vs. engineer self-merge. It exists because the Gitea `required_approvals` branch-protection gate is satisfied only by a Gitea Approve click — the Paperclip issue-thread QA/UAT-deploy/UAT-regression/security approvals do **not** clear it. The engineer **MUST** classify every `uat → main` PR against this policy before merging.

### The four pre-gates are unchanged

A `uat → main` PR is mergeable only when all of these are green on the linked Paperclip issue: QA code review, UAT deploy, UAT regression, and security review. The CTO Gitea Approve click is **in addition to** those four when the PR falls in one of the categories below; it does not replace any of them.

### Categories that require CTO Gitea Approve

A CTO Gitea Approve click is required only for PRs in one of the following three categories:

1. **Novel auth / session paths.** Login, OIDC, OOBE, session middleware, token issuance, password reset, MFA, or any new auth provider integration. Routine changes to auth-gated UI (button styling, error messages, form layout, copy edits) are **not** in this category.
2. **Infra / prod-affecting merges.** Deploys, infra manifests, secrets, GitOps overlays, CI/CD, `main` branch protection, prod-affecting routing/ingress, or any change that mutates prod state. **All Phase 5 infra overlay PRs in `groombook/infra` require CTO Gitea Approve without exception.**
3. **Risk-flagged merges.** The PR carries the `risk:cto-approve` label, **or** the PR or its linked Paperclip issue thread contains an explicit CTO/CEO sign-off request.

### Engineer workflow

The engineer who opened the PR classifies it against the three categories above (escalating to the CTO via comment if the call is unclear), then:

* **In a category** → request a CTO Gitea Approve click. Engineer merges once the CTO has approved.
* **Outside all three categories** → no CTO click needed. Engineer merges once the four pre-gates are green.

**Board/CEO approval is via SDLC code review (judgment) on the Paperclip issue, not via a Gitea Approve click.** The CEO's role at Phase 4 is to perform the code review on the Paperclip issue thread; that approval satisfies the "CEO approved" pre-condition and is recorded in Paperclip, not in Gitea.

### When uncertain

If a `uat → main` PR does not obviously belong to a category, comment on the PR with `@<the-dogfather>` (or escalate to the CEO if the CTO is unavailable) and pause the merge. Do not guess the category — a routine PR is a routine PR, but a borderline PR is cheaper to escalate than to misclassify.

## 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-<hash>`
- Pushes tagged images to `git.farh.net/groombook/<service>` (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

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

## Application tools (canonical, not alternatives)

These are application-level dependency choices. Alternatives are policy violations:

* **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.
* **Browser automation:** the `playwright` MCP server (`http://playwright:8931/mcp`). Target dev only — never test production.

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