d72454d929
Add routing pod to README architecture diagram and env vars table. Add routing MCP endpoint to .context/PROJECT.md. Regenerate derived context adapters via task context:sync. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# Project context
|
|
|
|
<!-- Canonical project context. Edit this, run `task context:sync`.
|
|
Root agent context from ~/dev/.context/AGENT.md is automatically
|
|
prepended for harnesses that don't walk the directory tree. -->
|
|
|
|
## Identity
|
|
|
|
- **Name**: supervisor
|
|
- **Owner**: Mathias
|
|
- **Client**: personal
|
|
- **Repo**:
|
|
- **Status**: active
|
|
|
|
## Stack
|
|
|
|
- **Primary language**: Go
|
|
- **UI layer**: HTMX + Templ (when applicable)
|
|
- **Fallback languages**: Python, TypeScript (justify in PR if used)
|
|
- **Build**: Task (taskfile.dev), not Make
|
|
- **Containers**: Docker (compose for dev, k3s for deploy)
|
|
- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
|
|
|
|
## Conventions
|
|
|
|
### Code style
|
|
- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
|
|
- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
|
|
- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
|
|
- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
|
|
|
|
### Architecture preferences
|
|
- Prefer standard library over frameworks (net/http over gin/echo)
|
|
- Dependency injection via constructor functions, not containers
|
|
- Configuration via environment variables, parsed at startup into a typed struct
|
|
- Structured logging via `slog`
|
|
|
|
### Git
|
|
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
|
- Branch naming: `feat/short-description`, `fix/short-description`
|
|
- PRs: one concern per PR, description explains *why* not *what*
|
|
|
|
### Security
|
|
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
|
- Client data never leaves local network unless explicitly cleared
|
|
- Dependencies: audit with `govulncheck` before adding
|
|
|
|
## MCP endpoints
|
|
|
|
Two MCP servers expose this project's tooling, both reachable over Tailscale:
|
|
|
|
- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
|
|
`brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
|
|
by the ingestion service directly.
|
|
- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
|
|
`tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
|
|
`trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
|
|
migration.
|
|
- **`routing`** at `http://koala:30310/mcp` — Mode 2 routing pod. Advertises
|
|
the same four cost-routable skills as the supervisor (`review`, `debug`,
|
|
`retrospective`, `trainer`) but per-call decides whether to use a local
|
|
model or Claude based on the brain's `/pass-rate` response. Bearer auth
|
|
via `ROUTING_MCP_TOKEN` (opt-in). Only `mode client-local` registers this
|
|
endpoint; Mode 1 and Mode 3 do not.
|
|
|
|
The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
|
|
`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
|
|
shell scripts and non-MCP clients.
|
|
|
|
The brain HTTP REST API also serves a read-only `GET /pass-rate?skill=X&window=Y`
|
|
endpoint that aggregates `final_status` counts from session logs and returns
|
|
`{skill, window, pass, fail, skip, total, pass_rate}`. Plan 6 (routing pod)
|
|
reads this to decide whether to route skill calls to local models. Pass rate
|
|
is `null` when no logged invocations are in the window.
|
|
|
|
## Agent instructions
|
|
|
|
When acting as a coding agent on this project:
|
|
|
|
1. Read this file and all `SKILL.md` files in `.skills/` before starting work
|
|
2. Run `task check` before committing (lint + test + vet)
|
|
3. If unsure about a convention, check `DECISIONS.md` or ask
|
|
4. Never modify files outside the project root without explicit permission
|
|
5. When adding a dependency, explain why in the commit message
|
|
6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|