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 <noreply@anthropic.com>
This commit is contained in:
@@ -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: "<target-agent-uuid>"` (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).
|
||||
+12
-12
@@ -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-<hash>`
|
||||
- Pushes tagged images to `ghcr.io/cartsnitch/<service>`
|
||||
|
||||
Reference in New Issue
Block a user