tapir/CLAUDE.md

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/<desc> branch when another agent is simultaneously active on this repo, merged within the same session.
• Run the quality gate before every push. task check. 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.

Skills (engineering discipline)

Skills live in the canonical library mathias/skills and are wired into this repo as gitignored symlinks — do not commit them, do not add a skills manifest to this repo.

• Install/refresh: task skills (or curl -fsSL https://gitea.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash). Idempotent.
• Most relevant skills for Tapir work:
  • tdd, atdd, test-design — the build is test-first; the .feature files are the ATDD spec.
  • clean-code, solid — the ports-and-adapters structure depends on these.
  • gitea-ci — for the CI workflow (and its act_runner gotchas) and the TBD section.
  • debug — when task check goes red for a non-obvious reason.
  • Reviewer-side: code-review, refactoring, cognitive-load.
  • Session close: session-retrospective (surface learnings into brain before context is lost).

Current build state (start here for the first task)

The repo is scaffolded and intentionally RED:

• Clean Architecture skeleton exists: internal/domain (entities), internal/ports (interfaces), internal/usecase (engine), cmd/tapir (entrypoint stub), internal/adapters (empty — concrete adapters go here).
• usecase.Engine.ProcessNewVideo returns ErrNotImplemented.
• test/acceptance/summarize_new_video_test.go translates the first two Gherkin scenarios and fails against the stub. task check is therefore red on test.
• First build task: implement ProcessNewVideo (resolve transcript -> summarize -> deliver to sinks | skip on no-transcript) to make the acceptance tests green, following the .feature files. Then add the AI-router Summarizer (copy llm per ADR-004), the YouTube VideoSource adapter (captions-first), and the store + brain sinks.

Unverified setup items (see docs/homelab-integration.md, marked confirm): the Go version in go.mod (1.23 — match the koala runner; estate elsewhere uses 1.26.1), the brain-mcp URL, the exact ESO secret-ref naming, and the summarization model alias. Resolve against the live cluster before depending on them, and pin answers back into docs/homelab-integration.md.

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.