# Protocol Core This is the reusable baseline protocol for **consent-based, peer multi-LLM collaboration with a human maintainer**. Use this document across projects. Put project-specific details in a separate [Session Charter](./SESSION_CHARTER.md). --- ## 1) Collaboration model This protocol governs **parallel agents with a human relay**: - Agents work concurrently on owned files, coordinated through a shared WORKLOG - Agents cannot see each other's in-progress work or communicate directly - The human maintainer is the only real-time coordinator and the final decision authority - The WORKLOG is eventually-consistent, not strongly-consistent All protocol rules are designed for this reality. Do not assume real-time awareness of what other agents are doing. --- ## 2) Roles - **Maintainer (required, exactly one):** sets priorities, breaks ties, holds merge authority, assigns lanes. See [Human Governance](./HUMAN_GOVERNANCE.md) for full responsibilities. - **Agents (required, two or more):** each agent owns a defined lane of files. Agent names, models, and lane assignments are configured in the session charter. - **Observers (optional):** read-only participants who may post review comments but do not own lanes or produce deliverables. The core protocol does not limit the number of agents — a session may have two, three, or more. --- ## 3) Invariant rules These rules cannot be overridden by the session charter: 1. **File-level lane ownership** must be defined before implementation begins. Each file has exactly one owner. If two agents might edit the same file, redesign the split. Lane assignments can only be revised by a logged maintainer decision in the WORKLOG. 2. **Contract-first:** shared interfaces, schemas, and contracts ship with tests before any agent begins parallel implementation. Without a locked contract, agents working in parallel will build against incompatible assumptions. 3. **Handoffs are mandatory** after every completed task (quick or full format, per [section 5](#5-handoff-formats)). 4. **Every completed task must include test evidence** (command + pass count). 5. **Retrospective required** at milestone close (see [section 9](#9-retrospective)). 6. **Counter-recommendations are encouraged.** When an agent disagrees with another agent's recommendation, they document it using the template in [section 5](#5-handoff-formats). Disagreement is signal, not friction. See [Conflict Resolution](./CONFLICT_RESOLUTION.md) for the full escalation ladder. 7. **Same-family instances count as one voice.** When a provider family has multiple concurrent instances, the family still contributes one review voice. Instances count as one family voice, cannot satisfy proposer/implementer separation against a sibling instance, and must reconcile conflicting family verdicts before recording the external review. 8. **Instance heartbeats use instance sentinels.** A persistent same-family instance may use `HEARTBEAT-..md` so one instance closing does not stop a sibling's steward. The existing `HEARTBEAT.md` name remains valid for single-instance operation. 9. **Ephemeral delegates are not protocol participants.** A delegate, subagent, or fan-out worker spawned by an agent or instance is attributed to the spawner. Delegate output must be reviewed by the spawner before it enters protocol evidence; delegates never write coordination artifacts such as TURNFILE, mailbox, review, or quorum records directly and cannot contribute quorum standing. --- ## 4) Cross-review policy Default: **aspirational, non-blocking**. When cross-review happens, the reviewing agent posts comments in the WORKLOG. Neither agent should wait for cross-review to declare a task complete. The test suite is the primary integration contract; cross-review is supplementary. If a milestone is security-critical or high-risk, the maintainer may set cross-review to **mandatory** in the session charter. --- ## 5) Handoff formats ### Full handoff (significant milestones or ownership transfers) ```text Handoff: Owner: Status: Changed files: Tests run: Risks/assumptions: Blocking items: Next owner: ``` ### Quick handoff (tasks under 30 minutes) ```text — : (). Next: . ``` Example: `14:32 — Agent-A: auth-module.js + tests complete (47 pass). Next: Agent-B integration wiring.` ### Counter-recommendation (disagreement) ```text ** recommended:** **'s counter-recommendation:** **Reasoning:** **Agreed action:** ``` See also: [templates/counter-recommendation.md](../templates/counter-recommendation.md) --- ## 6) WORKLOG requirements The WORKLOG is the shared communication channel. See [Communications Protocol](./COMMUNICATIONS_PROTOCOL.md) for the full event model. ### Pinned status block (top of file, updated in-place) ```text Now Working (): Now Working (): [... one line per active agent ...] Maintainer Focus: Next Review Checkpoint: ``` Each agent updates **only their own** "Now Working" line when starting or finishing work. The "Maintainer Focus" and "Next Review Checkpoint" lines are **maintainer-only** — agents must not edit them. ### Decision index (after status block, append-only) | Decision | Owner | Timestamp | Section | |----------|-------|-----------|---------| One row per significant decision. Keeps the WORKLOG scannable as it grows. ### Entry budget - Tasks under 30 minutes: quick handoff (1-3 lines max) - Tasks over 30 minutes or ownership transfers: full handoff - Tables and detailed analysis: only for milestone-level deliverables --- ## 7) Definition of done A task is done only when all of the following are true: - Acceptance criteria met (defined in the session charter) - Tests added/updated and passing - Docs updated if behavior changed - Handoff posted (quick or full, per [section 5](#5-handoff-formats)) - Status marked `Ready for review` or `Ready for merge` --- ## 8) Session kickoff checklist Run at the start of every collaborative session: - [ ] Confirm lane boundaries and file ownership (session charter) - [ ] Confirm shared contract/schema exists with tests, or create it first - [ ] Initialize WORKLOG with pinned status block (one line per agent) - [ ] Confirm handoff format expectations (quick vs full thresholds) - [ ] Confirm acceptance criteria and risk tier (session charter) - [ ] Each agent signs the handshake acknowledgment in the session charter - [ ] Commit to closing retro at milestone end ([section 9](#9-retrospective)) --- ## 9) Retrospective Every milestone closes with a retrospective. Previous retros should be archived with a version suffix (e.g., `RETRO_v1.md`). ### Minimum retro content ```text Wins: Risks: Surprises: Repeat: Change: ``` Detailed retros may expand with cross-agent comparison, metrics, and protocol recommendations. Review previous retros before changing the protocol. See also: [templates/retrospective.md](../templates/retrospective.md) --- ## 10) Versioning - The session charter or a protocol index file maintains the version history - Archive old protocol versions with a version suffix (e.g., `PROTOCOL_CORE_v1.md`) - Bump the protocol major version only when invariant rules ([section 3](#3-invariant-rules)) change - Link to the relevant retro from each version history entry when available