Agent Collab Treaty
A set of project docs that AI coding agents read before they work and write back to before they leave. Five Markdown files in your repo — two at the root, the rest in agent_worklog/ — doing three jobs:
- Agent handoff. The next session picks up where the last one left off, whether it's the same agent, a different model, or another machine.
- A project record for you. What's in flight, what shipped, and what was decided and why. Plain Markdown in git, ready to lift into a status update.
- AI-use disclosure, already written. Each session logs the model that did the work and what it decided, as it happens. When a journal, funder or reviewer asks how AI was used, point them at the folder — sleep_scoring's JOSS manuscript does exactly that.
Doesn't my agent already have memory? Yes, but only for itself. Built-in memory is tied to one tool and one account, and it's hard to review. These docs live in the repo: every agent and every collaborator reads the same record, and git keeps its history.
Language- and framework-agnostic. Your agent sets it up in two prompts, maintains it unprompted, and tells you when an update is out. Battle-tested across Codex, Claude Code / Cowork, and Grok Build.
How to read this README. Each blockquoted "Prompt" is a sentence you paste into your AI coding agent (Claude Code, Codex, Cursor, Gemini CLI, …), not a shell command. You need nothing installed first: the agent installs the CLI and runs it. Each prompt has a collapsed "Prefer to run it yourself?" section with the equivalent terminal commands.
Contents
- What's In The Template
- See It In A Real Project
- Install
- Set Up
- Update
- Validate
- Wiring Up Your Agent
- The Workflow In Practice
- Why "Treaty"
- Badge
- Contributing
What's In The Template
| File | Purpose |
|---|---|
AGENTS.md |
First-read contract: startup rule, doc map, runtime, common tasks, commit conventions, project reminders. This is the file you customize. |
project_overview.md |
Orientation map: active vs. legacy code, authored vs. derived files, repo structure, where to look first. |
agent_worklog/treaty_conventions.md |
The generic mechanics AGENTS.md links to: work-log criteria, rotation and dating rules, branch handoff, release gate, update procedure. Maintained upstream — leave it alone and treaty update keeps it current. |
agent_worklog/next_steps.md |
Active roadmap. "Currently Hot" points agents at the threads that matter now. |
agent_worklog/work_log.md |
Session journal, newest first. Agents prepend substantive work before handoff. |
agent_worklog/work_log_archive/ |
Rotated older work-log chunks, so the live log stays cheap to read. |
agent_worklog/README.md |
Tells anyone browsing the repo — a reviewer, a new contributor — what the folder is, before they open a file. Maintained upstream. |
AGENTS.md and treaty_conventions.md split along how they're maintained — your answers in one, shared mechanics in the other. That's what keeps treaty update close to conflict-free.
The working docs sit in agent_worklog/ so they don't crowd your repo root; AGENTS.md and project_overview.md stay at the root, where a newcomer and an agent both expect to find them. Set the docs_dir question to rename that folder, or to . to keep every file flat at the root. Projects installed before v0.8.0 stay flat automatically — see Where the docs live under Install.
See It In A Real Project
Not samples — living docs, filled in by months of real sessions:
- sleep_scoring — sleep-staging app, logged since April 2026 (folder layout): agent_worklog/ · work_log.md · next_steps.md
- fp_analysis — fiber-photometry app, logged since March 2026 (flat layout): work_log.md · next_steps.md
- This repo maintains itself the same way: work_log.md · next_steps.md
Open any work_log.md and read one entry. It says why something was decided, not which files changed — that's what makes it worth reading months later, by an agent or by you.
Install
Handing the install to your agent is the intended path, and how these docs are maintained in practice.
Prompt — type this into your agent's chat:
pip install agent-collab-treaty (needs Python 3.10+), then run
treaty initin this repo.
The agent installs the CLI, runs treaty init, and answers its questions with you. Nothing needs to be installed on your side first.
On macOS, python3 is often Apple's 3.9, whose pip says "No matching distribution found" rather than "Python too old". If python3 --version is below 3.10, install with a newer interpreter (python3.13 -m pip install …, or conda's python -m pip install …).
Prefer to run it yourself?
pipx install agent-collab-treaty # isolated (recommended)
pip install agent-collab-treaty # or in a regular venv
cd your-project && treaty init
treaty init asks a few short questions and writes the treaty files into the current directory.
Other ways to install the treaty
The CLI is a thin wrapper around Copier, so you can skip it:
pipx run copier copy gh:yzhaoinuw/agent_collab_treaty .
Or copy the files by hand from template/ — not from this repo's root, which holds our own dogfooded docs. Replace the Jinja placeholders in template/AGENTS.md.jinja, rename it to AGENTS.md, and fill in the bracket placeholders in the other files. The literal {{ docs_dir }} directory in there is the docs folder awaiting its name: copy its contents into agent_worklog/ (or straight to the root for a flat layout, leaving out its README.md).
Hand-copied projects have no .copier-answers.yml, so treaty update and treaty diff won't work on them — you'd copy new sections from template/ by hand instead.
Set Up
treaty init leaves bracket placeholders for the project-specific parts. One more prompt fills them.
Prompt — type this into your agent's chat:
Fill out the docs in the treaty.
That's the whole setup. The agent reads the repo, replaces the placeholders, and records what's in flight — the installed docs tell it the rest.
From there it's self-sustaining: sessions read AGENTS.md at startup, prepend to work_log.md before handoff, and keep next_steps.md honest, unprompted. Agents also tell you when a treaty update is out; saying yes is the only recurring ask.
Prefer to run it yourself?
Fill in the bracket placeholders in AGENTS.md (runtime, common tasks, project reminders) and project_overview.md (entrypoints, active vs. legacy, authored vs. derived), then put whatever is in flight into next_steps.md and run treaty validate ..
Leave work_log.md empty — it starts accumulating from the next session. Backfilling it from git history produces exactly the "implemented function X" noise the log exists to avoid.
Non-interactive install, if you're scripting adoption:
treaty init . --defaults \
--data integration_branch=main \
--data env_activation='conda activate myenv' \
--data verification_command='pytest -v -m "not slow"' \
--data has_releases=false \
--data 'agent_pointers=["claude-code", "cursor"]'
The questions it asks
Three questions drop sections that don't apply to your project. All default to yes, so code repos see no change:
| Question | Answering no drops |
|---|---|
has_releases |
The "Release / Tag Checklist" section (and the release gate in treaty_conventions.md) |
uses_precommit |
The "Pre-commit Note" section |
include_git_ownership_note |
The "Git Ownership Note" section |
Opting out beats deleting: a section that never rendered can never conflict, while a section you deleted collects a conflict every time upstream revises it.
Three more worth knowing:
docs_diris the folder the working docs live in,agent_worklogby default (treaty_docsbefore v0.11.0). Answer.to keep everything flat at the repo root. See Where the docs live below.env_activationacceptsnonefor projects that deliberately have no managed environment.AGENTS.mdthen says so explicitly, instead of leaving an agent to helpfully create a venv.verification_commandis whatever proves the repo is in good shape —pytest,npm test, a link checker, a lint pass, ortreaty validate .. It replacedtest_commandin v0.5.0; older projects carry their recorded answer over automatically.
Where the docs live
New installs put the working docs in agent_worklog/, leaving AGENTS.md and project_overview.md at the repo root:
your_repo/
|- .copier-answers.yml
|- AGENTS.md
|- project_overview.md
|- agent_worklog/
| |- README.md
| |- treaty_conventions.md
| |- next_steps.md
| |- work_log.md
| |- work_log_archive/
Until v0.11.0 the default folder was treaty_docs/. Projects installed with it keep that name, because treaty update never moves files. They get the folder README on their next update, and treaty relocate --to agent_worklog renames the folder if you want. The README is only rendered for folder layouts, since in a flat layout the name belongs to your project's own README. If your docs folder already had a README.md, the update shows it as a conflict. Keep your version.
AGENTS.md has to stay at the root: agents resolve the nearest AGENTS.md up the directory tree, so one nested inside agent_worklog/ would apply only to files inside that folder — the opposite of what you want. project_overview.md stays with it as the human-facing entry point.
.copier-answers.yml stays at the root too, whatever docs_dir is. It records your answers (including docs_dir itself) and the template version you're pinned to, and treaty update / treaty diff read it from there. Commit it: a gitignored answers file breaks every later update, which is why treaty init warns about one and treaty validate flags it.
Projects installed before v0.8.0 are not moved. They have no recorded docs_dir, and treaty update pins those to the flat layout automatically, so updating changes nothing but adds docs_dir: '.' to .copier-answers.yml. After updating a flat project, treaty update prints a one-line reminder that treaty relocate can move the docs; nothing moves unless you run it.
To move an existing project into a folder, use treaty relocate:
treaty update # first: records docs_dir
git commit -am "Update the treaty" # or skip this and pass --force below
treaty relocate --dry-run # see the plan
treaty relocate # apply it
treaty relocate wants a clean tree, so the relocation is one change you can undo on its own. To relocate on top of the update's uncommitted changes and commit both together, pass --force; that is what it is for.
In one pass it moves the working docs with git mv (so history follows), rewrites the doc links in AGENTS.md and project_overview.md, retargets links inside the moved docs for their new depth, and records the new docs_dir. It also handles the folder README: it writes one when leaving the root and removes an unedited one when flattening. When it finishes, everything it changed is staged, and it prints the git add for earlier changes it left alone. --to picks the folder; --to . flattens back to the root.
Two things it will not do silently:
- It refuses to run before
treaty update. A project whose answers predatedocs_diris pinned to a template that hardcodes the flat paths, so moving first guarantees a conflict on the next update. The command says so and stops. - It checks your
.gitignore. If your repo denies everything (*) and re-allows specific files, those rules stop matching once the docs move — already-tracked files survive, but the next work-log rotation is silently untracked.treaty relocatenames the offending rule, andtreaty validatekeeps flagging it (treaty-doc-gitignored) until it is fixed.
Links pointing in both directions are handled, but differently:
- Out of a moved doc, at your own files — a
[demo](media/README.md)innext_steps.md— is rewritten to../media/README.mdso it still resolves. URLs, bare anchors, absolute paths, and links that were already broken are left exactly as written. The dry run lists these before it touches anything. - Into the treaty docs, from files the treaty does not own — your README, CHANGELOG, CI config — is reported, with line numbers, but never rewritten. Those are yours to update.
Adding the treaty to a project that already has docs
treaty init runs a non-destructive preflight first. It warns about existing treaty files, case-mismatched ones such as Work_Log.md, and common planning docs such as TODO.md, ROADMAP.md, NOTES.md, or CLAUDE.md. It never moves, archives, rewrites, or deletes anything, and matching treaty paths are skipped rather than overwritten.
Case-mismatched treaty-looking paths block the install, because they can prevent canonical files from being created — especially on Windows. Rename or archive them, then rerun.
To fold existing docs into the treaty, say so explicitly — migration touches files the treaty otherwise never rewrites.
Prompt — type this into your agent's chat:
Migrate this repo's existing planning and logging docs into the treaty. Preserve the originals.
Update
Occasionally a new treaty version lands. One prompt takes care of it.
Prompt — type this into your agent's chat:
Update the treaty.
This is the step most worth handing over. The merge can leave conflicts, and resolving them is judgment work — deciding which side of each hunk is your content and which is new upstream guidance. The agent doesn't need telling: the procedure is in the treaty_conventions.md sitting in your repo.
Prefer to run it yourself?
pipx upgrade agent-collab-treaty # get the latest CLI first
treaty --version # CLI version, and the template you're pinned to
treaty diff # which sections would conflict?
git status # update needs a clean tree: commit or stash first
treaty update --dry-run # preview: answer changes, updated files, conflicts
treaty update --dry-run --diff # ...plus the full diff of each file
treaty update # apply
treaty update does a three-way merge from your pinned version up to the latest release, so edits that don't overlap upstream changes are kept automatically. If any file is left conflicted, the command names it and exits non-zero — a conflicted update is never reported as a success.
treaty update --dry-run runs that same merge in a disposable clone of your committed state and prints the summary a real apply would print — planned answer changes, files that update cleanly, files that would conflict — without writing anything to your project. It exits non-zero when the merge would conflict, so scripts can use it the same way as a real apply. Because the clone is of your committed state, uncommitted edits aren't previewed — but --data values are, since they come from the command line. Add --diff to see what changes inside each file, not just which files; the release notes list the CLI changes and which template files each release touches.
Upgrade the CLI first, as in the block above. An old CLI runs without complaint, and its treaty validate passes without knowing what the new template expects.
You don't have to remember to check. Since v0.11.0, agents run treaty update --dry-run each time they rotate the work log (about every five working days) and tell you if a newer version is out. Updating stays your call.
Answering questions that are new in the target version. Recorded answers are reused, and any question added since your pinned version silently takes the template default. Name the ones you care about with --data, repeatable:
treaty update --data uses_precommit=false --data verification_command="python -m pytest -q"
Without it, a big version jump means re-answering every question with --interactive, or hand-editing .copier-answers.yml. --data docs_dir=… is refused on purpose — changing the layout through Copier deletes your customized docs and writes pristine ones at the new path, which is what treaty relocate exists to do safely.
treaty diff writes nothing. It renders the template version you're pinned to into a temp directory and compares section by section:
AGENTS.md
untouched 9 modified 1 removed 3 added 1
! removed: '## Release / Tag Checklist' — upstream edits arrive with nothing local to merge into
~ modified: '## Runtime Environment'
Conflict exposure: 4 section(s) across 1 file(s) would conflict if upstream revises them.
What your edits cost at update time
Cost depends on what you edit, not how much:
| Edit | Cost on treaty update |
|---|---|
| Filling in a bracket placeholder | None. Upstream never ships a revision to [path/to/entrypoint]. |
| Adding a section | None. Additions always merge cleanly. |
| Rewriting a maintained body | A conflict whenever upstream revises the same region. |
| Deleting a section | A conflict every time upstream touches it, with nothing local to merge into. Prefer the has_releases / uses_precommit / include_git_ownership_note answers, which stop it rendering at all. |
| Renaming a heading | The worst case. The merge reads it as a delete plus an unrelated add, so it conflicts and can't be auto-resolved. Change the body, keep the heading. |
treaty diff reports this breakdown for your project, and calls out renamed headings by name so you can restore the upstream heading and keep your body. work_log.md and next_steps.md are yours by design, so their drift is reported but never counted as risk.
Resolving conflicts, and the git requirement
Where your edits overlap a changed region, the merge leaves standard markers (<<<<<<< before updating / >>>>>>> after updating) in an unmerged file. Resolve them like any git merge — keep your content, fold in the new sections — and don't commit unresolved markers:
# after resolving, stage every file treaty update listed, conflicted or not:
git add AGENTS.md .copier-answers.yml && git commit
Stage .copier-answers.yml along with the resolved files: it records the new template version, and committing the merge without it leaves the project pinned to the old one. treaty update prints the exact git add line for you; it names files rather than using git add -A, so untracked files you kept out of the way during the update stay out of the commit.
After merging, treaty update prints a summary: old → new template version, answer changes, updated files, conflicted files. "Updated files" counts content changes only. Under core.autocrlf=true, Git can keep listing files whose line endings were rewritten during the merge; the summary lists those separately, and committing them changes nothing. Your recorded answers are reused by default; pass --interactive only to re-answer the template questions.
The project must be git-tracked with a clean working tree — Copier uses git for the three-way merge and to show a reviewable diff. Run git init && git add . && git commit -m "treaty baseline" once if you haven't.
To keep unrelated untracked files (data, scratch output) from tripping the clean-tree check, list them in .git/info/exclude. Don't hide them with status.showUntrackedFiles=no, and make sure *.rej isn't gitignored (a repo that ignores everything with * can add a !*.rej exception): Copier finds each conflict through the .rej file it leaves in git status, so with either setting a conflicting file would be silently replaced by the template version. treaty update refuses to run under either one, and fails if a merge leaves a .rej behind anyway.
Validate
treaty --version # what you have, and what you're pinned to
treaty validate # in any project using the treaty
treaty validate --migration-hints # plus overlap hints for legacy docs
It checks canonical filenames, work_log.md structure, live-log rotation, session verification sections, next_steps.md "Currently Hot" links, and whether git would ignore the treaty docs themselves. Exits non-zero when issues are found; --warn-only keeps it advisory.
Some checks are warnings, which print but never fail:
- a
CLAUDE.mdthat doesn't importAGENTS.md(a line asking Claude to read it isn't an import;@AGENTS.mdis); - a
treatyCLI older than the template your project is pinned to; - template placeholders still unfilled, such as
[what it does]or links topath/to/.... A fresh install has plenty, and an update can add a section full of them to a doc you finished long ago; - template text that only your copy can fix: the "Setting this up for the first time?" paragraph in a work log that already has entries, an "Other sections below are background or paused" line sitting above active threads in
next_steps.md, and a Currently Hot thread filed under Background / Paused.
The template keeps that text because changing work_log.md or next_steps.md upstream would conflict with nearly every adopter's own edits. So validate points it out instead, and you delete it once.
Wiring Up Your Agent
AGENTS.md is the one file every agent should read at session start. Some tools load it directly; others want a small pointer file, which treaty init can generate:
| Tool | Pointer | Notes |
|---|---|---|
| Codex | none | Reads AGENTS.md natively. |
| Claude Code / Cowork | CLAUDE.md |
Imports AGENTS.md with Claude's @AGENTS.md syntax. |
| Cursor | .cursor/rules/treaty.mdc |
Always-applied project rule pointing back to AGENTS.md. Cursor also supports root AGENTS.md directly. |
| Windsurf | .windsurf/rules/treaty.md |
Always-on workspace rule pointing Cascade back to AGENTS.md. Windsurf also processes root AGENTS.md directly. |
| Aider | .aider.conf.yml |
Configures Aider to always read AGENTS.md as read-only context. |
For any other tool, add a one-line default instruction: "At the start of every new chat or session in this repository, read AGENTS.md first and follow the documentation map there."
The Workflow In Practice
This section describes what your agent does on its own — it is not a checklist for you to follow or to paste into a chat. The installed docs already tell the agent all of it. It's written out here so you know what a session should look like, and can tell when one has skipped a step.
When a new agent session opens, the agent:
- Reads
AGENTS.mdfirst. - Uses its documentation map to open only the relevant docs.
- Reads the top of
work_log.mdfor recent context. - Checks
next_steps.md→ "Currently Hot" for active priorities. - Does the work, following the conventions in
AGENTS.md. - At the end of substantive work: runs the pre-flight checklist, runs
treaty validate, prepends an entry towork_log.md, and updatesnext_steps.mdif follow-up changed. When the log needs rotating, it also checks for a treaty update and tells you if one is out.
Your only part in this is saying yes to the occasional update.
The rule that decides what goes in the log: it records decisions about the project, not the content of the work produced. The work itself is already in version control. "Implemented function X" and "drafted chapter 4" are noise for the same reason — the diff already says that. What belongs is the decision, the reversal, the approach tried and discarded and why, and evidence a future agent would otherwise have to rediscover.
That rule is also what makes the log worth reading for you. Because it captures decisions rather than activity, next_steps.md answers "where does this stand?" and work_log.md answers "what did we decide, and why?" — the two questions a status update or a handoff to a colleague actually needs. It costs no extra bookkeeping: the agent writes it as part of finishing the work.
treaty_conventions.md carries the full criteria, plus the log rotation policy that keeps work_log.md cheap to read.
Why "Treaty"
Because it's a small agreement about where project context lives, what agents read first, and what they write back before leaving.
Treat it as a starting point, not a fixed standard. Add a "CI Note" section for your stack's commands, a "Domain Reminders" section for non-obvious gotchas, extra project_overview.md subsections for the diagrams or schemas that matter. Keep additions coherent with the existing structure rather than rewriting it — the value of a shared template is that every repo looks the same to the next agent.
Badge
treaty init offers an opt-in "adopted" badge. It's hosted centrally by this repository, so your project receives no extra files and picks up any future design improvements automatically.
[](https://github.com/yzhaoinuw/agent_collab_treaty)
Why this one, and the fallback for non-GitHub renders
The tri-color SVG above is the primary recommendation: its text is outlined to vector paths, with no embedded or system font, so it renders identically on GitHub across every platform — no font substitution, no clipping.
Use the single-color shields.io fallback only if your README also renders outside GitHub — e.g. on PyPI or npm — where raw SVG images may be sanitized or blocked:
[](https://github.com/yzhaoinuw/agent_collab_treaty)
This repo's own README uses the tri-color badge via a relative path; adopters use the raw.githubusercontent.com URL, which is the same image.
Contributing
Bug reports, feature ideas, and PRs are welcome — see CONTRIBUTING.md. It's the contributor front door, and it also carries the release and publishing mechanics for maintainers. To cite the project, use the repo's CITATION.cff (GitHub's "Cite this repository" button) or the DOI badge above — 10.5281/zenodo.21746757, which always resolves to the latest archived release. Zenodo also mints a DOI per release if you need to cite a specific version.
Metadata
Release files for agent-collab-treaty 0.11.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_collab_treaty-0.11.1.tar.gz | 173.5 kB | With provenance | Details for agent_collab_treaty-0.11.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_collab_treaty-0.11.1-py3-none-any.whl | Python 3 | none | any | Details for agent_collab_treaty-0.11.1-py3-none-any.whl |
Total release size: 221.1 kB
Release files / agent_collab_treaty-0.11.1.tar.gz
| Download URL | agent_collab_treaty-0.11.1.tar.gz |
|---|---|
| Size | 173.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0ce5741915fb28f9c2acef88cebaae3f3c6bb0eee71d8697f47015f70e2ea40
|
|
BLAKE2b-256 checksum How to use checksums |
d85f29cd800a4a1d87d1c31a7475a851ae2ffb20bd72cb5c4f9de40dc5324211
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / agent_collab_treaty-0.11.1-py3-none-any.whl
| Download URL | agent_collab_treaty-0.11.1-py3-none-any.whl |
|---|---|
| Size | 47.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8b971393156641425ebb08dfa6effe76b732e9f2d0d7636b7f32fecd78fb8d4
|
|
BLAKE2b-256 checksum How to use checksums |
1c719db58f73d3d3569224d054ebcfb27612df6a3642a404bcd9a00762148662
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logSecurity for agent-collab-treaty 0.11.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_collab_treaty-0.11.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.