agent-collab-protocol

English | 简体中文

File-driven multi-agent collaboration for real software work.

Multi-agent coding usually breaks at handoff time.

This repository documents a practical way to run collaborative software work without relying on chat memory as the source of truth.

The protocol is built around one idea:

• requirements live in tracked files
• implementation handoff lives in tracked files
• review conclusions live in tracked files
• state transitions live in tracked files

Instead of "multiple chat windows", this protocol treats collaboration as a reproducible engineering workflow.

In One Sentence

Use files, explicit roles, and durable review writeback so multi-agent work behaves more like engineering and less like improvisation.

Who This Is For

This protocol is a good fit if you:

• use more than one coding agent or model on the same task
• want design, implementation, and review to stay separate
• are tired of manually relaying review comments between tools
• need work to survive long sessions, restarts, or tool switches
• care more about reliability than flashy autonomy demos

What Problem It Solves

Many multi-agent demos look convincing, but fail in day-to-day engineering because:

• requirements drift between chats
• one model silently plays planner, implementer, and reviewer
• review feedback is only summarized in chat and gets lost
• implementation gets mistaken for acceptance
• the human becomes the message bus

This protocol reduces those failures by making handoff artifacts explicit and durable.

What Makes It Different

Most "multi-agent" setups optimize for generation.

This protocol optimizes for:

• recoverability
• role clarity
• review quality
• test-backed acceptance
• future automation without hidden state

Core Model

Requirement -> Spec -> Impl -> Review -> Revise/Accept -> Archive

The protocol distinguishes:

• solo: normal tracked work, no formal collab artifacts
• collab: requirement uses explicit spec/impl/review/state artifacts

And for collab:

• B-lite: low-friction spec -> implement -> review
• A-review: plan-gated flow for high-risk work

A Minimal Example

1. Planner writes the requirement and spec
2. Implementer writes an implementation artifact and changes code
3. Reviewer writes a review artifact and either accepts or requests revision
4. Archive happens only after accepted review state is explicit

The result is a workflow another tool can resume without asking the human to paste the missing context again.

Role Boundaries

The same tool may switch roles, but role ownership must stay explicit.

Design Goals

• keep a single requirement entry point
• separate spec, implementation, and review roles
• make every handoff recoverable from files
• keep the workflow lightweight enough for daily use
• allow gradual automation later, without hiding the truth source

Source Of Truth

For a collab requirement, the source of truth is file-based:

.project/requirements/<id>.md
.project/collab/<id>/state.json
.project/collab/<id>/spec-rN.md
.project/collab/<id>/impl-rN.md
.project/collab/<id>/review-rN.md
AGENTS.md

Chat is a summary layer, not the primary handoff mechanism.

Collab State Flow

Review Model

A collab review should combine three layers:

1. requirement/spec compliance
2. project rule compliance from AGENTS.md
3. technical validation from a review engine such as diff analysis, compile checks, trace checks, or DB verification

That means "good-looking code" is not enough by itself.

Quick Start

1. Read docs/architecture.md
2. Read docs/workflow.md
3. Copy the files under templates/ into a test project
4. Run one requirement in solo or collab
5. Use the example under examples/ as a reference

If you only have 5 minutes, read the example first:

• examples/001-add-refund-flag/README.md
• 简体中文 README

Repository Layout

docs/
  architecture.md
  workflow.md
  faq.md
templates/
  AGENTS.md
  requirement.md
  collab-state.json
  spec-r1.md
  impl-r1.md
  review-r1.md
examples/
  001-add-refund-flag/

Principles

• tests are the primary executable verifier
• reviewers are not preference vetoers
• project rules outrank reviewer preferences
• implementers must not accept their own work
• review writeback must happen before chat summary
• automation is opt-in, not ambient

Scope

This repository shares the protocol and templates.

It does not require any specific vendor, model, CLI, or editor. The same protocol can be adapted to general-purpose coding agents, chat-based coding tools, editor-integrated assistants, or custom internal agents.

Status

This is a working protocol, not a finished platform.

The current focus is:

• stable human-driven collaboration
• explicit review writeback
• clear archive rules
• future-friendly state transitions

Automation can be layered later, but only after the manual protocol is already reliable.