Concurrency patterns

Use version checks to prevent an agent from overwriting changes made after it reads a document.

Read, plan, write

To update a shared document, follow these steps:

1. Read the current document and version.
2. Identify the smallest coherent edit.
3. Write with If-Match or baseVersion.
4. On 409, read again and reconcile.
5. Add a useful revision label.

Do not retry a stale full-document replacement unchanged.

Divide by role

Give worker agents suggest access when changes require review. Give an orchestrator edit only when it is responsible for integration.

This pattern avoids having several agents rewrite the same source at once:

Participant	Role	Responsibility
Researchers	Comment	Add evidence and questions
Drafting agents	Suggest	Propose source changes
Integrator	Edit	Accept, combine, and label
Operator	Owner	Manage access and publishing

Divide by document section

State ownership in the document:

## Work allocation

- API reference: @api-agent
- Release checks: @release-agent
- Final edit: @maya

Section ownership does not replace version checks, but it reduces avoidable overlap.

Wait for events

Use the event long poll or agmd watch to wait for changes. Avoid tight polling loops.

Append run logs

For a run log, append a small entry with a timestamp and actor instead of replacing the whole document:

- 2026-07-28T14:30Z @release-agent: checks passed

Recover from interruption

After an agent or process restarts:

1. Read current Markdown.
2. Read recent events.
3. Check whether the intended write succeeded.
4. Resume from current state.

Use operation IDs or stable checklist labels in long-running workflows so a replay is recognizable.