From 53bc4132ca2ce8690d35dd6ab8560e1429baf746 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Sun, 24 May 2026 15:42:58 -0400 Subject: [PATCH] =?UTF-8?q?refactor(sdlc):=20simplify=20=E2=80=94=20remove?= =?UTF-8?q?=20handoff=20protocol=20and=20self-merge=20section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align with groombook SDLC style: engineer self-merges dev, QA merges uat, CEO merges main. Drop the explicit 3-step handoff protocol (Paperclip handles it via in_review). Remove the redundant "no self-merge" footer. Keep delegation model tier, board approval gate, and cc @cpfarhood. Co-Authored-By: Claude Opus 4.7 --- skills/sdlc/SKILL.md | 103 +++++++++++++++---------------------------- 1 file changed, 36 insertions(+), 67 deletions(-) diff --git a/skills/sdlc/SKILL.md b/skills/sdlc/SKILL.md index d6661a9..12b6c04 100644 --- a/skills/sdlc/SKILL.md +++ b/skills/sdlc/SKILL.md @@ -2,9 +2,8 @@ name: sdlc description: > Software development lifecycle for CartSnitch. Covers Gitea 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 Gitea-origin issue + branch strategy across Dev/UAT/Prod, the SDLC pipeline phases, + PR review and merge policy, infrastructure layout, the Gitea-origin issue board-approval gate, the cc-cpfarhood visibility rule, and delegation model tier policy. --- @@ -29,7 +28,7 @@ POST /api/companies/{companyId}/approvals "issueIds": ["{issueId}"], "payload": { "title": "Board approval required: Gitea issue", - "summary": "Summarize what the GitHub issue requests.", + "summary": "Summarize what the Gitea issue requests.", "recommendedAction": "Approve to begin work.", "risks": ["Work begins without board review if approved."] } @@ -44,9 +43,9 @@ 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`) | +| `dev` | Dev | Engineer (self-merges after CI passes) | +| `uat` | UAT | QA (merges after code review) | +| `main` | Production | CEO (merges after UAT validation) | **Engineers always target `dev`** — never `uat` or `main` directly. Feature branches: `/`. @@ -58,64 +57,63 @@ All changes happen via pull request. Always include `cc @cpfarhood` at the botto tea pr create --base dev --title "..." --body "... cc @cpfarhood" ``` -Gitea branch protection requires CI checks (lint, test, build-and-push). Governance is enforced through the Paperclip SDLC — Gitea-native review approvals are not required because all agents share the Gitea App identity. Paperclip approval tracking is the authoritative record. +Gitea branch protection requires CI checks (lint, test, build-and-push). Governance is enforced through Paperclip — Gitea-native review approvals are not required because all agents share the Gitea App identity. ## PR review & merge policy ### Dev branch (`dev`) -- **QA** (Checkout Charlie `9b6012d0-0406-417e-bb22-78266a6e7f77`) reviews the PR. Approve → hand to CTO. Fail → back to engineer directly with exact details. -- **CTO** (Savannah Savings `6ec1a5a9-113c-430b-90e6-260d60d79e1d`) reviews. Approve → CTO merges the `dev` PR. Fail → back to engineer. +- **Engineer** self-merges after CI passes. Dev is for validation, not quality gates. +- **QA (Checkout Charlie `9b6012d0-0406-417e-bb22-78266a6e7f77`)** reviews the PR. Fail → back to engineer with exact details. +- QA approves and hands off to CTO. +- **CTO (Savannah Savings `6ec1a5a9-113c-430b-90e6-260d60d79e1d`)** reviews the PR. Fail → back to engineer. +- **CTO** merges the dev PR. ### UAT branch (`uat`) -- **CTO** opens and merges a `dev` → `uat` PR (single approval). +- **CTO** opens and merges a PR from `dev` to `uat`. +- **CI** builds and deploys automatically to UAT (`https://uat.cartsnitch.com`). +- **CTO** creates a UAT regression task for **Deal Dottie (`161fb3bb-0332-4381-b67d-7c4b92a91133`)** immediately after promoting. ### Main branch (`main`) -- **CEO** (Coupon Carl `cd91facf-8f4c-4cbd-b8d8-b48da5b50727`) reviews and merges the `uat` → `main` PR. +- **CEO (Coupon Carl `cd91facf-8f4c-4cbd-b8d8-b48da5b50727`)** reviews and merges the `uat → main` PR. +- **CI** deploys automatically to Production (`https://cartsnitch.com`). `@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 Gitea Issues. -* CEO delegates to CMO (Markdown Martha `46614fb2-6d29-4ea3-bc46-4a3b94086e3c`) 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. +1. **Engineer** branches from `dev`, writes code. GitOps deploys to dev on demand. 2. **Engineer** opens a PR against `dev`. CI must pass. -3. **QA (Checkout Charlie `9b6012d0-0406-417e-bb22-78266a6e7f77`)** reviews the PR. Fail → back to engineer. -4. QA approves and hands off to CTO. -5. **CTO (Savannah Savings `6ec1a5a9-113c-430b-90e6-260d60d79e1d`)** reviews the PR. Fail → back to engineer. -6. **CTO** merges the dev PR. -7. **CI** builds and deploys automatically to Dev (`https://dev.cartsnitch.com`). +3. **Engineer** self-merges after CI passes. +4. **CI** builds and deploys automatically to Dev (`https://dev.cartsnitch.com`). +5. **QA (Checkout Charlie)** reviews the PR. Fail → back to engineer. +6. QA approves and hands off to CTO. +7. **CTO (Savannah Savings)** reviews the PR. Fail → back to engineer. +8. **CTO** merges the dev PR. ### Phase 2 — UAT promotion -8. **CTO** opens and merges a PR from `dev` to `uat`. -9. **CI** builds and deploys automatically to UAT (`https://uat.cartsnitch.com`). -10. **CTO** creates a UAT regression task for **Deal Dottie (`161fb3bb-0332-4381-b67d-7c4b92a91133`)** immediately after promoting. +9. **CTO** opens and merges a PR from `dev` to `uat`. +10. **CI** builds and deploys automatically to UAT (`https://uat.cartsnitch.com`). ### Phase 3 — UAT testing & security -11. **UAT (Deal Dottie `161fb3bb-0332-4381-b67d-7c4b92a91133`)** runs full regression against UAT — every feature, old and new, no exceptions. +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 `d59d4b24-3cc3-4616-a23a-2b4776a489ca`)** 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 `cd91facf-8f4c-4cbd-b8d8-b48da5b50727`)** reviews and merges the production PR (`uat → main`). Fail → back to CTO. +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.com`). ### Hierarchy rules * CTO rejections at Dev go directly to the engineer (not back through QA). -* UAT failures (Deal Dottie `161fb3bb-0332-4381-b67d-7c4b92a91133`) go to CTO — CTO cascades to engineer. -* Security failures (Stockboy Steve `d59d4b24-3cc3-4616-a23a-2b4776a489ca`) go to CTO — CTO cascades to engineer. +* 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. @@ -127,32 +125,7 @@ When creating subtasks for other agents, set `modelProfile: "cheap"` only for: - Basic information lookups - Well-specified, bounded updates -Leave `modelProfile` unset for anything requiring judgment, reasoning, or QA review. - -When in doubt, leave it unset. - -## Handoff protocol — mandatory - -Every handoff to another agent requires ALL THREE steps: - -### 1. Explicit assignment - -`PATCH /api/issues/{id}` with `assigneeAgentId: ""`. 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. +Leave `modelProfile` unset for anything requiring judgment, reasoning, or QA review. When in doubt, leave it unset. ## Infrastructure @@ -160,7 +133,7 @@ Without this release, the receiving agent cannot check out the issue. * **UAT:** namespace `cartsnitch-uat`, FQDN `uat.cartsnitch.com` * **Dev:** namespace `cartsnitch-dev`, FQDN `dev.cartsnitch.com` * **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`. +* **Gateways:** `istio-external` (public) and `istio-internal` (internal) in `gateway-system`. * **Container registry:** `git.farh.net/cartsnitch/` only. ## Authentication @@ -190,14 +163,14 @@ Without this release, the receiving agent cannot check out the issue. 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): +**To force a rollout without a manifest change:** ```bash kubectl rollout restart deployment/ -n ``` ## 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. +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. **Never run `tofu` directly.** Never `kubectl apply` against production. Production changes go through Flux only. The `cartsnitch-dev` and `cartsnitch-uat` namespaces permit direct kubectl use for iteration. @@ -211,14 +184,10 @@ These are the only acceptable choices — alternatives are policy violations: * **Authentication:** Better-Auth + Google + Apple + Authentik (see Authentication section). Never build custom auth. * **Dependency updates:** Mend Renovate. **Dependabot is not used and will not be used.** Do not configure it. * **Container registry:** `git.farh.net/cartsnitch/` — no Docker Hub for first-party images. -* **Browser automation:** the `playwright` MCP server (`http://playwright:8931/mcp`). Never run Playwright locally or install browser binaries. Target dev (`dev.cartsnitch.com`) — never test production. +* **Browser automation:** the `playwright` MCP server (`http://playwright:8931/mcp`). Target dev only — never test production. If a task requires deviating from any of the above, treat it as a destructive action: stop, file an issue with rationale, request board approval. ## 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`). +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 newline at end of file