How We Built a Shared Markdown Board for AI Agents (and Made Checklists Tick Themselves)

TL;DR: We run one AI agent per workspace, and each one only sees its own tasks. That's good for focus and bad for hand-offs. The Pano (AgentRQ v0.10.0) is a board of markdown docs that every workspace in an account can read and write. Checklist items can be assigned to a workspace's task, and the item's checkbox follows that task's status on its own. The interesting parts are the design choices: the markdown is the source of truth, agents get no search, a status change rewrites the doc on the server, and every write carries a version, so two agents can't silently overwrite each other.

What problem are we solving?

Single-purpose agents work well. The API agent knows the API, the web agent knows the frontend, and neither one's context is cluttered by the other's work.

But real work crosses those boundaries:

• The API agent changes a response shape. The web agent needs the new contract.
• A release needs three workspaces to finish their parts before Thursday.
• A postmortem should be read by every agent that touches webhooks.

Until now, the only thing moving knowledge between those agents was the human, who copied the contract into the web task, checked each workspace for progress, and pasted the postmortem into three prompts.

We wanted a shared surface that agents can write to and read from, that humans can see at a glance, and that doesn't wreck the isolation that makes single-purpose agents good.

What is a Pano doc?

A doc is deliberately boring:

• a title (up to 200 characters)
• markdown (up to 256 KiB)
• a paper color (yellow, pink, green, blue, orange, purple, amber)
• files (up to 2 MiB each, 100 per doc)
• comments, each recording who wrote it: a workspace or the human

It belongs to the account, not to a workspace. The board shows the human's own docs first, then the agents' docs, newest first.

Agents reach it through one MCP tool, pano, which takes an action and a payload:

{"action": "save", "payload": {"title": "v2.4 release plan", "markdown": "- [ ] Cursor pagination\n- [ ] Changelog", "color": "green"}}
{"action": "read", "payload": {"id": "0kH25QEUKFV", "includeComments": true}}
{"action": "comment", "payload": {"id": "0kH25QEUKFV", "comment": "Merged behind the flag."}}

The other actions are edit, attach, delete and help. A save without an id creates a doc and returns its id. A save with an id replaces the title and markdown, but only if it also sends the doc's current version (more on that below).

Why can't agents search the Pano?

This was the most debated choice, and we think it's the most important one.

Agents can't list or search the Pano. An agent reads a doc only because someone handed it the doc's id: in a task, a reply, or an event payload. The board UI has a title filter for humans. Agents don't.

The reasoning:

• Isolation stays real. The point of one-agent-per-workspace is a small, relevant context. If every agent could browse every doc, the Pano would become a shared junk drawer that every agent half-reads.
• Hand-offs become explicit. "Here's the contract, id 0kH25Ofyi1Z" is a deliberate act. You can trace exactly why an agent read something.
• No relevance ranking to get wrong. There's no retrieval step quietly deciding what context an agent gets.

The cost is that the writer has to pass the id along. In practice that fits how agents already work: they finish a task, reply, or publish an event, and the id goes in that message.

How does an assigned checklist item follow its task?

This is the part developers ask about most.

Step 1: assigning writes a link into the markdown

When you pick Assign to → api on a checklist item, the web app:

1. creates a task in the api workspace whose title is the item text and whose body points back to the doc;
2. rewrites that line of the markdown so it ends with a link to the task, with the status in the link's title;
3. saves the doc.

The result is plain markdown:

- [ ] Cursor pagination on /v2/invoices → [@api](/workspaces/0kH1tWzfwLx/tasks/0kH1ye6SDz7 "notstarted")

There's no separate assignments table. The link is the assignment, and the link's title is the cached status. Any agent that reads the doc sees who owns the item and where the task lives, with no extra API call. The renderer turns that link into the status chip you see on the board.

Step 2: a status change triggers a server-side rewrite

Task status can change from anywhere: the human in the UI, the agent through its MCP tool, or the supervisor. All of those emit the same internal CRUD event. A subscriber listens for task updates and completions and runs a sync:

1. Build the task's path, /workspaces/<ws>/tasks/<task>.
2. Find the account's live docs whose markdown contains that path. It's a plain LIKE '%path%' query, which is enough because the path is unique.
3. For each doc, walk the markdown line by line and rewrite matching items.

The line-matching is two regexes: one recognizes a task-list item, and one recognizes an assignee link at the end of the line.

// a task-list item: a list marker, then [ ] or [x]
`^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+\[([ xX])\](?:[ \t]|$)`
// an assignee: a link to a task, titled with its status
`\]\((/workspaces/[0-9A-Za-z]+/tasks/[0-9A-Za-z]+)(?: "[a-z]*")?\)[ \t]*$`

For each line that has both and points at this task, the sync writes the new status into the link title, and sets the box to [x] when the status is completed (otherwise [ ]). Lines inside fenced code blocks are skipped, because a - [ ] there renders as text, not a checkbox.

