feat(skills): add sdlc, safety, and coding-standards org skills
Mirrors the privilegedescalation/org pattern: extract company-wide policy that was previously inlined in each agent's AGENTS.md into three shared skills. Agents will reference these via one-line invocation reminders in their Wake additions section.
This commit is contained in:
@@ -0,0 +1,155 @@
|
||||
---
|
||||
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`).
|
||||
Reference in New Issue
Block a user