amadan
Merge remote-tracking branch 'origin/docs/worktree-guidance' into HEAD
1 file changed,
+38
−0
AGENTS.md+38 −0
diff --git a/AGENTS.md b/AGENTS.md| index d658e1c..03b5e04 100644 |
| --- a/AGENTS.md |
| +++ b/AGENTS.md |
| @@ -122,3 +122,41 @@ Edit any line. **This file is the source of truth, not the profile name.** |
| The profile only seeded this list at scaffold time; nothing re-reads it, so |
| changing a line here changes what the app does. A convention deleted from |
| this file is not a convention to reinstate. |
| + |
| +## Work in a worktree, and catch main up first |
| + |
| +Take a worktree for the work. Do not work in the shared checkout. |
| + |
| + git -C <repo> fetch origin |
| + git -C <repo> worktree add ../<repo>-<task> -b <branch> origin/main |
| + |
| +Both halves matter, for different reasons. |
| + |
| +**The worktree**, because several sessions share this machine and some |
| +share this repository, and a checkout has one HEAD, one index and one |
| +working tree between all of them. A branch switch under somebody else's |
| +uncommitted work destroys it with nothing on screen to say so, and two |
| +sessions editing the same paths disagree quietly instead of conflicting |
| +loudly. A worktree gives the work its own HEAD and its own files, and |
| +costs a directory. |
| + |
| +**From `origin/main`, after a fetch** — not from whatever the checkout |
| +happens to be sitting on. A branch cut from a stale main is a merge |
| +conflict scheduled for later, against files somebody else has renamed in |
| +the meantime. A branch cut from another task's branch is worse: it |
| +carries that task's commits into yours, where they are reviewed as |
| +though you wrote them, and the two can only be separated by hand. |
| + |
| +Remove it when the work has landed — `git worktree remove` — so that |
| +`git worktree list` keeps saying something true. |
| + |
| +Written down because of 2026-09-17, in `meet`. The shared checkout was |
| +sitting on one task's branch while holding a *different* task's feature |
| +uncommitted on disk — some four hundred lines, a new migration among |
| +them — put there by a session nobody else knew was working in that tree. |
| +Two other sessions were meanwhile coordinating over the same checkout by |
| +asking each other not to touch it, which is the arrangement a worktree |
| +makes unnecessary. Nothing was lost. Nothing about the arrangement would |
| +have said so if it had been, and by then the same feature existed twice, |
| +once on each side of a rename, because the two sessions had branched |
| +from different starting points. |