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.