Files

Mathias Bergqvist 986e3e1d12 docs(hyperguild): document brain pass-rate subcommand and /pass-rate endpoint

Adds pass-rate to the CLI README's subcommand block. Updates CLAUDE.md
to note the new /pass-rate endpoint alongside the existing brain
HTTP REST API surface. Updates the session_log MCP tool's
final_status description to reflect the new pass|fail|skip vocabulary
introduced by Plan 5's SKILL.md instrumentation; the aggregator
still accepts legacy ok|error|skipped values for backwards compat.

2026-05-03 22:55:35 +02:00

3.2 KiB

Raw Blame History

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.

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:

Read this file and all SKILL.md files in .skills/ before starting work
Run task check before committing (lint + test + vet)
If unsure about a convention, check DECISIONS.md or ask
Never modify files outside the project root without explicit permission
When adding a dependency, explain why in the commit message
For client projects: never send code or context to cloud APIs — use local models via LiteLLM

3.2 KiB Raw Blame History