12 added, 7 removed. Audit A to A.
---
name: worktree-pr
description: "Decide whether a task deserves its own git worktree, then run it end to end: branch from the integration branch rather than the current tree, keep the main working copy untouched while the task runs, compare the result against the untouched baseline before declaring it done, and land it through a pull request instead of merging. Use when a request says to do the work in a new worktree or branch, when a change is large or risky enough that the main tree should stay usable, when several tasks need to run in parallel on one repository, when a result has to be diffed against current behavior, and when deciding where screenshots, builds, and other artifacts produced in a worktree should end up."
license: Apache-2.0
metadata:
author: scarletkc
fogmoe-source: https://github.com/FogMoe/agents
fogmoe-summary: "Run a task in its own worktree: branch from the integration branch, compare against the baseline, land through a PR."
---
# Worktree & PR
A worktree buys two things: the main working copy stays usable while the task
runs, and the untouched copy remains available as a baseline to compare
against. Both are worth real setup cost, and neither applies to every change.
+ This covers the isolation mechanics. How large the change itself should be is
+ [`scoped-change`](../scoped-change/SKILL.md), and it applies inside a
+ worktree exactly as it does anywhere else.
+
## Deciding
Open a worktree when at least one holds: the task is large enough that a
half-finished state would block other work, several tasks need to progress on
the same repository at once, the result has to be compared against current
behavior, or the change is risky enough that abandoning it should cost
nothing.
Skip it when the change is small, self-contained, and reviewable in one pass.
Setting up an isolated copy for a typo fix or a one-line config edit costs
more than it saves, and the extra branch, directory, and PR are all overhead
that someone pays later. When the requester says to work directly on the
current branch, that decision is already made.
## Running
- **Branch from the integration branch, not from whatever is checked out.**
The point of the isolated copy is a clean starting state; inheriting
unrelated in-progress edits forfeits it and makes the eventual diff
unreadable. Fetch first so the base is current, not a stale local ref.
- **Leave the main working copy alone while the task runs.** Editing both
defeats the isolation and destroys the baseline. If the task turns out to
need a change in the main tree, stop and say so rather than reaching
across.
- - **Keep the worktree's scope to its own task.** Parallel worktrees on one
- repository stay independent only if each one edits what it was opened for;
- two of them touching the same files converge into a conflict nobody
- scheduled.
+ - **Parallel worktrees stay independent only while they stay disjoint.** Two
+ copies of one repository editing the same files converge into a conflict
+ nobody scheduled, and the cost lands at merge time rather than now. Before
+ opening a second one, check what the first is touching.
- **Name the artifacts' destination explicitly.** Screenshots, builds, and
exports produced inside a worktree vanish with it. Anything the requester
needs to see must be written somewhere durable, or attached to the PR, and
the location has to be stated rather than assumed.
## Before declaring it done
- **Compare against the untouched baseline, not against expectation.** The
reason to keep a clean copy is to run both and see the difference. For
behavior changes this means exercising the old path and the new one; for
visual changes it means the same view captured twice. "Should be
equivalent" is a claim, and the baseline is right there to check it.
- - **Confirm the diff contains only this task.** Generated files, formatter
- churn, and dependency lock updates ride along easily and are hard to
- distinguish from intent once merged.
+ - **Account for what the tooling added.** Generated output, formatter churn,
+ and dependency lock updates accumulate in an isolated copy without anyone
+ choosing them, and they are indistinguishable from intent once merged.
+ Either explain why each belongs in this branch, or drop it.
## Landing
Push the branch and open a pull request describing motivation, the commands
exercised, and anything reviewers must check by hand; leave merging to the
repository owner unless told otherwise. Say plainly which parts are done,
which are unverified, and which were deliberately left out, since a
worktree's isolation makes it easy to report an untested result as
finished. Once the branch has landed, remove the worktree; a stale copy of a
merged branch is a trap for the next session that opens it.