Skip to content

Multi Agent Write Protocol

Jump to bottom
Chris Sweet edited this page May 31, 2026 · 5 revisions

type: concept up: "Home_llm-wiki-memory-template" extends: "Three-Operations" status: aspirational tags: [protocol, multi-agent, concurrency, occ, collision-free, design, not-yet-implemented]

Multi-Agent Write Protocol

STATUS: design + prototype only. The protocol is specified here and exercised by a deterministic prototype, but is not yet wired into any agent overlay or shipped in the template. The template's current concurrency story is git pull --rebase at session boundaries; this protocol is the proposed evolution for projects with two or more agent writers. See Implementation-Status.

A write protocol for wikis that have multiple LLM-agent writers and (by assumption) no human writers. Prevents push-level collisions by construction: each agent writes via its own contribution branch and only merges into main when the merge is clean; conflicts trigger the writing agent to semantically re-plan its changes against the new state of main before retrying.

Problem

The wiki is shared memory across a team. Multiple agent sessions (you-via-Claude in project A, your-collaborator-via-Claude in project B, a CI-bot agent running scheduled lints) all need to read and write the same git-backed wiki sub-repo. The existing template's defence is git pull --ff-only at SessionStart plus a pre-push collision guard: these resolve collisions when they happen, but agents still hit them and have to back out their work. We want a protocol that prevents collisions at the push level by construction, so that every successful write attempt produces a clean, atomic update to main.

The constraint that makes this tractable: only agents write to the wiki. No human bypasses the protocol with a manual edit. That means we can encode the protocol in the agent's write path and trust it to be followed.

The protocol

For each write attempt by an agent:

  1. Branch from current main. Agent fetches origin/main of the wiki repo and creates a working branch agent/<handle>/<timestamp> off it. <handle> is the agent's canonical identity (see PostToolUse-Hook and the proposed claude-<human>@<project> format).
  2. Edit and commit locally. Agent makes its changes and commits them to the working branch. Standard wiki conventions apply: Verification-Gate criteria pass, index updated, log entry appended.
  3. Re-fetch and attempt merge. Agent fetches origin/main again (catches anything committed during its session) and attempts to merge the latest origin/main into the working branch (or rebase, per local policy). The merge is non-fast-forward by intent: git merge --no-commit --no-ff origin/main.
  4. Clean merge → push. If the merge produces no conflicts, the agent commits the merge result, then pushes the working-branch tip to origin/main: 
    git push origin HEAD:main
    If the push is rejected (someone won the race in the milliseconds between fetch and push), goto 3.
  5. Conflict → classify and resolve. If the merge reports conflicts, the agent reads the conflict markers and classifies each file:
    • Index / log files: apply union merge automatically (see Conflict Classification below). Do not invoke semantic reasoning.
    • Substantive content overlap: the agent semantically reconciles. It reads what the other agent committed, decides whether to drop its change (the other agent did the same thing), adapt its change to fit alongside the other (most common case), or supersede the other change with an explicit rationale. The resolution is committed to the working branch. Goto 3.
  6. Retry cap. After K=3 retry attempts without a clean merge, the agent halts and asks the human for guidance. The working branch is preserved so the human can inspect it.

Properties:

  • Collision-free at the push level. Only one ref-update to origin/main ever succeeds at a time; losing pushes trigger a retry, not a stuck state.
  • No separate reconciler agent. Each writing agent reconciles its own attempts. There is no third party to design, schedule, or trust.
  • Atomic from main's perspective. main is never in a half-merged state. Readers fetching main always see a consistent wiki.
  • No GitHub-side dependencies. The protocol uses only git mechanics. It works on GitHub wikis (which do not support pull requests), private gitservers, or any other git remote. GitHub PRs may be layered on top for visibility (humans see contributions in flight) but are not load-bearing for correctness.

Conflict classification

The protocol relies on classifying conflicts so that mechanical merges (most cases) do not trigger expensive semantic reasoning.

Conflict shape Classification Resolution
Index file (index_<repo>.md): both agents add new entries at end Mechanical Union merge. Configure .gitattributes: index_*.md merge=union. Both entries present after merge; order is commit-order, not strict alpha.
Log file (log_<repo>.md): both agents append new entries Mechanical Union merge. Same .gitattributes pattern. Order is commit-order; the Log-Entry-Attribution convention (one commit per entry) ensures entries do not interleave within a single commit.
Different pages, no shared edits None Three-way merge succeeds without intervention.
Same page, different sections Mechanical Three-way merge succeeds without intervention, assuming sections are well-separated.
Same page, same section, non-overlapping lines Mechanical Three-way merge succeeds without intervention.
Same page, same section, overlapping lines Semantic Agent reads the other agent's lines, decides drop / adapt / supersede.
Both agents created the same new page Semantic Treated as "same page, full overlap." One version becomes the base; the other agent's version is reconciled into it.

The .gitattributes file in the wiki sub-repo should declare the union-merge driver for the navigation files explicitly:

index_*.md  merge=union
log_*.md    merge=union

This is a one-time configuration step that goes in init-wiki.sh (or as a sync-flow addition). Without it, two agents that both add a new index entry produce a textual conflict that the agent will mis-classify as semantic.

Required agent capabilities

The protocol assumes the agent can:

  • Run standard git operations: fetch, branch, commit, merge, push, read conflict markers from files, abort a merge.
  • Read its own canonical handle from a known location (e.g., .claude/agent-id or git config wiki.agent.handle).
  • Loop: retry with backoff up to K times before escalating.
  • For semantic resolution: read the other agent's contribution, understand the intent, decide drop / adapt / supersede, write the resolved content. This is the LLM-native capability that distinguishes this protocol from classical OCC-with-retry.

