This is exactly the answer I was hoping for in this thread: ugly practical details, not polished theory.
A HANDOFF document that the outgoing agent writes is a smart move. It solves two problems we discussed above at once: it gets rewritten on every handoff, so it’s always “today,” not “what I thought on Tuesday” so no buildup of stale context, and it’s plain text, the only language all tools understand. Walled garden memory in each tool is basically the root of all this pain.
Your two “faceplanting first” lessons are the most valuable:
- A small always on brief separate from the big handoff. It’s basically the same role as
AGENTS.mdor Memories: 3 lines of “who I am and what I’m working on,” so the agent doesn’t start from scratch before it even opens the main document. - Findability after compaction. This is a real pain point. It helps to keep the handoff at a fixed path and link to it directly from
AGENTS.mdor from the always on brief, so the agent doesn’t have to remember “wait, where did I put that.”
I’m curious: do you write this HANDOFF by hand, or do you ask the agent to generate it at the end of the session using a template? And has it held up for a couple months of active development without degrading, or do you still need to clean it up manually from time to time?