From ffab815f6ba8f1055c0b20fe6c14e82914157059 Mon Sep 17 00:00:00 2001 From: Johannes Kresner Date: Wed, 8 Apr 2026 17:50:35 +0200 Subject: [PATCH] docs: add repository agent guidance --- AGENTS.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..da18fb4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md + +## Purpose + +This repository uses `docs/` as the source of truth for technical documentation and implementation planning. + +## Working Rules + +1. Keep the root `README.md` short and navigational. +2. Keep detailed technical documentation in `docs/`. +3. Update relevant documentation in the same change whenever implementation changes: + - architecture + - protocol or state machine + - integrations or tool behavior + - deployment assumptions + - backlog ordering or exit criteria +4. Treat `docs/backlog.md` as the current phased implementation backlog. +5. Prefer small, safe increments that keep docs and implementation aligned. + +## Documentation Map + +- `docs/overview.md` — project overview and scope +- `docs/architecture.md` — system structure and pipeline +- `docs/protocol.md` — event contract and state machine +- `docs/integrations.md` — service integrations and tool safety +- `docs/deployment.md` — deployment topology, security, and risks +- `docs/backlog.md` — phased implementation backlog + +## Update Expectations During Implementation + +- If code changes behavior, update the matching document before considering the work done. +- If implementation reveals a new constraint or decision, document it in the most relevant existing file. +- If a document becomes too broad, split it into smaller files instead of overloading the root `README.md`. +- Do not silently let docs drift from implementation.