From 897c21bb414a6afd72183139901957854b76936d Mon Sep 17 00:00:00 2001
From: Klagarge <remi@heredero.ch>
Date: Wed, 14 Oct 2026 11:57:15 +0200
Subject: [PATCH] ops: create AGENTS.md

---
 AGENTS.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..313d14e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,22 @@
+# Agent Guidelines
+
+## Architecture & Modules
+- Each tool/service lives in its own top-level folder (`<service>/`) with its own `Justfile`.
+- The root `Justfile` registers every service using `mod <service>` and runs `just <service>::deploy` in `all`.
+- Deployment links the **entire module folder** directly to its target destination (e.g. `ln -sfnT {{config_dir}} {{dest}}`), rather than linking individual files or subfolders.
+
+## Justfile Philosophy
+- Keep `Justfile` recipes declarative, clean, and minimal — **never use bash loops, subshells, or complex inline scripts**.
+- Always define paths at the top using `source_directory()` and `env("HOME")`.
+- Always set the default recipe to list commands:
+  ```just
+  @default:
+      just --list
+  ```
+- Every module `Justfile` **must** expose a `deploy` recipe.
+
+## Git & Commit Convention
+- Follow Conventional Commits: `<type>(<scope>): <short imperative description>` (or `<type>: <description>` for root-level changes).
+  - Allowed types: `feat`, `fix`, `refactor`, `chore`, `doc`, `ops`.
+  - `<scope>` is the module name (`niri`, `xxh`, `agents`, etc.).
+  - Keep messages lowercase, concise, and without a trailing period (e.g., `feat(agents): add initial skills`, `refactor(xxh): standardize justfile`).