mathias
ff1fa982be
Tells an agent to wire skills via `task skills` (gitignored symlinks, never committed) and which skills matter for Tapir; documents the scaffolded-and-RED state with the first build task spelled out; flags the unverified setup items (Go version, brain-mcp URL, secret-ref naming, model alias) to resolve against the live cluster.
109 lines
6.5 KiB
Markdown
109 lines
6.5 KiB
Markdown
# 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.
|