org/CLAUDE.md

# 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/` — Application code lifecycle: branch strategy, SDLC phases 1-5, Stage 1 CI image build, auth framework, application-tool policy, delegation tier
- `skills/devops/` — Infrastructure lifecycle on `cartsnitch/infra`: Flux GitOps reconciliation, OpenTofu controller, cluster topology, operator install
- `skills/safety/` — Non-negotiable rules: secret handling, SealedSecrets workflow, kubectl scope limits, destructive-action gating, Gitea-origin board-approval gate
- `skills/coding-standards/` — Engineering quality bar, priority ordering, test requirements, task decomposition template

## Safety (Non-Negotiable)

These rules apply without exception:

- **Never exfiltrate secrets.** API keys, tokens, PEM files, database credentials, kubeconfig contents — never log, comment, or return these in any output.
- **Never kubectl apply/create secret against production** (`cartsnitch` namespace). All changes go through `cartsnitch/infra` via PR. Flux manages production.
- **Never commit plaintext secrets.** Use Bitnami Sealed Secrets (`kubeseal`). No plain Kubernetes secrets at any environment.
- **Seek board approval for destructive actions.** Deleting resources, dropping tables, wiping namespaces, force-pushing, resetting git history — use `request_board_approval`.
- **Never run `tofu` directly.** Terraform goes through the Flux OpenTofu Controller via PR to `cartsnitch/infra`.
- **If uncertain, stop.** Post a comment explaining what you're about to do and why, set issue to `blocked`, and escalate.

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

Gitea is the **primary source of truth**. Every Paperclip issue must have a corresponding Gitea issue.

### 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 headers `Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID`

### 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` | `dev.cartsnitch.com` | Full read/write |
| UAT | `cartsnitch-uat` | `uat.cartsnitch.com` | Full read/write |
| Production | `cartsnitch` | `cartsnitch.com` | Read-only |

**Production is Flux-managed.** Never `kubectl apply` or `kubectl create secret` against `cartsnitch`. All changes go through `cartsnitch/infra` via PR.

**Gateways:** `istio-external` (public) and `istio-internal` (internal) in `gateway-system`.

## 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 at `https://auth.farh.net` — 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
- **Container registry:** `git.farh.net/cartsnitch/<service>` only — never Docker Hub for first-party images

## Branch & Merge Policy

- Engineers target `dev` first — never `uat` or `main` directly
- Engineer merges all three branches; prerequisites differ:
  - `dev`: CI passes
  - `uat`: QA (Checkout Charlie) code review approval
  - `main`: UAT validation (Deal Dottie), security review (Stockboy Steve), CEO (Coupon Carl) code review approval
- 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.

## Task Decomposition Template

When delegating tasks to other agents, structure them like this:

```
## What
[One sentence: the specific action to take]

## Where
[Exact repo, branch, file paths]

## Why
[One sentence: business/technical reason]

## How
[Step-by-step instructions, no ambiguity]

## Acceptance Criteria
- [ ] [Specific, verifiable condition]

## Context
[Code snippets, links, or prior decisions needed to complete the task]
```

## Code Review Tone

Hold a high bar. PRs with obvious mistakes, missing tests, hardcoded values, or policy violations get firm, specific review comments citing what's wrong and what the fix is. Cite the file and line. Don't sugarcoat — but be professional and constructive.

## SDLC Phase Summary

1. **Phase 1 — Dev**: Engineer → PR vs `dev` → CI pass → Engineer self-merges → auto-deploy to Dev (`dev.cartsnitch.com`)
2. **Phase 2 — UAT promotion**: Engineer opens `dev→uat` PR → CI pass → QA (Checkout Charlie `9b6012d0-0406-417e-bb22-78266a6e7f77`) code review → Engineer merges → auto-deploy to UAT (`uat.cartsnitch.com`)
3. **Phase 3 — UAT testing & security**: Deal Dottie (`161fb3bb-0332-4381-b67d-7c4b92a91133`) full regression → Stockboy Steve (`d59d4b24-3cc3-4616-a23a-2b4776a489ca`) security code review
4. **Phase 4 — Production promotion**: Engineer opens `uat→main` PR → CI pass → CEO (Coupon Carl `cd91facf-8f4c-4cbd-b8d8-b48da5b50727`) code review → Engineer merges → CI builds & tags image
5. **Phase 5 — Production deployment**: Engineer opens PR against `cartsnitch/infra` updating the overlay image tag → from here the `devops` skill owns review, merge, and Flux reconciliation to `cartsnitch.com`

If any phase fails, work returns to the engineer. CTO (Savannah Savings `6ec1a5a9-113c-430b-90e6-260d60d79e1d`) is the escalation target for re-distribution and disputes.

## Agent Roster

| Agent | Role | UUID |
|-------|------|------|
| Coupon Carl | CEO | `cd91facf-8f4c-4cbd-b8d8-b48da5b50727` |
| Savannah Savings | CTO | `6ec1a5a9-113c-430b-90e6-260d60d79e1d` |
| Markdown Martha | CMO | `46614fb2-6d29-4ea3-bc46-4a3b94086e3c` |
| Deal Dottie | UAT | `161fb3bb-0332-4381-b67d-7c4b92a91133` |
| Stockboy Steve | Security | `d59d4b24-3cc3-4616-a23a-2b4776a489ca` |
| Barcode Betty | Engineer | `1ba0c654-eba6-4d17-8c8e-b0a923ead8e6` |
| Checkout Charlie | QA | `9b6012d0-0406-417e-bb22-78266a6e7f77` |

## Versioning

CartSnitch CI uses **CalVer** (`YYYY.MM.DD[.N]`) for image tags. CI also publishes `latest` and `sha-<hash>`. Do not introduce other versioning schemes for application images.