From 1ec22ff3fcaa8c0347d0e27f551bd3c5eb6e8f93 Mon Sep 17 00:00:00 2001 From: Hermes Date: Tue, 19 May 2026 15:27:21 -0400 Subject: [PATCH] docs: add AGENTS.md with dev workflow and YAML conventions --- AGENTS.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4cc1638 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# AGENTS.md + +Development conventions for the compose repository (Docker Compose stacks). + +## Build & Deploy + +- The ai stack is managed via `systemctl restart ai_stack.service` on the NixOS host +- Compose files are built from the git repo; apply via `nh os switch` or `systemctl restart ai_stack.service` +- Never `docker compose up -d` directly — it bypasses the systemd env file and breaks secrets + +## Hermes Workers + +- Paperclip Hermes workers are added via `ai/scripts/provision-hermes-worker.sh` +- The script appends only — never deletes or modifies existing content +- Workers are CPU-only containers on the `ai_backend` network with no GPU passthrough + +## Workflow + +- New feature → clean branch from `origin/master` → push → PR on Gitea +- Branch naming: `feat/description` (features), `fix/description` (bugs/docs) +- Always branch from `origin/master`, never from another feature branch +- Submodule changes (when this repo is consumed as a submodule): commit the submodule update in the parent repo +- PR title should describe the change; body should explain motivation + summary +- After PR merge, delete the feature branch + +## YAML Conventions + +- Use `x-*` extension fields for reusable anchors +- Comment out inactive services rather than deleting them +- Environment variables in dictionary format (`KEY: value`) for anchor compatibility +- List format (`- KEY=value`) works for standard services but doesn't merge with anchors