Protocol v6

The protocol is the product. It defines how agents collaborate under human governance: how turns are structured, how decisions are recorded, how phases advance through gates, and how humans retain final authority. v6 is the current constitution.

Overview

Protocol v6 closes the constitutional gap left by v5. In v5, multi-repo coordination was informal — teams used conventions but nothing was enforced. v6 introduces the coordinator initiative: a first-class mechanism for governing work across multiple repositories with shared barriers, cross-repo context, and synchronized gates.

v6 also tightens the single-repo protocol with mandatory objections, structured verification evidence, and a decision ledger that serves as an audit trail.

Version history

Version	Release	Key changes
v4	2025-Q1	Initial governed mode. Single-repo only. Phases and roles. Manual adapter. No structured decisions or objections.
v5	2025-Q3	Added local_cli and api_proxy adapters. Introduced decision/objection schema. Added verification evidence. Plugin system (script hooks). Dashboard.
v6	2026-Q1	Coordinator initiative (multi-repo). super_run_id linking. Cross-repo barriers and gates. HTTP hooks. Mandatory objections. Decision ledger as constitutional record. Schema version 1.0 for all artifacts.

Repo-local governed run

A governed run within a single repository is the foundation of the protocol. Every concept in v6 builds on this base.

Files

Path	Purpose
agentxchain.json	Project configuration: roles, adapters, phases, plugin config
.agentxchain/state.json	Mutable run state: current phase, pending turn, blocked status, run ID
.agentxchain/history.jsonl	Append-only log of all accepted turn results (one JSON object per line)
.agentxchain/decision-ledger.jsonl	Append-only log of all decisions, objections, gate approvals, and rejections
.agentxchain/dispatch/turns/<turn_id>/	Dispatch bundle for each turn (ASSIGNMENT.json, PROMPT.md, CONTEXT.md)
.agentxchain/staging/<turn_id>/turn-result.json	Staged turn result awaiting acceptance
.agentxchain/prompts/<role>.md	Role prompt templates
.planning/	Human-facing planning artifacts (PM_SIGNOFF.md, ROADMAP.md, etc.)
TALK.md	Free-form communication channel between human and agents

Commands

The governed run is driven by a sequence of commands:

init → step (pm) → accept-turn → approve-transition
     → step (dev) → accept-turn
     → step (qa) → accept-turn → approve-completion

Each step creates a turn. Each accept-turn commits the result to history. Gates (approve-transition, approve-completion) are human-only checkpoints that the orchestrator cannot bypass.

Phase model

Phase	Purpose	Entry gate	Exit gate
planning	PM defines scope, acceptance criteria, roadmap	init (automatic)	approve-transition to implementation
implementation	Dev writes code, tests, documentation	approve-transition from planning	approve-transition to verification
verification	QA challenges the implementation, runs tests	approve-transition from implementation	approve-completion

Custom phases can be defined in agentxchain.json. The protocol enforces that every phase transition passes through a human gate.

Coordinator initiative

The coordinator initiative extends governed runs across multiple repositories. A coordinator manages a super run that links individual repo runs through shared barriers and gates.

Core concepts

Concept	Description
super_run_id	A unique ID that links all repo-level runs in a coordinated initiative
Workstream	A single repo-level governed run, identified by repo name and run ID
Barrier	A synchronization point where all workstreams must reach a given phase before any can proceed
Cross-repo gate	A human approval that applies to the super run, not just one workstream
Coordinator hooks	Lifecycle hooks that fire at the super-run level

How it works

1. A human creates a coordinator config (agentxchain-multi.json) that defines workstreams and barriers.
2. Each workstream is initialized as an independent governed run with a shared super_run_id.
3. When a workstream reaches a barrier phase, it enters blocked:barrier state.
4. The coordinator polls all workstreams. When all have reached the barrier, the coordinator fires a cross-repo gate.
5. The human approves the cross-repo gate, and all workstreams are unblocked simultaneously.

Workstream A:  init → pm → [barrier: planning] ─────────────┐
Workstream B:  init → pm → [barrier: planning] ──────┐      │
Workstream C:  init → pm → [barrier: planning] ──┐   │      │
                                                  ▼   ▼      ▼
                                          Cross-repo gate (human)
                                                  │   │      │
                                                  ▼   ▼      ▼
Workstream A:  ──────────────────── dev → qa → [barrier: verification]
Workstream B:  ──────────── dev → qa → [barrier: verification]
Workstream C:  ──── dev → qa → [barrier: verification]

Coordinator config

The coordinator config lives at the initiative root (not inside any single repo):

agentxchain-multi.json

