amadan
docs: CLAUDE.md — delegation policy and the rules this repo has paid for
The delegation ladder (Haiku transcribes, Sonnet implements from a precise brief, Opus designs and reviews anything authority- or production-touching) is Paul's standing rule, recorded where every session reads it. The rest is the day's tuition: consumer lists follow the SHAPE not the API, wire changes are additive, promote-adopt-restart in that order, gate ordering, and verify with the binary you built.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 file changed,
+61
−0
CLAUDE.md+61 −0
diff --git a/CLAUDE.md b/CLAUDE.md| new file mode 100644 |
| index 000000000..b1797c72e |
| --- /dev/null |
| +++ b/CLAUDE.md |
| @@ -0,0 +1,61 @@ |
| +# CLAUDE.md |
| + |
| +CARLOS platform — bucket-as-control-plane deployment platform. Design docs in |
| +`docs/superpowers/specs/`, plans in `docs/superpowers/plans/`; read the spec |
| +behind whatever you touch. |
| + |
| +## Delegation policy (Paul's rule, 2026-08-02) |
| + |
| +Delegate mechanical work to subagents on the cheapest model that fits, and |
| +have Opus review anything that grants authority or touches production paths: |
| + |
| +- **Haiku** — transcription-grade work: the plan contains the exact code, |
| + single-file mechanical fixes, doc edits. |
| +- **Sonnet** — implementation from a precise brief: 1-3 files, clear |
| + interfaces, established conventions to follow. |
| +- **Opus** — design judgment, multi-file integration, anything security- or |
| + production-touching; and the **reviewer** for work in those areas. |
| + |
| +Always name the model explicitly when dispatching; an omitted model silently |
| +inherits the session's (usually the most expensive). A precise brief beats a |
| +capable model — exact values, file paths and interfaces go in the brief. |
| + |
| +## Build & test |
| + |
| +- `go build ./...`, `go vet ./...`, `go test ./... -count=1` — all clean, all |
| + 14 packages, before any commit lands. |
| +- `gofmt -l` clean for files you touch (three pre-existing unformatted files |
| + elsewhere are left alone). |
| +- Sandbox note: use `GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod |
| + GOPROXY=off`; go commands may need the sandbox disabled ("read-only file |
| + system" from the toolchain is the tell). |
| + |
| +## Rules this repo has paid for |
| + |
| +- **When a storage shape changes, the consumer list is everything that PARSES |
| + the shape** — not everything that calls the API. (Learned three times.) |
| +- **Wire-shape changes are additive**: live pointers/manifests exist in |
| + production buckets; anything written before your change must still parse. |
| +- **Production channel names are pinned in tests** |
| + (`internal/release/laddercheck_test.go`) — the fleet runs on `canary/*` |
| + channels today; a ladder change that refuses them stops deploys. |
| +- **Adoption swaps a symlink; it does not restart processes.** Order is: |
| + promote → adopt → restart. Long-running units (console, keymail relay) need |
| + the restart; hibernating tenants pick it up on wake. |
| +- **Console security gates are ordered**: session → CSRF → owner (byte-identical |
| + 404) → `requireFreshAuth` LAST. A non-member must never get a redirect that |
| + confirms an account exists. |
| +- **Verify against the thing you changed, with the binary you built.** Stale |
| + DNS answers and stale `CARLOS_BIN` binaries have both produced false |
| + "verified" reports in one day. |
| +- Icons are vendored Lucide (in-code SVG constants, never CDN); emoji is |
| + content, icons are chrome. |
| + |
| +## Deploy reality (2026-08-02) |
| + |
| +- Flagship (keymail AWS acct): console, kass, keymail, platform-site. Ship via |
| + `scripts/ship-app.sh` / `promote-app.sh` in the pinfra checkout — the signing |
| + key comes from SSM inside the script, never a terminal. |
| +- Tito production is self-hosted CARLOS on `carlos-tito-ie` (titogo AWS acct). |
| +- keymail.dev deploys via `carlos ship`/`promote` (account `bae`), NOT via its |
| + repo's legacy `deploy/deploy.sh` — see that repo's CLAUDE.md. |