worktree

Create an isolated git worktree for safe development on: $ARGUMENTS

Iron Law

All new feature work happens in a worktree. The main branch stays clean.

If you think "this change is small enough to do on main" — you are wrong. Worktrees cost 5 seconds. Debugging a polluted main branch costs hours.

Steps

1. Verify Clean Baseline

Before creating the worktree:

# Ensure we're in a git repo
git rev-parse --is-inside-work-tree

# Check for uncommitted changes
git status --porcelain

If there are uncommitted changes, ask the user whether to stash or commit them first. Do NOT proceed with dirty state.

2. Create the Worktree

Sanitize the branch name from the user's description:

• Lowercase everything
• Replace spaces and special characters with hyphens
• Remove consecutive hyphens
• Example: "User Notifications!" → feature/user-notifications

# Create worktree on a new branch
git worktree add "../$(basename $PWD)-feature-$BRANCH_NAME" -b "feature/$BRANCH_NAME"

3. Verify Test Baseline

Run the project's test suite in the new worktree BEFORE making any changes:

cd "../$(basename $PWD)-$BRANCH_NAME"
# Run tests (detect test command from package.json, Makefile, etc.)

If tests fail BEFORE any changes, the baseline is broken. Stop and report.

4. Work in the Worktree

• Make all changes in the worktree directory
• Commit frequently with descriptive messages
• Run tests after each meaningful change

5. Finish

When work is complete, present options:

Red Flags

• "Let me just make this quick fix on main" — NO. Use a worktree.
• "The tests were already failing" — Then fix the baseline FIRST.
• "I'll clean up the branch later" — You won't. Clean it now.