org/skills/sdlc/SKILL.md

name, description

name	description
sdlc	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:

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.

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

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.