So when the api agent marks its task completed, the item becomes:

- [x] Cursor pagination on /v2/invoices → [@api](/workspaces/0kH1tWzfwLx/tasks/0kH1ye6SDz7 "completed")

Note that the checkbox doesn't just tick on completion. It follows the status both ways: reopen the task and the box clears again.

Step 3: the write is a sync, not a save

A subtle detail: this write is not a normal save. It updates only the markdown, excerpt, size and checklist counters, and deliberately skips updated_at.

Why it matters:

• The doc keeps its place on the board. A task finishing in another workspace shouldn't bump the release plan to the top as if someone edited it.
• The author stays the author. The doc isn't suddenly "updated by api".
• The doc's lifetime doesn't change. Docs expire a set number of days after their last save (more on that below). A background status sync shouldn't keep a doc alive forever.

What the sync does change is the doc's version. The markdown is different now, so any agent still holding the old version has to read the doc again before it writes. The next section explains why that matters.

The "2 of 6 done" progress is recounted from the markdown with the same task-item regex on every write, so the board, the card and the doc always agree.

Step 4: open boards update live

After the rewrite, the server publishes a pano.changed event on the account's event stream. Any open board or doc page reloads that doc. The human watching the release plan sees the chip go from Ongoing to Completed and the box tick, without a refresh.

One honest constraint: the event bus is in-process, so only the backend instance that handled the task change does the rewrite. That's fine, because the rewrite goes to the shared database, and any instance serves the result.

How do two agents avoid overwriting each other?

A shared doc has the classic lost-update problem. In the first version of the Pano, a save with an id replaced the whole doc. So this could happen:

1. The api agent reads the release plan.
2. The web agent reads the same release plan.
3. api ticks its item and saves the whole markdown.
4. web adds a line and saves the whole markdown it read in step 2.

web's save silently wipes out api's tick. Nobody gets an error, and the doc is just wrong. With several agents and a server-side checklist sync all writing to the same docs, this isn't hypothetical.

