Expands the communications section from a list of what worked into the actual convention: the
directory's lifetime and the rule that anything durable must move to docs/ before the merge;
numbering, parity as attribution, non-consecutive numbers; slugs; reply-in-a-new-file and the
one case where editing your own is right; referring to commits by sha because three remotes
carried the same branch names.
Records what a handoff must contain, with the verified/assumed split named as the rule that
carried the most weight — a handoff confident about something untested is worse than none,
because the reader builds on it. Adds a skeleton to copy.
Documents termination as the four attempts it actually took, ending at the only checkable
version: the exchange pauses when no open item is actionable by a participant. Adds the third
state, deferred-with-a-reason, since a two-state protocol forces an agent to lie in one
direction. Notes that a stall must be detectable because the human spotted both before either
agent did.
Adds a review-discipline section — check the enforcement rather than the description, run it
against a real machine, a check never seen failing is not evidence, distrust vacuous passes,
expect stacked bugs, distrust "inert today", and look at which way unknown resolves. Adds a
failure-mode table to pattern-match against, and the git hygiene that bit us, including
merge-verify-then-delete, which I got wrong.
Closes with session economics, an ordered list of what to build, and the one thing not to
automate: agents may coordinate on what is true and must not decide what is permitted.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The owner could not convey this to the second agent, who launched it differently and got
something that looked identical and did not work. The script was never the hard part; the
mechanism is.
States the requirement so it survives a different harness — a detached shell process owned by
the agent's harness, which exits when it has something to say, and whose exit re-invokes the
agent — and notes that dropping any one of those three breaks it invisibly.
Then the four wrong ways, each of which looks correct while running. Backgrounding with nohup
or & produces a process that polls correctly, detects the push, exits, and never tells the
agent, because the harness is not tracking it; I made that exact mistake and caught it only by
re-reading my own command. A model-driven interval is functionally correct and pays a full
context re-read per tick to learn nothing — the intuitive design, and the expensive one, which
is why it is the first thing to warn a new agent about. A loop that does not exit on detection
has no path to the agent at all. And per-tick logging is deferred cost that lands all at once
on wake.
Also records why 30s polling is free in a shell and ruinous in the model, including the
five-minute prompt-cache TTL that makes any model-side wake beyond it pay for a full uncached
read.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
docs/agent-coordination.md states the objective — several agents on one body of work,
coordinating with each other rather than through the human — and was written in theory on
2026-08-07. On 2026-08-11/12 it ran for ten hours with two agents and the owner arbitrating.
This is what happened, written as evidence rather than proposal.
The load-bearing observation is narrower than "two reviewers are better than one": the person
who writes the sentence explaining why something is safe is the worst-placed person to notice
the code disagrees with it. One agent wrote "a wrong answer here must not happen by accident"
and shipped that accident in the same commit; the other wrote a verification script that could
not fail on the first one's machine. Neither was careless. Each was reading their own reasoning
back and finding that it agreed with itself.
Also records what only running found — an installer piped into the wrong shell, a parent
directory created root:root, an ACL mask clamped so the file browser could not read a member's
home, a chat cwd the member could not enter, ACL entries surviving a chown — all on first
executions, all invisible to review. And what the communications channel got right and the five
ways its termination rules broke, and why the repo watcher belongs in a shell loop rather than
in the model.
Names the identity gap as the first thing to build: both agents commit as the owner, so neither
the log nor an agent can say who wrote a line. docs/agent-git-identity.md has called that an
idea since 2026-08-10; it stopped being one tonight.
Also corrects the deprovision spec's status, which still said "not yet run against a real
account" after it had been run and verified clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5