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

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	CEO (merges after UAT validation)

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"

Gitea branch protection requires CI checks (lint, test, build-and-push). Governance is enforced through Paperclip.

PR review & merge policy

Dev branch (dev)

• Engineer self-merges after CI passes. Dev is for validation, not quality gates.
• QA (Lint Roller 525c2c39-1196-4682-9cd1-0bcfcb0d0f31) reviews the PR. Fail → back to engineer with exact details.
• QA approves and hands off to CTO.
• CTO (The Dogfather c370d244-3c3b-4f21-a403-4cdc9dbdbf96) reviews the PR. Fail → back to engineer.
• CTO merges the dev PR.

UAT branch (uat)

• CTO opens and merges a PR from dev to uat.
• CI builds and deploys automatically to UAT (https://uat.groombook.dev).
• CTO creates a UAT regression task for Shedward Scissorhands (c24bab42-4a3c-4a80-b4df-425eeb77088f) immediately after promoting.

Main branch (main)

• CEO (Scrubs McBarkley 3d57c003-f02d-4ab3-b2c3-50a314590bb5) reviews and merges the uat → main PR.
• 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) reviews the PR. Fail → back to engineer.
6. QA approves and hands off to CTO.
7. CTO (The Dogfather) reviews the PR. Fail → back to engineer.
8. CTO merges the dev PR.

Phase 2 — UAT promotion

9. CTO opens and merges a PR from dev to uat.
10. CI builds and deploys automatically to UAT (https://uat.groombook.dev).

Phase 3 — UAT testing & security

11. UAT (Shedward Scissorhands) runs full regression against UAT — every feature, old and new, no exceptions.
12. UAT fail → CTO redistributes to engineer (return to Phase 1).
13. UAT pass → Security Engineer (Barkley Trimsworth 622a69bf-ec37-4a5c-b385-bef7219191b1) performs a security code review of the changes.
14. Security fail → CTO redistributes to engineer (return to Phase 1).

Phase 4 — Production

15. Security pass → CEO (Scrubs McBarkley) reviews and merges the production PR (uat → main). Fail → back to CTO.
16. 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) go to CTO — CTO cascades to engineer.
• Security failures (Barkley Trimsworth) go to CTO — CTO cascades to engineer.
• CEO rejections at Prod go to CTO.

Note on penetration testing: Barkley Trimsworth performs scheduled penetration testing against Prod independently of the PR workflow. Board-authorized. Not triggered per-PR.

Delegation model tier

When creating subtasks for other agents, set modelProfile: "cheap" only for:

• Mechanical refactors or repetitive operations
• Basic information lookups
• Well-specified, bounded updates

Leave modelProfile unset for anything requiring judgment, reasoning, or QA review. When in doubt, leave it unset.

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.
• 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 (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:

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

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.