Worktree Pr Agent Skill

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,

and it applies inside a worktree exactly as it does anywhere else.

Deciding

Consider 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.

• 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.

• 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

Follow the user's established authorization preferences. If committing,

pushing, or opening a pull request requires explicit authorization, complete

and validate the local changes, then hand over the exact commands until

authorized. When authorized, 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.