From e9a77895d6551d6b8a637bcc3460b6cf8446403c Mon Sep 17 00:00:00 2001 From: Flea Flicker Date: Fri, 12 Jun 2026 16:27:32 +0000 Subject: [PATCH] docs: add AGENTS.md and CONTRIBUTING.md (GRO-2381) Point at the authoritative groombook/org skills (sdlc, coding-standards, safety) and document the phase-by-phase PR flow + uat->main merge-gate policy summary. Whitelist reminder for main branch protection: engineer team only. cc @cpfarhood Co-Authored-By: Paperclip --- AGENTS.md | 54 ++++++++++++++++++++++ CONTRIBUTING.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c9ae143 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,54 @@ +# AGENTS.md + +This repository (`groombook/api`) is part of the GroomBook application stack. The +authoritative process, quality bar, and safety rules live in the shared +[`groombook/org`](https://git.farh.net/groombook/org) skills repository. Read +those first; this file is only a pointer. + +## Authoritative skills + +- **SDLC (branching, PRs, phases, handoffs):** + [`groombook/org/skills/sdlc/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/sdlc/SKILL.md) +- **Coding standards (priority ordering, PR discipline, tests, no-hardcoded-values, CalVer):** + [`groombook/org/skills/coding-standards/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/coding-standards/SKILL.md) +- **Safety (no plaintext secrets, no direct `kubectl apply` to `groombook`, no self-merge, board approval for destructive actions):** + [`groombook/org/skills/safety/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/safety/SKILL.md) + +For human contributors and humans reviewing agent work, see +[`CONTRIBUTING.md`](./CONTRIBUTING.md) in this repo for the phase-by-phase PR +flow and the `uat→main` merge-gate policy summary. + +## Non-negotiable operational rules + +These mirror the org skills; they are restated here so any agent landing in +this repo sees them without a cross-repo fetch. + +- **All changes go through a PR.** Never push directly to `dev`, `uat`, or `main`. +- **Branch strategy:** `feature/` → `dev` → `uat` → `main`. Engineers + always target `dev` first. +- **No self-merge contract.** The engineer who opened a PR clicks merge only + after the named reviewer (CI / QA / UAT / Security / CTO per phase) + approves. Issue-thread QA / UAT / security approvals do **not** clear the + Gitea `required_approvals` gate on `uat→main` — only a Gitea **Approve** + click from a member of the `approvals_whitelist_username` does. On this + repo that whitelist is `["gb_flea", "gb_dogfather"]` (engineer team). + Board-level accounts cannot give the Approve click by policy. +- **Always include `cc @cpfarhood`** at the bottom of every PR body for + board visibility (not as a reviewer). +- **Secrets in code are forbidden.** Use Bitnami Sealed Secrets; never commit + plaintext. See the `safety` skill. +- **Production (`groombook` namespace) is Flux-managed.** Never + `kubectl apply` directly. Infrastructure changes go through PRs in + `groombook/infra`. + +## Local development + +See the repo's own README, package scripts, and CI workflow. The +authoritative pipeline (Gitea Actions, image build, deploy hooks) is the +shared `groombook/infra` overlay; do not reimplement it here. + +## When uncertain + +If a task conflicts with the org skills, **the org skills win**. Open an +issue in `groombook/org` to propose a change rather than encoding a local +exception. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..64a918a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,117 @@ +# Contributing to `groombook/api` + +Thanks for contributing. This document is the human-facing companion to +[`AGENTS.md`](./AGENTS.md) and the authoritative +[`groombook/org`](https://git.farh.net/groombook/org) skills. The org skills +govern; this file is a quick-reference for the human/agent PR flow in this +repo. + +## Branch strategy + +Three long-lived branches; one PR per promotion step. + +| Branch | Environment | Who merges | Prerequisites for merge | +|---------|-------------|-----------|-------------------------| +| `dev` | Dev | Engineer | CI passes | +| `uat` | UAT | Engineer | QA code review approval | +| `main` | Production | Engineer | UAT validation + CTO Gitea Approve when the `uat→main` merge-gate policy applies (see below) | + +Engineers always target `dev` first. Feature branches: `/`. + +## Phase-by-phase PR flow + +### Phase 1 — Dev + +1. Branch from `dev`: `git checkout -b / origin/dev`. +2. Write code + tests. Run unit tests, type check, and lint locally (or rely on CI). +3. Open a PR against `dev`: + ```bash + tea pr create --base dev --title "..." --body "..." + ``` + Include `cc @cpfarhood` at the bottom of the body for board visibility. +4. CI must pass. CI green → engineer self-merges. +5. CI builds and deploys to Dev automatically. + +### Phase 2 — UAT promotion + +1. Open a PR from `dev` to `uat`. +2. CI must pass. +3. **QA (Lint Roller)** reviews and approves on the Gitea PR. +4. QA approved → engineer self-merges. +5. CI builds and deploys to UAT automatically. + +### Phase 3 — UAT regression + Security review + +1. **UAT (Shedward Scissorhands)** runs full regression against UAT — every + feature, old and new, no exceptions. +2. **Security (Barkley Trimsworth)** reviews the changes. +3. Failures in either gate bounce back to Phase 1. + +### Phase 4 — Production promotion (`uat → main`) + +This is the gate the org PR +[`groombook/org#13`](https://git.farh.net/groombook/org/pulls/13) defines. +The full rule is in +[`groombook/org/skills/sdlc/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/sdlc/SKILL.md) +and +[`groombook/org/skills/coding-standards/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/coding-standards/SKILL.md); +the summary is below. + +**The CTO Gitea Approve click is NOT the default gate.** Once the four +pre-gates (QA, UAT deploy, UAT regression, security) are green, the engineer +self-merges. + +**A CTO Gitea Approve click IS required** only for PRs in one of three +categories: + +1. **Novel auth / session paths** — login, OIDC, OOBE, session middleware, + token issuance, password reset, MFA, new auth provider integrations. + Routine auth-gated UI (button styling, error messages, form layout) is + **not** in this category. +2. **Infra / prod-affecting merges** — deploys, infra manifests, secrets, + GitOps overlays, CI/CD, `main` branch protection, production + routing/ingress, prod state mutations. All Phase 5 infra overlay PRs in + `groombook/infra` require CTO Gitea Approve without exception. +3. **Risk-flagged merges** — `risk:cto-approve` label, or explicit CTO/CEO + sign-off request in the PR or issue thread. + +The engineer opens the `uat→main` PR, classifies it against the three +categories above, and adds `cc @cpfarhood`. If the PR is in scope, the CTO +clicks Approve; once approved (and the four pre-gates are green), the +engineer merges. + +### Phase 5 — Production deployment + +A separate PR in `groombook/infra` bumps the overlay image tag for prod. +Handed to QA (Lint Roller) for review, then self-merged by the engineer. + +## The four pre-gates (uat→main) + +A `uat→main` PR is mergeable when **all four** are green: + +1. **QA code review** — done on the dev→uat promotion PR. +2. **UAT deploy** — the UAT image built from the uat tip is live in UAT. +3. **UAT regression** — Shedward's full-feature UAT pass is green (no + pre-existing defects, no new defects). +4. **Security review** — Barkley's security code review is green. + +Issue-thread QA / UAT / security approvals do **not** clear the Gitea +`required_approvals` gate. Only a Gitea **Approve** click from a member of +the `approvals_whitelist_username` for `main` clears it. In this repo that +whitelist is the engineer team (`gb_flea`, `gb_dogfather`). + +## Style, tests, and quality bar + +See +[`groombook/org/skills/coding-standards/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/coding-standards/SKILL.md) +for the engineering priority ordering, test requirements, no-hardcoded-values +rules, CalVer versioning policy, and the `git.farh.net` container registry +policy. + +## Safety + +See +[`groombook/org/skills/safety/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/safety/SKILL.md) +for the non-negotiable rules: no plaintext secrets, no `kubectl apply` to +`groombook`, no self-merge, no direct `tofu` runs, board approval for +destructive actions, escalation protocol.