7.3 KiB
Agent Guidelines — hermenix
Rules and best practices for any AI agent working in this repository. Read this file before making any changes.
Mandatory First Step — Always Present a Plan
Before making any change to this repository, you MUST present a short plan to the user and wait for their approval. This applies to every task, no matter how small.
Your plan must include:
- What you intend to change (files, modules, seed content)
- Why the change is needed
- How you will do it (which files you will edit, in what order)
- What you will NOT do (e.g., "I will not run hermenix setup or build the image")
Only after the user approves the plan may you proceed with edits.
Hard Rules — Never Break These
❌ NEVER run builds or disk-writing steps directly — ZERO EXCEPTIONS
DO NOT RUN ANY OF THESE COMMANDS DIRECTLY AT ANY TIME, FOR ANY REASON:
nix build # never directly — see the test-proxy exception below
nix flake check # never directly
hermenix setup # unless the user is actively running it themselves with you watching
hermenix migrate # same — it writes into a live guest
dd ... of=/var/lib/hermes-vm/** # writing any disk image
nixos-rebuild switch / test / build (on any host consuming this flake)
Test-proxy exception (the only allowed build path for agents):
Agents may run the repo's test wrapper scripts. Those scripts are the
deliberate proxy through which builds happen — they scope what gets
evaluated/built and never touch live disks under /var/lib/hermes-vm/**:
bin/runtest # CLI unit tests (nu/tests/) — no nix build
bin/runtest-debug
bin/runvmtest # guest VM checks via nix build of flake checks only
bin/runvmtest-debug
Do not invent your own nix build .#... / nix flake check invocations.
If a check is not reachable through those wrappers, describe it and let the
operator run it.
Why the direct ban exists:
hermenix setupcreates/writes disk images and generates host secrets (a binary cache signing key) — destructive if repeated carelessly, and it's the operator's host, not yours to act on.hermenix migratewrites into a running guest and rewrites its config, even though it never touches the migration source.- A
nixos-rebuild switchon a consuming host is a live, production-affecting action — forhl-fwdeskspecifically, it's the machine running the operator's actual daily-use Hermes deployment. - Bare
nix build/nix flake checkcan take a long time and consume real resources on a machine you don't control from here.
Your job: Write good Nix, good Nu, and good docs. The operator runs
hermenix setup, hermenix migrate, image builds outside the test wrappers,
and any nixos-rebuild themselves, on the host, watching each step.
❌ NEVER run hermenix vm rollback or hermenix ctl reseed without fresh confirmation
Both are destructive to live guest state — rollback replaces the current
state disk with an old snapshot; reseed overwrites SOUL.md, memories, and
config.yaml with the seed. A prior approval for a different task does not
carry over. Ask again, in the moment, before either.
❌ NEVER edit guest/hardware.nix's disk labels blindly
fileSystems."/" and "/boot" assume labels nixos and ESP. Getting this
wrong produces a guest that won't boot after its first self-rebuild. Only
change these after the operator has run lsblk -f inside the actual guest
and told you the real labels.
❌ NEVER commit live secrets to guest/hermes/home
That directory is a template seed for fresh deployments — it gets copied
into the guest on first boot and is world-readable in git history forever
after. Real credentials belong in the guest's own ~/.hermes/.env
(hermenix ctl secrets edit), never in this repo, never in the Nix store.
❌ NEVER move or delete source data during a migration
When carrying over an existing Hermes deployment (see hermenix migrate /
nu/host/migrate.nu), only ever read from and copy the source. Leave it in
place and untouched until the operator has verified the new deployment
end-to-end. This is the rollback safety net — don't remove it.
❌ NEVER commit or push unless explicitly asked
Same as any other repo: describe your changes and let the operator review before committing.
Safe Operations
These are always safe to perform without asking:
- Reading any file in this repo
- Editing
modules/host.nixto add/adjust options (gated behindmkIf cfg.enable, following the existing style) - Editing anything under
nu/— check changes by parsing (nu nu/hermenix.nu --helpandnu nu/hermenix.nu <subcommand> --helpparse the whole tree without running any subcommand body) before handing it back - Editing
guest/hermes/home/guest/hermes/workspacetemplate seed content (as long as it stays free of real secrets — see above) - Editing
README.md/GUIDELINES.md/AGENTS.md/ anything underdocs/ nix-instantiate --parse <file>.nix— syntax check only, no eval, no build- Running
bin/runtest,bin/runtest-debug,bin/runvmtest,bin/runvmtest-debug(the test-proxy path above)
When In Doubt
If you are unsure whether a command is safe, assume it is NOT SAFE and don't run it. Describe what you would do and ask.
Repository Layout
hermenix/
├── flake.nix # guest image + hermenix CLI package + nixosModules.default + checks
├── modules/host.nix # services.hermenix — host-side NixOS module
├── nu/
│ ├── hermenix.nu # top-level CLI dispatch
│ ├── lib/ # shared helpers (common.nu, guest.nu)
│ ├── host/ # setup, migrate, remote
│ ├── vm/ # hermenix vm *
│ ├── ctl/ # hermenix ctl *
│ ├── tests/ # CLI unit tests (nutest)
│ ├── completions.nu # generated tab completions
│ └── gen-completions.nu # regenerates completions.nu from usage blocks
├── bin/ # runtest / runvmtest wrappers (agent-safe test proxy)
├── guest/
│ ├── flake.nix # the GUEST's own /etc/nixos flake — belongs to the agent
│ ├── common.nix # guest NixOS config baked into the bootstrap image
│ ├── hardware.nix # guest disk layout — verify labels before ever editing
│ ├── local.nix.example # shape of /etc/hermenix/local.nix on the host
│ ├── vm-tests/ # NixOS VM checks (bridged / unbridged / migrate)
│ └── hermes/
│ ├── home/ # template seed → ~/.hermes on first boot
│ └── workspace/ # template seed → ~/workspace on first boot
├── tests/ # static module evaluation checks (no VM boot)
├── docs/ # operator documentation (see README index)
├── AGENTS.md # pointer at this file for coding agents
├── GUIDELINES.md # this file
└── README.md # quickstart + doc index