The TODO-as-Blackboard Pattern

Multi-agent coordination without message queues, databases, or orchestration infrastructure - using a shared Markdown file and git as the synchronization layer.

The Coordination Problem

When you run more than one agent, you immediately face a coordination problem: how do agents know what work is available, what is already claimed, and what is done? Traditional solutions - message queues, distributed databases, orchestration frameworks - solve this problem but add infrastructure complexity, operational overhead, and new failure modes. For a small fleet (2-10 agents), this overhead is rarely worth it.

The blackboard pattern is a classical multi-agent architecture from the 1980s: a shared data structure that agents all read from and write to, with no direct agent-to-agent communication. Each agent polls the blackboard, picks up available work that matches its capabilities, does the work, and updates the blackboard. For our fleet, the blackboard is a Markdown file - TODO.md - and git is the synchronization mechanism.

Why Markdown + Git Works

The combination of a Markdown file with git solves the coordination problem in a way that is uniquely well-suited to an AI agent fleet:

• It is human-readable. The human operator can read the current state of the fleet at a glance - what is queued, what is in progress, what is done. No dashboard required.
• It is agent-readable. AI agents are extremely good at parsing structured Markdown. A well-formatted TODO file is an ideal input for an agent that needs to select work items.
• Git provides versioned history. Every state change to the blackboard is committed. You can see exactly when each item was picked up, what the state looked like when each agent ran, and roll back to any previous state.
• Conflict detection is built in. If two agents try to update the same file simultaneously (rare in our setup, since agents run at different times), git merge conflicts surface the collision rather than silently losing one update.
• The PR gate enforces atomic commits. Because agents make their TODO.md updates as part of their PR (not as a direct push to master), the status update and the output are committed atomically. If a PR is rejected, the TODO item status reverts too.

The Three Zones of a Well-Designed TODO File

Our TODO.md has evolved into a structure with three distinct zones, each serving a different function:

Status Markers: The State Machine

The TODO file implements a lightweight state machine through status markers. These markers are the mechanism by which agents communicate state to each other and to humans:

The status-marker system means that agents do not need to communicate directly. ContentCreation-Draft marks its item "In progress (PR #N)" as part of its PR. If the agent were to run again the following Thursday, it would see the "In progress" marker and skip that item. If the PR is rejected and closed without merging, the human resets the marker to unchecked and the item becomes available again on the next run.

The Audit Trail Property

One of the most valuable properties of the blackboard-in-git pattern is that it produces a complete, automatic audit trail. Every state transition - every item picked up, every PR opened, every completion marked - is recorded in git history with a timestamp and a commit message that explains what the agent did and why. When something goes wrong (and it will), the audit trail tells you exactly what the agent saw, what it decided, and what it changed.

This audit trail has practical value beyond debugging. When reviewing fleet performance, you can answer questions like: how long did each item spend in the queue before an agent picked it up? Which items took multiple PR iterations before merging? Which items were marked in-progress but never completed? These patterns reveal spec quality issues, agent capability limits, and backlog management problems that would otherwise be invisible.

Adding Items to the Backlog: The Owner’s Role

The backlog is not managed by the agents - it is managed by the human. The human adds items when they identify work that matches a fleet agent’s capabilities. The spec for each agent explicitly describes what kind of items it will pick up. When an item does not match any agent’s spec, it stays in the queue with a note that it requires manual work.

This division - agents execute, humans prioritize - is what makes the fleet model sustainable. Agents are extremely good at execution given clear instructions. They are not good at deciding what is worth doing, what the strategic priorities are, or what quality looks like in context. The human keeps those decisions. The agents handle the execution.

What This Pattern Does Not Solve

The TODO-as-blackboard pattern is well-suited to sequential, non-time-sensitive task coordination. It is a poor fit when agents need to coordinate in real time, when tasks have complex dependencies that require dynamic ordering, or when you need guaranteed delivery semantics (an item must be processed exactly once, even if the system crashes mid-execution). For those use cases, purpose-built orchestration tools are a better choice. The blackboard works because our fleet’s tasks are independent, idempotent, and tolerant of occasional re-runs if a PR is not merged.