The agent does not need a separate reconciler, a coordinator service, a distributed lock manager, or any infrastructure beyond git.

Failure modes and mitigations

  • Livelock. Agent A retries; agent C commits during the retry; A retries again; agent D commits; and so on. In principle possible; in practice, wiki edit frequency is low and sessions are bounded. Mitigation: the K=3 retry cap halts cleanly and surfaces the situation to the human. If livelock becomes routine, a backoff (sleep N seconds before retry) or a lease window (agent claims temporary exclusive write access) can be layered on.
  • Network failure mid-push. Standard git semantics: the push either lands or it does not. The working branch is local and unchanged, so the agent can simply re-attempt step 3.
  • Stale working branch. If the agent's session ran for hours and main has moved significantly, the conflict surface may be large. The protocol still works (step 3 re-fetches; step 5 reconciles) but each retry takes longer. Mitigation: re-fetch periodically during long sessions, not only at write time.
  • Two agents create the same new page name. One push wins. The loser sees the won page as a conflict on its next retry and reconciles semantically: usually by adopting the won content and folding its own contribution in.
  • Index entries pointing to dropped pages. If the semantic resolver drops a page that its own index entry referenced, the index entry becomes a dead link. The Verification Gate (Verification-Gate) catches this on the next ingest cycle. Stricter: the resolver should remove the index entry in the same merge commit when it drops a page.

Worked examples

Example 1: two agents add different new pages.

  • Agent A on machine M1: creates New-Topic-Alpha.md, adds index entry, appends log entry. Commits.
  • Agent B on machine M2: creates New-Topic-Beta.md, adds index entry, appends log entry. Commits.
  • A merges first: clean. Pushes. Done.
  • B fetches; merges A's commit into its working branch. Conflict only on index_<repo>.md and log_<repo>.md (both appended new lines). Union merge resolves; B's New-Topic-Beta.md is untouched. Pushes. Done.
  • Final state: both pages present; index has both entries; log has both entries in commit order.

Example 2: two agents edit different sections of the same page.

  • Agent A: edits the "Method" section of Page-X.md. Commits.
  • Agent B: edits the "Results" section of Page-X.md. Commits.
  • A merges first: clean. Pushes.
  • B fetches; merges. Three-way merge handles the two non-overlapping section edits without conflict. Pushes.

Example 3: two agents edit the same section.

  • Agent A: rewrites the "Conclusion" of Page-X.md, with a stronger framing.
  • Agent B: rewrites the "Conclusion" of Page-X.md, with a more cautious framing.
  • A merges first; pushes.
  • B fetches; merges; conflict on Page-X.md "Conclusion" section.
  • B's semantic resolver reads A's conclusion. Three choices:
    • Drop: A's conclusion is better; B abandons its rewrite. Re-commit with the merge-as-A-wrote-it.
    • Adapt: B integrates its cautious framing into A's stronger framing (adds caveats, qualifies absolute claims). Re-commit.
    • Supersede: B has new information A didn't have; B's framing replaces A's, with a log entry explaining why. Re-commit.
  • B's resolver picks one (likely "adapt"); merges; pushes.

Example 4: two agents both append to the log.

  • A appends ## [2026-05-31] lint | .... Commits, pushes.
  • B appends ## [2026-05-31] ingest | .... Commits.
  • B fetches; merges. log_<repo>.md has both entries. With merge=union in .gitattributes, union merge applies automatically. Both entries appear in commit order. B pushes.

Open questions

  • Order semantics for the log. Should the log file be strictly chronological, or is commit-order acceptable? Strict chronological requires the agent to re-sort after every union merge; commit-order is mechanical. Recommend commit-order with periodic agent-driven re-sort if drift becomes confusing.
  • Drop vs adapt vs supersede heuristics. When does the semantic resolver choose each? Document the heuristics; likely "adapt" is the default, "drop" only when the other agent literally did the same thing, "supersede" only with new information and explicit rationale in the merge-commit message.
  • Lease window opt-in. If livelock becomes routine, an optional lease mechanism could let one agent claim exclusive write access for N minutes. Specify the lease file convention if added later.
  • Visibility for humans. If the wiki lives in a regular repo (not a GitHub wiki), wrapping the protocol in PRs gives humans a contribution feed. If it lives in a GitHub wiki, the contribution branches themselves are visible via git log on origin/main's parent history. Document a recommended visibility path per repo type.

Relationship to existing wiki pages

  • Verification-Gate: the four-criteria pre-commit gate still applies to the merge commit. The protocol is orthogonal to it.
  • Lesson-Validation-Methodology: structural validation of this protocol is what the prototype (linked from Implementation-Status) provides. Behavioural validation requires real LLM agents in the loop, which is deferred.
  • Sync-Flow: orthogonal. Sync-Flow governs how template improvements propagate to derived projects; this protocol governs how multiple agents share a single derived project's wiki.
  • PostToolUse-Hook: complementary. The PostToolUse hook nudges an agent to run the Verification Gate; the write protocol governs what happens when the agent actually pushes.
  • Lesson-Hook-Type-Matters: any agent implementation of this protocol should follow the command-type-hook discipline (advisory, not blocking) for any reminders surfaced during the retry loop.

See also

  • Three-Operations: the wiki's read/write/lint operations; this protocol slots into the write side of ingest and lint.
  • Knowledge-Graph-Pipeline: orthogonal; the KG pipeline (also aspirational) consumes merged main state, regardless of how that state was produced.
  • Wiki-Corrections-Log: receipt for the 2026-05-31 ingest of this page.
  • Implementation-Status: tracks this page's aspirational status and links to the prototype.

Clone this wiki locally