/flow-next-worktree-kit

name: flow-next-worktree-kit
description: Manage git worktrees (create/list/switch/cleanup) and copy .env files. Use for parallel feature work, isolated review, clean workspace, or when user mentions worktrees.

Worktree kit

Use the manager script for all worktree actions.

WORKTREE_SH="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-worktree-kit/scripts/worktree.sh"
[ -f "$WORKTREE_SH" ] || WORKTREE_SH="<plugin-root>/skills/flow-next-worktree-kit/scripts/worktree.sh"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
bash "$WORKTREE_SH" <command> [args]

Commands:

• `create <name> [base]`
• `list`
• `switch <name>` (prints the worktree path; it cannot change your shell's directory - use `cd "$(... switch <name>)"`)
• `cleanup [<name>...] [--yes]` (no args = interactive; names skip the prompt; `--yes` skips the confirmation, required off a terminal)
• `copy-env <name>`

Safety notes:

• `create` does not change the current branch
• `create` sets no upstream on the new branch (`--no-track`) - under the upstream-based push modes (`simple`, `upstream`, `current`) a bare `git push` cannot aim at the base branch; under the default `push.default=simple` (without `push.autoSetupRemote`) the first push needs `git push -u origin <name>` (legacy `push.default=matching` pushes all name-matched branches regardless of upstream)
• `cleanup` does not force-remove worktrees and does not delete branches
• `cleanup` deletes the worktree directory (including ignored files); removal fails if the worktree is not clean
• `.env*` is copied with no overwrite (symlinks skipped)
• refuses to operate if `.worktrees/` or any worktree path component is a symlink
• `copy-env` only targets registered worktrees
• `origin` fetch is optional; local base refs are allowed
• fetch from `origin` only when base looks like a branch
• Worktrees live under `.worktrees/`
• `create` initializes `.worktrees/.gitignore` (`*` plus `!.gitignore`) when

absent, so `git add -A` cannot stage nested worktrees as gitlinks; existing custom ignore files are preserved

**Shared claim state.** Parallel agents in sibling worktrees driving `flowctl` on the same repo share claim state via `.git/flow-state`. Set `FLOW_STATE_DIR` per agent (outside the tree) when running flow pipelines concurrently.