using-git-worktrees

name	using-git-worktrees
description	Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Iron Law: Use bd worktree, NOT git worktree

ALWAYS use bd worktree commands. NEVER use raw git worktree commands.

Why: bd worktree create does everything git worktree add does PLUS:

• Worktree automatically shares the main repo's beads database via git common directory discovery
• Adds the worktree path to .gitignore automatically
• Ensures consistent issue state across all worktrees

Raw git worktree add misses .gitignore setup and safety checks — while beads database sharing works via git common directory, you lose the automation bd worktree create provides.

Action	Use This	NOT This
Create worktree	bd worktree create .worktrees/<name>	git worktree add
List worktrees	bd worktree list	git worktree list
Remove worktree	bd worktree remove .worktrees/<name> (if the safety check flags the local-only branch as unpushed, verify the merge landed, then add --force)	git worktree remove
Worktree info	bd worktree info	(no equivalent)

Note: Claude Code provides a native EnterWorktree tool for worktree management. For non-beads projects, this is a viable alternative. For beads-integrated projects, bd worktree create remains mandatory — it handles database sharing and .gitignore management that EnterWorktree does not provide.

Deliberate divergence from upstream: superpowers v6.0.3 rewrote this skill to prefer the harness-native worktree tool first (EnterWorktree → existing .worktrees/ → raw git worktree). We do not adopt that native-tool-first selection order — it bypasses bd worktree's beads-database sharing across worktrees. The Iron Law above (always bd worktree) is intentional and takes precedence.

Directory Selection

Always create worktrees under .worktrees/ in the project root:

• bd worktree create .worktrees/<name> — creates the worktree at .worktrees/<name> and adds the path to .gitignore automatically
• Trap: the bare-name form (bd worktree create <name>) creates at ./<name>, cluttering the repo root — always pass the full path
• If your project's CLAUDE.md names a different preferred worktree directory, pass that path instead

Safety Verification

bd worktree create automatically adds the worktree path to .gitignore when inside the repo root. Verify as a safety net:

git check-ignore -q <worktree-path> 2>/dev/null

If NOT ignored (edge case — bd worktree create should have handled this): add the path to .gitignore and commit.

Pre-Flight Checks

Run these checks BEFORE creating any worktree.

Detect Existing Worktree Isolation

Check whether you are already inside a worktree:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
if [ "$GIT_DIR" != "$GIT_COMMON" ]; then
  echo "WARNING: Already inside a worktree."
fi

If already in a worktree, warn and ask via your structured question tool whether to proceed (creating a nested worktree) or abort.

Submodule Guard

Check whether you are inside a git submodule:

SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
if [ -n "$SUPERPROJECT" ]; then
  echo "WARNING: Inside a git submodule. Worktrees behave unpredictably here."
fi

If inside a submodule, warn and stop. Do NOT create worktrees inside submodules.

Consent Flow

• User-initiated (manual worktree creation): Ask via your structured question tool before creating — "I'd like to create a worktree at <path>. Proceed?"
• Dispatched by subagent-driven-development: Consent is implicit — the orchestrator authorized worktree creation. Skip the prompt.

Creation Steps

0. Claim the bead first

Before creating the worktree, claim the issue you're about to work on. This prevents ownerless work — you own the bead before any environment exists.

bd update <issue-id> --claim

--claim consent boundary. Claim the specific bead you are about to work on (bd update <id> --claim, above). The autonomous take-next form bd ready --claim is NOT this skill's pattern and is FORBIDDEN wherever the user picks the work — the consent gate binds even when this skill is not loaded.

1. Create Worktree with bd worktree create

# Standard — creates worktree at .worktrees/<name> with matching branch
bd worktree create .worktrees/<feature-name>

# With explicit branch name
bd worktree create .worktrees/<feature-name> --branch <branch-name>

# Then cd into it
cd .worktrees/<feature-name>

What bd worktree create does automatically:

1. Creates the git worktree with a new branch
2. Worktree automatically discovers the main repo's beads database via git common directory (no redirect file needed)
3. Adds worktree path to .gitignore (if inside repo root)

2. Run Project Setup

Auto-detect and run appropriate setup:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

3. Verify Clean Baseline

Run tests to ensure worktree starts clean:

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

