This commit is contained in:
ari committed 2026-11-01 13:13:04 -05:00
1 parent 0ac61b4ece
commit 7a8fa22e70
7 files changed
+386 -237

No files matched your search

+68
View File
@@ -0,0 +1,68 @@
# 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 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.
## 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.
- 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
## Git
- Don't commit, push or rewrite history unless asked.
- Never commit build output (`result`, the `slackerbot` binary, `.direnv/`).