worktree

name	worktree
description	Standard Operating Procedures for managing git worktrees to isolate tasks.

Worktree Management

This skill mandates and guides the use of git worktree for task isolation.

1. Detection & Mandate

CRITICAL: You MUST inspect the workspace root before beginning work.

Recognition Pattern

You are in a Worktree-Enabled Workspace if:

1. There is a directory named main or master which represents the primary branch.
2. The root contains agent metadata folders (e.g., .agent/, .gemini/) but no direct source code files at the root level.
3. (Optional) The root contains sibling directories (e.g., feature-xyz, fix-abc) alongside main.

The Mandate

If this pattern is detected:

• YOU MUST use a git worktree for your current task.
• YOU MUST NOT edit files directly inside the main or master directory (except for repo-wide maintenance).
• YOU MUST NOT create a subdirectory inside main for your work. You must create a sibling directory.

2. Creating a Worktree

Step 1: Update the Source of Truth

Before creating a worktree, ensure the local main (or master) is up to date to avoid divergence.

# Assuming 'main' is the primary directory
git -C main checkout main
git -C main pull origin main

Step 2: Initialize the Worktree

Create a new folder and branch as a sibling to main.

# Syntax: git -C <base> worktree add ../<folder-name> -b <branch-name>

# Example: Creating a feature branch
git -C main worktree add ../feature-new-login -b feature.new-login

Naming Convention:

• Folder name: Kebab-case matching the task (e.g., feature-new-login).
• Branch name: type.name (e.g., feature.new-login, fix.crash-handling).

3. Working in the Worktree

Context Switch

Immediately after creation, you must switch your working directory/context.

cd ../feature-new-login

Rule: All subsequent commands (builds, tests, git commits) MUST be run from inside this new worktree directory.

4. Cleanup

When the task is completed and verified:

1. Remove Worktree:

   # From the root or main directory
   rm -rf feature-new-login
   git -C main worktree prune
   

2. Verify: Ensure the directory is gone and git -C main worktree list no longer shows it.

5. Troubleshooting

"Branch is already checked out"

If you see fatal: 'feature/xyz' is already checked out at...:

1. Check git -C main worktree list.
2. If the directory exists, use it.
3. If the directory is missing but git thinks it exists, run git -C main worktree prune.

"No tracking information"

If git pull fails in the new worktree:

git branch --set-upstream-to=origin/main

"INSTALL_FAILED_VERSION_DOWNGRADE" (Android)

If switching between worktrees causes installation issues:

1. Uninstall the app: adb uninstall <package_name>
2. Reinstall from the current worktree.