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

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

Steps

1. 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).

2. Create — always a new branch and worktree:

   git worktree add -b <branch> <worktree-path> [<base-ref>]

   Omit <base-ref> to branch from current HEAD.

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

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

5. Hand off — move_agent_to_root with the absolute worktree path. Not move_agent_to_cloned_root.

6. 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).