From 75f314a76768d2a6dd8a75444d2382f22af6954b Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Mon, 1 Jun 2026 22:27:58 +0800 Subject: [PATCH] docs(agents): add multi-agent working discipline to AGENTS.md Codifies the rules for operating in this parallel-agent repo (learned the hard way this session): only touch your task's files; one feature branch + PR per task; never force-push or push main; verify the current branch before every commit/push (HEAD can be switched by another agent); edit+commit shared barrels atomically and verify the commit contains your lines; don't rebase shared branches. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3ee9d5724..a7ff9b867 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,32 @@ Other scripts: `objectui:bump` (pull only), `objectui:build`, `objectui:clean`. --- +## Multi-agent working discipline + +This repo is worked on by **multiple agents in parallel**. Branches get switched +and shared files change *under you* mid-task — this is expected, not a bug. +Operate defensively: + +1. **Only touch the files your task needs.** Don't "fix" unrelated diffs, + reverts, or other agents' in-flight edits, and don't try to manage the whole + working tree. If a file you didn't change shows as modified, leave it. +2. **One feature branch + one PR per task.** Branch off `main`. **Never commit + task work straight to `main`.** +3. **Never `git push --force` / `--force-with-lease`, and never push `main`.** A + force-push can clobber a parallel agent's work; `main` is shared — land + everything via PR. +4. **Verify the current branch before every commit/push** + (`git rev-parse --abbrev-ref HEAD`). HEAD may have been switched by another + agent — if it isn't your feature branch, stop and re-checkout before pushing. +5. **Shared files (barrels/registries like `builtin/index.ts`): edit → `git add` + → commit atomically, then confirm the commit really contains your lines** + (`git show HEAD: | grep `). A concurrent edit can revert + your working-tree change between the edit and the commit. On a real conflict, + re-apply only *your* lines and let the PR merge integrate the rest. +6. **Don't rebase or force-update shared branches** to tidy other agents' commits. + +--- + ## Monorepo Layout ```