From 6f135470d274daa3e7a7fec1cb8f36204abd90f0 Mon Sep 17 00:00:00 2001 From: "Henry J. Webster" Date: Mon, 3 Aug 2026 23:26:57 -0500 Subject: profiles: add agent-context — one AGENTS.md for every harness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There is no cross-vendor standard for agent instruction files: claude-code reads CLAUDE.md, opencode and pi read AGENTS.md, each with its own global path. Keep one canonical file (common/AGENTS.md) in this repo, ship it to /etc/AGENTS.md, and symlink every harness's global context path to it via tmpfiles for all normal users: ~/.claude/CLAUDE.md (claude-code 2.1.187 — no AGENTS.md support) ~/.config/opencode/AGENTS.md (opencode 1.15.10) ~/.pi/agent/AGENTS.md (pi 0.75.4) Paths verified against the packaged binaries; see the profile header for details and for the per-repo convention (AGENTS.md + CLAUDE.md symlink). Assisted-by: claude-code:Fable 5 --- common/AGENTS.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 common/AGENTS.md (limited to 'common') diff --git a/common/AGENTS.md b/common/AGENTS.md new file mode 100644 index 0000000..24690c0 --- /dev/null +++ b/common/AGENTS.md @@ -0,0 +1,38 @@ +# Global agent context (all harnesses, all machines) + +One file, every harness: this is `common/AGENTS.md` in the nixos-config repo, +deployed by `profiles/sandbox.nix` to `/etc/AGENTS.md` and symlinked to +each harness's global context path (`~/.claude/CLAUDE.md`, +`~/.config/opencode/AGENTS.md`, `~/.pi/agent/AGENTS.md`). To change it, edit it +in nixos-config and rebuild — it is read-only everywhere else on purpose. + +## Machines + +- `kusanagi` — AMD workstation (ROCm GPU; Ollama/Immich/Kavita services). +- `enzo` — laptop. + +Both are NixOS, configured by the flake in `nixos-config`. + +## If you are running as `yokai` (the agent sandbox) + +- You work in your own clone of each repo under `/srv/git/`; the owner's + canonical repo lives in their home, which you cannot reach. +- Deliver work as commits in your clone — the owner reviews by fetching from + it, so uncommitted work is invisible to them. +- Never push to origin or any external remote, and never sign commits; the + owner squashes and signs what lands. Full workflow: `profiles/sandbox.nix`. + +## Conventions + +- Nix code: format with `nixfmt`. Profiles stay username-agnostic — per-user + configuration goes in `machines/*/default.nix`. +- Never run `nixos-rebuild` or otherwise apply system configuration; propose + changes as commits and let the owner apply them. + +### Git + +- Trailers: `Assisted-by: AGENT_NAME:MODEL_VERSION`. Do NOT use `Co-authored-by`. +- Commit subjects: `area: imperative summary` (e.g. `profiles: extract shared + sandbox profile`); the body explains why, not what. + + -- cgit v1.3