majiayu000 Managing Git Worktrees
Use this skill to manage worktrees with a standard structure and tracking. Use the /sc-git-worktree command to invoke this skill.
Agent Delegation
This skill delegates to specialized agents via the Task tool:
| Operation | Agent | Returns |
|---|---|---|
| Create | sc-worktree-create |
JSON: success, path, branch, tracking_row |
| Scan | sc-worktree-scan |
JSON: success, worktrees list, recommendations |
| Cleanup | sc-worktree-cleanup |
JSON: success, branch_deleted, tracking_update |
| Abort | sc-worktree-abort |
JSON: success, worktree_removed, tracking_update |
To invoke an agent, use the Task tool with:
- Prompt file:
.claude/agents/<agent-name>.md - Parameters as documented in each agent's Inputs section
Standards and paths
- Repo root: current directory.
- Default worktree base:
../synaptic-canvas-worktrees. - Worktrees live in
<worktree_base>/<branch>. - Tracking document (if used):
<worktree_base>/worktree-tracking.mdmust be updated on create/scan/cleanup/abandon. Allow a toggle to disable tracking for repos that don’t use it. - Naming: worktree directory = branch name; branch naming follows repo policy (e.g., master release; develop/DevBranch integration; feature from integration; hotfix from master; release branches as needed).
- Branch protections/hooks: no direct commits to protected branches; ensure hooks/branch protections are respected across worktrees.
- Cleanliness: worktrees must be removed and tracking updated when work is complete or branch is merged.
Workflows
Scaffolding (if missing)
- Ensure base path exists:
<worktree_base>. If missing, create it. - If tracking is enabled, ensure tracking doc exists with headers.
Create worktree (and branch)
- Inputs:
--branch <name>,--base <master|develop|...>, optional--path. - Ensure scaffolding/tracking doc exists (if enabled); fetch all:
git fetch --all --prune. - Confirm base branch exists and is up to date.
- Determine path: default
<worktree_base>/<branch>(or override). - Create branch/worktree:
- If branch does not yet exist:
git worktree add -b <branch> <path> <base>. - If branch exists:
git worktree add <path> <branch>.
- If branch does not yet exist:
- In the new worktree, ensure hooks apply and verify status is clean.
- If tracking enabled, add/refresh entry in tracking doc (branch, path, base, purpose, owner, created date, status).
- Agent option: delegate to
sc-worktree-createagent; it returns structured JSON (tracking row, status).
Scan/verify worktrees
- List worktrees:
git worktree list --porcelain. - Cross-check tracking doc (if enabled); flag missing/stale entries or extra rows.
- For each worktree, check status and merge state:
git -C <path> status --shortgit -C <path> fetchgit branch --remotes --contains <branch>to see if merged.
- Identify issues: untracked changes, diverged branches, merged-but-not-cleaned worktrees, missing tracking entries.
- Update tracking doc with current state and issues (if enabled); propose cleanup where appropriate.
- Agent option: delegate to
sc-worktree-scanagent; it returns structured JSON.
Clean-up worktree (post-merge or finished work)
- If
git statusis not clean, stop and request explicit approval/coordination. - Ensure all work is committed/pushed or explicitly confirmed to discard.
- Confirm target branch merged or otherwise approved for removal.
- Remove worktree:
git worktree remove <path>(use--forceonly with approval). - If merged and no unique commits, delete the branch locally (
git branch -d <branch>) and remotely (git push origin --delete <branch>) by default; only skip if the user explicitly opts out. If the remote branch is already absent, continue without error. If not merged, only delete with explicit approval. - If tracking enabled, update tracking doc to remove/mark cleaned with merge SHA/date.
- Agent option: delegate to
sc-worktree-cleanupagent; it returns structured JSON.
Abandon worktree (discard work)
- If
git statusis not clean, stop and request explicit approval/coordination. - Confirm user approval to discard local changes and optionally delete the branch.
- Remove worktree:
git worktree remove <path>(force only with approval). - If instructed, delete the branch locally (
git branch -D <branch>) and remotely (git push origin --delete <branch>). - If tracking enabled, update tracking doc to remove the entry and note abandonment.
- Agent option: delegate to
sc-worktree-abortagent; it returns structured JSON.
Safety and reminders
- Never delete branches or force-remove worktrees without explicit approval.
- Never clean/abandon a worktree with uncommitted changes unless explicitly approved.
- Keep tracking doc in sync on every operation when enabled.
- Respect branch protections and hooks; no direct commits to protected branches.
- Use background agents for long scans/cleanups; keep the main context focused on decisions and summaries.