From deb8523d75445bdc6771376d67ecac8a5cc46972 Mon Sep 17 00:00:00 2001 From: mathias Date: Tue, 2 Jun 2026 10:37:22 +0000 Subject: [PATCH] docs: add CLAUDE.md agent operating instructions Operational context for independent agent sessions: orientation order, TBD + conventional-commit workflow, the three "looks reusable but isn't" traps (llm is copied not imported, brain sink is HTTP not filesystem, OAuth is fresh), the settled decisions not to reopen, the Clean Architecture/BDD stance, and a provenance trail back to the S5 spike and the llm source. Distills the operating knowledge surfaced during the 2026-06-02 planning+grill session. --- CLAUDE.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..53e7bcd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,74 @@ +# CLAUDE.md — Agent operating instructions for Tapir + +Read this first if you are an agent (or human) starting a work session in this repo. +It tells you how to work here. For *what* and *why*, read `README.md` and the guardrail +docs it indexes. + +## Orientation order + +1. `README.md` — what Tapir is, links to all guardrails. +2. `VISION.md` — the staged Definition of Success. **Stage 0 ("useful to me") is the gate.** + Do not build Stage 1+ machinery before Stage 0 holds. +3. `DECISIONS.md` — the ADRs. Decisions are settled here; do not re-litigate without a new ADR. +4. `docs/architecture/architecture.md`, `docs/data-model.md`, `docs/use-cases/*.feature`. +5. `docs/homelab-integration.md` — the concrete endpoints/conventions you'll need. + +## How to work in this repo + +- **Trunk-Based Development (ADR-009).** Commit directly to `main`. One logical change per + commit. Every commit deployable. No feature branches or PRs for solo/agent work — the only + exception is a short-lived `agent/` branch when another agent is *simultaneously* + active on this repo, merged within the same session. +- **Run the quality gate before every push.** `task check` (once a Taskfile exists). CI is the + gate, not branch protection — do not enable branch protection on this repo. +- **Conventional commits.** `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`. Subject line says + what; body says why. +- **Language is Go (ADR-001).** Do not introduce Python or a second language. If you think you + need one, that's a new ADR with a real justification, not a default. + +## Things that look reusable but are NOT — read before "reusing" + +These caused real mistakes that were caught and corrected; the corrections are load-bearing. + +- **The `llm` package is COPIED from `hyperguild/ingestion`, not imported (ADR-004).** Tapir + owes that repo nothing at the dependency level. Do not add `hyperguild/ingestion` as a Go + module dependency to "share" code. If the copied `llm` needs changes, change Tapir's copy. +- **The brain sink is HTTP to brain-mcp, NOT the filesystem `brain` package (ADR-005).** + `hyperguild/ingestion`'s `internal/brain` writes files into a brain git checkout on disk. + That is the wrong model for Tapir. The brain sink calls brain-mcp's `brain_ingest` tool over + HTTP. Do not copy or replicate the filesystem brain package. +- **YouTube/Vimeo OAuth is written fresh (ADR-006).** `hyperguild/ingestion`'s `internal/oauth` + is the MCP *server's inbound* auth (client_credentials). It has nothing to do with *outbound* + OAuth to video providers despite the shared name. Use `golang.org/x/oauth2`. + +## Settled decisions you should not "helpfully" reopen + +(See `DECISIONS.md` for full rationale. Listed here so you don't propose them.) + +- **No Supabase** — reuse Dex / ESO+1Password / Postgres (ADR-002). +- **No global cross-tenant video/transcript table** — per-user isolation (data-model). Dedup + across users is a Future C concern, not a Stage 0/1 default. +- **No audio-download + speech-to-text in the core path** — captions-first (ADR-007). STT is a + deferred, bounded optional component. +- **No public SaaS / sign-up / billing / Google OAuth verification at scale** — Future C, + deferred behind the Stage 0 gate (ADR-008). + +## Architecture stance for new code + +- **Clean Architecture, dependencies point inward.** The engine (use cases) depends only on the + ports (`VideoSource`, `Summarizer`, `Sink`, `SecretStore`). Concrete providers, the AI router, + stores, and sinks are adapters. Adding a video provider or a sink = a new adapter implementing + the interface, nothing in the engine changes. This is what keeps "standalone vs homelab" a + wiring choice (ADR-003). +- **BDD.** The `docs/use-cases/*.feature` files are the behavior spec. New behavior gets a + scenario; the use-case core is tested through fake adapters, not live YouTube/brain. + +## Provenance (where this design came from) + +- The reuse decisions came from **Spike S5**, recorded at + `infra/docs/superpowers/handoffs/2026-06-02-video-adapter-placement.md` (read it for the + per-package lift-vs-copy analysis). +- The `llm` package source is `hyperguild/ingestion/internal/llm` (`Client` + `Router`). +- The standalone-first framing, the Supabase/Python rejections, and the staged success + definition came from a planning + grill session on 2026-06-02 (claude.ai). The conclusions are + in `VISION.md` and `DECISIONS.md`; this file is the operational distillation.