@@ -39,13 +39,40 @@ gh issue edit <N> --repo modelcontextprotocol/servers --add-assignee @me
3939
4040## 2. Branch
4141
42- ` v2/<type>/<N>-<slug> ` , cut from ** ` origin/v2/main ` ** :
42+ ` v2/<type>/<N>-<slug> ` , cut from ** ` origin/v2/main ` ** into a ** new git
43+ worktree** , never by switching branches in the primary checkout. Several agent
44+ sessions work this repo on one machine at once and share the primary checkout:
45+ a ` git switch ` there moves the branch out from under every other session using
46+ it, and carries one task's uncommitted edits, ` dist/ ` output and
47+ ` node_modules ` into another's. A worktree per issue gives each task its own
48+ tree and leaves the primary checkout alone.
49+
50+ Run it from the primary checkout. The worktree is a ** sibling** directory named
51+ for the checkout plus the issue number (` servers ` → ` ../servers-4810 ` ), never a
52+ directory inside the repo, where every format, lint and typecheck scope would
53+ see a second copy of the source:
4354
4455``` sh
4556git fetch origin v2/main
46- git switch -c v2/fix/4810-filesystem-symlink-escape origin/v2/main
57+ git worktree add --no-track " ../$( basename " $PWD " ) -4810" \
58+ -b v2/fix/4810-filesystem-symlink-escape origin/v2/main
59+ cd " ../$( basename " $PWD " ) -4810"
60+ npm install
4761```
4862
63+ - ` --no-track ` keeps the new branch from tracking ` origin/v2/main ` , so
64+ ` git status ` does not report your work as "ahead of v2/main", and the first
65+ push is an explicit ` git push -u origin <branch> ` to a branch of its own name.
66+ - ⚠️ ** The ` npm install ` is part of the step.** A worktree starts with no
67+ ` node_modules ` , no ` dist/ ` and no ` .venv ` (` /local-dev ` ). The root install
68+ builds every TypeScript server; a Python server builds its ` .venv ` on its
69+ first ` uv run ` . Background the install if you have edits to make first; the
70+ gate needs it finished.
71+ - Every later step (edits, the gate, commits, the push) runs ** inside the
72+ worktree** .
73+ - The harness's ` EnterWorktree ` tool, where available, does the same; name the
74+ branch by the rule above.
75+
4976` <type> ` follows the issue's type label: ` bug ` → ` fix ` , ` enhancement ` → ` feat ` ,
5077` documentation ` → ` docs ` , ` chore ` → ` chore ` . A ` question ` has no branch type,
5178because answering one ships nothing: if it turns out to need a change, relabel
@@ -56,10 +83,11 @@ branch and keeps the work legible in `git branch -a` next to `main`.
5683history, so the PR diff would show unrelated changes.
5784
5885** Stacking.** When one issue's work depends on another PR that has not merged
59- yet, branch from that PR's branch and open the PR with ` --base ` set to it. Say
60- in the body that it is stacked and on which PR. When the lower PR merges,
61- retarget the stacked one to ` v2/main ` (` gh pr edit <PR> --base v2/main ` ) and
62- rebase it if GitHub reports conflicts.
86+ yet, branch from that PR's branch (its worktree is cut from it:
87+ ` git worktree add … -b <child> <parent-branch> ` ) and open the PR with ` --base `
88+ set to it. Say in the body that it is stacked and on which PR. When the lower
89+ PR merges, retarget the stacked one to ` v2/main `
90+ (` gh pr edit <PR> --base v2/main ` ) and rebase it if GitHub reports conflicts.
6391
6492## 3. Sign off every commit (DCO)
6593
@@ -310,6 +338,9 @@ worth doing on its own. Implementing a suggestion differently is fine.
310338 -f body=' Fixed in <sha>: …'
311339 ```
312340
341+ A round with many comments is a bulk write: send the replies one at a time,
342+ paced by ` AGENTS.md ` ** Pacing GitHub writes** .
343+
313344- ⚠️ ** Then post a PR-level summary of the round, in addition, never instead.**
314345 Inline replies go hidden once the fix is pushed, because the threads become
315346 outdated, so the summary is what keeps the round readable afterwards. It does
@@ -391,3 +422,16 @@ issue will not be done, the issue shipped nothing: close it as not planned and
391422**delete its card** (`/board-ops`) rather than moving it to Done.
392423
393424If PRs were stacked on this one, retarget each to `v2/main` (step 2).
425+
426+ **Then remove the worktree and its local branch**, from the primary checkout,
427+ once the PR shows as merged (or closed, for abandoned work). A stale worktree
428+ keeps its branch checked out, so git refuses to check that branch out anywhere
429+ else, and it holds a full `node_modules` on disk per issue:
430+
431+ ```sh
432+ git worktree remove "../$(basename "$PWD")-<N>"
433+ git branch -D v2/<type>/<N>-<slug>
434+ ```
435+
436+ `git worktree remove` refuses a worktree with uncommitted or untracked changes;
437+ read what is there before reaching for `--force`.
0 commit comments