diff --git a/skills/sdlc/SKILL.md b/skills/sdlc/SKILL.md index 124ffba..8996c2f 100644 --- a/skills/sdlc/SKILL.md +++ b/skills/sdlc/SKILL.md @@ -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 @@ -48,7 +45,7 @@ Three long-lived branches map to the three deployment environments: |--------|-------------|-----------| | `dev` | Dev | Engineer (self-merges after CI passes) | | `uat` | UAT | QA (merges after code review) | -| `main` | Production | UAT (validates browser, then merges) | +| `main` | Production | CEO (merges after UAT validation) | **Engineers always target `dev`** — never `uat` or `main` directly. Feature branches: `/`. @@ -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`) - -- **Engineer** self-merges after CI passes. No review required. Dev is for validation, not quality gates. -- **QA (Lint Roller `525c2c39-1196-4682-9cd1-0bcfcb0d0f31`)** reviews the PR. Fail → back to engineer directly with exact details. +- **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`) - -- **QA (Lint Roller)** merges `dev → uat` after approval. +- **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`) - -- **UAT (Shedward Scissorhands `c24bab42-4a3c-4a80-b4df-425eeb77088f`)** validates the deployed application via Playwright browser testing. -- **UAT** merges `uat → main` after validation passes. +- **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,50 +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`). -5. **QA (Lint Roller `525c2c39-1196-4682-9cd1-0bcfcb0d0f31`)** reviews the PR. Fail → back to engineer. +5. **QA (Lint Roller)** reviews the PR. Fail → back to engineer. 6. QA approves and hands off to CTO. -7. **CTO (The Dogfather `c370d244-3c3b-4f21-a403-4cdc9dbdbf96`)** reviews the PR. Fail → back to engineer. +7. **CTO (The Dogfather)** reviews the PR. Fail → back to engineer. 8. **CTO** merges the dev PR. ### Phase 2 — UAT promotion -9. **QA (Lint Roller)** merges `dev → uat` after CTO approval. +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 → **UAT (Shedward Scissorhands)** 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:** `ghcr.io/groombook/` only. ## Authentication @@ -139,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-` - Pushes tagged images to `ghcr.io/groombook/` +- 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`. @@ -155,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/ -n ``` ## 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) @@ -174,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:** `ghcr.io/groombook/` — 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 GroomBook agent team (external users, human reviewers, non-agent entities), include `cc @cpfarhood` for visibility — never as a reviewer. -