org/skills/sdlc/SKILL.md

name, description

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

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):

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