hyperguild/.context/PROJECT.md

Project context

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