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:

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.md must 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.

Protected Branch Configuration

Protected branches (main, develop, master, etc.) require special handling to prevent accidental deletion:

yaml
1# Configuration (typically in repo .claude/config or passed to agents)
2git_flow:
3  enabled: true  # boolean: whether git-flow workflow is used
4  main_branch: "main"  # or "master" - the primary production branch
5  develop_branch: "develop"  # only if git_flow.enabled = true
6
7protected_branches:
8  - "main"
9  - "develop"
10  - "master"
11  # Can include additional patterns: "release/*", "hotfix/*"

Protected Branch Rules:

• If git_flow.enabled: false → protect only main_branch
• If git_flow.enabled: true → protect main_branch + develop_branch
• Additional branches can be added to protected_branches array
• Cleanup/abort agents NEVER delete protected branches (local or remote)
• Protected branches can only be removed from worktrees, never deleted
• Use --update to safely pull changes for protected branches in worktrees

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)

1. Inputs: --branch <name>, --base <master|develop|...>, optional --path.
2. Ensure scaffolding/tracking doc exists (if enabled); fetch all: git fetch --all --prune.
3. Confirm base branch exists and is up to date.
4. Determine path: default <worktree_base>/<branch> (or override).
5. Create branch/worktree:
   • If branch does not yet exist: git worktree add -b <branch> <path> <base>.
   • If branch exists: git worktree add <path> <branch>.
6. In the new worktree, ensure hooks apply and verify status is clean.
7. If tracking enabled, add/refresh entry in tracking doc (branch, path, base, purpose, owner, created date, status).
8. Agent option: delegate to sc-worktree-create agent; it returns structured JSON (tracking row, status).

Scan/verify worktrees

1. List worktrees: git worktree list --porcelain.
2. Cross-check tracking doc (if enabled); flag missing/stale entries or extra rows.
3. For each worktree, check status and merge state:
   • git -C <path> status --short
   • git -C <path> fetch
   • git branch --remotes --contains <branch> to see if merged.
4. Identify issues: untracked changes, diverged branches, merged-but-not-cleaned worktrees, missing tracking entries.
5. Update tracking doc with current state and issues (if enabled); propose cleanup where appropriate.
6. Agent option: delegate to sc-worktree-scan agent; it returns structured JSON.

Clean-up worktree (post-merge or finished work)

1. Check if branch is protected: If branch is in protected_branches list, ONLY remove worktree, NEVER delete the branch.
2. If git status is not clean, stop and request explicit approval/coordination.
3. Ensure all work is committed/pushed or explicitly confirmed to discard.
4. Confirm target branch merged or otherwise approved for removal.
5. Remove worktree: git worktree remove <path> (use --force only with approval).
6. For non-protected branches: 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.
7. For protected branches: Only remove worktree, preserve branch locally and remotely. Update tracking to note "worktree removed, branch preserved (protected)".
8. If tracking enabled, update tracking doc to remove/mark cleaned with merge SHA/date.
9. Agent option: delegate to sc-worktree-cleanup agent; it returns structured JSON.

Abandon worktree (discard work)

1. Check if branch is protected: If branch is in protected_branches list, ONLY remove worktree, NEVER delete the branch.
2. If git status is not clean, stop and request explicit approval/coordination.
3. Confirm user approval to discard local changes and optionally delete the branch.
4. Remove worktree: git worktree remove <path> (force only with approval).
5. For non-protected branches: If instructed, delete the branch locally (git branch -D <branch>) and remotely (git push origin --delete <branch>).
6. For protected branches: Only remove worktree, preserve branch locally and remotely. Require confirmation: "Branch is protected. Remove worktree but preserve branch?"
7. If tracking enabled, update tracking doc to remove the entry and note abandonment.
8. Agent option: delegate to sc-worktree-abort agent; it returns structured JSON.

Update protected branch (pull latest changes)

1. Verify branch is protected: Only operates on branches in protected_branches list. If no branch is specified, update all protected branches that have worktrees.
2. Check if worktree exists at expected path; error if missing.
3. If git status is not clean, stop and report dirty state.
4. Fetch and pull: git fetch origin <branch> then git pull origin <branch>.
5. If merge conflicts occur:
   • Collect conflicted files: git diff --name-only --diff-filter=U
   • Return control to main agent with conflict details
   • Main agent coordinates with user to resolve conflicts
   • After resolution, user commits and continues
6. If clean pull: Update tracking with last_checked timestamp and commits pulled count.
7. Agent option: delegate to sc-worktree-update agent; it returns structured JSON with success or conflict details.

Safety and reminders

• NEVER delete protected branches (main, develop, master) under any circumstances.
• Protected branches can only be removed from worktrees; the branch itself must always be preserved.
• 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.
• When updating protected branches in worktrees, handle merge conflicts by returning control to main agent for user coordination.