Agent Collab Treaty

A drop-in documentation contract for repositories worked on by agents, humans, or both. Five Markdown files and an archive folder at your repo root, doing two jobs:

• Agent handoff. The next session picks up where the last one left off — less repeated reading, fewer lost decisions — whether it's the same agent, a different model, or a different machine.
• Planning and work log, for you. The same files are a running record of what's in flight, what shipped, and what was decided and why. Plain Markdown in git: nothing to log into, diffable, and ready to lift straight into a status update.

Language- and framework-agnostic — code repos, but also prose, research, and ops. Your agent can set it up in two prompts and maintain it unsupervised from there. Battle-tested across Codex, Claude Code / Cowork, and Grok Build with near-zero friction.

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
• Badge
• Why "Treaty"
• Developer Notes

What's In The Template

Those first two files 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.

See It In A Real Project

Not samples — living docs, filled in by months of real sessions:

• sleep_scoring — sleep-staging app; 39 dated entries since April 2026, rotated across 8 archive chunks: work_log.md · next_steps.md
• fp_analysis — fiber-photometry app; 20 dated entries since March 2026, 21 sessions in the live log alone: 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

Hand this to your agent — that's the intended path, and how these docs are maintained in practice:

pip install agent-collab-treaty, then run treaty init in this repo.

pipx install agent-collab-treaty     # isolated (recommended)
pip install agent-collab-treaty      # or in a regular venv

cd your-project && treaty init

pipx run copier copy gh:yzhaoinuw/agent_collab_treaty .

Set Up

treaty init leaves bracket placeholders for the project-specific parts. One prompt fills them:

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. The only recurring ask is the occasional update.

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"]'

Update

Occasionally, when a new treaty version lands:

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.

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 add -A && git commit -m "wip"     # update refuses a dirty tree
treaty update --dry-run               # preview without writing
treaty update                         # apply

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.

# after resolving what treaty update listed:
git add -A && git commit

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, and next_steps.md "Currently Hot" links. Exits non-zero when issues are found; --warn-only keeps it advisory.

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:

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

When a new agent session opens:

1. Read AGENTS.md first.
2. Use its documentation map to open only the relevant docs.
3. Read the top of work_log.md for recent context.
4. Check next_steps.md → "Currently Hot" for active priorities.
5. Do the work, following the conventions in AGENTS.md.
6. At the end of substantive work: run the pre-flight checklist, run treaty validate, prepend an entry to work_log.md, and update next_steps.md if follow-up changed.

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.

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.

[![Agent Collab Treaty](https://raw.githubusercontent.com/yzhaoinuw/agent_collab_treaty/main/assets/treaty-adopted.svg)](https://github.com/yzhaoinuw/agent_collab_treaty)

[![Agent Collab Treaty](https://img.shields.io/badge/Agent_Collab_Treaty-adopted-6d81f1?style=flat-square)](https://github.com/yzhaoinuw/agent_collab_treaty)

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.

Developer Notes

For maintainers of this repository. If you're using the treaty, you want Set Up instead.

Two GitHub Actions workflows handle publishing, both via PyPI Trusted Publishing (OIDC), so no API tokens are stored in the repo:

• .github/workflows/release.yml — fires on a v* tag push, builds sdist + wheel, publishes to PyPI, creates a GitHub Release.
• .github/workflows/test-publish.yml — manual workflow_dispatch, publishes to TestPyPI for dry-runs.

Cutting a release:

gh workflow run test-publish.yml      # dry-run to TestPyPI first

# smoke-test the dry-run:
pipx install --index-url https://test.pypi.org/simple/ \
  --pip-args="--extra-index-url https://pypi.org/simple/" agent-collab-treaty

# then bump the version in pyproject.toml and __init__.py, and:
git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0