From 63e150f445fd8d72baa6251cc93a161853332603 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Fri, 22 May 2026 21:16:38 -0400 Subject: [PATCH] refactor(sdlc): migrate from GitHub to Gitea with tea CLI - Replace github-app-token skill with GITEA_TOKEN env var and tea CLI - Update all GitHub references to Gitea (auth, issues, PRs, origin policy) - Add CLAUDE.md with org-level guidance for future Claude Code sessions Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 62 ++++++++++++++++++++++++++++++++++++++++++++ skills/sdlc/SKILL.md | 24 ++++++++--------- 2 files changed, 74 insertions(+), 12 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0dd7a16 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,62 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Purpose + +This is the **CartSnitch org-level governance repository** — it contains operational policies and skill definitions for AI agents that develop and maintain the CartSnitch e-commerce platform. It is **not an application codebase**; there is nothing to build or test here. All policy lives in `skills/`: +- `skills/sdlc/` — Software development lifecycle, branch strategy, deployment via Flux GitOps, infrastructure layout +- `skills/safety/` — Non-negotiable rules: secret handling, SealedSecrets workflow, kubectl scope limits, destructive-action gating +- `skills/coding-standards/` — Engineering quality bar, priority ordering, test requirements, task decomposition template + +## Key Operational Procedures + +### Gitea authentication +Use the `GITEA_TOKEN` environment variable (already set in the agent environment). Use the **`tea`** CLI for all Gitea/Git operations (e.g., `tea issue list`, `tea pr create`). Re-invoke on 401. + +### Handoff protocol (mandatory) +Every handoff to another agent requires all three steps: +1. `PATCH /api/issues/{id}` with `assigneeAgentId: ""` (mentioning is NOT a handoff) +2. Set `status: "todo"` — never `in_review` or `backlog` +3. Call `POST /api/issues/{issueId}/release` with proper headers + +### Gitea-origin issue policy +If a task has `originKind: "gitea"`, do not begin work — create a board approval first via `POST /api/companies/{companyId}/approvals`. Set issue to `blocked` until approved. + +## Infrastructure Overview + +| Environment | Namespace | FQDN | kubectl access | +|-------------|-----------|------|----------------| +| Dev | `cartsnitch-dev` | `cartsnitch.dev.farh.net` | Full read/write | +| UAT | `cartsnitch-uat` | `cartsnitch.uat.farh.net` | Full read/write | +| Production | `cartsnitch` | `cartsnitch.farh.net` | Read-only | + +**Production is Flux-managed.** Never `kubectl apply` or `kubectl create secret` against `cartsnitch`. All changes go through `cartsnitch/infra` via PR. + +## Canonical Toolchain (policy-mandated, no alternatives) + +- **Secret management:** Bitnami Sealed Secrets (`kubeseal`) — no plain Kubernetes secrets +- **Database:** CloudNativePG Operator (Postgres) +- **Cache/pub-sub:** DragonflyDB Operator +- **Authentication:** Better-Auth + Google + Apple + Authentik OIDC — never build custom auth +- **Dependency updates:** Mend Renovate — **Dependabot is not used** +- **Browser automation:** Playwright MCP server (`http://playwright:8931/mcp`) — target dev only, never production + +## Branch & Merge Policy + +- Engineers target `dev` only — never `uat` or `main` directly +- No self-merge: CTO merges `dev` and `uat` PRs; CEO merges `main` PR +- All PRs include `cc @cpfarhood` at the bottom (visibility, not review) +- Flux Image Tag Automation is **denied** — image updates must be intentional PRs to `cartsnitch/infra` + +## Delegation Model + +Set `modelProfile: "cheap"` only for mechanical refactors, information lookups, and well-specified bounded updates. Leave unset for anything requiring judgment. When in doubt, leave it unset. + +## SDLC Phase Summary + +1. **Dev** — Engineer → PR → QA (Checkout Charlie) → CTO (Savannah Savings) → CTO merges +2. **UAT** — CTO opens `dev→uat` PR → deploys → Deal Dottie regression → Stockboy Steve security review +3. **Production** — CEO (Coupon Carl) reviews and merges `uat→main` → auto-deploy via Flux + +If any phase fails, work returns to the engineer (CTO cascades). \ No newline at end of file diff --git a/skills/sdlc/SKILL.md b/skills/sdlc/SKILL.md index 44ce4a3..2614704 100644 --- a/skills/sdlc/SKILL.md +++ b/skills/sdlc/SKILL.md @@ -1,25 +1,25 @@ --- name: sdlc description: > - Software development lifecycle for CartSnitch. Covers GitHub authentication, + Software development lifecycle for CartSnitch. Covers Gitea authentication, branch strategy across Dev/UAT/Prod, the four-phase SDLC pipeline with product analysis intake, PR review and merge policy, the handoff protocol, - status semantics, infrastructure layout, the GitHub-origin issue + status semantics, infrastructure layout, the Gitea-origin issue board-approval gate, the cc-cpfarhood visibility rule, and delegation model tier policy. --- # Software Development Lifecycle -## GitHub authentication +## Gitea authentication -**Invoke the `github-app-token` skill** before any GitHub operation. It generates a short-lived installation token and writes it to `$GH_CONFIG_DIR/.gh-token` (or `$AGENT_HOME/.gh-token` as fallback) and authenticates `gh` automatically. **Never** run `gh auth login` — it hangs headless agents. Token expires after ~1 hour; re-invoke to regenerate. +**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. -GitHub is the **primary source of truth**. Every Paperclip issue must have a corresponding GitHub 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. -## GitHub-origin issue policy — board approval required +## Gitea-origin issue policy — board approval required -If a task originated from GitHub (`originKind: "github"`), **do not begin work**. Immediately create a board approval: +If a task originated from Gitea (`originKind: "gitea"`), **do not begin work**. Immediately create a board approval: ``` POST /api/companies/{companyId}/approvals @@ -28,7 +28,7 @@ POST /api/companies/{companyId}/approvals "requestedByAgentId": "{your-agent-id}", "issueIds": ["{issueId}"], "payload": { - "title": "Board approval required: GitHub issue", + "title": "Board approval required: Gitea issue", "summary": "Summarize what the GitHub issue requests.", "recommendedAction": "Approve to begin work.", "risks": ["Work begins without board review if approved."] @@ -55,10 +55,10 @@ Three long-lived branches map to the three deployment environments: 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 --base dev --title "..." --body "... cc @cpfarhood" +tea pr create --base dev --title "..." --body "... cc @cpfarhood" ``` -GitHub branch protection requires CI checks (lint, test, build-and-push). Governance is enforced through the Paperclip SDLC — GitHub-native review approvals are not required because all agents share a GitHub App identity. Paperclip approval tracking is the authoritative record. +Gitea branch protection requires CI checks (lint, test, build-and-push). Governance is enforced through the Paperclip SDLC — Gitea-native review approvals are not required because all agents share the Gitea App identity. Paperclip approval tracking is the authoritative record. ## PR review & merge policy @@ -78,7 +78,7 @@ GitHub branch protection requires CI checks (lint, test, build-and-push). Govern ### Product analysis (feature intake) -* Feature requests arrive at the CEO via Paperclip or GitHub Issues. +* Feature requests arrive at the CEO via Paperclip or Gitea Issues. * CEO delegates to CMO (Markdown Martha) for review. * CMO: Accepted → CEO routes to CTO for work breakdown. Backlogged → CEO handles prioritization. Denied → closed as unplanned. * CTO breaks accepted work into atomic tasks and assigns to Engineering. @@ -172,7 +172,7 @@ Without this release, the receiving agent cannot check out the issue. ## Deployment — 2-stage Flux GitOps -**Stage 1 — CI (GitHub Actions, 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: CalVer (`YYYY.MM.DD[.N]`), `latest`, and `sha-` - Pushes tagged images to `ghcr.io/cartsnitch/`