flow-next-worktree-kit_skill

Overview

This skill manages Git worktrees and .env file propagation for isolated, parallel development. It provides simple commands to create, list, switch to, clean up, and copy environment files into registered worktrees. The tool enforces safety checks to avoid symlink surprises and accidental data loss.

How this skill works

A single manager script exposes commands: create, list, switch, cleanup, and copy-env. Worktrees are created under a .worktrees/ directory and the script enforces non-symlink path components, optional origin fetch logic, and safety checks before deletion. .env* files are copied into registered worktrees without overwriting existing files and skipping symlinks.

When to use it

• Working on multiple features in parallel without contaminating the main workspace
• Preparing isolated review branches for PRs or multi-model review gates
• Cleaning up stale or unused worktrees while preserving branch refs
• Propagating local .env configuration to a specific worktree for testing
• When an agent-driven workflow (planning or autonomous mode) needs a fresh file-based context

Best practices

• Use create <name> [base] to start a worktree; create does not change your current branch so you won’t lose context
• Keep worktrees under .worktrees/ and avoid symlinking any component of that path to prevent operation refusal
• Run cleanup only on clean worktrees; cleanup will not force-remove dirty directories and will not delete branches
• Use copy-env <name> to safely copy .env* files; it never overwrites existing files and skips symlinks
• Prefer local base refs when appropriate; fetch from origin only when the base looks like a branch

Example use cases

• Create isolated feature worktrees for parallel feature development without switching your main branch
• Spin up a temporary review worktree for automated multi-model review and then run cleanup after approval
• Copy local .env into a test worktree to reproduce environment-specific bugs without altering your main workspace
• List and switch to a registered worktree path to quickly inspect or run tests in that checkout