org/skills/sdlc/SKILL.md

name, description

name

description

sdlc

Software development lifecycle for GroomBook. Covers GitHub authentication, branch strategy across Dev/UAT/Prod, the four-phase SDLC pipeline with product analysis intake, PR review and merge policy, the handoff protocol, status semantics, infrastructure layout, the canonical tools list, the GitHub-origin issue board-approval gate, the cc-cpfarhood visibility rule, the scheduled penetration testing program, and delegation model tier policy.

Software Development Lifecycle

GitHub authentication

Invoke the github-app-token skill before any GitHub operation. It generates a short-lived installation token and sets GH_TOKEN. Never run gh auth login — it hangs headless agents. Token expires after ~1 hour; re-invoke to regenerate.

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

GitHub-origin issue policy — board approval required

If a task originated from GitHub (originKind: "github"), 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: GitHub issue",
    "summary": "Summarize what the GitHub 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	CTO (after QA approval)
uat	UAT	CTO (promotes dev → uat)
main	Production	CEO (promotes uat → main)

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.

gh pr create --base dev --title "..." --body "... cc @cpfarhood"

PR review & merge policy

Dev branch (dev)

• QA (Lint Roller) reviews the PR. Approve → hand to CTO. Fail → back to engineer directly with exact details.
• CTO (The Dogfather) reviews. Approve → CTO merges the dev PR. Fail → back to engineer.

UAT branch (uat)

• CTO opens and merges a dev → uat PR.

Main branch (main)

• CEO (Scrubs McBarkley) reviews and merges the uat → main PR.

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

SDLC pipeline

Phase 0 — Product analysis (feature intake)

• Feature requests arrive at the CEO via Paperclip or GitHub Issues.
• CEO delegates to CMPO (Pawla Abdul) for review.
• CMPO returns one of three decisions:
  • Accepted → CEO routes to CTO for work breakdown.
  • Backlogged → CEO handles prioritization.
  • Denied → CEO closes as unplanned.
• CTO breaks accepted work into atomic tasks and assigns to Engineering.

Phase 1 — Dev

1. Engineer (Flea Flicker) branches from dev, writes code. GitOps deploys to dev on demand.
2. Engineer opens a PR against dev. CI must pass.
3. QA (Lint Roller) reviews the PR. Fail → back to engineer.
4. QA approves and hands off to CTO.
5. CTO (The Dogfather) reviews the PR. Fail → back to engineer.
6. CTO merges the dev PR.
7. CI builds and deploys automatically to Dev (https://dev.groombook.dev).

Phase 2 — UAT promotion

8. CTO opens and merges a PR from dev to uat.
9. CI builds and deploys automatically to UAT (https://uat.groombook.dev).
10. CTO creates a UAT regression task for Shedward Scissorhands immediately after promoting.

Phase 3 — UAT testing & security

11. UAT (Shedward Scissorhands) runs full regression against UAT — every feature, no exceptions.
12. UAT fail → CTO redistributes to engineer (return to Phase 1).
13. UAT pass → Security Engineer (Barkley Trimsworth) 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) go to CTO — CTO cascades to engineer.
• Security failures (Barkley) go to CTO — CTO cascades to engineer.
• CEO 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.

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.

Handoff protocol — mandatory

Every handoff to another agent requires ALL THREE steps:

1. Explicit assignment

PATCH /api/issues/{id} with assigneeAgentId: "<target-agent-uuid>". Mentioning is NOT a handoff — the agent won't wake without explicit assignment.

2. Status = todo

Every handoff sets status: "todo". Never in_review, never backlog — both are invisible in inbox-lite and the receiver won't wake.

3. Release checkout

POST /api/issues/{issueId}/release
Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID

Without this release, the receiving agent cannot check out the issue.

Saying you are reassigning a task is NOT the same as reassigning it. Verify the PATCH succeeded (200) before posting a comment claiming the handoff is done.

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 (GitHub Actions, 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.

No self-merge

No agent merges their own PR. The merger is always the next role up the SDLC ladder (CTO for dev and uat, CEO for main).