docs(agents): add multi-agent PR coordination rules - #809
Conversation
|
PR template check (advisory, non-blocking) This PR body doesn't look like it covers everything
This isn't a required check -- it won't block merge. See the template's own "Notes for contributors" for which sections lighter-path PRs can skip. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 831b2b578f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| git merge-base --is-ancestor HEAD origin/main \ | ||
| && echo "OK: linear, pull is fine" \ | ||
| || echo "REWRITE/DIVERGED: hard-reset or re-clone" |
There was a problem hiding this comment.
When this snippet is run on the feature branch that agents are told may already contain current origin/main, the ancestry test is reversed: git merge-base -h documents --is-ancestor as checking whether “the first one” is ancestor of “the other”, so any healthy branch with its own commits fails HEAD origin/main and is reported as REWRITE/DIVERGED. That contradicts the repo’s fresh-main gate, which requires origin/main to be an ancestor of the branch, and can send agents into unnecessary hard-reset/re-clone recovery for valid PR branches; swap the arguments for branch freshness or explicitly scope this snippet to local main only.
AGENTS.md reference: AGENTS.md:L304-L307
Useful? React with 👍 / 👎.
chatgpt-codex-connector flagged that the new "quick stale-clone test" snippet had its git merge-base --is-ancestor arguments backwards: `--is-ancestor HEAD origin/main` asks whether HEAD is an ancestor of origin/main, which is false for any healthy feature branch carrying its own commits -- it would report REWRITE/DIVERGED and send agents into an unneeded hard-reset/re-clone even when the branch already contains current origin/main. Verified empirically: running the old check against a branch that already contains the latest origin/main plus 10 of its own commits prints "REWRITE/DIVERGED" (false positive); the corrected `--is-ancestor origin/main HEAD` correctly prints "OK". Co-Authored-By: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
831b2b5 to
cd0f4ac
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cd0f4ac40b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ```bash | ||
| git checkout main | ||
| git fetch origin | ||
| git reset --hard origin/main |
There was a problem hiding this comment.
When local main contains unique commits or tracked edits—the kind of divergence this section is intended to address—this unguarded command discards them; git reset -h confirms that --hard resets HEAD, the index, and the working tree. The canonical workflow instead requires isolating unknown or dirty checkouts and treating destructive actions as approval-gated, so the recovery should first inspect and preserve local work and prefer a fast-forward when possible.
AGENTS.md reference: AGENTS.md:L261-L264
Useful? React with 👍 / 👎.
| || echo "REWRITE/DIVERGED: hard-reset or re-clone" | ||
| ``` | ||
|
|
||
| If branches have diverged, refuse merge "fixes." Reset to remote truth: |
There was a problem hiding this comment.
When the preceding test is run from a feature branch that merely fell behind origin/main, it reports failure because the new main tip is not an ancestor of that feature HEAD. Switching to main and resetting it does not change the feature branch, so returning to the feature branch produces the same failure and the pre-push gate still refuses it; the documented recovery is to rebase the feature branch onto fresh origin/main, inspect conflicts, and rerun validation rather than refusing merge-based reconciliation.
AGENTS.md reference: AGENTS.md:L261-L264
Useful? React with 👍 / 👎.
…ly stale Two more codex findings on the same section fixed in the prior commit: - The documented recovery (checkout main, fetch, hard-reset main) only helps when local main itself is what's stale. Run the quick-check from a feature branch that's simply behind (the common case for an agent branch cut before a later merge landed on main) and it reports REWRITE/DIVERGED, but resetting main does nothing for that branch -- switching back to it fails the same check and the pre-push gate still refuses it. Verified against this session's own history: PR #804/#809/#810 were in exactly this state (cut before #802 merged) and the fix was `git rebase origin/main` on each feature branch, not a main reset. - `git reset --hard origin/main` was presented unconditionally, with no check for unique local commits or uncommitted work it would discard. `git reset -h` confirms --hard resets HEAD, the index, and the working tree. CLAUDE.md's own Git Safety Protocol treats `reset --hard` as destructive and never to run without explicit confirmation; this doc contradicted that by presenting it as a bare recovery one-liner. Added the feature-branch rebase path as the primary recovery, and gated the main-reset path on `git status --short` being clean and `git log origin/main..main` being empty first. Co-Authored-By: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e9d22103cd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 1. **One source of truth.** Always `git fetch origin` first. Current | ||
| `origin/main` is the only tip that counts. |
There was a problem hiding this comment.
In a feature-only or --single-branch clone, remote.origin.fetch maps only that feature branch, so git fetch origin leaves origin/main absent; I reproduced this with the configured refspec +refs/heads/feature:refs/remotes/origin/feature (the checked git fetch -h syntax makes the refspec optional). The ancestry snippet then emits an invalid-revision error and classifies the checkout as rewritten/diverged rather than checking freshness. Explicitly fetch main into refs/remotes/origin/main before relying on that ref.
AGENTS.md reference: AGENTS.md:L304-L307
Useful? React with 👍 / 👎.
| ```bash | ||
| git merge-base --is-ancestor origin/main HEAD \ | ||
| && echo "OK: current branch already contains origin/main" \ | ||
| || echo "REWRITE/DIVERGED: hard-reset or re-clone" |
There was a problem hiding this comment.
Although the newly added recovery prose now correctly says that an ordinarily behind feature branch must be rebased, the command itself still prints hard-reset or re-clone for exactly that common case. This can direct an agent following the executable snippet toward unnecessary destructive recovery; report only that the branch does not contain current origin/main and point to the branch-specific recovery below.
AGENTS.md reference: AGENTS.md:L353-L357
Useful? React with 👍 / 👎.
Two more codex findings on the same stale-clone-test block: - A single-branch or sparse clone's remote.origin.fetch maps only the checked-out branch, so a plain `git fetch origin` never creates `origin/main` -- the ancestry check then fails with "unknown revision" (exit 128), which the `&&`/`||` wrapper reports as REWRITE/DIVERGED even though nothing has actually diverged. Reproduced live: cloned this repo with `--single-branch`, ran the documented `git fetch origin`, confirmed `origin/main` doesn't exist and the check misreports. The snippet now fetches `origin/main` with an explicit destination refspec (`git fetch origin main:refs/remotes/origin/main`), which creates the ref regardless of the configured fetch refspec -- verified this resolves it in the same single-branch clone. - The failure branch of that same snippet still printed "REWRITE/DIVERGED: hard-reset or re-clone" for the ordinarily-behind feature-branch case the prior commit's recovery prose already says to rebase, not reset -- steering an agent that only reads the echoed message toward unneeded destructive recovery. Message is now branch-neutral and points at the recovery section below instead of prescribing one. Co-Authored-By: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
1 participant
Summary
Adds a concise Multi-Agent PR Coordination section to
AGENTS.mdso Grok/Claude/Codex/Kimi/etc. sessions share the same operating rules when opening parallel PRs.Rules captured
origin/mainafter fetch is the only source of truthAlso includes the quick
merge-basestale-clone check and the hard-reset recovery commands.Test plan
## Known Gotchas