Draft, review, merge

kind asynchronous patternmembership openplaybook v1

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.

Draft, review, merge

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 DECLINED is 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.