Files
2026-10-09 14:35:12 -04:00

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:

  1. What you intend to change (files, modules, seed content)
  2. Why the change is needed
  3. How you will do it (which files you will edit, in what order)
  4. 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 setup creates/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 migrate writes into a running guest and rewrites its config, even though it never touches the migration source.
  • A nixos-rebuild switch on a consuming host is a live, production-affecting action — for hl-fwdesk specifically, it's the machine running the operator's actual daily-use Hermes deployment.
  • Bare nix build / nix flake check can 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.nix to add/adjust options (gated behind mkIf cfg.enable, following the existing style)
  • Editing anything under nu/ — check changes by parsing (nu nu/hermenix.nu --help and nu nu/hermenix.nu <subcommand> --help parse the whole tree without running any subcommand body) before handing it back
  • Editing guest/hermes/home / guest/hermes/workspace template seed content (as long as it stays free of real secrets — see above)
  • Editing README.md / GUIDELINES.md / AGENTS.md / anything under docs/
  • 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

Operator-facing docs live under docs/. Start at the README.