switch

name	switch
description	Switch the session's execution context between the primary checkout (root) and a session worktree - resolve the target, surface done and active-edit state, enter it, and verify the handoff. Use when the operator asks to run /switch, to enter or work in a specific worktree, to return to the root repo or primary checkout, or asks where the session is currently working.

switch

Move this session's execution context to the primary checkout (root) or to a linked session worktree, on operator request, deliberately and verifiably. The resolver is pnpm run worktree:switch; the move itself is the host EnterWorktree / ExitWorktree tool or cd; the proof is git rev-parse --show-toplevel.

Follow AGENTS.md and docs/development/conventions.md. Switching only changes where subsequent commands run; it never integrates, rebases, or edits work by itself.

Boundaries

• Read-only toward every non-target worktree: inspect candidates with git -C <path> ... during discovery, never mutate them.
• The only mutation this skill performs is the active-edit marker refresh that worktree:switch applies to a live session worktree target.
• Never create, remove, reopen, or release a worktree here; that is worktree:create / worktree:reopen / worktree:release / /ship.
• The primary checkout is a dispatch context: after /switch root, keep edits trivial per conventions unless the operator explicitly asks for work on main.
• Report resolved absolute paths to the operator.

Arguments

/switch                     # report the current context, then offer targets
/switch root                # primary checkout
/switch <slug|branch|path>  # a worktree, resolved like other worktree subcommands

Unknown flags are not passed through: stop, list the accepted arguments, and ask.

Step 0 - Current context

pnpm run worktree:switch

Report the current path and kind. When the operator only asked where the session is working, stop here.

With no target argument, enumerate targets with pnpm run worktree:list and present a menu (host AskUserQuestion when available, else a numbered list): root plus every non-done session worktree, each with its branch and path verbatim, its task description or (no task description recorded), and its edit status. Include done worktrees only on explicit operator request, mirroring docs/development/worktree-selection-gate.md.

Step 1 - Resolve the target

pnpm run worktree:switch <root|slug|branch|path>

The subcommand resolves the target, prints from/to, branch, and kind plus, for a worktree, its task and pre-switch edit status, refreshes a live session worktree's active-edit marker, and prints the handoff instructions. The root keyword takes precedence over slug matching; reach a hypothetical session/root worktree by full branch name or path. Stop on a resolver error (zero or multiple matches) and ask rather than guessing.

Step 2 - Safety gate

• Status active (marker refreshed ...) that this session did not write means another session may be editing there: confirm with the operator before entering (the confirmation rule of the worktree selection gate).
• note: marked done: entering to inspect is fine; before any edit, offer pnpm run worktree:reopen <branch>.
• A dirty target tree is reported, not blocked; do not clean it up.

Step 3 - Enter and verify

• Enter with the host tool: EnterWorktree <path> for a worktree, or ExitWorktree to return to root when the session entered through EnterWorktree. Fall back to cd <path>.
• Verify the handoff: git rev-parse --show-toplevel must print the target path. Stop if it does not; acting could mutate the wrong tree.
• From then on run every command inside the new context; reserve git -C <path> for read-only peeks at other trees.

Output

Switched: <from-path> -> <to-path>
  - branch: <branch> | (detached)
  - kind: root (primary checkout) | session worktree | linked worktree
  - marker: refreshed | n/a
  - notes: <done/reopen hint, active-edit confirmation, or none>

When no switch happened - already in the target context, or the operator only asked for the current context - report that instead.