From 7137aa15c5bf93242791c89e00d3a17a0582011c Mon Sep 17 00:00:00 2001
From: Valentin Haudiquet <valentin.haudiquet@canonical.com>
Date: Sun, 20 Sep 2026 23:08:28 +0200
Subject: [PATCH] docs: add AGENTS.md with commit and code conventions

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

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..c9f04a8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,82 @@
+# AGENTS.md
+
+Conventions for working in this tree. They apply to every commit; the
+whole history follows them.
+
+## Before every commit
+
+Run, in order, and make sure they are clean before committing:
+
+```sh
+cargo fmt --all
+cargo clippy --all-targets   # no new warnings
+cargo test                   # keep green when touching behavior
+```
+
+These mirror CI (`.github/workflows/ci.yml` runs check, `fmt --check`,
+clippy, and `cargo test --all-features`). `cargo fmt` may amend files
+you did not touch — include those changes in the commit (or in a
+separate `chore:` commit) rather than leaving the tree dirty.
+
+## Commit messages
+
+Follow Conventional Commits with a component scope:
+
+```
+<type>(<scope>): <short summary>
+```
+
+Rules:
+
+- Types: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `build`,
+  `ci`, `chore`.
+- Scopes match the component touched — the module name under `src/`:
+  - `cli` — entry point and flags (`src/main.rs`, `src/cli.rs`)
+  - `config` — config file (`src/config.rs`)
+  - `distro` — distro definitions and mirrors (`src/distro.rs`)
+  - `download` — image download (`src/download.rs`)
+  - `extract` — rootfs extraction (`src/extract.rs`)
+  - `chroot` — chroot setup (`src/chroot.rs`)
+  - `namespace` — Linux namespaces (`src/namespace.rs`)
+  - `mount` — bind mounts and mount table (`src/mount.rs`)
+  - `kernel` — kernel/initramfs handling for `--kernel` (`src/kernel.rs`)
+  - `qemu` — QEMU VM mode (`src/qemu.rs`, `src/qemu_vm.rs`)
+  - `utils`, `verbose` — shared helpers (`src/utils.rs`,
+    `src/verbose.rs`)
+  - `deps` — dependency additions/bumps (manifests, lockfile)
+- Omit the scope entirely for repo-wide changes that do not belong to a
+  single component (README.md, SPEC.md, root config).
+- Summary: imperative mood ("add", never "added" or "adds"), lowercase
+  first letter, no trailing period, max ~72 characters.
+- Body (optional): separated by a blank line, wrapped at 72 columns;
+  explain why rather than what. Reference issues as `#123`.
+- A commit touching several components should be split into one commit
+  per component when practical; otherwise use the dominant scope.
+- **No merge commits.** Integrate work by rebasing onto the target
+  branch (`git rebase`, `git pull --rebase`, `git cherry-pick`); the
+  history stays linear. When several work streams run in parallel, land
+  them one rebase at a time.
+
+### Examples
+
+```
+feat(namespace): set unique hostname per run
+fix(extract): handle hard links in rootfs archives
+fix(kernel): parse =PATH syntax for --kernel
+test(chroot): cover path resolution helpers
+feat(qemu): enable KVM when available
+deps: bump nix to 0.31
+docs: document QEMU system mode and =PATH syntax
+chore: apply cargo fmt
+```
+
+## Code
+
+- Tests live inline as `#[cfg(test)]` modules at the bottom of each
+  `src/` module; there is no `tests/` directory. Scope test commits to
+  the module under test.
+- Comments state constraints the code cannot show; no narration.
+- Anything user-facing (CLI flags, config keys, error text users act
+  on) is reflected in `README.md` before commit.
+- Design decisions that outlive the session go to `SPEC.md`, not to
+  new docs or repos.