Chris Farhood
63e150f445
- 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>
62 lines
3.5 KiB
Markdown
62 lines
3.5 KiB
Markdown
# 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). |