ACOP

ACOP at a Glance

A two-page orientation for first-time readers. Nothing here is normative — every rule is stated properly in acop.md. This document exists to make that one readable.

What ACOP is

ACOP is a coordination protocol for multi-agent software development. It defines what work exists, who may pick it up, how long they hold it, and what “done” means — as a contract, not as one vendor’s implementation.

It answers questions that come up the moment more than one agent works on the same repository:

The problem it prevents

Two agents read the same plan and both start on PaymentService. Neither knows about the other. One finishes and force-pushes; the other’s work is gone. Nothing failed loudly — there was simply no place to record that the work was taken.

Chat between agents does not fix this: a message is not a lock. A tool call does not fix it either: a tool executes, it does not arbitrate. The missing piece is a coordination layer that owns the answer to who holds what.

Where it sits

   +-------------------------------------------------+
   |  ACOP    what work exists, who holds it, done?   |
   +-------------------------------------------------+
   |  A2A     agent-to-agent messaging and delegation |
   +-------------------------------------------------+
   |  MCP     tools, resources, context               |
   +-------------------------------------------------+

ACOP does not replace MCP or A2A and does not compete with them. It specifies the contract those transports carry. ACOP is transport-neutral; acop-http-binding.md defines the normative HTTP+JSON mapping.

The mental model

A work item moves through states. A claim is the lease that lets exactly one worker act on it.

   producer emits          worker claims        worker finishes
        |                        |                     |
        v                        v                     v
     ready  ---------->      claimed  ------->    in_progress
        ^                        |                     |
        |                        | (release/expire)    v
        |                        |                completed
        +------------------------+                     |
                                                       | downstream
                                                       v  accepts
                                                   accepted
                                                       |
                                                       v
                                                   consumed

Blocked work never reaches ready. Terminal states are consumed, cancelled, and superseded. The full table — which transitions MUST be supported, which MAY be, and which MUST be rejected — is in acop.md § State machines.

Completion is not acceptance. completed is the worker’s own assertion about its output. accepted is a decision made by whoever consumes it. Keeping them separate is what stops an agent from signing off on its own work.

The objects

Object What it is
WorkItem The unit of coordinated work. Stable, opaque work_item_id.
Blocker Why a work item is not actionable, with a coded reason.
Claim Time-boxed ownership. Has expires_at_utc; renew it or lose it.
Artifact A file, patch, contract, or report the work refers to.
ValidationRequirement Evidence that MUST exist before the item may complete.
BlackboardEntry Append-only shared note: a finding, risk, decision, partial result.

Every ACOP document carries protocol_version — acop/1.0 for this release. Servers reject versions they do not accept.

A claim, end to end

POST claims
{
  "protocol_version": "acop/1.0",
  "work_item_id": "work:resource-hub:extract-seam",
  "worker_agent_uid": "worker-7",
  "requested_ttl_seconds": 1800,
  "scope": "owned_paths"
}

201 Created
{
  "claim": {
    "claim_id": "claim:9f2a",
    "claim_status": "active",
    "expires_at_utc": "2026-08-03T18:30:00Z"
  },
  "work_item_status": "claimed"
}

A second worker attempting the same item gets 409 with a claim_conflict error. The first worker then renews before expiry, and finally calls complete with its validation evidence — a completion missing required evidence is rejected with validation_required, not accepted on trust.

Seven verbs cover the whole protocol: claim, renew, release, complete, create work item, accept handoff, post blackboard. See acop-http-binding.md § Verb table.

Four rules worth knowing early

  1. The coordination owner holds claim truth. Not the producer, not the MCP layer. A worker that is asked politely not to claim taken work will eventually claim it anyway.
  2. Claims expire. A crashed worker releases its lease by doing nothing. This is why TTL is mandatory and heartbeats do not extend it — only an explicit renew does.
  3. The blackboard is append-only. Revising a note means posting a new entry that supersedes the old one, so the reasoning trail survives.
  4. Undeterminable state blocks. Anywhere ACOP cannot establish that a condition is met, the answer is “not ready.” Failing open defeats the point of having a gate.

Two optional extensions

Both are stable at v1.0 and both are opt-in. A core implementation that needs neither is fully conformant.

What ACOP is not

It is not a scheduler, a queue implementation, a storage design, a message bus, or a language-specific refactoring model. It defines the coordination contract and stops there. Nothing here dictates how you store work items or which agent framework you run.

Where to go next

You want to… Read
Understand the semantics properly acop.md
Build a server acop-http-binding.md, then fixtures/
See real documents acop_examples.md
Check what “conformant” means acop.md § Conformance
Know what can change under you acop.md § Versioning policy

If you are evaluating ACOP for adoption, read this page and acop.md § Problem statement. If you are implementing it, the fixtures are the fastest way to find out whether you have it right — they encode the rules that JSON Schema alone cannot catch.

This site is open source. Improve this page.