Worktree Kit

flow-next-worktree-kit is the thin wrapper flow-next uses for git worktrees. It is the engine behind /flow-next:work --branch=worktree, but it can also be invoked directly when you want a worktree without the rest of the work loop.

Worktrees live under .worktrees/<name>/ and never touch the current branch.

When to use it

• Running two specs in parallel without context switching.
• Reviewing a PR on a separate branch while keeping your main branch dirty.
• Running an expensive build or test suite in isolation.
• Trying a destructive refactor where you want a clean undo.

Commands

bash ${PLUGIN_ROOT}/skills/flow-next-worktree-kit/scripts/worktree.sh <command> [args]

Command	Effect
create <name> [base]	New worktree under .worktrees/<name>/. Does not switch the current branch.
list	All registered worktrees with paths and branches.
switch <name>	Prints the absolute path so a shell helper can cd into it.
cleanup	Remove worktrees whose checkouts are clean. Does not delete branches.
copy-env <name>	Copy .env* files from the repo root into the worktree. No overwrite; symlinks skipped.

Safety guarantees

• create does not change the current branch.
• cleanup does not force-remove a worktree with uncommitted changes; it fails loudly instead.
• cleanup deletes the worktree directory including ignored files, but never deletes branches.
• .env* copies refuse to overwrite an existing file.
• The script refuses to operate if .worktrees/ or any worktree path component is a symlink.
• copy-env only targets worktrees registered with git; ad-hoc directories are rejected.

When fetch happens

create fetches from origin only when the base argument looks like a branch name. Passing a SHA, a tag, or any non-branch ref keeps the create offline. This avoids unnecessary network traffic during fast local work.

What this is not

• Not a git frontend. The kit handles the worktree lifecycle and nothing else. Use git directly for branch operations.
• Not a deploy primitive. Worktrees are local-only; pushing or sharing them is your call.

Next step

flow-next:work <spec-id> --branch=worktree