If tests fail: Report failures, then use your structured question tool to ask: Question: "Baseline tests failing in worktree ( failures). How should I proceed?" Options: "Investigate failures" (debug before starting feature work), "Proceed anyway" (start implementation despite pre-existing failures) A skipped, dismissed, or auto-resolved answer is not consent — stop and ask in plain text.

If tests pass: Report ready.

4. Report Location

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Multiple Worktrees for Parallel Subagents

When Subagent-Driven Development runs independent tasks in parallel, the orchestrator creates and manages multiple worktrees. Subagents never create or destroy worktrees — they receive a path and work within it.

Pattern:

# 1. Orchestrator creates epic worktree (once)
bd worktree create .worktrees/<epic-name>

# 2. For each parallel task (max 5 concurrent):
bd worktree create .worktrees/<task-name> --branch feature/<epic>/<task>

# 3. Subagent receives path in its prompt:
#    "Work from: <task-worktree-path>"

# 4. After task passes review — orchestrator merges and cleans up:
cd .worktrees/<epic-name>
git merge feature/<epic>/<task>
bd worktree remove .worktrees/<task-name>
# (if the safety check flags the local-only branch as unpushed, verify the merge landed, then add --force)

Constraints:

• Maximum 5 concurrent task worktrees (resource limit)
• Orchestrator manages the full lifecycle — subagents never run bd worktree commands
• All task worktrees branch from the same HEAD commit (created before any subagent commits)
• After merge, run the full test suite on the epic worktree to catch integration issues

See also: beads-superpowers:subagent-driven-development → Parallel Batch Mode section for the full orchestration flow.

Quick Reference

Situation	Action
Creating a worktree	bd worktree create .worktrees/<name> — handles path + .gitignore
Different directory preferred by project CLAUDE.md	pass that path the same way
Directory not ignored	Add to .gitignore + commit (edge case)
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install
Parallel subagent work	Create one bd worktree per task, orchestrator manages lifecycle (max 5)
Working across worktrees	bd -C .worktrees/<name> ready — run bd in a worktree without cd

Common Mistakes

Using git worktree instead of bd worktree

• Problem: Raw git worktree add misses .gitignore setup and safety checks — while beads database sharing works via git common directory, you lose the automation bd worktree create provides
• Fix: ALWAYS use bd worktree create. If you catch yourself typing git worktree, stop and use bd worktree instead.

Skipping ignore verification

• Problem: Worktree contents get tracked, pollute git status
• Fix: Verify with git check-ignore after creation (bd worktree create handles this automatically, but verify as a safety net)

Bare-name worktree paths

• Problem: bd worktree create <name> creates at ./<name>, cluttering the repo root
• Fix: Always pass the full path: bd worktree create .worktrees/<name> — location + .gitignore handled in one step

Proceeding with failing tests

• Problem: Can't distinguish new bugs from pre-existing issues
• Fix: Report failures, get explicit permission to proceed

Hardcoding setup commands

• Problem: Breaks on projects using different tools
• Fix: Auto-detect from project files (package.json, etc.)

Example Workflow

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Create worktree: bd worktree create .worktrees/auth --branch feature/auth]
  ✓ Created worktree at .worktrees/auth
  ✓ Beads database shared via git common directory
  ✓ Added to .gitignore
[cd .worktrees/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

Capture what you learned. At close, record durable, evidence-backed insights (still true next month, tied to a file, test, or command). Never record guesses, one-offs, or secrets (tokens, keys, PII — every memory is injected into all future sessions). Update in place (bd remember --key <key>) rather than adding a near-duplicate.

bd remember "<kind>: <durable, evidence-backed insight>"   # kind: lesson / pattern / design / root-cause / research

Red Flags

Never:

• Use raw git worktree commands — ALWAYS use bd worktree
• Create worktree without verifying it's ignored (project-local)
• Skip baseline test verification
• Proceed with failing tests without asking
• Assume directory location when ambiguous
• Skip CLAUDE.md check

Always:

• Use bd worktree create / bd worktree list / bd worktree remove
• Let bd worktree create handle path and .gitignore
• Auto-detect and run project setup
• Verify clean test baseline

Integration

Invoked by: Any task needing workspace isolation, or user on-demand.

Required by:

• subagent-driven-development — must create worktree before delegating to implementer subagents.
• executing-plans — workspace isolation before starting plan execution.

Pairs with: subagent-driven-development — parallel batch mode creates multiple worktrees (one per task) for concurrent subagent execution.