agentsclimarketplace

Using git worktrees

Skill RBraga01/a-team/skills/using-git-worktrees

Create or verify an isolated git worktree before starting any development work. Prevents main branch contamination, enables parallel feature development, and gives subagents a clean baseline. Use at the start of every feature branch.From its SKILL.md

Install
npx -y skills add RBraga01/a-team --skill using-git-worktrees

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

3.8 KB, as published. Nobody here has run it

Using Git Worktrees

Why Worktrees

A worktree is a second checkout of the same repo in a separate directory. Each worktree has its own working tree and HEAD, but shares the git object store. This means:

  • Subagents work in isolation — no interference with your main session
  • You can switch tasks without stashing
  • Parallel features develop independently
  • Clean rollback: abandon the worktree, nothing pollutes main

When to Use

Use at the START of every feature or bug fix. Do NOT start implementation until a clean worktree exists or you've confirmed you're already in one.

Mandatory before:

  • subagent-driven-development skill
  • executing-plans skill
  • Any work touching more than one file

The Process

Step 1: Detect Existing Isolation

First check — are you already isolated?

# Check if current directory is a worktree (not the main checkout)
git worktree list
pwd

If you're already in a worktree for this feature: proceed to Step 3 (verify clean baseline). If you're in the main checkout: proceed to Step 2.

Step 2: Create the Worktree

# Create worktree + new branch in one command
git worktree add ../worktrees/<feature-name> -b feat/<feature-name>

# Examples:
git worktree add ../worktrees/stripe-billing -b feat/stripe-billing
git worktree add ../worktrees/fix-auth-bug -b fix/auth-token-expiry

The worktree is created at ../worktrees/<feature-name> (sibling of the project root). If the project uses .claude/worktrees/, use that path instead:

git worktree add .claude/worktrees/<feature-name> -b feat/<feature-name>

Step 3: Verify Clean Baseline

Move into the worktree and confirm it starts clean:

cd ../worktrees/<feature-name>   # or .claude/worktrees/<feature-name>
git status                        # Should show: "nothing to commit"
git log --oneline -3              # Confirm you branched from the right point

If status shows unexpected changes: something is wrong — investigate before proceeding.

Step 4: Run Project Setup

Install dependencies and confirm the baseline builds:

npm install          # or pip install -r requirements.txt / go mod download
npm run build        # Confirm baseline build passes BEFORE any changes
npm test             # Confirm baseline tests pass BEFORE any changes

If baseline build or tests fail: STOP. Fix the issue on main first, then recreate the worktree.

Step 5: Proceed with Work

Now development starts. The worktree is isolated, the baseline is confirmed clean.

Cleanup After Work Completes

After the branch is merged or abandoned:

# From the main checkout (not from inside the worktree)
git worktree remove ../worktrees/<feature-name>
git branch -d feat/<feature-name>   # Only after merge

Common Issues

IssueFix
"already checked out" errorThe branch exists in another worktree — use a different branch name
Worktree has unexpected changesRun git status to investigate; never force-remove with uncommitted work
Setup script fails in worktreeCheck for absolute paths in scripts; worktrees use different working directories
Submodules not initializedRun git submodule update --init --recursive in the new worktree

Worktree vs Branch Checkout

git worktreegit checkout -b
Main session disruptedNoYes
Parallel work possibleYesNo
Independent node_modulesYes (separate dir)Shared
Subagent isolationCleanRisk of contamination

Always use worktrees for subagent work. The isolation is the point.

Keep looking

Skills are one crate of 613,531. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.