# 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).