diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d7202f2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,106 @@
+# 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 --all-features   # zero warnings
+```
+
+CI builds and lints with `RUSTFLAGS: -Dwarnings`, so a `cargo build`
+warning fails the gate too. `cargo fmt` may amend files you did not
+touch — include those changes in the commit (or in a separate `fmt:`
+commit) rather than leaving the tree dirty.
+
+The test suite is heavy (chroots, ssh, network): always run the
+`#[cfg(test)]` modules of what you touch, and the full suite when
+changing shared plumbing (`report`, `logfmt`, `test_support`,
+`debian/`). Tests marked `#[ignore]` shell out or hit the network and
+are for deliberate ad-hoc runs (`cargo test -- --ignored`), not for the
+pre-commit pass. Building needs the gpgme/openssl system packages
+(`pkg-config libssl-dev libgpg-error-dev libgpgme-dev`).
+
+## Commit messages
+
+There are no conventional-commit types; the format is a component scope
+and a summary:
+
+```
+<scope>: <short summary>
+```
+
+Rules:
+
+- The scope is the component touched — the module under `src/` (file or
+  directory), named after the user-facing subcommand when that differs:
+  - `pull` — source package download (`src/pull.rs`)
+  - `chlog` — changelog entry generation (`src/changelog.rs`)
+  - `build` — source package builds, .dsc (`src/build/`)
+  - `deb` — binary package builds, .deb (`src/deb/`)
+  - `put` — PPA/archive upload (`src/put/`)
+  - `new` — package scaffolding (`src/new/`)
+  - `lint` — tree linting (`src/lint/`)
+  - `prune`, `package_info` — remaining subcommand modules
+  - `context` — build contexts: local, ssh, chroot/schroot, unshare
+    (`src/context/`)
+  - `debian` — Debian format primitives: control, versions, checksums,
+    arch (`src/debian/`)
+  - `apt`, `launchpad`, `distro_info`, `quirks` — archive/distro
+    integration
+  - `report` — BuildView/Prompter ports and the views implementing them
+  - `ui`, `logfmt` — terminal rendering and output classification
+  - `data` — the `data/*.yml` embed convention itself; content changes
+    to a data file belong to the commit of the module consuming it
+  - `cli` — the binary, argument wiring (`src/main.rs`)
+  - `test` — test-only changes (shared plumbing: `src/test_support.rs`)
+  - `deps` — dependency additions/bumps (manifests, lockfile)
+  - `fmt`, `clippy` — rustfmt/clippy fixups
+  - `ci`, `snap`, `docs` — workflows, snap packaging, README
+- Use the submodule path when the change is confined to one
+  (`apt/keyring`, `debian/version`).
+- A commit touching several components should be split into one commit
+  per component when practical; otherwise comma-join the scopes without
+  spaces (`pull,deb`).
+- Summary: imperative mood, lowercase first letter (proper nouns keep
+  theirs: Ubuntu, SRU, lintian), no trailing period, max ~72 characters.
+- Body (expected for anything nontrivial): separated by a blank line,
+  wrapped at 72 columns; explain why, and the design when the approach
+  was a choice among alternatives. Reference issues as `#123`.
+- Reverts use git's default `Revert "<original subject>"`.
+
+### Examples
+
+```
+chlog: fall back to the changelog history when no version tag exists
+ui: ellipsize fake-terminal pane lines wider than the terminal
+lint: add pkh lint, wrapping lintian for parity plus pkh-native checks
+chlog: number Ubuntu backports with the per-release SRU scheme
+deb: resolve cross pkg-config against the target multiarch
+pull,deb: add top-level --pocket option
+debian/version: dpkg-compatible version comparison
+deps: bump git2 to 0.21
+fmt: apply rustfmt
+docs: refresh the README roadmap for 1.0
+```
+
+## Code
+
+- The crate denies missing docs (`#![deny(missing_docs)]` in
+  `src/lib.rs`): every public item carries a doc comment, and the module
+  list there is the layout map — keep it in sync when adding a module.
+- Subcommand business logic lives in the library and reports through the
+  `report` ports (`BuildView`, `Prompter`) instead of printing;
+  `src/main.rs` is argument wiring only. Subprocess output
+  classification is pure logic in `logfmt`, testable without a pty.
+- Static reference data (series tables, keyserver URLs, licenses,
+  forges, templates) lives in `data/*.yml`, embedded with the
+  `embed_data!` macro — not in hardcoded tables.
+- Comments state constraints the code cannot show; no narration.
+- Anything user-facing (subcommands, flags, option defaults) is
+  reflected in `README.md` — including its roadmap checklists — before
+  commit.
\ No newline at end of file