The coordination protocol for parallel AI agents that guarantees merge-conflict-free execution by construction.
This repository contains the implementation-agnostic specification of the Polywave protocol. These documents define the coordination rules, correctness guarantees, and behavioral contracts that any Polywave implementation must satisfy, independent of the runtime, LLM provider, or tooling used.
Using Claude Code? Start at polywave for the Agent Skill and install guide. This repo is the protocol reference, not the entry point for users.
No two agents in the same wave own the same file (I1: Disjoint File Ownership). This is not a convention or a preference. It is a hard constraint enforced before any worktree is created. Merge conflicts between parallel agents become structurally impossible.
Unlike frameworks that detect conflicts at merge time and attempt resolution (always lossy, often manual), Polywave makes conflicts structurally impossible before agents start. The file ownership partition is validated, the suitability gate passes, and only then are worktrees created. Safety comes from protocol enforcement, not agent cooperation.
Read these in order to understand the complete protocol:
| Document | Description |
|---|---|
| participants.md | Seven participant roles (Orchestrator, Scout, Scaffold Agent, Wave Agent, Integration Agent, Critic Agent, Planner), their execution modes, responsibilities, and forbidden actions |
| preconditions.md | Five preconditions that must hold before the protocol may run |
| invariants.md | Six invariants (I1-I6) that must hold throughout protocol execution |
| execution-rules.md | 49 execution rules (E1-E45, including sub-rules) governing state transitions, agent launches, merge procedures, verification gates, and failure recovery |
| state-machine.md | Protocol states and transitions |
| message-formats.md | IMPL doc and completion report schemas |
| procedures.md | Step-by-step procedures for all protocol phases |
| interview-mode.md | E39: Structured interview mode for deterministic requirements gathering |
| observability-events.md | E40: Observability event emission schema |
| program-invariants.md | P1-P5: Program-level invariants for multi-IMPL coordination |
| program-manifest.md | PROGRAM manifest schema for coordinating multiple IMPLs |
| impl-manifest.schema.json | JSON Schema for IMPL manifest validation |
When all preconditions are met and all invariants hold throughout execution, the protocol guarantees:
- No merge conflicts between agents working in the same wave
- Reproducible verification via agent-specific gates before merge
- Human checkpoint enforcement at suitability gate and REVIEWED state
- Structured failure recovery via completion reports, failure taxonomy (E19), and orchestrator escalation
- Post-wave quality enforcement via stub detection (E20) and automated quality gates (E21)
- Interface build safety via Scaffold Agent build verification before wave launch (E22)
The protocol is designed to be implemented on any platform that can spawn parallel agents and enforce file ownership boundaries.
| Implementation | Platform | Status |
|---|---|---|
| polywave | Claude Code (Agent Skill) | Production |
| polywave-go | Go SDK + CLI (polywave-tools) |
Production |
| polywave-web | Web app (React + Go) | Production |
- Read the protocol docs in the order listed above
- Identify which participant roles your runtime will support (minimum: Orchestrator + Wave Agent)
- Choose an isolation mechanism that satisfies I1 (disjoint file ownership): git worktrees, filesystem snapshots, containers, etc.
- Choose an enforcement mechanism for I1 at the tool boundary: pre-execution validation, filesystem permissions, platform-specific hooks, or any mechanism that blocks writes outside an agent's assigned files
- Implement the state machine transitions (see state-machine.md)
- Implement structured message parsing (see message-formats.md)
- Verify your implementation satisfies all six invariants (see invariants.md)
The protocol requires that invariants be enforced. It does not prescribe how. Each implementation chooses enforcement mechanisms appropriate to its platform.
This protocol specification follows semantic versioning. Breaking changes to invariants, preconditions, or message formats increment the major version. New optional fields or clarifications increment the minor version.