|
|
|
@@ -1,193 +1,144 @@
|
|
|
|
|
---
|
|
|
|
|
name: sdlc
|
|
|
|
|
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, the cc-cpfarhood visibility rule,
|
|
|
|
|
and delegation model tier policy.
|
|
|
|
|
Software development lifecycle for GroomBook application repos. Covers
|
|
|
|
|
Gitea authentication, the 3-branch dev/uat/main strategy, the SDLC
|
|
|
|
|
pipeline phases 1-5, the uat→main merge-gate policy (engineer
|
|
|
|
|
self-merge when pre-gates are green; CTO Gitea Approve only for
|
|
|
|
|
novel auth, infra/prod-affecting, and risk-flagged merges),
|
|
|
|
|
the Stage 1 CI image build, the authentication framework, and
|
|
|
|
|
application-tool policy. For infrastructure (groombook/infra), see
|
|
|
|
|
the devops skill.
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Software Development Lifecycle
|
|
|
|
|
|
|
|
|
|
This skill governs **application code repos**. For infrastructure (`groombook/infra`), see the `devops` skill. For PR/test discipline and the `cc @cpfarhood` visibility rule, see `coding-standards`. For non-negotiable safety rules, see `safety`. The **uat→main merge-gate policy** (which uat→main PRs need a CTO Gitea Approve click vs. engineer self-merge) is defined in this skill — see "uat→main merge-gate policy" below.
|
|
|
|
|
|
|
|
|
|
## 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, and the uat→main merge-gate policy (below) |
|
|
|
|
|
|
|
|
|
|
**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.
|
|
|
|
|
|
|
|
|
|
## PR review & merge policy
|
|
|
|
|
|
|
|
|
|
### Dev branch (`dev`)
|
|
|
|
|
- **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** 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`)
|
|
|
|
|
- **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.
|
|
|
|
|
|
|
|
|
|
## SDLC pipeline
|
|
|
|
|
|
|
|
|
|
### Phase 1 — Dev
|
|
|
|
|
|
|
|
|
|
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)** 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.
|
|
|
|
|
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.groombook.dev`).
|
|
|
|
|
|
|
|
|
|
### 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.groombook.dev`).
|
|
|
|
|
1. **Engineer** opens a PR from `dev` to `uat`.
|
|
|
|
|
2. **CI** fail → back to **Engineer** (return to Phase 1).
|
|
|
|
|
3. **CI** pass → **QA** 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.groombook.dev`).
|
|
|
|
|
|
|
|
|
|
### Phase 3 — UAT testing & security
|
|
|
|
|
### Phase 3 — User Testing & Security Review
|
|
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
1. **UAT (Shedward Scissorhands)** 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** 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
|
|
|
|
|
### Phase 4 — Production Promotion
|
|
|
|
|
|
|
|
|
|
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`).
|
|
|
|
|
1. **Engineer** opens a PR from `uat` to `main`.
|
|
|
|
|
2. **CI** fail → back to **Engineer** (return to Phase 1).
|
|
|
|
|
3. **CI** pass → **Engineer** classifies the PR against the **uat→main merge-gate policy** (below):
|
|
|
|
|
* **In a category that requires CTO Gitea Approve** (novel auth / session paths, infra / prod-affecting merges, `risk:cto-approve` label or explicit CTO/CEO sign-off request) → Engineer pings the CTO for a Gitea Approve click.
|
|
|
|
|
* **CTO** rejected → back to **Engineer** (return to Phase 1).
|
|
|
|
|
* **CTO** approved → continue to step 4.
|
|
|
|
|
* **Outside all three categories** → no CTO click needed; jump to step 4 once the four pre-gates (QA, UAT deploy, UAT regression, security) are green.
|
|
|
|
|
4. **Engineer** merges the PR.
|
|
|
|
|
5. **CI** fail → back to **Engineer** (return to Phase 1).
|
|
|
|
|
6. **CI** pass → Begin Phase 5.
|
|
|
|
|
|
|
|
|
|
### Hierarchy rules
|
|
|
|
|
### Phase 5 — Production Deployment
|
|
|
|
|
|
|
|
|
|
* CTO rejections at Dev go directly to the engineer (not back through QA).
|
|
|
|
|
* 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.
|
|
|
|
|
The **Engineer** opens a PR against `groombook/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://demo.groombook.dev`).
|
|
|
|
|
|
|
|
|
|
> **Note on penetration testing:** Barkley Trimsworth performs scheduled penetration testing against Prod independently of the PR workflow. Board-authorized. Not triggered per-PR.
|
|
|
|
|
## uat→main merge-gate policy
|
|
|
|
|
|
|
|
|
|
## Delegation model tier
|
|
|
|
|
This is the process policy that governs which `uat → main` PRs need a CTO Gitea Approve click vs. engineer self-merge. It exists because the Gitea `required_approvals` branch-protection gate is satisfied only by a Gitea Approve click — the Paperclip issue-thread QA/UAT-deploy/UAT-regression/security approvals do **not** clear it. The engineer **MUST** classify every `uat → main` PR against this policy before merging.
|
|
|
|
|
|
|
|
|
|
When creating subtasks for other agents, set `modelProfile: "cheap"` only for:
|
|
|
|
|
- Mechanical refactors or repetitive operations
|
|
|
|
|
- Basic information lookups
|
|
|
|
|
- Well-specified, bounded updates
|
|
|
|
|
### The four pre-gates are unchanged
|
|
|
|
|
|
|
|
|
|
Leave `modelProfile` unset for anything requiring judgment, reasoning, or QA review. When in doubt, leave it unset.
|
|
|
|
|
A `uat → main` PR is mergeable only when all of these are green on the linked Paperclip issue: QA code review, UAT deploy, UAT regression, and security review. The CTO Gitea Approve click is **in addition to** those four when the PR falls in one of the categories below; it does not replace any of them.
|
|
|
|
|
|
|
|
|
|
## Infrastructure
|
|
|
|
|
### Categories that require CTO Gitea Approve
|
|
|
|
|
|
|
|
|
|
* **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` (public) and `istio-internal` (internal) in `gateway-system`.
|
|
|
|
|
* **Container registry:** `git.farh.net/groombook/<service>` only.
|
|
|
|
|
A CTO Gitea Approve click is required only for PRs in one of the following three categories:
|
|
|
|
|
|
|
|
|
|
1. **Novel auth / session paths.** Login, OIDC, OOBE, session middleware, token issuance, password reset, MFA, or any new auth provider integration. Routine changes to auth-gated UI (button styling, error messages, form layout, copy edits) are **not** in this category.
|
|
|
|
|
2. **Infra / prod-affecting merges.** Deploys, infra manifests, secrets, GitOps overlays, CI/CD, `main` branch protection, prod-affecting routing/ingress, or any change that mutates prod state. **All Phase 5 infra overlay PRs in `groombook/infra` require CTO Gitea Approve without exception.**
|
|
|
|
|
3. **Risk-flagged merges.** The PR carries the `risk:cto-approve` label, **or** the PR or its linked Paperclip issue thread contains an explicit CTO/CEO sign-off request.
|
|
|
|
|
|
|
|
|
|
### Engineer workflow
|
|
|
|
|
|
|
|
|
|
The engineer who opened the PR classifies it against the three categories above (escalating to the CTO via comment if the call is unclear), then:
|
|
|
|
|
|
|
|
|
|
* **In a category** → request a CTO Gitea Approve click. Engineer merges once the CTO has approved.
|
|
|
|
|
* **Outside all three categories** → no CTO click needed. Engineer merges once the four pre-gates are green.
|
|
|
|
|
|
|
|
|
|
**Board/CEO approval is via SDLC code review (judgment) on the Paperclip issue, not via a Gitea Approve click.** The CEO's role at Phase 4 is to perform the code review on the Paperclip issue thread; that approval satisfies the "CEO approved" pre-condition and is recorded in Paperclip, not in Gitea.
|
|
|
|
|
|
|
|
|
|
### When uncertain
|
|
|
|
|
|
|
|
|
|
If a `uat → main` PR does not obviously belong to a category, comment on the PR with `@<the-dogfather>` (or escalate to the CEO if the CTO is unavailable) and pause the merge. Do not guess the category — a routine PR is a routine PR, but a borderline PR is cheaper to escalate than to misclassify.
|
|
|
|
|
|
|
|
|
|
## 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/groombook/<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.
|
|
|
|
|
* **Social login:** Google and Apple OAuth.
|
|
|
|
|
* **OAuth Providers:** GroomBook (Authentik), Google, and Apple.
|
|
|
|
|
* **SSO:** Authentik OIDC at `https://auth.farh.net` (credentials in `authentik-credentials` secret).
|
|
|
|
|
* **Never build custom authentication.**
|
|
|
|
|
|
|
|
|
|
## Deployment — 2-stage Flux GitOps
|
|
|
|
|
## Application tools (canonical, not alternatives)
|
|
|
|
|
|
|
|
|
|
**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/groombook/<service>`
|
|
|
|
|
- Creates a CalVer git tag in the source repo
|
|
|
|
|
These are application-level dependency choices. Alternatives are policy violations:
|
|
|
|
|
|
|
|
|
|
**Stage 2 — GitOps (Flux, managed externally):**
|
|
|
|
|
- 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`.
|
|
|
|
|
|
|
|
|
|
**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 `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 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 `groombook/infra` — the tofu controller reconciles them on merge.
|
|
|
|
|
|
|
|
|
|
**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)
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
* **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.
|
|
|
|
|
* **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, 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.
|
|
|
|
|
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`.
|
|
|
|
|
Flea Flicker
Chris Farhood
Flea Flicker
Scrubs McBarkley
The Dogfather