feat(skills): add sdlc, safety, and coding-standards org skills
Mirrors the groombook/org and privilegedescalation/org pattern: extract company-wide policy that's currently inlined across each agent's AGENTS.md (plus auxiliary HEARTBEAT.md / GITHUB.md / SOUL.md / TOOLS.md / INFRASTRUCTURE.md files) into three shared skills. Agents will reference these via one-line invocation reminders in their Wake additions section once the AGENTS.md files are rewritten.
This commit is contained in:
@@ -0,0 +1,192 @@
|
||||
---
|
||||
name: sdlc
|
||||
description: >
|
||||
Software development lifecycle for CartSnitch. 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 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 writes it to `$GH_CONFIG_DIR/.gh-token` (or `$AGENT_HOME/.gh-token` as fallback) and authenticates `gh` automatically. **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 must 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.
|
||||
|
||||
```bash
|
||||
gh pr create --base dev --title "..." --body "... cc @cpfarhood"
|
||||
```
|
||||
|
||||
GitHub branch protection requires CI checks (lint, test, build-and-push). Governance is enforced through the Paperclip SDLC — GitHub-native review approvals are not required because all agents share a GitHub App identity. Paperclip approval tracking is the authoritative record.
|
||||
|
||||
## PR review & merge policy
|
||||
|
||||
### Dev branch (`dev`)
|
||||
- **QA** (Checkout Charlie) reviews the PR. Approve → hand to CTO. Fail → back to engineer directly with exact details.
|
||||
- **CTO** (Savannah Savings) reviews. Approve → CTO merges the `dev` PR. Fail → back to engineer.
|
||||
|
||||
### UAT branch (`uat`)
|
||||
- **CTO** opens and merges a `dev` → `uat` PR (single approval).
|
||||
|
||||
### Main branch (`main`)
|
||||
- **CEO** (Coupon Carl) reviews and merges the `uat` → `main` PR.
|
||||
|
||||
`@cpfarhood` is cc'd for visibility on all PRs — never as a reviewer.
|
||||
|
||||
## SDLC pipeline
|
||||
|
||||
### Product analysis (feature intake)
|
||||
|
||||
* Feature requests arrive at the CEO via Paperclip or GitHub Issues.
|
||||
* CEO delegates to CMO (Markdown Martha) for review.
|
||||
* CMO: Accepted → CEO routes to CTO for work breakdown. Backlogged → CEO handles prioritization. Denied → closed as unplanned.
|
||||
* CTO breaks accepted work into atomic tasks and assigns to Engineering.
|
||||
|
||||
### Phase 1 — Dev
|
||||
|
||||
1. **Engineer** branches from `dev`, writes code. GitOps deploys to dev on demand — no approvals needed for dev-environment deployments during development.
|
||||
2. **Engineer** opens a PR against `dev`. CI must pass.
|
||||
3. **QA (Checkout Charlie)** reviews the PR. Fail → back to engineer.
|
||||
4. QA approves and hands off to CTO.
|
||||
5. **CTO (Savannah Savings)** reviews the PR. Fail → back to engineer.
|
||||
6. **CTO** merges the dev PR.
|
||||
7. **CI** builds and deploys automatically to Dev (`https://cartsnitch.dev.farh.net`).
|
||||
|
||||
### Phase 2 — UAT promotion
|
||||
|
||||
8. **CTO** opens and merges a PR from `dev` to `uat`.
|
||||
9. **CI** builds and deploys automatically to UAT (`https://cartsnitch.uat.farh.net`).
|
||||
10. **CTO** creates a UAT regression task for **Deal Dottie** immediately after promoting.
|
||||
|
||||
### Phase 3 — UAT testing & security
|
||||
|
||||
11. **UAT (Deal Dottie)** 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 (Stockboy Steve)** 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 (Coupon Carl)** reviews and merges the production PR (`uat → main`). Fail → back to CTO.
|
||||
16. **CI** deploys automatically to Production (`https://cartsnitch.farh.net`).
|
||||
|
||||
### Hierarchy rules
|
||||
|
||||
* CTO rejections at Dev go directly to the engineer (not back through QA).
|
||||
* UAT failures (Deal Dottie) go to CTO — CTO cascades to engineer.
|
||||
* Security failures (Stockboy Steve) go to CTO — CTO cascades to engineer.
|
||||
* CEO rejections at Prod go to CTO.
|
||||
|
||||
> **Note on penetration testing:** Stockboy Steve performs scheduled penetration testing against Prod independently of the PR workflow. Board-authorized. Not triggered per-PR.
|
||||
|
||||
## 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:** namespace `cartsnitch`, FQDN `cartsnitch.farh.net`
|
||||
* **UAT:** namespace `cartsnitch-uat`, FQDN `cartsnitch.uat.farh.net`
|
||||
* **Dev:** namespace `cartsnitch-dev`, FQDN `cartsnitch.dev.farh.net`
|
||||
* **Auth:** Better-Auth + OAuth2 via Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret in the relevant namespace). Authentik / Auth0 / Okta / Entra-ID are all supported. **Never build custom auth.**
|
||||
* **Cluster:** Kubernetes — cluster-wide read; read/write on `cartsnitch-dev` and `cartsnitch-uat`; read-only on `cartsnitch` (production).
|
||||
* **Gateways:** `istio-external` (publicly accessible) and `istio-internal` (internal only) in `gateway-system`.
|
||||
* **Container registry:** `ghcr.io/cartsnitch/<service>` only.
|
||||
|
||||
## 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: CalVer (`YYYY.MM.DD[.N]`), `latest`, and `sha-<hash>`
|
||||
- Pushes tagged images to `ghcr.io/cartsnitch/<service>`
|
||||
- Creates a CalVer git tag in the source repo
|
||||
|
||||
**Stage 2 — GitOps (Flux, managed externally):**
|
||||
- Flux watches `cartsnitch/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` → `cartsnitch-dev`, `apps/overlays/uat` → `cartsnitch-uat`, `apps/overlays/prod` → `cartsnitch`.
|
||||
- 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 `cartsnitch/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 `cartsnitch/infra` to update the relevant overlay; merge after kustomize CI passes.
|
||||
3. Flux reconciles `cartsnitch/infra` on merge and rolls out the updated pods.
|
||||
|
||||
**To force a rollout without a manifest change** (e.g., pick up a new `:latest` on stuck nodes):
|
||||
```bash
|
||||
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 `cartsnitch/infra` — the tofu controller reconciles them on merge. Use for Authentik configuration, DNS, or other infra provisioning.
|
||||
|
||||
**Never run `tofu` directly.** Never `kubectl apply` against production. Production changes go through Flux only.
|
||||
|
||||
## External communication
|
||||
|
||||
When communicating in any context visible outside the CartSnitch 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`).
|
||||
Reference in New Issue
Block a user