May 3, 2026 · 5 min read
For about three months I ran an AI-operated news site with a stack of markdown files holding the project’s working memory. There was a CLAUDE.md for instructions. A learnings.md for cross-project lessons. A roadmap.md for the council to read. A MEMORY.md index pointing at fifty-something memory files. A project_next_session.md that was supposed to be the queue of upcoming work.
It worked. Mostly.
The thing that did not work was that I never knew, at a glance, what was in flight.
The agent knew. Or some agent knew. Different agents read different files. The session-start memory load was its own subsystem. I’d ask, “is the comments anti-bot work still active?” and the answer was buried in a paragraph in project_next_session.md that had not been touched in three weeks. By the time I’d verified it, I had lost the original question.
So I built a kanban board. One session — design locked one evening, all six phases shipped the next morning. About 550 lines of TypeScript wrapped around a single YAML file, behind the existing admin Basic Auth. Five columns: inbox, parked, next, doing, done.
That’s it. That’s the whole thing.
It changed how I work with the agents more than any of the harder infrastructure I’ve built this year.
WHAT WAS ACTUALLY BROKEN
The phrase “human-AI collaboration” gets used a lot. In my experience the bottleneck was not the AI. The agents were perfectly happy to read whatever I pointed them at.
The bottleneck was that I had no idea what I’d asked them to do. My own intent was scattered across markdown files I’d forgotten I’d written.
A few specific failure modes:
- I’d start a session, the agent would faithfully load
project_next_session.md, and I’d discover I’d told myself two weeks ago that “F8 is the next priority” — a card I had no current opinion on. - I’d add a TODO to a session note, that note would compact, and the TODO would dissolve into the conversation history along with everything else.
- The agents were good about saving learnings. I was bad about reading them.
- “What’s done?” was a question you answered by reading git log and triangulating. There was no surface that said “these things shipped this month.”
None of this was the agents’ fault. They were doing exactly what I’d told them. The instructions just lived in too many files for me to keep coherent.
THE CARDS
A card has a title, an ID, a column, an order, a category, a priority, and an optional notes field — twelve fields total. Most run ten to fifteen lines of YAML; the verbose ones with embedded notes run longer. The board has a __meta__ block with a version number that increments every save — optimistic locking via If-Match, the same pattern HTTP gives you for free.
What each column is for:
- Inbox — things I dropped in without committing. Some get archived. Some get promoted.
- Parked — good ideas at the wrong time. Audio narration lives here. So does an interview-format experiment.
- Next — work that’s queued, ordered. Top card is what I’d start tomorrow.
- Doing — one card at a time, by rule.
- Done — recent shipped work, ordered by completion. Trims as it grows.
The agents read this at session start. There’s a memory entry that says, more or less:
the kanban is the live source of truth for in-flight work; read it before answering the operator’s first question; offer an unprompted ten-line summary.
They do.
Confession: my next column is currently three times longer than it should be. That’s a discipline failure on my part, not a tool problem. The kanban gives me the information; pruning is still my job.
WHAT I UNDERESTIMATED
The most useful column turned out to be parked, which I almost did not include.
Parked is for ideas that are good and not now. Things I keep coming back to and would lose track of if they sat in project_next_session.md next to the actually current work.
Parked solves a specific anti-pattern: dropping a half-formed idea into a markdown file you’ll forget to re-read, and then re-inventing the same idea three months later because you forgot you’d already thought it through. With a kanban column, the idea has a place. It’s not in your queue. It’s not in your face. It’s findable.
The other thing I underestimated was the drag-to-reorder priority. Just being able to physically move “this is next” above “this is also next” gave me an interface for a kind of decision I was making constantly and never recording. Before, “what’s most important right now” was a vibe. Now it’s an ordered list, and the agent reads the order.
WHAT’S STILL ROUGH
A few honest annoyances.
Optimistic locking has saved exactly one merge so far — me editing a card in the UI while an agent was writing the same record from another session. The 409 came back, the agent re-read the board, my edit stuck. That’s the failure mode the version field was added to catch. So far, once.
The YAML format is operator-readable but the diffs are noisy when cards reorder — every card below the moved one shifts. I’d prefer a stable-id-with-explicit-order field over relying on array position. Small refactor I haven’t gotten around to.
There’s no view of who-touched-what. The agents update cards; so do I. When two of us update the same card the version field stops a clobber, but there’s no audit trail of which session changed the description on Tuesday. For a one-person operation it’s fine. If a second person joined, this would need to be the first thing fixed.
MY READ
The kanban isn’t a tool I built for the agents. It’s a tool I built so the agents and I could see the same thing.
A few things I think generalize:
- The shared visual surface matters more than the data model. What the kanban gives me is a picture I can hold in one screen. That’s the whole product. The YAML underneath is a serialization choice; the picture is what I actually use.
- Optimistic locking is the right default for operator+agent shared state. Cheap, well-understood, and the failure mode (refresh and try again) is one the agent already knows how to handle.
- Lightweight beats featureful when the second user is an agent. A schema the agent can hold in context is a schema the agent will respect. Jira’s API surface is the wrong shape for a model that’s about to write back to it.
That’s a small change. Most of the time, when I describe what’s running here, people focus on the agents — the content pipeline, the legal-watch cron, the security sentinel. The kanban is the least technical piece of infrastructure on the system.
It’s also the one I’d build first if I were starting over.