I keep seeing this question in the community. Here's what I actually tried, why it broke, and what I ended up shipping.
The problem
When you're running multiple agents across a session (one that writes, one that reviews, one that deploys) you need them to share state. Not just conversation history. Actual verified state: what changed, what's blocked, what evidence exists that a task is done.
What I tried first (and why it failed)
Attempt 1: I maintained the handoff notes myself
After every session, I updated a Markdown file. This worked until I finished tired and skipped the update. The next agent read stale context as if it were current. Worse: even when the file was accurate, I was still the router, a human bottleneck between every agent transition.
Attempt 2: I let agents maintain the notes
The agent finished its work, updated the handoff, and the next continued from there. Then I noticed the real problem: an agent could write "tests pass" just as easily as it could actually run the tests.
Agent A would write: "Refactored auth. Tests pass."
Agent B had no idea which tests ran, against which version, or whether the slow integration suite was skipped. It didn't inherit verified work. It inherited a story about the work.
What I built
Three principles became the foundation:
State in fields, not paragraphs. What changed, what's blocked, what's unresolved as explicit fields, not embedded in a summary. An agent can't make unresolved work disappear by writing a nicer paragraph.
The agent that does the work can't approve it. A separate reviewer starts from the original goal and inspects the result directly, not from the implementing agent's explanation of why it's probably done.
Machine-checkable claims need evidence attached to a specific version. "Tests pass" is a claim. A test result attached to the exact commit hash is evidence. If the code changes after the evidence was produced, the evidence doesn't automatically transfer.
This became an open-source project (link in comments).
Results over 30 days of dogfooding
4,172 PRs merged across 16 repositories, one maintainer
Coordination overhead stayed roughly flat from 3 agents to 10; adding agents stopped adding to my mental load linearly
Stale-context bugs dropped to near zero because agents can't declare victory without attached evidence
The number I actually care about: my day looks the same with 3 agents as with 10. That wasn't true before.
What didn't work
The reviewer agent still occasionally fails to distinguish "the goal changed mid-task" from "the implementation is wrong." We handle this with an explicit goal-hash that both agents reference, but it adds friction. Still working on the right UX for that.
Has anyone else hit the "agent self-reports done but the work isn't clean" problem? Curious what enforcement patterns people are using, if any.
