# Agent guidelines Rules for anyone, human or AI, changing this repo. Read [ARCHITECTURE.md](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-`. `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 same goes for `in-flight-.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-`, `c-`), unit names (`slackerbot-.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 - 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`, the `slackerbot` binary, `.direnv/`).