5.1 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 wheregocommands 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 addnew files before a nix build. - After changing Go dependencies, run
go mod tidy, then setvendorHashinflake.nixto thegot:hash the nextnix build .#slackerbotprints. - Bazel sits alongside Nix and reads the same
go.mod. When you add, remove or move a Go file, package or import, runbazel run //:gazellefrom the repo root and commit the updatedBUILD.bazelfiles. After changing Go dependencies, runbazel mod tidyas well.bazel test //...must pass. Gazelle keeps hand-added attributes such asdata,pureandx_defs. - The Nix build skips tests (
doCheck = false), because they open local ports and read../config.example.toml.go testis 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.1using fake nodes (internal/testutil). Code that shells out tobtrfs,systemd-runor D-Bus (local, parts ofstorage) 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,storageandutilimport nothing internal, andbotandmainsit at the top. Never introduce a cycle. If two packages need a type, it belongs inmodel(ornodefor node wire types). manager, its cluster link and migration stay in one package on purpose.commandsonly parses text. It must never call Slack or the manager.- The bot talks to nodes only through
manager, neverlocaldirectly. - Shared test fakes go in
internal/testutil. Tests that need a running cluster usetestutil/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}), orgo vetwill complain. - Keep a function's arguments, results and locals from using a package's name (
node,state, …). - Text that Slack users see lives in
botand goes in plain sentences. Keep it consistent with USERGUIDE.md.
Behaviour you must not break
- The
state.jsonformat: existing owners, sessions and permissions must still load. JSON field names are effectively a public format. The same goes forin-flight-<channel>.json: turns written by the previous build are resumed by the next one. - 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 matchnix/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
- Before you start changing anything, ask the human whether to work in a git worktree (
git worktree add). Wait for an answer, and don't create a worktree or edit files until you have one. - Don't commit, push or rewrite history unless asked.
- Never commit build output (
result, theslackerbotbinary,.direnv/).