{
  "schema_version": "1.0",
  "super_run_id": "super_run_abc123",
  "description": "Q2 platform migration across three services",
  "workstreams": [
    {
      "name": "auth-service",
      "repo": "[email protected]:org/auth-service.git",
      "branch": "feature/q2-migration",
      "config_path": "agentxchain.json"
    },
    {
      "name": "api-gateway",
      "repo": "[email protected]:org/api-gateway.git",
      "branch": "feature/q2-migration",
      "config_path": "agentxchain.json"
    },
    {
      "name": "web-client",
      "repo": "[email protected]:org/web-client.git",
      "branch": "feature/q2-migration",
      "config_path": "agentxchain.json"
    }
  ],
  "barriers": [
    {
      "name": "planning-sync",
      "phase": "planning",
      "description": "All workstreams must complete planning before any begins implementation"
    },
    {
      "name": "verification-sync",
      "phase": "verification",
      "description": "All workstreams must complete implementation before final verification"
    }
  ],
  "hooks": {
    "on_barrier_reached": "./coordinator-hooks/barrier-reached.sh",
    "on_barrier_approved": "./coordinator-hooks/barrier-approved.sh",
    "on_super_run_completed": "./coordinator-hooks/completed.sh",
    "on_workstream_failed": "./coordinator-hooks/workstream-failed.sh"
  },
  "context_generation": {
    "enabled": true,
    "output_dir": ".coordinator/context/",
    "include_decisions": true,
    "include_objections": true,
    "include_file_summaries": true
  }
}

Gates and resync

The coordinator enforces three invariants at every barrier:

Invariant 1: Barrier completeness

All workstreams must reach the barrier phase before any can proceed past it. A single lagging workstream blocks all others. This prevents one repo from advancing to implementation while another is still in planning.

Invariant 2: Cross-repo gate approval

When all workstreams reach a barrier, the coordinator creates a cross-repo gate. A human must approve it. The approval applies to the super run — individual workstream approvals are not sufficient to cross a barrier.

agentxchain coordinator approve-barrier --barrier planning-sync

Invariant 3: State coherence after resync

After a barrier is approved, the coordinator resyncs all workstreams:

1. Each workstream's state.json is updated with the barrier approval timestamp.
2. Cross-repo context is regenerated (see below).
3. Each workstream transitions to the next phase simultaneously.
4. The coordinator records the resync in its own ledger.

If any workstream fails to resync (e.g., corrupt state file), the coordinator enters blocked:resync_failed and requires manual intervention.

Cross-repo context generation

When context generation is enabled, the coordinator assembles a cross-repo context document for each workstream before each phase. This gives each agent visibility into what the other workstreams decided.

The context document is written to each workstream's dispatch bundle as an additional file:

.agentxchain/dispatch/turns/<turn_id>/
  ASSIGNMENT.json
  PROMPT.md
  CONTEXT.md
  CROSS_REPO_CONTEXT.md    ← generated by coordinator

What it contains

Section	Content
Workstream summary	Name, repo, current phase, last accepted turn summary for each workstream
Decisions	All decisions from all workstreams, grouped by category
Open objections	All unresolved objections from all workstreams
File summaries	High-level summary of files changed in each workstream (not full diffs)
Barrier history	Record of all barrier approvals with timestamps and comments

This allows a dev agent in auth-service to know that api-gateway decided to use JWT tokens, and a QA agent in web-client to know that api-gateway has an open objection about rate limiting.

Coordinator hooks

The coordinator fires hooks at four phases of the super-run lifecycle:

Hook	Fires when	Payload
on_barrier_reached	All workstreams have reached a barrier	Barrier name, workstream statuses, phase
on_barrier_approved	A human approves a cross-repo gate	Barrier name, approver comment, timestamp
on_super_run_completed	All workstreams complete and the final gate is approved	Full super-run summary, all decisions, all objections
on_workstream_failed	A workstream enters a failed state	Workstream name, error details, affected barrier

Coordinator hooks follow the same contract as plugin hooks: they receive context via environment variables and a payload JSON file, must exit with code 0 on success, and are killed on timeout.

File layout

A coordinated initiative has this layout on disk:

initiative-root/
  agentxchain-multi.json                    # Coordinator config
  .coordinator/
    state.json                               # Coordinator state (barriers, workstream refs)
    ledger.jsonl                             # Coordinator decision ledger
    context/                                 # Generated cross-repo context documents
      auth-service/CROSS_REPO_CONTEXT.md
      api-gateway/CROSS_REPO_CONTEXT.md
      web-client/CROSS_REPO_CONTEXT.md
  coordinator-hooks/                         # Coordinator hook scripts
    barrier-reached.sh
    barrier-approved.sh
    completed.sh
    workstream-failed.sh
  auth-service/                              # Cloned repo (workstream)
    agentxchain.json
    .agentxchain/
      state.json                             # Has super_run_id field
      ...
  api-gateway/                               # Cloned repo (workstream)
    agentxchain.json
    .agentxchain/
      state.json
      ...
  web-client/                                # Cloned repo (workstream)
    agentxchain.json
    .agentxchain/
      state.json
      ...

Compatibility

v6 extends v5 — it does not replace it. A v5 single-repo governed run is fully valid under v6. The coordinator initiative is an opt-in layer.

Feature	v5	v6
Single-repo governed runs	Yes	Yes
Decisions and objections	Yes	Yes (mandatory objections)
Verification evidence	Yes	Yes
Script plugin hooks	Yes	Yes
HTTP plugin hooks	No	Yes
Dashboard	Yes	Yes
super_run_id linking	No	Yes
Cross-repo barriers	No	Yes
Coordinator initiative	No	Yes
Cross-repo context generation	No	Yes
Coordinator hooks	No	Yes
Decision ledger as constitutional record	Informal	Enforced

To migrate a v5 project to v6:

agentxchain migrate --yes

This adds the schema_version: "1.0" field to all artifacts, enables mandatory objection validation, and prepares the state file for optional coordinator linking. No breaking changes are introduced — existing runs continue without interruption.