pi_mcps/zoo_backup/home/skills/switch-worktree/SKILL.md

name, description

name	description
switch-worktree	Switch VS Code to an existing git worktree. Lists worktrees, replaces the current window (code -r), announces BigMind focus, and restores session context. Use when asked to switch worktree, open another ticket, change to a different branch/ticket, or activate a worktree.

Switch Worktree

When to use

• User wants to switch to a different ticket worktree
• User says "switch to PROJECT-XXX", "open worktree for ...", "go to ticket ..."
• User wants to see available worktrees and pick one

When NOT to use

• User wants to create a new worktree → use create-worktree skill instead
• User wants to delete/remove a worktree
• User just wants to see git history (no switch needed)

Inputs

Input	Required	Source	Example
TICKET_KEY	Optional	User or interactive selection	PROJECT-123

If no ticket key is provided, list all worktrees and let the user pick.

Workflow

1. List available worktrees

git -C <your-repo-path> worktree list

Parse output to show available worktrees with their branches.

2. Match or select target

If TICKET_KEY provided:

• Look for a worktree path containing the ticket key
• If not found, report error and show available worktrees

If no TICKET_KEY:

• Present the list and ask the user to pick

3. Show worktree status before switching

cd <target_worktree_path>
git branch --show-current
git status --short
git log --oneline -3

Report: branch name, uncommitted changes (if any), last 3 commits.

4. Switch VS Code window

code -r <target_worktree_path>

This replaces the current VS Code window with the target worktree.

Important: After this command, the current Roo session ends because the workspace changes. The next Roo session will start in the new worktree.

5. Update BigMind focus

Before executing code -r, announce the switch:

memory_store_fact(
    category="codebase",
    fact=f"Switched worktree to {TICKET_KEY} at {target_path}, branch {branch_name}"
)
memory_announce_focus(
    session_id=SESSION_ID,
    description=f"Switching to {TICKET_KEY} worktree",
    files=[target_path],
    ide_hint="Roo"
)

6. Context recovery hint

After switching, the next session should:

1. Run memory_search_facts("<TICKET_KEY>") to find prior work
2. Run memory_search_chunks("<TICKET_KEY>") for detailed context
3. Check docs/<MODULE>/<TICKET_KEY>/ for existing documentation

This happens automatically via the BigMind session ritual.

Error Handling

Error	Resolution
No worktrees found	Only the main repo exists — suggest create-worktree
Ticket worktree not found	Show available worktrees, ask user to pick or create
Uncommitted changes in current worktree	Warn user before switching — suggest commit or stash
code CLI not available	Run Shell Command: Install 'code' command in PATH from VS Code

Notes

• code -r replaces the current window — the Roo session will end after this
• The new window starts fresh — BigMind provides continuity across the switch
• If the user has uncommitted changes, always warn before switching