diff --git a/skills/coding-standards/SKILL.md b/skills/coding-standards/SKILL.md new file mode 100644 index 0000000..28449c6 --- /dev/null +++ b/skills/coding-standards/SKILL.md @@ -0,0 +1,62 @@ +--- +name: coding-standards +description: > + Engineering quality bar for GroomBook code: priority ordering of correctness + vs. clarity vs. maintainability vs. performance vs. elegance, PR and test + requirements, no-hardcoded-values rules, branch discipline, and the no-self- + merge contract. +--- + +# Coding Standards + +These rules apply to any GroomBook agent that writes, reviews, or merges code. + +## Priority ordering + +When making technical decisions, prioritize in this order: + +1. **Correctness** — does it work? Does it handle edge cases? Have you proven it, not assumed it? +2. **Clarity** — will another engineer understand this without context in 6 months? +3. **Maintainability** — will it be safe to change? +4. **Performance** — fast enough for the use case? Profile before optimizing. +5. **Elegance** — nice if free; never trade any of the above for it. + +## Pull request discipline + +* All changes go through a PR. **Never push directly to `dev`, `uat`, or `main`.** +* No agent merges their own PR. +* Always include `cc @cpfarhood` at the bottom of the PR body for visibility (not as a reviewer). + +## Test requirements + +* **Every PR must include tests** for new code paths. No exceptions for "small" changes. +* Run unit tests, type check, and lint locally (or rely on CI) **before** requesting review. +* A PR without passing tests does not get approval. +* New code paths require coverage. No coverage = no approval. + +## Code review tone + +Hold a high bar. PRs with obvious mistakes, missing tests, hardcoded values, or policy violations get firm, specific review comments citing what's wrong and what the fix is. Cite the file and line. Suggest the fix when you know it. Don't sugarcoat — but be professional and constructive. "This looks wrong" is not a review comment. + +## Hardcoded values + +* **Colors** use CSS variables / theme tokens. Never raw hex in components. +* **Strings** use constants or i18n. No magic strings. +* **Numbers** that aren't trivially obvious go in named constants. +* **No magic numbers** in business logic. + +## Secrets in code + +Secrets never touch source. See the `safety` skill for the SealedSecrets workflow. If your implementation requires a Kubernetes secret you cannot create, file an issue for the agent who owns the SealedSecrets workflow rather than committing a plaintext value. + +## Releases and versioning + +All releases use SemVer. No CalVer, no custom schemes. + +## Container images + +Push to `ghcr.io` only. Never Docker Hub for first-party images. + +## When uncertain + +If a code-quality call isn't covered above and you can't decide cleanly, escalate to the CTO via comment rather than guessing. diff --git a/skills/safety/SKILL.md b/skills/safety/SKILL.md new file mode 100644 index 0000000..0be7115 --- /dev/null +++ b/skills/safety/SKILL.md @@ -0,0 +1,38 @@ +--- +name: safety +description: > + Non-negotiable safety rules for all GroomBook agents. Covers secret handling, + destructive-action gating, the SealedSecrets workflow, the tools we use vs. + the ones we don't, and the escalation protocol when an action's safety is + uncertain. +--- + +# Safety + +The following rules apply to every GroomBook agent without exception. + +## Non-negotiable rules + +* **Never exfiltrate secrets or private data.** This includes API keys, tokens, PEM files, database credentials, kubeconfig contents, and any value sourced from a secret reference in your adapter config. Never log, comment, or return these values in any output — including PR descriptions, issue comments, and chat responses. + +* **Seek board approval before destructive actions.** "Destructive" means: deleting resources, dropping tables, wiping namespaces, force-pushing branches, resetting git history, removing secrets, or any operation that cannot be undone without restoring from backup. Use `request_board_approval` and set the source issue to `blocked` until approved. + +* **Never commit plaintext secrets.** Kubernetes secrets go through Bitnami Sealed Secrets (`kubeseal`). Application credentials go in environment variables injected at runtime — never hardcoded in source. + +* **Never use `kubectl create secret` in production.** The `groombook` and `groombook-uat` namespaces are Flux-managed. Secret changes go through the SealedSecrets workflow, committed to `groombook/infra`. The `groombook-dev` namespace permits direct kubectl use for iteration but secrets there should also follow the same pattern when they reflect anything sensitive. + +* **Never bypass the merge gate.** No self-merging PRs. No pushing directly to `dev`, `uat`, or `main`. Every change goes through a PR with the reviews required by the `sdlc` skill. + +## Tools (canonical, not alternatives) + +* **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. +* **Dependency updates:** Mend Renovate — no Dependabot. +* **Container registry:** `ghcr.io` — no Docker Hub for first-party images. + +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. + +## If you are unsure + +If you are unsure whether an action is safe, **stop**. Post a comment on the Paperclip issue explaining what you are about to do and why you are uncertain, set the issue to `blocked`, and escalate to your manager. Do not guess. diff --git a/skills/sdlc/SKILL.md b/skills/sdlc/SKILL.md new file mode 100644 index 0000000..37d9ae4 --- /dev/null +++ b/skills/sdlc/SKILL.md @@ -0,0 +1,155 @@ +--- +name: sdlc +description: > + Software development lifecycle for GroomBook. Covers GitHub authentication, + branch strategy across Dev/UAT/Prod, PR review and merge policy, the SDLC + pipeline and stage handoffs, status semantics, infrastructure layout, the + GitHub-origin issue board-approval gate, and the cc-cpfarhood visibility + rule. +--- + +# Software Development Lifecycle + +## GitHub authentication + +**Invoke the `github-app-token` skill** before any GitHub operation. It generates a short-lived installation token and sets `GH_TOKEN`. **Never** run `gh auth login` — it hangs headless agents. Token expires after ~1 hour; re-invoke to regenerate. + +## GitHub-origin issue policy — board approval required + +If a task originated from GitHub (`originKind: "github"`), **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: GitHub issue", + "summary": "Summarize what the GitHub 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 | CTO (after QA + CTO approval) | +| `uat` | UAT | CTO (promotes `dev` → `uat`) | +| `main` | Production | CEO (promotes `uat` → `main`) | + +**Engineers always target `dev`** — never `uat` or `main` directly. + +## 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. + +```bash +gh pr create --title "..." --body "... cc @cpfarhood" +``` + +## PR review & merge policy + +### Dev branch (`dev`) + +Requires **2 approving GitHub reviews** before merge: + +1. **QA** (Lint Roller) — code review, CI signal, test coverage +2. **CTO** (The Dogfather) — architecture, security, correctness + +CTO review requires QA approval as a precondition. + +### UAT branch (`uat`) + +Requires **1 approving GitHub review** before merge: + +* **CTO** (The Dogfather) — promotes `dev` → `uat` + +### Main branch (`main`) + +Requires **1 approving GitHub review** before merge: + +* **CEO** (Scrubs McBarkley) — promotes `uat` → `main` + +`@cpfarhood` is cc'd for visibility on all PRs — never as a reviewer. + +## Pipeline + +``` +Dev stage: Engineer → QA Review → CTO Review → CTO merges PR to dev → [auto deploy Dev] +UAT stage: CTO opens dev→uat PR → Shedward (regression) → Barkley (security) → CEO assigned +Prod stage: CEO merges uat→main PR → [auto deploy Production] +``` + +### Dev stage + +1. Engineer creates a PR targeting `dev`, hands off to QA (Lint Roller) with `status: "todo"`. +2. QA reviews code and CI. Pass → hand to CTO. Fail → hand back to engineer directly with exact failure details. +3. CTO reviews. Approve → merge PR into `dev` (auto-deploys to Dev). Deny → hand back to engineer. + +### UAT stage + +4. CTO opens a PR from `dev` → `uat` to promote the change, assigns Shedward Scissorhands for regression: `status: "todo"`. +5. Shedward runs UAT in `uat.groombook.dev`. Pass → reports to CTO. Fail → reports to CTO (CTO cascades to engineer). +6. CTO assigns Barkley Trimsworth for security review: `status: "todo"`. +7. Barkley reviews. Pass → CTO assigns to CEO. Fail → CTO cascades to engineer. + +### Prod stage + +8. CEO reviews and merges the `uat` → `main` PR → auto-deploys to Production. +9. CEO rejects → returns to CTO → engineer. + +### Hierarchy rules + +* CTO rejections go directly to the engineer (not through QA). +* Shedward UAT failures go to CTO (not directly to the engineer). +* Barkley security failures go to CTO. +* CEO rejections go to CTO. + +## Handoff protocol — mandatory + +Every handoff to another agent requires ALL THREE steps: + +### 1. Explicit assignment + +PATCH the issue 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` for handoffs — it doesn't surface in the receiver's inbox. + +### 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. + +## Infrastructure + +* **Production / Demo:** namespace `groombook`, FQDN `demo.groombook.dev` +* **UAT:** namespace `groombook-uat`, FQDN `uat.groombook.dev` +* **Dev:** namespace `groombook-dev`, FQDN `dev.groombook.dev` +* **Auth:** Better-Auth + OAuth2 via Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret) +* **Cluster:** Kubernetes — cluster-wide read; read/write on `groombook-dev` and `groombook-uat`. +* **Gateways:** `istio-external` and `istio-internal` in `gateway-system`. +* **Deployment:** 2-stage Flux GitOps — CI builds images → updates tags in `groombook/infra` → Flux applies. Never `kubectl apply` for app manifests. No Flux Image Automation. +* **Infra provisioning:** Commit OpenTofu HCL to `groombook/infra`. Never run `tofu` directly. +* **Dependency updates:** Mend Renovate only. Never Dependabot. + +## 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. + +## No self-merge + +No agent merges their own PR. The merger is always the next role up the SDLC ladder (CTO for `dev`/`uat`, CEO for `main`).