Git Worktree Enforcement Skill

You enforce a mandatory git worktree policy: all feature work must happen inside worktrees/ subdirectories, never in the main clone.

Policy Rules

1. Main Clone on main Only

The base clone must stay on main (or master) at all times. Never checkout a feature branch in the main clone.

2. Feature Work in worktrees/ Only

All branches with these prefixes must be checked out as worktrees inside worktrees/:

• feature/*, fix/*, refactor/*, hotfix/*, bugfix/*, chore/*, docs/*, release/*

3. Branch-to-Folder Naming

Slashes become hyphens:

• feature/user-auth → worktrees/feature-user-auth
• fix/login-bug → worktrees/fix-login-bug
• hotfix/critical-patch → worktrees/hotfix-critical-patch

4. Gitignore

worktrees/ must be listed in .gitignore.

Pre-Flight Check (Before Any Git Write Operation)

1. Run pwd - confirm you are inside worktrees/<name>
2. Run git branch --show-current - confirm you are on the expected feature branch
3. If on a feature branch but NOT inside worktrees/ → STOP and relocate

Standard Workflow

Create a New Feature Branch

cd /path/to/repo
git branch --show-current  # must be: main
grep -q '^worktrees/' .gitignore || echo 'worktrees/' >> .gitignore
git worktree add worktrees/feature-my-feature -b feature/my-feature main
cd worktrees/feature-my-feature
# ALL work happens here

Work on an Existing Branch

git fetch origin
git worktree add worktrees/feature-existing feature/existing
cd worktrees/feature-existing

Cleanup After Merge

cd /path/to/repo  # main clone
git worktree remove worktrees/feature-my-feature
git worktree prune

What This Prevents

• Branch conflicts between concurrent sessions
• Lost work from accidental branch switches
• Clobbered changes from multiple tools on the same checkout
• Detached HEAD from working in wrong directory

When to Apply This Skill

• Before ANY git write operation (commit, add, push, merge, rebase)
• When creating new feature branches
• When switching between tasks or features
• When onboarding to a new repository