08 — The workspace as an inbox

What you will have at the end: work left behind in a workspace that an agent finds and does the next time it arrives — and an understanding of what "check in" actually does, which is what makes a written playbook worth writing.

What you need: tutorial 02 finished, with an agent connected and an AGENTS.md at the root.

The shift

In tutorial 02 you asked an agent for something and watched it work. You were sitting there. That is a conversation.

This tutorial is about the other mode: you leave work behind, and the agent picks it up when it next arrives. Nothing is waiting on you being present. The workspace holds the queue.

That changes what you write down. In a conversation you can clarify as you go. In a queue, whatever you left has to be enough on its own — which is exactly why the house rules live in a file instead of in your memory of what you told it last time.

1. "Check in" is the command

There is one phrase that starts the whole loop:

"Check in to markdown-den."

It is not a single poll. It is a loop, and it runs until there is nothing left:

Query for work.
Do everything outstanding, one item at a time, fully.
Query again — work often arrives while the first batch is being done.
Stop only when a fresh query turns up nothing new.

You do not have to teach an agent this. Every session is handed a compact form of that contract when it connects, before any workspace playbook, so "check in" means this sequence even to an agent that has never worked in your workspace before.

Your AGENTS.md can refine the loop: say how work reaches you here, and the session works to that instead of to the default. Worth knowing where the line actually is — the server tells every agent that a workspace's playbook beats its own private brief, but it does not tell it that the playbook beats the check-in contract above — and it says even that only to an agent that has a brief. So refine the loop freely, and treat a rule that contradicts the contract as something you are relying on the agent to reconcile.

2. Leave a work item: mention on the thing

The most precise way to hand over work is to attach it to what it is about.

Open a document, select the sentence in question, start a comment, type @ and pick your agent:

@helper-bot The figures in this table came from last quarter. Check them against data/results.md and say here whether they still hold.

Then walk away. That is a queued item now. It will still be there tomorrow.

Three properties are worth noticing, because together they are the reason this beats a message in a chat:

The request carries its context. The agent does not need to be told which table — the thread is anchored to it.
The reply is the report. It lands on your thread, so the answer sits next to the question and next to the sentence both are about.
It survives edits. The paragraph around it can be rewritten and the thread stays attached to the words it was about.

3. Leave a work item: a document as a queue

Not everything is about one sentence. For the rest, use a document — conventionally TODO.md at the root — and say in your playbook how to read it:

## How work reaches you

- I @mention you in a comment thread. Reply on that thread when you are done —
  your reply is the report.
- `TODO.md` at the root: an unstruck bullet is open work. Strike it through when
  you finish it and append where it landed.

Then the file itself is just a list:

## TO DOs

* ~~Check the quarterly figures in the summary~~ (they still hold; noted on the thread)
* Draft a one-page brief for the new reviewer agent
* Work out why the export drops the last row

The appeal is that it is an ordinary document. You can reorder it, annotate it, add a paragraph of context under a bullet, or leave a note to yourself in the middle of it — because it is markdown and nothing is parsing it but the agent that agreed to read it.

Striking a line through instead of deleting it matters more than it looks: the file becomes a record of what was done as well as a list of what is left.

4. What actually happens when it arrives

Worth knowing, because it explains why steps 2 and 3 work at all. The playbook comes first — the session is pointed at it on connection and told to read it before its first action. Then it widens to narrow, cheap questions first:

What it asks	Why it asks it
How should I do it?	Your `AGENTS.md`, read fresh from the file rather than from anything cached
What happened while I was gone?	Its notifications. The widest net: mentions in comments and in documents, and replies in threads it is part of
What is still open?	Mentions on unresolved threads — a notification says something happened, this says it is still live
What is the context?	The threads themselves, when a request needs the conversation around it
What moved?	Files changed since its last visit, which catches a quiet rewrite no notification covers

The first row is the one to take away. The playbook is read from the live file, so editing it mid-session changes what the agent does next — there is no snapshot to go stale, because nothing was ever handed over except the file's location.

The last row is the quiet hero. A notification only exists if something notified; a file delta catches the case where you simply rewrote a document the agent was working on and told nobody.

5. Two rules that make the queue trustworthy

Both belong in your playbook, and both are about signals not being ambiguous.

An agent is told never to resolve a thread, by the server, before it reads anything of yours. Resolving is your signal that you are satisfied. If an agent resolved its own work, you would lose the only marker that distinguishes "answered" from "accepted". Its reply is the report; your resolve is the acceptance. Say it in your playbook too — an agent that can write can technically resolve, so this is a convention held up by instruction rather than by a wall.

A prior reply means handled. An agent that has already replied on a thread treats that mention as done and skips it. Which means: if you want more, reply again — a new reply on the thread is a new item, and re-mentioning is not required for the agent to see it, because a reply in a thread it is part of reaches its inbox too.

That second rule is the one that catches people out in a good way. You can carry on a genuine back-and-forth on a thread across days, and each of your replies is a new piece of queued work.

6. Try the whole loop

Leave two items: a mention on a document, and a bullet in TODO.md.
Do not tell the agent anything about them.
Later — a different session entirely — say "check in to markdown-den".

It finds both, does them one at a time, replies on the thread for the first and strikes through the bullet for the second, then polls once more before stopping.

Then add a third item while it is working, and watch it get picked up in the same check-in. That is step 3 of §1 doing its job: the loop ends on an empty poll, not on an empty first batch.

What you have now

A workspace that holds work rather than a conversation that has to be kept alive. You leave things; the agent finds them; the answers come back attached to the documents they are about.

And a reason to write the playbook properly. In a conversation you can correct an agent as it goes. In a queue, the playbook is the only correction available — so the quality of that one file is the quality of everything that happens while you are not watching.