org/skills/sdlc/SKILL.md

name, description

name	description
sdlc	Software development lifecycle for GroomBook. Covers GitHub authentication, branch strategy across Dev/UAT/Prod, PR review and merge policy, the SDLC pipeline and stage handoffs, status semantics, infrastructure layout, the GitHub-origin issue board-approval gate, and the cc-cpfarhood visibility rule.

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-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 + CTO approval)
uat	UAT	CTO (promotes dev → uat)
main	Production	CEO (promotes uat → main)

Engineers always target dev — never uat or main directly.

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 --title "..." --body "... cc @cpfarhood"

PR review & merge policy

Dev branch (dev)

Requires 2 approving GitHub reviews before merge:

1. QA (Lint Roller) — code review, CI signal, test coverage
2. CTO (The Dogfather) — architecture, security, correctness

CTO review requires QA approval as a precondition.

UAT branch (uat)

Requires 1 approving GitHub review before merge:

• CTO (The Dogfather) — promotes dev → uat

Main branch (main)

Requires 1 approving GitHub review before merge:

• CEO (Scrubs McBarkley) — promotes uat → main

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

Pipeline

Dev stage:   Engineer → QA Review → CTO Review → CTO merges PR to dev → [auto deploy Dev]
UAT stage:   CTO opens dev→uat PR → Shedward (regression) → Barkley (security) → CEO assigned
Prod stage:  CEO merges uat→main PR → [auto deploy Production]

Dev stage

1. Engineer creates a PR targeting dev, hands off to QA (Lint Roller) with status: "todo".
2. QA reviews code and CI. Pass → hand to CTO. Fail → hand back to engineer directly with exact failure details.
3. CTO reviews. Approve → merge PR into dev (auto-deploys to Dev). Deny → hand back to engineer.

UAT stage

4. CTO opens a PR from dev → uat to promote the change, assigns Shedward Scissorhands for regression: status: "todo".
5. Shedward runs UAT in uat.groombook.dev. Pass → reports to CTO. Fail → reports to CTO (CTO cascades to engineer).
6. CTO assigns Barkley Trimsworth for security review: status: "todo".
7. Barkley reviews. Pass → CTO assigns to CEO. Fail → CTO cascades to engineer.

Prod stage

8. CEO reviews and merges the uat → main PR → auto-deploys to Production.
9. CEO rejects → returns to CTO → engineer.

Hierarchy rules

• CTO rejections go directly to the engineer (not through QA).
• Shedward UAT failures go to CTO (not directly to the engineer).
• Barkley security failures go to CTO.
• CEO rejections go to CTO.

Handoff protocol — mandatory

Every handoff to another agent requires ALL THREE steps:

1. Explicit assignment

PATCH the issue 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 for handoffs — it doesn't surface in the receiver's inbox.

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.

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
• Auth: Better-Auth + OAuth2 via Authentik OIDC at https://auth.farh.net (credentials in authentik-credentials secret)
• Cluster: Kubernetes — cluster-wide read; read/write on groombook-dev and groombook-uat.
• Gateways: istio-external and istio-internal in gateway-system.
• Deployment: 2-stage Flux GitOps — CI builds images → updates tags in groombook/infra → Flux applies. Never kubectl apply for app manifests. No Flux Image Automation.
• Infra provisioning: Commit OpenTofu HCL to groombook/infra. Never run tofu directly.
• Dependency updates: Mend Renovate only. Never Dependabot.

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.

No self-merge

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