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

```bash
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`).