Create a sibling git worktree Skill

Create a sibling git worktree

Goal: one name → new branch + sibling worktree at ../<name>, ready to work in.

For git command details and path naming, read nv-worktree-commands. For cleanup, read nv-worktree-cleanup.

Inputs

| Input | Required | Default | |---|---|---| | Branch / worktree name | yes — ask if missing | — | | Base ref | no | current HEAD | | --lite | no | off — copy only the core app .env files (api, worker, ws, dashboard), no dirty-check | | --no-env | no | off — skip the env copy entirely | | --enterprise | no | off — also link/init the enterprise .source submodule (slow: network + symlinks) |

Use the name as-is for the git branch. Use the sanitized name for the directory (see nv-worktree-commands).

Steps

Preflight — one call from the main repo root:
```
git rev-parse --show-toplevel && git worktree list && git status --porcelain
```
Abort if the target path already exists. If the status is non-empty, warn that the working tree is dirty and ask whether to proceed (skip this ask with --lite).
Create — always a new branch and worktree:
```
git worktree add -b <branch> <worktree-path> [<base-ref>]
```
Omit <base-ref> to branch from current HEAD.
Copy local env files — only the gitignored .env files (the .env.* variants are tracked and already in the worktree). Use the fast git ls-files recipe in nv-worktree-commands (~0.1s). With --lite use its core-apps recipe; with --no-env skip. Do not use a recursive rsync over the repo (walks node_modules/.nx, ~10s). Report what was copied. Do not run setup-env-files.js — it regenerates encryption keys.
Enterprise submodule — only with --enterprise; otherwise skip and continue in OSS mode. From the worktree root (best-effort; do not block handoff):
- Skip if .source already exists or is linked.
- Prefer linking an existing packages-enterprise clone before submodule init — same candidates as .cursor/scripts/install.sh (sibling ../packages-enterprise, parent checkout .source, /agent/repos/packages-enterprise, etc.).
- Else configure HTTPS git fallback when SSH is unavailable, then shallow-init .source (matches install.sh):
```
git config --global url."https://github.com/".insteadOf "git@github.com:"
gh auth setup-git
git submodule update --init --depth 1 .source
```
- If .source is available, refresh symlinks (warn-only on failure):
```
pnpm symlink:submodules || echo "WARN: symlink:submodules failed; continuing in OSS mode"
```
- If enterprise setup fails, warn and continue in OSS mode — do not block the worktree. For troubleshooting, read enterprise-submodule.
Hand off — move_agent_to_root with the absolute worktree path. Not move_agent_to_cloned_root.
Confirm — branch name, worktree path, base ref, copied env files, enterprise submodule status (or "skipped").

Example

User: /worktree branch=more-dcr-oauths

Branch:     more-dcr-oauths
Path:       ../more-dcr-oauths
Command:    git worktree add -b more-dcr-oauths ../more-dcr-oauths

Then copy .env, move_agent_to_root. Add --enterprise to also wire .source + pnpm symlink:submodules.

Do not

Check out an existing branch — this skill always creates a new branch.
Copy the whole repo — only .env.
Run pnpm install, pnpm build, or pnpm setup:agent — never, not even if a task fails; tell the user instead. (pnpm symlink:submodules under --enterprise is the only pnpm script allowed.)
Symlink node_modules from the parent checkout.
Pick the branch name without the user providing it (or confirming a suggested name).

Agent Skills: Create a sibling git worktree

Install this agent skill to your local

Skill Files