using-git-worktrees

Using Git Worktrees

Core Principle

Worktrees isolate implementation branches without disturbing the main checkout. Use them only after choosing a safe location and verifying the baseline.

When To Use

• nous-execute-plan selects phase-worktrees.
• A plan phase uses worktree or parallel-worktree.
• Multiple independent implementation branches should run without switching the main checkout.

Directory Selection

Use this priority order:

1. Existing .worktrees/ directory.
2. Existing worktrees/ directory.
3. Worktree directory preference in CLAUDE.md.
4. Ask the user: .worktrees/ or ~/.config/nous/worktrees/<project-name>/.

Project-local directories must be gitignored before use. If .worktrees/ or worktrees/ is not ignored, stop and add the ignore rule before creating the worktree.

Creation Workflow

1. Resolve the repository root with git rev-parse --show-toplevel.
2. Choose a branch name from the plan phase, e.g. feature/ui-ultra-header.
3. Create the worktree with git worktree add <path> -b <branch>.
4. Run project setup based on lockfiles or project files.
5. Run baseline verification before implementation.
6. Report path, branch, setup command, and verification result.

Safety Gates

• Never create a project-local worktree unless its directory is ignored.
• Never proceed from a failing baseline without explicit user approval.
• Never use worktrees for sequential migrations, deployments, or same-file competing edits.
• Never merge/reconcile without a verification step in the integration checkout.

Report Contract

## Worktree Location
## Branch
## Baseline Setup
## Baseline Verification
## Ready For
## Blockers

Output Contract

Return the worktree setup report, or stop with the exact blocker that prevents safe worktree creation.