org/skills/sdlc/SKILL.md

name, description

name

description

sdlc

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.

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.