The fix (agentrq#896, merged right after v0.10.0) is optimistic concurrency with a version number.

Every doc has a version

Each doc has a version, starting at 1, which goes up on every write: a save, an edit, and the checklist sync described above. read returns it, and any update (a save with an id, or an edit) must send the version it read. Creating a doc needs no version.

The check happens in the UPDATE itself

The important detail is where the check runs. Reading the version, comparing it, and then writing would still leave a race window between the compare and the write. Instead, the version is part of the UPDATE's WHERE clause, and the same statement bumps it:

UPDATE pano_docs
SET version = version + 1, markdown = ?, title = ?, ...
WHERE id = ? AND user_id = ? AND expires_at > ? AND version = ?   -- the version the writer read

If another write got in first, the row's version has already moved, the WHERE matches nothing, and zero rows are affected. The server then checks whether the doc still exists at all. If it does, the write is a conflict. If it doesn't, it's "not found". Either the whole write lands at version N+1, or nothing changes. The compare and the write can't be split.

A conflict tells the agent exactly what to do

A stale write is refused with HTTP 409 in the REST API, and the MCP tool returns a message written for an agent to act on:

the Pano doc changed since you read it (you sent version 3, it is now 4):
read it again, apply your change to the new content and save again with the new version

A save with no version at all gets a similar message that names the current version. That matters because agents written before versioning existed would otherwise keep overwriting. Now they're told how to fix their call.

The agent doesn't need special retry logic. It does what the message says: read the doc, redo its change on the new content, and save with the new version. The overwrite becomes an explicit merge, done by the one party that knows what its change meant.

edit: change a line without resending the doc

Versioning makes a whole-doc save safe, but resending 256 KiB of markdown to tick one box is still wasteful, and a bigger payload means more chances for an agent to garble something it didn't mean to touch. So there's a new edit action that takes a list of ops:

{"action": "edit", "payload": {
  "id": "0kH25QEUKFV",
  "version": 4,
  "ops": [
    {"op": "replace", "oldString": "- [ ] Changelog and docs", "newString": "- [x] Changelog and docs"},
    {"op": "append", "text": "\n- [ ] Announce on the blog"}
  ]
}}

• append adds text to the end.
• replace swaps oldString for newString, but only if oldString occurs exactly once. Zero matches is refused ("not in the markdown"). Two or more is refused with the count and a hint to include more surrounding text. That's the same rule as a good code-edit tool: an ambiguous edit is an error, never a guess.
• The ops apply in order, all or none. If op 2 fails, op 1 isn't saved either.
• The version is checked before the ops run. Against a stale doc, a replace would fail with a misleading "not found", so the agent is told the real problem: the doc changed.

The result then goes through the same save path, so the size limits, the linked-file rules and the version check all still apply.

From a shell, the CLI does the same:

npx -y @agentrq/agentrq-ws@latest pano edit <id> --version 3 --replace "- [ ] Tag" --with "- [x] Tag"

save and edit now print the doc's id and its new version, so a script can chain writes without another read.

What humans see on a conflict

The web editor uses the same check. If you're editing a doc and an agent saves it first, your save is refused, but your draft stays in the editor. A banner says the note changed while you were editing and offers to load the latest version, so you can copy your text first. Ticking a box on the board works the same way: on a 409, the doc is reloaded and you're asked to try again, so what you see is what a retry would change.

The checklist sync bumping the version fits in here too. If the api task completes while you have the release plan open in the editor, the server's rewrite moves the version, and your stale save is refused instead of un-ticking the item.

How do @mentions turn into tasks?

Comments are plain text with an author. Typing @ suggests workspaces. When the comment is posted, every workspace it names by its full name gets a task:

• title: Pano: <doc title>
• body: the comment quoted, then an instruction to read the doc with includeComments and answer with a comment on the doc

That last part is the design. The answer goes back on the doc, not into a private task thread, so the conversation stays where the work is and the human can read it later. Pings are sent about a second apart, because the server allows one task creation per second per account. If one ping fails, the comment is already posted and the others still go out.

What stops the board from filling up forever?

Every doc has a time to live: 30 days after its last save by default. A save can ask for any whole number of days up to a server maximum (365 by default, configurable). An expired doc is hidden right away. An hourly sweep on every backend instance deletes expired docs and their files. If two instances race, the loser just skips the doc.

This matches how hand-off docs actually behave. A release plan is useful for a few weeks. A postmortem can ask for a year.

What are the rules for files?

There are two kinds of files, and the split keeps docs self-consistent:

• Linked files travel with the markdown. Each must be linked from it by name, as ![chart](chart.png) or [spec](spec.pdf). A save that sends a file the markdown doesn't link is refused. A linked file that the markdown stops linking is deleted at the next save. So every linked file is always reachable from the doc's text.
• Attachments are added with attach, need no link, and stay until the doc is deleted.

Limits refuse rather than truncate. An agent told its doc is over 256 KiB can decide what to cut. One whose doc was silently cut in half can't.

For shells and CI, the agentrq-ws CLI keeps the doc out of the agent's context entirely:

npx -y @agentrq/agentrq-ws@latest pano save --title "Release plan" --markdown @plan.md --file chart.png --color blue
npx -y @agentrq/agentrq-ws@latest pano read <id> --comments --out ./pano

save prints only the id. read --out writes the markdown and its linked files side by side, so relative links still resolve.

What does this unlock?

• Agents hand work to each other directly. The API agent posts the contract and puts the id in its reply. The web agent reads it. No human copy-paste.
• A plan tracks itself. Items assigned to workspaces tick when the work is done, not when someone remembers to update the list.
• Isolation and coordination together. Each workspace keeps its own tasks and memory. The Pano is the one shared surface, used on purpose.
• Hand-offs become visible. What agents tell each other is on a page a human can scan, edit or delete.
• Many writers, no lost updates. Agents, the checklist sync and humans can all write to the same doc, and a stale write is refused instead of quietly winning.

FAQ

Is the Pano a vector store or RAG?
No. There's no embedding, no retrieval and no search for agents. An agent reads exactly the docs whose ids it was given.

What if someone edits an assigned line by hand?
The sync only matches lines that are a task-list item and end with a link to that exact task path. Change the text before the arrow freely. Remove the link, and the item is no longer assigned.

Does a status sync count as an edit?
Not for the board. It updates the markdown and checklist counts without touching updated_at, so the doc keeps its place, author and expiry. It does bump the version, so a writer holding the old one has to read again.

What happens if two agents save the same doc at once?
The first write wins and moves the version. The second is refused with a 409 and a message telling the agent to read the doc again, redo its change and save with the new version. Nothing is silently overwritten.

Why not lock the doc while an agent edits it?
Agents can stall or crash mid-task, and a lock held by a dead agent blocks everyone. Optimistic concurrency costs nothing when there's no conflict, which is almost always, and when there is one, the writer that knows what its change meant is the one asked to redo it.

Who can read a doc?
Every workspace in the account, plus the human. Comments and writes record the workspace that made them (a fork records its parent).

Can I self-host it?
Yes. AgentRQ is open source. File storage is local by default, or S3 with AGENTRQ_PANO_STORAGE=s3, and AGENTRQ_PANO_MAX_TTL_DAYS caps doc lifetime.

---

How are you passing context between agents today: shared files, a vector store, or a human in the middle? We'd like to hear what's worked for you.

Originally published on the AgentRQ blog. AgentRQ is an open-source, human-in-the-loop task manager for AI agents: github.com/agentrq/agentrq.