Agent Skills: Git Worktrees

Git Worktrees

Critical rules

• Prefer the bundled script over hand-rolled commands.
• Project-local worktree dirs must be git-ignored before use.
• Run baseline tests before starting work; ask before proceeding on failure.
• Directory priority: existing .worktrees/ > worktrees/ > CLAUDE.md > ask. Never guess.
• Always report the worktree path when ready.
• Before manual flows or directory edge cases, read references/directory-and-setup.md.

Workflow

1. Prefer: scripts/create-worktree.sh <branch-name> [base-dir] (from this skill). Exit 2 = not ignored; exit 3 = baseline tests failed.
2. If the script cannot run or you must deviate: follow directory priority, gitignore check, create branch worktree, project setup, baseline tests (see reference).
3. Report location and baseline status; only then implement.
4. Cleanup via git worktree remove (or branch-completion for land/discard options).

Resources

• scripts/create-worktree.sh — deterministic create + setup + baseline. Run when creating a worktree; use --help for usage and exit codes.
• references/directory-and-setup.md — directory priority, gitignore, manual steps, cleanup. Read when not using the script or on edge cases.

Validation

• [ ] Directory chosen by priority order
• [ ] Project-local dir git-ignored
• [ ] Setup ran; baseline tests pass (or failures reported and approved)
• [ ] Worktree path reported

Constraints

• Skip for trivial one-line fixes on the current branch.
• Related: design-exploration, implementation-planning, parallel-agent-dispatch, branch-completion.