cartsnitch/org
12
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(skills): mirror groombook sdlc structure, split devops skill

Browse Source 
- sdlc: trim to application-repo scope with Phase 1-5 pipeline; engineer
  self-merges all branches with per-branch prerequisites; move infra,
  Flux, tofu, and operator-install content out
- devops: new skill mirroring groombook/org/skills/devops — owns
  cartsnitch/infra, Flux GitOps, OpenTofu controller, cluster topology,
  Flux Image Tag Automation denied policy
- safety: add Gitea-origin board-approval gate, board-approval scope
  section, and adapterConfig.env read-before-write rule
- coding-standards: replace "no agent merges their own PR" with the
  reviews-required-then-engineer-may-merge rule consistent with sdlc
- CLAUDE.md: update skill index, branch & merge policy, and SDLC phase
  summary to reflect engineer-self-merge and the new devops skill

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chris Farhood
2026-06-09 09:25:58 -04:00
parent d0ff14c155
commit 530ecc74e6
5 changed files with 237 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/sdlc/SKILL.md
+78 -142
View File
@@ -1,122 +1,123 @@
---
name: sdlc
description: >
Software development lifecycle for CartSnitch. Covers Gitea authentication,
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.
Software development lifecycle for CartSnitch application repos. Covers
Gitea authentication, the 3-branch dev/uat/main strategy, the SDLC
pipeline phases 1-5, the Stage 1 CI image build, the authentication
framework, application-tool policy, and delegation model tier policy.
For infrastructure (cartsnitch/infra), see the devops skill.
---
# Software Development Lifecycle
This skill governs **application code repos**. For infrastructure (`cartsnitch/infra`), see the `devops` skill. For PR/test discipline and the `cc @cpfarhood` visibility rule, see `coding-standards`. For non-negotiable safety rules (including the Gitea-origin board-approval gate), see `safety`.
## Gitea authentication
**Use the `GITEA_TOKEN`** environment variable for all Gitea operations. It is already set in the agent environment. Use the **`tea`** CLI for all Gitea/Git operations (e.g., `tea issue list`, `tea pr create`). The token expires when the environment variable is rotated — re-invoke any Gitea operation if you get a 401.
Gitea is the **primary source of truth**. Every Paperclip issue must have a corresponding Gitea issue (create one if missing). Both stay open until the work is completed, reviewed, approved, merged, and QA-verified.
## Gitea-origin issue policy — board approval required
If a task originated from Gitea (`originKind: "gitea"`), **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: Gitea issue",
"summary": "Summarize what the Gitea 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 | Engineer (self-merges after CI passes) |
| `uat` | UAT | QA (merges after code review) |
| `main` | Production | CEO (merges after UAT validation) |
| Branch | Environment | Who merges | Prerequisites for merge |
|--------|-------------|-----------|-----------|
| `dev` | Dev | Engineer | CI passes |
| `uat` | UAT | Engineer | QA code review approval |
| `main` | Production | Engineer | UAT validation, security review, CEO code review |
**Engineers always target `dev`** — never `uat` or `main` directly. Feature branches: `<agent-name>/<short-description>`.
**Engineers always target `dev` first** — 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.
All changes happen via pull request. Gitea branch protection requires CI checks to pass. See `coding-standards` for the no-self-merge contract and the `cc @cpfarhood` visibility rule.
```bash
tea pr create --base dev --title "..." --body "... cc @cpfarhood"
```
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`)
- **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 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.
- **CI** deploys automatically to Production (`https://cartsnitch.com`).
`@cpfarhood` is cc'd for visibility on all PRs — never as a reviewer.
Governance is enforced through Paperclip — Gitea-native review approvals are not required because all agents share the Gitea App identity.
## SDLC pipeline
### Phase 1 — Dev
1. **Engineer** branches from `dev`, writes code. GitOps deploys to dev on demand.
2. **Engineer** opens a PR against `dev`. CI must pass.
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.
1. **Engineer** branches from `dev`, writes code.
2. **Engineer** opens a PR against `dev`.
3. **CI** fail → back to **Engineer**.
4. **CI** pass → **Engineer** merges PR.
5. **CI** builds and deploys automatically to Dev (`https://dev.cartsnitch.com`).
### Phase 2 — UAT promotion
9. **CTO** opens and merges a PR from `dev` to `uat`.
10. **CI** builds and deploys automatically to UAT (`https://uat.cartsnitch.com`).
1. **Engineer** opens a PR from `dev` to `uat`.
2. **CI** fail → back to **Engineer** (return to Phase 1).
3. **CI** pass → **QA (Checkout Charlie `9b6012d0-0406-417e-bb22-78266a6e7f77`)** performs code review.
4. **QA** rejected → back to **Engineer** (return to Phase 1).
5. **QA** approved → **Engineer** merges PR.
6. **CI** builds and deploys automatically to UAT (`https://uat.cartsnitch.com`).
### Phase 3 — UAT testing & security
### Phase 3 — User Testing & Security Review
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).
1. **UAT (Deal Dottie `161fb3bb-0332-4381-b67d-7c4b92a91133`)** runs full regression against UAT — every feature, old and new, no exceptions.
2. **UAT** fail → back to **Engineer** (return to Phase 1).
3. **UAT** pass → **Security Engineer (Stockboy Steve `d59d4b24-3cc3-4616-a23a-2b4776a489ca`)** performs a security code review of the changes.
4. **Security** fail → back to **Engineer** (return to Phase 1).
5. **Security** pass → Begin Phase 4.
### Phase 4 — Production
> **Note on penetration testing:** Stockboy Steve performs scheduled penetration testing against Production independently of the PR workflow. Board-authorized. Not triggered per-PR.
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`).
### Phase 4 — Production Promotion
1. **Engineer** opens a PR from `uat` to `main`.
2. **CI** fail → back to **Engineer** (return to Phase 1).
3. **CI** pass → **CEO (Coupon Carl `cd91facf-8f4c-4cbd-b8d8-b48da5b50727`)** performs code review.
4. **CEO** rejected → back to **Engineer** (return to Phase 1).
5. **CEO** approved → **Engineer** merges PR.
6. **CI** fail → back to **Engineer** (return to Phase 1).
7. **CI** pass → Begin Phase 5.
### Phase 5 — Production Deployment
The **Engineer** opens a PR against `cartsnitch/infra` to update the relevant Kustomize overlay with the new image tag. From this point the work follows the **`devops` skill pipeline** end-to-end — review, merge, and Flux reconciliation are all owned there. On merge, Flux rolls out the updated pods to production (`https://cartsnitch.com`).
### 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.
* Failures at any phase return to the engineer.
* **CTO (Savannah Savings `6ec1a5a9-113c-430b-90e6-260d60d79e1d`)** is the escalation target for ambiguous returns and re-distribution when an engineer is unavailable or disputes a return.
* UAT failures (Deal Dottie) and security failures (Stockboy Steve) cascade through the CTO when re-distribution is needed.
* CEO rejections at Prod cascade through the CTO.
> **Note on penetration testing:** Stockboy Steve performs scheduled penetration testing against Prod independently of the PR workflow. Board-authorized. Not triggered per-PR.
## Stage 1 CI — Image build
Triggered automatically on every merge to `main` in an application repo:
- Builds and tags the Docker image: CalVer (`YYYY.MM.DD[.N]`), `latest`, and `sha-<hash>`
- Pushes tagged images to `git.farh.net/cartsnitch/<service>` (see `coding-standards` for the registry and CalVer policy)
- Creates a CalVer git tag in the source repo
Stage 2 (Flux GitOps deployment) is owned by `devops`.
## Authentication
* **Framework:** Better-Auth.
* **OAuth Providers:** Google and Apple.
* **SSO:** Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret).
* **Never build custom authentication.**
## Application tools (canonical, not alternatives)
These are application-level dependency choices. Alternatives are policy violations:
* **Database:** CloudNativePG-managed Postgres — no SQLite, MariaDB, or MySQL.
* **Cache / pub-sub:** DragonflyDB — no Redis.
* **Authentication:** Better-Auth + Google + Apple + Authentik (see Authentication above).
* **Dependency updates:** Mend Renovate. **Dependabot is not used and will not be used.** Do not configure it.
* **Browser automation:** the `playwright` MCP server (`http://playwright:8931/mcp`). Target dev only — never test production.
For the container registry, CalVer versioning, and general PR/test discipline, see `coding-standards`. For the operator install side (CNPG, Dragonfly, Sealed Secrets), see `devops`.
## Delegation model tier
@@ -126,68 +127,3 @@ When creating subtasks for other agents, set `modelProfile: "cheap"` only for:
- Well-specified, bounded updates
Leave `modelProfile` unset for anything requiring judgment, reasoning, or QA review. When in doubt, leave it unset.
## Infrastructure
* **Production:** namespace `cartsnitch`, FQDN `cartsnitch.com`
* **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` (public) and `istio-internal` (internal) in `gateway-system`.
* **Container registry:** `git.farh.net/cartsnitch/<service>` only.
## Authentication
* **Framework:** Better-Auth.
* **Social login:** Google and Apple OAuth.
* **SSO:** Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret).
* **Never build custom authentication.**
## Deployment — 2-stage Flux GitOps
**Stage 1 — CI (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 `git.farh.net/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:**
```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.
**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.
## Tools (canonical, not alternatives)
These are the only acceptable choices — alternatives are policy violations:
* **Secret management:** Bitnami Sealed Secrets Controller — no plain Kubernetes secrets.
* **Database:** CloudNativePG Operator (Postgres) — no SQLite, MariaDB, or MySQL.
* **Cache / pub-sub:** DragonflyDB Operator — no Redis.
* **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/<service>` — no Docker Hub for first-party images.
* **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.