Use when user wants to start new code work, create a new feature branch, begin coding on a fresh branch, or switch to latest main before starting work. Supports both regular branches and isolated worktrees.
Start new code work from the latest main branch. Supports two modes:
Ask the user:
How would you like to work?
1. Regular branch (default) — Simple git checkout
2. Worktree — Isolated workspace (recommended for multi-task or experimental work)
If no preference expressed, default to regular branch.
Use these prefixes based on the type of work:
feat/ - New features (e.g., feat/user-authentication)fix/ - Bug fixes (e.g., fix/login-validation)docs/ - Documentation changesrefactor/ - Code restructuringtest/ - Adding or updating testschore/ - Maintenance tasksls -la /path/to/repo/.git
If not exists, clone from remote:
git clone <remote-url>
cd repo-name
git fetch origin
git remote show origin | grep "HEAD branch"
Common names: main, master, develop
git checkout origin/<main-branch> -b <main-branch>
If user specified a branch name:
git checkout -b <prefix>/<description>
If user didn't specify, ask them:
Example:
git checkout -b feat/user-login
Report:
Core principle: Systematic directory selection + safety verification = reliable isolation.
Follow this priority order:
# Check in priority order
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
If found: Use that directory.
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If preference specified: Use it without asking.
If no directory exists and no CLAUDE.md preference:
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local)
3. ~/.config/worktrees/<project>/ (global)
Which would you prefer?
CRITICAL: Must verify directory is ignored before creating worktree.
# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null && echo "IGNORED" || echo "NOT_IGNORED"
git check-ignore -q worktrees 2>/dev/null && echo "IGNORED" || echo "NOT_IGNORED"
If NOT ignored:
Per the "Fix broken things immediately" rule:
.gitignoreWhy critical: Prevents accidentally committing worktree contents to repository.
No .gitignore verification needed — outside project entirely.
project=$(basename "$(git rev-parse --show-toplevel)")
# Determine full path
case $LOCATION in
.worktrees|worktrees)
path="$LOCATION/$BRANCH_NAME"
;;
~/.config/worktrees/*)
path="$LOCATION/$project/$BRANCH_NAME"
;;
esac
# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
Auto-detect and run appropriate setup:
# Node.js
if [ -f package.json ]; then npm install; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then uv sync; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Go
if [ -f go.mod ]; then go mod download; fi
Run tests to ensure worktree starts clean:
# Use project-appropriate command
npm test
cargo test
pytest
go test ./...
If tests fail: Report failures, ask whether to proceed or investigate.
If tests pass: Continue.
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
git check-ignore before creating project-local worktree