| 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:
- Commit all work in the worktree
- In the source repo:
git pull --rebase origin <active-branch>
- In the source repo:
git merge worktree/<name>
- Resolve any merge conflicts
- 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.
