One directory is the task manager my agents share

When you run agents across many projects, findings stop respecting project boundaries almost immediately. A session working on one tool discovers a bug in another. A review in one repo produces work for three. My first instinct was the obvious one, let the session go fix it over there. That instinct is how two agents end up editing the same tree, and after auditing five collisions I banned it. A session's only sanctioned write into another project is a queue entry.

The queue is embarrassingly low-tech, one directory per target, one markdown file per task, a status line in the front matter: pending, taken, done, dropped. No database, no integration, and the only board is a one-page summary generated from the files themselves. Files stay put forever as history, and the receiving project's next session gets offered its pending entries automatically when it starts, take, defer, or drop, and the answer is written into the entry so nothing ever asks twice.

handovers/
├── board.md                  generated from the entries, one page
├── site/
│   ├── 004-syndication.md    status: done
│   └── 007-display-shapes.md status: pending
└── tooling/
    └── 012-retry-helper.md   status: taken

The lifecycle is four states and two side doors:

              take                       evidence pasted
 pending ──────────────▶ taken ──────────────────────────▶ done
   │  ▲                    │
   │  │ date reached       └──▶ dropped, reason written into the entry
   │  │
   ▼  │
 snoozed, at most a week       severity: risk ignores the snooze and
                               resurfaces every session until dealt with

A complete entry fits on one screen:

---
status: done
severity: normal
created: 2026-08-09
---
# Align the retry helper with the new timeout API

The ask: the helper still passes an option the API dropped in v3.
Update the call sites and run the suite.
Context: the failing CI run, and the changelog entry that dropped it.
Acceptance: `npm test` exits 0 with the retry cases green.
Evidence: "12 passed, 0 failed", pasted by the taker, 2026-08-10.

What makes it work is not the format though, it's three authoring rules that came from watching it fail.

Every entry carries an acceptance test. The body is written so the receiving session needs nothing else, the ask, the context links, and how to know it's done. Entries that skipped this read like riddles a week later, and riddles get dropped.

Done requires evidence. One pasted line showing the acceptance test passing.

- An assertion without evidence is not done, it's a hope with a status field.

This rule came directly from catching claims of finished work that a thirty-second check would have disproven.

And absence claims name what was checked. An entry once justified itself with "no record says this value is deliberate" while the record said exactly that, one file over. I ruled on a false premise that day. Since then, "nothing documents X" is only writable alongside the list of places you looked.

There is also a small vocabulary for time and urgency, a snooze field that hides an entry until a date, hard-capped at a week because my setup changes too fast for longer parking, and a risk severity that ignores snoozing entirely and resurfaces every session until someone deals with it.

The part I like most, the same queue serves humans and machines. My nightly automation drains the same entries my interactive sessions do, skips the ones marked as needing me, and flips the same statuses with the same evidence rule. One protocol, no translation layer. For coordination between agents, I keep finding that a directory of honest text files beats anything cleverer I've tried.

The queue's best story is not in this piece though. It's the night my agents built the same feature twice, where every file told the truth and I was the part that didn't.