agents: coordinator-created worktrees and branches must be cleaned up automatically when their PR merges #75

New Issue

Claude · 2026-07-05T13:29:46Z

Claude commented

2026-07-05 13:29:46 +00:00

Context

During the session that fixed issues #68–#71, the coordinator spawned three Agent calls with isolation: "worktree" — one running itself (the manifest/install.sh fix) and two general-purpose subagents (the docs fix and the kyberforge dogfooding fix). Each produced real commits and opened a PR (#72, #73, #74). All three merged successfully.

None of the three worktrees, and none of the associated local branches, were cleaned up as part of that workflow. They sat on disk until the user explicitly asked "delete the local worktrees now that they're merged" — and even after that request was handled, git branch still showed five stale local branches: the three merged feature branches (docs/68-70-subagent-orchestration-guidance, fix/69-71-factory-authoring-fixes, fix/plugin-manifest-and-worktree-hooks) plus two worktree-agent-<id> branches that the Agent tool's worktree isolation mechanism creates automatically and that git worktree remove does not delete on its own. The user had to notice this from raw git branch output and ask again before a second cleanup pass happened.

Two compounding mechanical gotchas made this worse:

git worktree remove refuses to run ("fatal: working trees containing submodules cannot be moved or removed") on any worktree where a test run initialized git submodules (this repo has several — tests/bats, docs/wiki, etc.) — required git worktree remove --force --force (double -f) to override, which isn't discoverable without hitting the error first.
git worktree remove never deletes the branch checked out in that worktree — branch cleanup is a fully separate, easy-to-forget step, and the Agent tool's own auto-generated worktree-agent-<id> isolation branch isn't the same as the feature branch the agent actually pushed, so both need deleting independently.

Recommendation

Treat "PR merged" and "worktree/branch cleanup" as one atomic step, not two separately-remembered ones. Whenever a coordinator creates a worktree (via Agent(isolation: "worktree") or git worktree add directly) to land a PR, the close-out for that PR should immediately include:

Verify the merge (pull_request_read state, or merged: true).
git worktree remove --force --force <path> (the double--f is required whenever the worktree initialized submodules to run tests — assume it will have, in this repo).
git branch -d the feature branch and any worktree-agent-<id> isolation branch tied to that worktree.

This should be documented in this repo's AGENTS.md "Subagent orchestration" section (added in #73) as a standing rule, so it happens as a matter of course rather than requiring the user to inspect git worktree list/git branch and ask for cleanup twice.

## Context During the session that fixed issues #68–#71, the coordinator spawned three `Agent` calls with `isolation: "worktree"` — one running itself (the manifest/install.sh fix) and two general-purpose subagents (the docs fix and the kyberforge dogfooding fix). Each produced real commits and opened a PR (#72, #73, #74). All three merged successfully. None of the three worktrees, and none of the associated local branches, were cleaned up as part of that workflow. They sat on disk until the user explicitly asked "delete the local worktrees now that they're merged" — and even after that request was handled, `git branch` still showed five stale local branches: the three merged feature branches (`docs/68-70-subagent-orchestration-guidance`, `fix/69-71-factory-authoring-fixes`, `fix/plugin-manifest-and-worktree-hooks`) plus two `worktree-agent-<id>` branches that the `Agent` tool's worktree isolation mechanism creates automatically and that `git worktree remove` does not delete on its own. The user had to notice this from raw `git branch` output and ask again before a second cleanup pass happened. Two compounding mechanical gotchas made this worse: - `git worktree remove` refuses to run ("fatal: working trees containing submodules cannot be moved or removed") on any worktree where a test run initialized git submodules (this repo has several — `tests/bats`, `docs/wiki`, etc.) — required `git worktree remove --force --force` (double `-f`) to override, which isn't discoverable without hitting the error first. - `git worktree remove` never deletes the branch checked out in that worktree — branch cleanup is a fully separate, easy-to-forget step, and the `Agent` tool's own auto-generated `worktree-agent-<id>` isolation branch isn't the same as the feature branch the agent actually pushed, so both need deleting independently. ## Recommendation Treat "PR merged" and "worktree/branch cleanup" as one atomic step, not two separately-remembered ones. Whenever a coordinator creates a worktree (via `Agent(isolation: "worktree")` or `git worktree add` directly) to land a PR, the close-out for that PR should immediately include: 1. Verify the merge (`pull_request_read` state, or `merged: true`). 2. `git worktree remove --force --force <path>` (the double-`-f` is required whenever the worktree initialized submodules to run tests — assume it will have, in this repo). 3. `git branch -d` the feature branch **and** any `worktree-agent-<id>` isolation branch tied to that worktree. This should be documented in this repo's `AGENTS.md` "Subagent orchestration" section (added in #73) as a standing rule, so it happens as a matter of course rather than requiring the user to inspect `git worktree list`/`git branch` and ask for cleanup twice.

Claude added the Kind/Bug

Priority

Low

4

labels 2026-07-05 13:29:46 +00:00

Defame1297 referenced this issue from a commit

2026-07-05 13:36:35 +00:00

docs(agents): document worktree/branch cleanup as part of PR close-out

Defame1297 closed this issue

2026-07-05 13:36:35 +00:00

Claude referenced a pull request that will close this issue

2026-07-05 13:36:48 +00:00