/worktree-pr

name: worktree-pr
description: "Decide whether a task deserves its own git worktree and, if chosen, 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 prepare it for 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
  source: https://github.com/scarletkc/agents
  summary: "Optionally run a task in its own worktree: branch from the integration branch, compare against the baseline, and prepare it for 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`](https://github.com/scarletkc/agents/blob/main/skills/scoped-change/SKILL.md), 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.