# Worktree Kit

Source: https://flow-next.dev/skills/worktree-kit/

Manage git worktrees for parallel feature work, isolated review, and clean workspaces.

`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
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.

## Where it stops

* 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.

## Worked example

```bash
bash ${PLUGIN_ROOT}/skills/flow-next-worktree-kit/scripts/worktree.sh create fn-14-rate-limits
```

```text
Created worktree: .worktrees/fn-14-rate-limits/ (branch fn-14-rate-limits, base main)
Current branch unchanged. Next: copy-env fn-14-rate-limits if the app needs .env files.
```

A parallel workspace in one command - the current branch and working tree stay exactly as they were.

* `cleanup` fails loudly on uncommitted changes instead of force-removing - a dirty worktree is a decision, not debris.
* `copy-env` never overwrites and skips symlinks; secrets handling stays deliberate.
* Passing a SHA or tag as base keeps `create` fully offline - only branch-name bases trigger a fetch.

## Dynamic usage

Recipes that compose with worktree-kit in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Parallelize](https://flow-next.dev/guides/cookbook/#parallelize) - worktrees are the isolation layer under “run two specs side by side”.
* [Team patterns](https://flow-next.dev/guides/cookbook/#team-patterns) - review a teammate’s PR in a worktree while your own branch stays dirty.

## Next step

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