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