multi-agent-git

name	multi-agent-git
description	Discipline for working in a git repo that other agents (or humans) may also be pushing to. Load this whenever editing files on a shared branch like main, especially when working directly to main rather than through a feature branch + PR. Covers when to use Edit vs Write, when to re-Read files, and how to respond when sync-guard's pre-push hook fires.

Multi-agent git discipline

This repo has the sync-guard plugin installed. It catches a specific failure: two sessions both push to the same branch, the second one's git pull --rebase succeeds cleanly, but the files it writes contain content from before the first session's push landed — so the push silently rolls work back to a recent past state, with no merge conflict.

Three rules avoid this almost entirely.

1. Edit, don't Write, for files that already exist

Edit validates that old_string still matches the file on disk. If another session moved the branch and your in-context copy is stale, Edit fails loudly — that's the signal to re-Read before continuing. Write silently overwrites whatever's there.

• Use Edit for any modification to a file that already exists.
• Use Write only for genuinely new files.
• If Edit fails because old_string no longer matches, re-Read the file before retrying — don't just expand the match window. The mismatch usually means the file has legitimately changed.

2. Re-Read after every git pull --rebase

Your memory of file contents goes stale the moment another session pushes. Even if you read a file earlier this session, after a rebase that brought in new commits you have to re-Read every file you plan to edit. The rebase fast-forwards the local ref but doesn't refresh anything in your context window.

In practice: when working directly to a shared branch (no PR), the right sequence is:

1. git pull --rebase origin <branch>
2. Re-Read every file you plan to edit, even ones you read earlier
3. Make changes with Edit
4. Commit
5. git pull --rebase origin <branch> && git push

3. If sync-guard fires on push, don't --no-verify

The hook reports files where the push appears to revert recent work. The default response is:

1. git pull --rebase origin <branch> to pull in whatever you missed
2. Re-Read the named files to see what they actually contain now
3. Redo your edit on top of the current content
4. Push again

git push --no-verify bypasses the check. Only use it when you actually intend to revert — and in that case, prefer making the commit message start with Revert: so the hook recognises the intent without needing an override flag.

What sync-guard does NOT catch

• Cross-file rewrites where reverted content moves between files.
• Reverts of work older than the hook's look-back window (default 6 hours, file history depth 20 commits).
• Pushes to non-protected branches (defaults to only main). Feature branches rely on PR review.

Rules 1 and 2 cover the in-session case; rule 3 is the boundary backstop.