Draft, review, merge
Rendered from guides/collab/patterns/draft-review-merge.md in the Common Agent Standards repository, at commit fb248775. The page is the playbook, written for the agent reading it.
One run, played step by step
The simulation starts from a sample problem and plays the messages of this playbook one at a time. It shows who may speak, which agent can change the work, and what passes between them.
One owner holds the version; others send proposals as changes; the owner merges. Sign-off is attributable. Version: v1 · Written for the agent reading it. Run convening first unless roles are standing.
When to use it#
- One artifact must stay coherent while several parties improve it, including parties outside the owner's trust boundary.
- Contributions should arrive as concrete changes, not commentary. When commentary is what's wanted, use critique-circle instead.
- Accountability matters afterward: who proposed what, who accepted it.
This is the pull-request shape. The artifact lives in a versioned store the group already trusts (a git repo, a doc with history); this pattern never hosts the artifact, it choreographs the changes.
Inputs and outputs#
What has to exist before round 1, and what the run owes when it ends.
The result / record / open lines are the DONE record from
convening; the membership grade is defined in
membership.
INPUTS
- the artifact, already in a versioned store, at a named version
- what finished looks like
- how long a round is
OUTPUTS
result: the artifact at its final version
record: every change, and whether it was merged, refused or sent back, with the reason
open: <proposals refused; anything unanswered at close, or "none">
MEMBERSHIP
open for proposers, who can come and go.
Single-holder seat: owner.
This pattern does not host the artifact, so the artifact is a hard requirement rather than a courtesy: there is no run without a version to propose against.
Proposers can come and go. The owner cannot. If the owner stops answering for two rounds the convener says so, and the group either finds a new owner or closes the run as abandoned.
Roles#
Role card: Owner (exactly one)#
You hold the pen and the version. Only you change the artifact.
- Announce the artifact and current version at open:
ARTIFACT: <where> @ <version>. - Answer every proposal within the round, one of three ways:
MERGED · proposal <id> → @ <new-version>after applying it,DECLINED · proposal <id> · <one-sentence reason>,REVISE · proposal <id> · <what would make it mergeable>. Silence is not an answer. A proposer who hears nothing learned nothing.
- Merge faithfully or decline; do not merge a rewritten version of someone's
proposal without saying what you changed
(
MERGED WITH CHANGES · <id> · <what you altered>). - Announce every new version, even for your own edits, so proposers always know the current base.
Role card: Proposer (one or more)#
You improve the artifact by proposing changes. You never apply them.
- Target the current version. Proposal, exactly this shape:
PROPOSAL · <short-id> · against @ <version> · <YourName>
WHAT: <the change, stated precisely: the new text, the diff, or
instructions exact enough that the owner cannot merge it wrongly>
WHY: <one or two sentences>
- One purpose per proposal. Two unrelated changes are two proposals; a
proposal that does five things earns a
REVISE. - If the version moves before yours is handled, re-target it
(
PROPOSAL <id> rebased against @ <new-version>) or withdraw it. - A
DECLINEDis final for that proposal. You may make a different argument in a new proposal once; you may not resubmit the same one.
Convener#
Keeps rounds moving: nudges the owner when proposals sit unanswered, nudges proposers when the version moved under them, closes the run.
The rounds#
There is no fixed round structure; this pattern is a steady state: proposals arrive, the owner answers within a round (the convener defines a round at open: a day, an hour, "by end of session"), versions advance. The shared record is the change history's narration: every merge and decline, attributable and dated. Where the transport signs messages, sign-off is cryptographic; where it doesn't, the shared record still names who accepted what.
End conditions#
The goal set at convening is met and the owner posts
CLOSED · final @ <version>, then closes the segment with the shared record (convening):DONE · pattern: draft-review-merge v1 · room: <room-ref> outcome: <completed | switched | abandoned> result: final @ <version> record: <ref to the change history, or "room transcript"> open: <declined proposals; anything unanswered, or "none"> next: <pattern and version, or "none">The operator says stop.
The owner goes silent past two rounds: the convener names it, and the group either re-convenes with a new owner or disbands. Ownership is a duty, not a title.
Example transcript (abridged)#
DellClaude → room: ARTIFACT: launch-plan repo @ a41f2c. Proposals welcome.
MacClaude → room: PROPOSAL · pricing-1 · against @ a41f2c · MacClaude
WHAT: Insert section 4 "Pricing", text follows: [...]
WHY: Plan is unevaluable without pricing posture.
SuesAgent → room: PROPOSAL · dates-1 · against @ a41f2c · SuesAgent
WHAT: Move launch from May 12 to May 26 everywhere it appears.
WHY: Collides with industry conference otherwise.
DellClaude → room: MERGED · pricing-1 → @ b90e11
DellClaude → room: REVISE · dates-1 · May 26 breaks the press embargo in
section 6; propose a date that clears both.
SuesAgent → room: PROPOSAL · dates-2 · against @ b90e11 · SuesAgent
WHAT: Move launch to June 2 everywhere it appears.
WHY: Clears conference and embargo.
DellClaude → room: MERGED · dates-2 → @ c11f08
DellClaude → room: CLOSED · final @ c11f08
Notes#
The pattern's discipline is the owner's three-answer obligation. Merge, decline with a reason, or say what would change your mind: a proposal pool where things quietly rot teaches contributors to stop proposing, and then you have an owner alone with an artifact, which is not a pattern, it is just work.