Move-to-Worktree

Companion to /start-task for parallel Phase 4 lanes (see specs/claude-lens-phase4-parallelization.md). /start-task leaves the primary checkout on the new feature branch; this skill moves that branch into its own worktree and puts the primary back on main — one worktree + one branch + one Claude session per in-flight issue.

Run (1 bash call)

bash {base_directory}/move-to-worktree.sh

No arguments — it operates on the branch currently checked out. The script:

1. Hard-stops unless run in the primary checkout, on a task branch ({type}/{issue#}/{slug}), with a clean tree and its matching origin/ upstream set — i.e. exactly the state /start-task leaves behind.
2. Pushes any local-only commits, checks out and fast-forwards main (this must happen before the worktree is created — git refuses to check out a branch in two places).
3. git worktree add .worktrees/<issue#> <branch> — nested inside the repo root (gitignored), never a ../ sibling. The context file specs/context/<issue#>.md travels with the branch (it's committed).
4. Writes the lane's port block to <worktree>/.env.local (gitignored): CLAUDE_LENS_PORT_BASE = 4128 + 10 × issue# — backend = base, Vite = base+1, E2E = base+2, Storybook = base+3. Issue-derived, so lanes cannot collide.
5. Runs npm ci in the worktree (per-worktree node_modules; also wires the Husky pre-push hook so npm run verify gates pushes from this lane).

Non-zero exit → hard-stop, print stderr verbatim.

Report

The script's summary block (worktree path, branch, ports), plus: "Open a new Claude session in the worktree and continue the pipeline there (/plan-architecture / /implement → /review → /commit → PR with Closes #N)."

When the PR has squash-merged, /finish-worktree <issue#> (run back in the primary) does the teardown.

You Must NOT

• Run the underlying git commands yourself — the script owns all mutation.
• Stash, discard, or commit anything to satisfy the clean-tree check — hard-stop instead.
• Move a branch whose upstream is ahead or does not match origin/<branch>.
• Create the worktree while the primary is still on the feature branch.