ACOP is a vendor-neutral coordination protocol for multi-agent software development work. It defines work-item, claim, blackboard, and orchestration semantics that sit above MCP (tool/context access) and A2A (agent-to-agent messaging).
ACOP core, the HTTP+JSON binding, and both extensions are at v1.0 (stable). Each is versioned independently; see acop.md § Versioning policy for the stability labels and the additive-versus-breaking rules.
Adopting an extension is optional. A core implementation that orchestrates no staged work and operates under no formal requirements is fully conformant without either one.
New to ACOP? Start with acop-at-a-glance.md — two pages, non-normative.
| File | What it defines | Stability |
|---|---|---|
| acop-at-a-glance.md | Two-page orientation for first-time readers. Non-normative. | stable |
| acop.md | Core protocol: work items, claims, blackboard, artifacts, state machines, conformance, versioning policy. | stable |
| acop.schema.json | JSON Schema for the core contract. | stable |
| acop-http-binding.md | Normative HTTP+JSON transport binding, error model, auth, sequence diagrams. | stable |
| acop-errors.schema.json | JSON Schema for HTTP error response bodies. | stable |
| fixtures/ | Conformance test fixtures (one JSON file per scenario). | stable |
| acop-orchestration.md | Orchestration extension: stages, lanes, gates, acceptance. | stable |
| acop-orchestration.schema.json | JSON Schema for orchestration flows. | stable |
| acop-orchestration-mcp.md | Recommended MCP read tools for orchestration state. | stable |
| acop-orchestration-cypher.md | Cypher query templates for graph-projected orchestration. | stable |
| acop-compliance.md | Compliance extension: requirements, evidence, exceptions. | stable |
| acop-compliance.schema.json | JSON Schema for the compliance extension. | stable |
| acop_examples.md | Worked examples of the core and extension shapes. | stable |
ACOP layers on top of existing standards:
ACOP does not replace MCP or A2A; it specifies the contract those transports carry for work coordination.
ACOP is transport- and backend-agnostic; this repo contains the specification only. The reference implementation lives in a separate repository:
BogDb.Acop.Mcp.Server
exposes ACOP claim/complete/work-item/blackboard tools over stdio
JSON-RPC and delegates the actual coordination authority to a pluggable
backend adapter. Its
HttpAcopBackend
adapter implements the HTTP+JSON binding.BogDb.Mcp.Server,
which reads from the graph projection of coordination state.Neither implementation is normative. Where an implementation and this specification disagree, the specification wins.
The schema $id URIs resolve under https://acop.ai/schemas/v1.0/....
They are published from main on every push; see
.github/workflows/pages.yml.
acop.ai is deliberately not tied to any implementation or vendor. The
$id value is the canonical identifier for a schema version and is stable:
it will not be repointed or reused for a different schema. Files under
schemas/v1.0/ are frozen — a breaking change ships as a new version
directory, never as an edit in place.
The host is a convenience for tools that resolve $id over the network,
not a runtime dependency. ACOP validation is fully offline: the schemas
contain no external $refs, so a copy of this repository is sufficient and
implementations SHOULD vendor the schemas rather than fetch them.
npm ci
npm test
This checks that every JSON file parses, every schema compiles under
Ajv (2020-12), every schema $id matches the path
it is published at, every fixture matches the fixture envelope and resolves
its variable references, and every relative Markdown link resolves. CI runs
the same command on push and pull request.
Node is used only for validation tooling. ACOP has no runtime dependencies and implementations are not expected to use JavaScript.
See CONTRIBUTING.md for how changes are proposed, the RFC 2119 conventions this repo follows, and which changes require a version bump. Security issues in the specification — as opposed to an implementation of it — are covered by SECURITY.md.
Released schemas are frozen. See CONTRIBUTING.md § Published schemas are frozen.