mathias/hyperguild

Fork 0

Files

Mathias Bergqvist d44427e71f

CI / Lint / Test / Vet (push) Successful in 9s

Details

CI / Mirror to GitHub (push) Successful in 3s

Details

docs: document brain MCP endpoint at koala:30330

- README architecture diagram now shows two MCP servers (supervisor +
  brain) with the brain hosted by ingestion directly.
- Connect-a-project example includes both servers.
- .context/PROJECT.md replaces the boilerplate "Knowledge base access"
  block with the actual hyperguild MCP endpoints.
- Adapters regenerated via task context:sync.

Captures the transitional state where two MCPs coexist; the supervisor
MCP will shrink as skill workers move to SKILL.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-02 23:03:45 +02:00

2.9 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.

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

2.9 KiB Raw Blame History