Why markdown plans break when you run multiple AI agents
Most of us coordinate AI coding agents the same way: a markdown file in the repo with a checklist. The agent reads it, picks an item, does the work, ticks the box and commits. For one agent in one session, it works well. Then you start a second session. And a third. What goes wrong Two agents pick the same item. Nothing in a markdown file stops two readers from choosing the same line at the same…
When coordinating multiple AI coding agents using markdown checklists, various problems arise. Two agents may attempt to claim the same task within the same session, leading to conflicts when they both submit pull requests for the same fix. If an agent's session times out or the laptop goes to sleep, the unfinished task remains marked in progress and unclaimed by other agents.
Editing the plan simultaneously by two agents can result in conflicting changes or merge conflicts, which the agents may resolve incorrectly. Git history becomes difficult to navigate, as it is unclear which agent claimed what and why certain changes were rejected. The issue lies in the shared mutable state of the markdown file, which is not an ideal solution for handling such tasks.
To address these problems, the author built a system called workstream-mcp. It utilizes an MCP server to provide ordinary tool calls for agents, ensuring atomic claims where two claimers cannot select the same item. Tasks have a TTL, and if an agent fails to refresh its task, it returns to the pool, preventing deadlocks caused by agents stuck in loops.
Dependencies determine what tasks can run in parallel, and the task manager prevents agents from working on the same code simultaneously. The system uses a state machine stored in a JSON graph, specifying statuses, transitions, allowed roles, and retry caps for each plan type. If an agent attempts an illegal transition, the tool returns an error along with allowed next steps, allowing the model to correct itself.
Reviews are integrated into the workflow, with a developer agent submitting an attempt, and a reviewer approving it or sending it back for another pass. After the retry cap is reached, the task is assigned to a human. Every change is recorded as an event, with database triggers preventing updates or deletions on the event log, ensuring an unalterable history.
GitHub and Slack integration is achieved through an outbox, ensuring that changes and their notifications occur in the same transaction, with a background worker delivering them with retries. This approach eliminates issues caused by GitHub or Slack outages affecting agent tool calls.
The system provides a dashboard displaying each plan as a board, showing which agent holds each task, the remaining time on the task's claim, pending tasks, and stuck tasks. The dashboard uses the same tools agents call, allowing for seamless integration. Docker can be used to run the demo at http://localhost:8080/demo-insecure-token/ui/, where two developer agents and a reviewer can be simulated against a ten-task plan.
To connect a custom agent, use claude mcp add --transport http workstream-demo http://localhost:8080/demo-insecure-token/mcp, then ask the agent to claim the next task. The system is MIT licensed, with a public roadmap and good first issues for webhooks, connectors, and SDK development.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
