Files
slacker-bot/AGENTS.md
T
2026-11-01 14:59:37 -05:00

4.8 KiB

Agent guidelines

Rules for anyone, human or AI, changing this repo. Read ARCHITECTURE.md first.

Environment

  • nix develop (or direnv with .envrc) gives Go, gopls, staticcheck, delve, bazelisk and btrfs-progs. Use it rather than system tools.
  • Go code lives in slackerbot/, and that's where go commands run. Nix files and docs live at the repo root.

Versioning

Versions look like YYYY.MM.DD-<commit-sha>. flake.nix builds the string from the commit date and short rev (with -dirty for uncommitted trees) and passes it to the binary with -X main.version. Don't hardcode a version anywhere. slackerbot -version prints it, and a plain go build reports dev. Bazel builds the same string in tools/workspace_status.sh and stamps it only with --config=release.

Checks before you finish

Run from slackerbot/, and all must pass:

gofmt -l .          # must print nothing
go vet ./...
go test ./...

If you changed flake.nix, nix/, go.mod or go.sum, also run from the repo root:

nix build .#slackerbot
nix build .#agent
nix flake check --no-build
  • Flakes only see files tracked by git. git add new files before a nix build.
  • After changing Go dependencies, run go mod tidy, then set vendorHash in flake.nix to the got: hash the next nix build .#slackerbot prints.
  • Bazel sits alongside Nix and reads the same go.mod. When you add, remove or move a Go file, package or import, run bazel run //:gazelle from the repo root and commit the updated BUILD.bazel files. After changing Go dependencies, run bazel mod tidy as well. bazel test //... must pass. Gazelle keeps hand-added attributes such as data, pure and x_defs.
  • The Nix build skips tests (doCheck = false), because they open local ports and read ../config.example.toml. go test is the real test run.
  • Tests need no root, btrfs or Slack. The manager and bot tests start a real master and slave over TLS on 127.0.0.1 using fake nodes (internal/testutil). Code that shells out to btrfs, systemd-run or D-Bus (local, parts of storage) has no automated tests, so test it by hand on a btrfs host.

Package rules

  • Each package does one job (see the table in ARCHITECTURE.md). Put new code where its job is, and don't create a package for a single function.
  • Imports go downward only: model, units, storage and util import nothing internal, and bot and main sit at the top. Never introduce a cycle. If two packages need a type, it belongs in model (or node for node wire types).
  • manager, its cluster link and migration stay in one package on purpose.
  • commands only parses text. It must never call Slack or the manager.
  • The bot talks to nodes only through manager, never local directly.
  • Shared test fakes go in internal/testutil. Tests that need a running cluster use testutil/clustertest.

Code style

  • Few comments. Code should document itself. Only add a comment when the code really is unclear, such as a non-obvious reason, a protocol quirk or a race. Don't add comments that repeat the code, section banners or doc comments on obvious functions.
  • Follow the existing style: short functions, early returns, errors wrapped with %w, and user-facing text written plainly.
  • Key struct literals for types from other packages (model.Size{MemoryMB: 1024, CPUs: 1}), or go vet will complain.
  • Keep a function's arguments, results and locals from using a package's name (node, state, …).
  • Text that Slack users see lives in bot and goes in plain sentences. Keep it consistent with USERGUIDE.md.

Behaviour you must not break

  • The state.json format: existing owners, sessions and permissions must still load. JSON field names are effectively a public format.
  • The cluster wire protocol: frame types and call names in manager/cluster.go. A master and slaves may run different versions for a while.
  • Machine names (u-<id>, c-<id>), unit names (slackerbot-<machine>.service), and paths (/var/lib/slackerbot, the agent env file at /var/lib/slackerbot/agent.env, which must match nix/container.nix).
  • Anything that decides whether a message is a command or goes to the agent: commands.ErrNotCommand. Ordinary sentences must still reach the agent.

Docs

Update the matching doc in the same change:

  • Slack commands, replies or permissions → USERGUIDE.md
  • Packages, data flow, protocol, placement → ARCHITECTURE.md
  • Config, Nix module options, setup steps → INSTALLATION.md and config.example.toml
  • Workflow or rules → this file

Designs that aren't built yet live in plan/. When you build one, move what it describes into the docs above and delete the plan file.

Git

  • Don't commit, push or rewrite history unless asked.
  • Never commit build output (result, the slackerbot binary, .direnv/).