workflow-worktree

name	workflow-worktree
description	Use when creating, managing, or merging worktrees. Triggers on worktree creation, merge-back, subagent isolation, sparse checkout. Use when the user says "worktree" or when launching subagents that make changes.

Worktree Management

Worktree Location

Worktrees are created by hooks in ~/.claude/scripts/. They are placed in a central directory:

• Repos under ~/Projects/ → worktrees under ~/Projects/worktrees/<repo-path>/<name>
• Repos under ~/Dropbox/Projects/ → worktrees under ~/Dropbox/Projects/worktrees/<repo-path>/<name>

Naming

Always give worktrees a name that (1) reflects what they are working on and (2) has words spelled correctly. Examples: fix-auth-redirect, add-search-api, refactor-model-loader.

When to Use a Worktree

Use a worktree for ALL work beyond a single action that will be immediately committed. The main checkout stays on the active branch so the user can merge, pull, and push freely. Only skip the worktree for trivially small, single-commit changes (e.g., fixing a typo, adding one line).

When in doubt, use a worktree.

MANDATORY Merge-Back Protocol

Merging work back is NOT optional. It is a critical responsibility. Failure to merge back means lost work.

Before exiting a worktree session, you MUST:

1. Commit all work in the worktree
2. In the source repo: git pull --rebase origin <active-branch>
3. In the source repo: git merge worktree/<name>
4. Resolve any merge conflicts
5. Verify the merge succeeded

If any step fails, do NOT silently exit. Report the failure to the user and ask how to proceed.

Subagents and Worktrees

• When launching a subagent (via the Task tool) that will make changes, use isolation: "worktree" so it works on an isolated copy.
• This keeps the main working copy clean and avoids conflicts between parallel agents or between agents and the user's own edits.
• Read-only research and exploration agents do NOT need worktree isolation.
• Subagents MUST follow the merge-back protocol above before completing.

Sparse Checkout

For large repos where the task only touches a few directories, you may use sparse checkout to reduce disk and time:

git sparse-checkout init --cone
git sparse-checkout set <paths>

Use your judgment — only bother if the repo is large and the task is narrow.