continue-in-worktree

name

continue-in-worktree

description

Use when handing off to a fresh Claude session in a brand-new git worktree (isolated branch + tmux window). Runs `wtn` to create the worktree and launches claude pre-loaded with an initial prompt — a handoff doc reference (`@<doc>`), a slash command (`/brainstorming`, `/writing-plans @<spec>`, `/subagent-driven-development @<plan>`), or any free-text instruction; pass skill args through verbatim. Triggers on "continue in worktree", "spin up a worktree", "new branch for this", or after producing a spec/plan/handoff that's ready for the next phase in isolation.

Continue in Worktree

Overview

Spin up a new git worktree (under <repo>/.worktrees/<branch>/) and launch a fresh Claude session in it, pre-loaded with the right slash command for the next phase. Sister skill to continue-in-new-session — use this one when the next phase needs branch isolation (implementation work, parallel exploration), use the other when you just want a clean session in the same worktree.

The actual work is done by the wtn command shipped in this plugin's bin/ (on PATH in Claude Code Bash sessions; also symlinked to ~/.local/bin for human shells), which handles worktree creation, env setup, tmux window/pane layout, and launching claude with an optional initial prompt.

When to Use

• User passed a handoff doc / prompt as skill args → launch the worktree session with it
• Just produced a handoff summary (e.g. via /handoff) → next session reads it and continues in isolation
• Just finished a spec → next session: /writing-plans in a new worktree (clean branch for the implementation work to come)
• Just finished a plan → next session: /subagent-driven-development in a new worktree (isolated branch for the implementation)
• Starting a new exploration/discussion that wants its own branch → /brainstorming in a new worktree
• User says "continue in worktree", "new branch for this", "spin up a worktree"

Don't use when:

• Not running inside tmux ($TMUX empty) — wtn requires it
• Not inside a git repo — wtn will refuse
• The current conversation should continue in this worktree (no isolation needed → use continue-in-new-session instead)

What You Do

1. Decide the initial prompt the new session boots with. In priority order:

   • User gave skill args → use them as the prompt verbatim (normalize any @<file> to an absolute path). The override — don't second-guess it.
   • Handoff doc just produced (e.g. via /handoff) → read @<absolute-path> and continue.
   • Spec finished → /writing-plans @<absolute-spec-path>.
   • Plan finished, ready to implement → /subagent-driven-development @<absolute-plan-path>.
   • Fresh exploration → /brainstorming.
   • Otherwise → any free-text instruction describing the next task.

   The prompt is just a string handed to wtn -p; it need not be a slash command. wtn shell-escapes it via printf %q, so spaces, @, /, and apostrophes are all safe — no manual escaping (unlike the tmux split in continue-in-new-session).

2. Absolute paths only for any @<file>. Worktrees share the filesystem, so absolute paths from the original repo work even if the file isn't on the new branch yet (uncommitted).

3. Pick the branch name — derive from context:

   • Plan/spec filename topic (e.g. plans/2026-04-19-auth-rewrite.md → auth-rewrite)
   • Conversation topic if no file
   • Ask the user only if context is ambiguous

4. Verify environment: [ -n "$TMUX" ] AND we're inside a git repo (git rev-parse --show-toplevel)

5. Run wtn in a single Bash call. <prompt> is whatever you picked in step 1:

   wtn <branch> -p "<prompt>"
   

6. Tell the user in one sentence: branch name, prompt, file (if any). Mention that focus jumps to the new tmux window automatically.

Examples

After finishing a plan at /path/to/repo/plans/2026-04-19-auth-rewrite.md:

wtn auth-rewrite -p "/subagent-driven-development @/path/to/repo/plans/2026-04-19-auth-rewrite.md"

Handing off a handoff doc:

wtn auth-rewrite -p "read @/path/to/repo/HANDOFF.md and continue"

Free-text prompt (user-supplied args, apostrophe safe via printf %q):

wtn rate-limiter -p "implement the rate limiter we discussed; don't touch the existing middleware"

Then say: "Spawned worktree auth-rewrite (/.worktrees/auth-rewrite) with /subagent-driven-development loaded."

How wtn Handles the Prompt

wtn accepts -p "<prompt>" as an optional flag. It uses printf %q to shell-escape the prompt before sending it via tmux send-keys to the new window's interactive shell. This means special characters in the prompt (spaces, @, /) are handled safely — just pass the prompt as a normal string, no manual escaping.

Common Mistakes

Mistake	Fix
Using clawd inside -p "..."	The prompt is sent to the new window's interactive zsh shell, so clawd would expand — but wtn already runs claude --dangerously-skip-permissions as the command. The -p value is only the prompt (e.g. /writing-plans @foo.md), not the whole command line.
Forcing a slash command when the user gave a plain prompt	The -p value is any string. If the user handed you free text or a handoff doc, pass it through — don't wrap it in a superpowers command.
Passing a relative file path	New worktree's cwd differs from yours. Always use absolute paths in the prompt.
Forgetting to commit the spec/plan	Worktree creates a fresh checkout — uncommitted files in your current dir are NOT on the new branch. Absolute paths still work (filesystem is shared) but the new branch won't track them until you commit. Decide whether to commit first or rely on absolute path.
Using this skill when not in a git repo	wtn aborts. Use continue-in-new-session instead.
Picking a branch name that already exists	claude --worktree (which wtn launches) attaches to the existing branch as-is (not create new). If that's not what you want, pick a unique name.

Related Skills

• continue-in-new-session — same intent (handoff to fresh claude) but stays in the current worktree (just splits a pane). Use when branch isolation isn't needed.