Work through a plan with agents

Write a plan, have agents work its tasks in order, and approve the ones that need a person. What each part means: Tasks.

The agent's steps are MCP tool calls; the person's are in the web app. Your agent needs a read-write connection to the vault, and you need to be an owner or editor (or a named owner of the plan file's path).

1. Write the plan

Create a file, such as plans/launch.md, with one fenced work_plan block:

- key: brief
  title: Write the launch brief
  gate: review
- key: page
  title: Draft the landing page from the brief
  blocked_by: brief
- key: emails
  title: Draft the launch emails from the brief
  blocked_by: brief

gate: review on brief means nothing that waits on it starts until a person approves it. A person or an agent can write the file. If the path is canon, the file exists only once its proposal is applied.

2. Register it (agent)

Call register_work_plan with the vault and plans/launch.md. A mistake in the block is refused with its line number; fix the file and register again. The plan now shows on the vault's Tasks page.

3. Ask for work and wait (agent)

Call request_work with the vault and the plan's path. The answer comes at once:

• Granted: you hold a task. Keep the fence and the secret: every later call on the task needs both, from this connection.
• Wait: your place in line, and when to ask again. Stop, and call request_work again at that time, not sooner: asking early only repeats the answer. Waiting on several plans, call my_places once to see them all.
• Plan complete or blocked by a cancelled task: stop asking. The second needs a person.

To give up a place you no longer need, call leave_queue.

4. Work the task (agent)

• Read the task with work_plan_status. If its state line says context moved, read the cited files again first.
• On long work, call checkin_step with the fence and secret before the lease runs out. A task whose lease runs out goes to the next agent in line, and letting tasks run out costs your person a cooldown.
• Can't finish it? Call release_step to give it back.

5. Finish the task (agent)

Call complete_step with the fence and secret. The tasks waiting on it become ready for whoever is next in line.

For a task with gate: review, the task is Awaiting review instead. If its work is a change to a canon file, propose the change first with propose, then pass that proposal's id as proposal to complete_step. Then tell your person the task is waiting for their review. You can't approve it yourself.

6. Approve it (person)

Open the vault's Tasks, then the plan. Tasks awaiting review come first.

• Check the work, choose Approve on the task, and confirm. Or, if its agent linked a proposal, approve that proposal in your Inbox: applying it approves the task too.
• Not ready? Not yet on the confirm page leaves it as it is. To drop the task, choose Cancel; to let what waits on it go ahead without it, Skip.

Once approved, page and emails are ready, and the agents waiting in line get them.

7. Add tasks (agent or person, then agent)

Add new steps to the plan file's block, each with a new key, and leave the existing ones exactly as they are. Then have an agent call register_work_plan again. The new tasks join the end of the plan; the others keep their state. A changed or missing step is refused by name, and nothing is added.

8. Reopen a cancelled task (person)

On the plan's page, a cancelled task has Reopen. If the work has changed since it was cancelled, add a new task that names the old one by its key instead (step 7). Reopen only when it really is the same task: it goes back in the plan, and what waited on it waits for it again.

Only a person can approve, cancel, skip or reopen a task. See the ceiling.