muster CLAUDE.md

CLAUDE.md — muster

Conventions for working in this repo (humans and agents).

What muster is

A local multi-agent coordination bus: independent coding-agent sessions (Claude Code + OpenAI Codex, each in its own tmux tab) hand tasks/messages to each other — no copy/paste, subscription-only (the bus never calls a model; it routes between agents already running on their own plans). One static Go binary, multi-mode (serve daemon · mcp stdio server · human CLI · lambda handler for the optional hosted backend).

Build / test / run

• just verify — the gate: gofmt, golangci-lint, go test -race, build, cross (all four release targets plus the -tags lambda build). Run it before every commit; CI runs the same recipe, so local and CI can't drift.
• just verify-dynamo — the second gate, deliberately NOT part of verify because it needs Docker. Runs internal/dynamostore and the DynamoDB half of the cross-backend conformance suite against DynamoDB Local. Without an endpoint those tests skip, so verify compiles and vets them but proves nothing about DynamoDB semantics — run this after touching internal/dynamostore. The dynamo job in CI runs the same two packages against a service container.
• cgo-free — the binary builds under CGO_ENABLED=0 (pure-Go SQLite via modernc.org/sqlite). Don't add cgo dependencies.
• macOS tests use internal/mustertest.ShortHome() for unix-socket paths (the sun_path ~104-char limit; t.TempDir() is too long and breaks the socket).
• Build + run: go build -o ~/.local/bin/muster ./cmd/muster, then muster serve | mcp | agents | send | inbox | tasks | nudge | register | ….

Branch model

feat/* → dev → main. CI (just verify) is required on dev and main; main is the release line. Never develop on main — do feature work in a git worktree off dev, merged via PR.

Releases are automated. The VERSION file is the knob: bump it on dev, and when the promotion PR merges to main, the release workflow tags v<VERSION>, creates the GitHub release with generated notes, and attaches cross-compiled binaries (darwin/linux × arm64/amd64) with checksums. A merge to main that doesn't bump VERSION releases nothing. The darwin binaries are signed and notarized by the release job itself, which is why that job runs on a macOS runner, and it fails rather than publishing anything unsigned — so a green release needs no manual signing step. contrib/release-sign.sh v<VERSION> remains only for repairing an already-published release by hand.