groombook/org
13
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(sdlc): align SDLC skill with cartsnitch/org structure #7

Merged
Chris Farhood merged 3 commits from loose-sdlc-to-match-privesc into main 2026-05-26 15:32:24 +00:00
Conversation 0 Commits 3 Files Changed 3
+58 -49
3 changed files with 58 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+1 -1
View File
@@ -8,7 +8,7 @@ This is the GroomBook **agent skills repository** — it contains skill definiti
## Skills Overview
- **coding-standards** — Engineering quality bar: priority (correctness > clarity > maintainability > performance > elegance), PR discipline, test requirements, no-hardcoded-values rules, CalVer versioning, `ghcr.io` container registry policy.
- **coding-standards** — Engineering quality bar: priority (correctness > clarity > maintainability > performance > elegance), PR discipline, test requirements, no-hardcoded-values rules, CalVer versioning, `git.farh.net` container registry policy.
- **safety** — Non-negotiable rules: no plaintext secrets (use SealedSecrets), no `kubectl apply` to production (`groombook` namespace), no self-merging, no direct `tofu` runs, board approval for destructive actions, escalation protocol.
- **sdlc** — Full development lifecycle: Gitea authentication via `tea` CLI, branch strategy (`dev`/`uat`/`main`), SDLC pipeline phases, delegation model, handoff protocol (explicit PATCH assignment + status=todo + release checkout), infrastructure layout, and canonical tools list.
skills/coding-standards/SKILL.md
+1 -1
View File
@@ -55,7 +55,7 @@ All releases use CalVer (`YYYY.MMDD.PATCH`, e.g. `2026.0504.0`). No SemVer, no c
## Container images
Push to `ghcr.io` only. Never Docker Hub for first-party images.
Push to `git.farh.net` only. Never Docker Hub for first-party images.
## When uncertain
skills/sdlc/SKILL.md
+56 -47
View File
@@ -4,20 +4,17 @@ description: >
Software development lifecycle for GroomBook. 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, and the canonical tools list.
board-approval gate, the cc-cpfarhood visibility rule,
and delegation model tier policy.
---
# Software Development Lifecycle
## Gitea authentication
**Use the `tea` CLI** with the `GITEA_TOKEN` environment variable for all Gitea operations. Configure it once:
**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.
```bash
tea login add --url https://git.farh.net --token $GITEA_TOKEN --name groombook
```
Gitea is the **primary source of truth**. Every Paperclip issue should have a corresponding Gitea issue (create one if missing). Both stay open until the work is completed, reviewed, approved, merged, and QA-verified.
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
@@ -46,9 +43,9 @@ Three long-lived branches map to the three deployment environments:
| Branch | Environment | Who merges |
|--------|-------------|-----------|
| `dev` | Dev | CTO (after QA review and CTO approval) |
| `uat` | UAT | CTO (after dev merge) |
| `main` | Production | CEO (after UAT and security pass) |
| `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: `<agent-name>/<short-description>`.
@@ -60,22 +57,24 @@ 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 Paperclip.
## PR review & merge policy
### Dev branch (`dev`)
- **QA (Lint Roller `525c2c39-1196-4682-9cd1-0bcfcb0d0f31`)** reviews the PR. Fail → back to engineer directly with exact details. Pass → hand off to CTO.
- **CTO (The Dogfather `c370d244-3c3b-4f21-a403-4cdc9dbdbf96`)** does a final review. Fail → back to engineer. Pass → CTO merges.
- **Engineer** self-merges after CI passes. Dev is for validation, not quality gates.
- **QA (Lint Roller `525c2c39-1196-4682-9cd1-0bcfcb0d0f31`)** reviews the PR. Fail → back to engineer with exact details.
- QA approves and hands off to CTO.
- **CTO (The Dogfather `c370d244-3c3b-4f21-a403-4cdc9dbdbf96`)** reviews the PR. Fail → back to engineer.
- **CTO** merges the dev PR.
### UAT branch (`uat`)
- **CTO (The Dogfather)** opens and merges `dev → uat` after dev merge.
- **CTO** opens and merges a PR from `dev` to `uat`.
- **CI** builds and deploys automatically to UAT (`https://uat.groombook.dev`).
- **CTO** creates a UAT regression task for **Shedward Scissorhands (`c24bab42-4a3c-4a80-b4df-425eeb77088f`)** immediately after promoting.
### Main branch (`main`)
- **Barkley Trimsworth** performs a security review. Pass → assigns task to CEO.
- **CEO (Scrubs McBarkley `3d57c003-f02d-4ab3-b2c3-50a314590bb5`)** merges `uat → main` after confirming UAT + security pass.
- **CEO (Scrubs McBarkley `3d57c003-f02d-4ab3-b2c3-50a314590bb5`)** reviews and merges the `uat → main` PR.
- **CI** deploys automatically to Production (`https://demo.groombook.dev`).
`@cpfarhood` is cc'd for visibility on all PRs — never as a reviewer.
@@ -84,49 +83,57 @@ tea pr create --base dev --title "..." --body "... cc @cpfarhood"
### Phase 1 — Dev
1. **Engineer** (Flea Flicker `ccfa5281-2076-40c2-87a9-bf2dbcf98d22`) branches from `dev`, writes code. GitOps deploys to dev on demand.
1. **Engineer (Flea Flicker `ccfa5281-2076-40c2-87a9-bf2dbcf98d22`)** 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.groombook.dev`).
4. **QA (Lint Roller `525c2c39-1196-4682-9cd1-0bcfcb0d0f31`)** reviews the PR. Fail → back to engineer.
5. QA approves and hands off to CTO.
6. **CTO (The Dogfather `c370d244-3c3b-4f21-a403-4cdc9dbdbf96`)** reviews the PR. Fail → back to engineer.
7. **CTO** merges the dev PR.
5. **QA (Lint Roller)** reviews the PR. Fail → back to engineer.
6. QA approves and hands off to CTO.
7. **CTO (The Dogfather)** reviews the PR. Fail → back to engineer.
8. **CTO** merges the dev PR.
### Phase 2 — UAT promotion
9. **CTO (The Dogfather)** merges `dev → uat` after approving the dev PR.
9. **CTO** opens and merges a PR from `dev` to `uat`.
10. **CI** builds and deploys automatically to UAT (`https://uat.groombook.dev`).
11. **CTO** creates a UAT regression task for **Shedward Scissorhands (`c24bab42-4a3c-4a80-b4df-425eeb77088f`)** immediately after promoting.
### Phase 3 — UAT testing
### Phase 3 — UAT testing & security
12. **UAT (Shedward Scissorhands `c24bab42-4a3c-4a80-b4df-425eeb77088f`)** runs full regression against UAT — every feature, no exceptions.
13. UAT fail → CTO redistributes to engineer (return to Phase 1).
14. UAT pass → **Security Engineer (Barkley Trimsworth `622a69bf-ec37-4a5c-b385-bef7219191b1`)** performs a security code review of the changes.
15. Security fail → CTO redistributes to engineer (return to Phase 1).
11. **UAT (Shedward Scissorhands)** 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 (Barkley Trimsworth `622a69bf-ec37-4a5c-b385-bef7219191b1`)** performs a security code review of the changes.
14. Security fail → CTO redistributes to engineer (return to Phase 1).
### Phase 4 — Production
16. Security pass → **Barkley** assigns the Paperclip task to **CEO (Scrubs McBarkley `3d57c003-f02d-4ab3-b2c3-50a314590bb5`)** who merges `uat → main`.
17. **CI** deploys automatically to Production (`https://demo.groombook.dev`).
15. Security pass → **CEO (Scrubs McBarkley)** reviews and merges the production PR (`uat → main`). Fail → back to CTO.
16. **CI** deploys automatically to Production (`https://demo.groombook.dev`).
### Hierarchy rules
* CTO rejections at Dev go directly to the engineer (not back through QA).
* UAT failures (Shedward Scissorhands `c24bab42-4a3c-4a80-b4df-425eeb77088f`) go to CTO — CTO cascades to engineer.
* Security failures (Barkley Trimsworth `622a69bf-ec37-4a5c-b385-bef7219191b1`) go to CTO — CTO cascades to engineer.
* UAT rejections at Prod go to CTO.
* UAT failures (Shedward Scissorhands) go to CTO — CTO cascades to engineer.
* Security failures (Barkley Trimsworth) go to CTO — CTO cascades to engineer.
* CEO rejections at Prod go to CTO.
> **Penetration testing.** Barkley performs scheduled penetration testing against Production (`demo.groombook.dev`) and Demo independently of the PR workflow. Board-authorized; not triggered per-PR. Findings get filed as Paperclip issues with severity (`CRITICAL` / `HIGH` / `MEDIUM` / `LOW`) and routed to CTO for engineer redistribution.
> **Note on penetration testing:** Barkley Trimsworth performs scheduled penetration testing against Prod independently of the PR workflow. Board-authorized. Not triggered per-PR.
## Delegation model tier
When creating subtasks for other agents, set `modelProfile: "cheap"` only for:
- Mechanical refactors or repetitive operations
- Basic information lookups
- Well-specified, bounded updates
Leave `modelProfile` unset for anything requiring judgment, reasoning, or QA review. When in doubt, leave it unset.
## Infrastructure
* **Production / Demo:** namespace `groombook`, FQDN `demo.groombook.dev`
* **Production:** namespace `groombook`, FQDN `demo.groombook.dev`
* **UAT:** namespace `groombook-uat`, FQDN `uat.groombook.dev`
* **Dev:** namespace `groombook-dev`, FQDN `dev.groombook.dev`
* **Cluster:** Kubernetes — cluster-wide read; read/write on `groombook-dev` and `groombook-uat`; read-only on `groombook` (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/groombook/<service>` only.
## Authentication
@@ -138,14 +145,16 @@ tea pr create --base dev --title "..." --body "... cc @cpfarhood"
## Deployment — 2-stage Flux GitOps
**Stage 1 — CI (Gitea Actions, uses GitHub Actions-compatible YAML syntax, runs in each application repo):**
**Stage 1 — CI (runs in each application repo):**
- Triggered automatically on every merge to `main`
- Builds and tags the Docker image
- Builds and tags the Docker image: CalVer (`YYYY.MM.DD[.N]`), `latest`, and `sha-<hash>`
- Pushes tagged images to `git.farh.net/groombook/<service>`
- Creates a CalVer git tag in the source repo
**Stage 2 — GitOps (Flux, managed externally):**
- Flux watches `groombook/infra` as the **target** GitRepository — it is **not** a Flux bootstrap/cluster repo.
- Flux watches `groombook/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` → `groombook-dev`, `apps/overlays/uat` → `groombook-uat`, `apps/overlays/prod` → `groombook`.
- 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 `groombook/infra`.
@@ -154,16 +163,16 @@ tea pr create --base dev --title "..." --body "... cc @cpfarhood"
2. Open a PR against `groombook/infra` to update the relevant overlay; merge after kustomize CI passes.
3. Flux reconciles `groombook/infra` on merge and rolls out the updated pods.
**To force a rollout** (pick up new `:latest` on stuck 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 configurations via a PR to `groombook/infra` — the tofu controller reconciles them on merge.
Terraform (OpenTofu) is deployed via the **Flux OpenTofu Controller** in a GitOps fashion. Submit Terraform configurations via a PR to `groombook/infra` — the tofu controller reconciles them on merge.
**Never run `tofu` directly.** Never `kubectl apply` against production. Production changes go through Flux only.
**Never run `tofu` directly.** Never `kubectl apply` against production. Production changes go through Flux only. The `groombook-dev` and `groombook-uat` namespaces permit direct kubectl use for iteration.
## Tools (canonical, not alternatives)
@@ -173,12 +182,12 @@ These are the only acceptable choices — alternatives are policy violations:
* **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.**
* **Dependency updates:** Mend Renovate. **Dependabot is not used and will not be used.** Do not configure it.
* **Container registry:** `git.farh.net/groombook/<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, stop and escalate to CTO (or CEO if CTO is the one deviating). Do not request board approval — tool-choice decisions are within CTO's mandate.
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 GroomBook agent team (external users, human reviewers, non-agent entities), include `cc @cpfarhood` for visibility — never as a reviewer.