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/ — 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).