name: worktree-helper
description: Guide for creating and working in Git worktrees with a consistent workflow. Use when a user wants to run a task in a separate worktree, create or clean up worktrees, migrate a repo into a main/worktrees layout, or implement work based on an issue ID using GitHub/GitLab tooling.

Worktree Helper

Overview

Use this skill to set up a clean worktree workflow, create new worktrees, and guide issue-based or task-based work. Keep the user in control for any destructive or structural change.

Workflow Decision Tree

1) Is the request issue-based?

• Yes → Use references/hosting.md to fetch issue details (MCP → gh → glab → manual).
• No → Continue with the task description.

2) Is the repo layout already main/ + worktrees/?

• Yes → Work from main/.
• No → Recommend migration and offer to run scripts/migrate_to_main_layout.sh.

3) Create a worktree using the naming rules in references/workflow.md.

4) Implement the task in the worktree, then review with the user.

5) Finish: merge or open a PR/MR, then clean up worktrees and branches.

Required Checks

• Confirm the user wants to migrate before running any migration command.
• Confirm before deleting branches or removing worktrees.
• If tooling is missing for issue intake, ask the user to paste issue details.

Core References

• references/workflow.md — step-by-step commands, naming, create/remove worktrees.
• references/hosting.md — MCP/CLI/manual issue intake and tooling detection.
• references/troubleshooting.md — common worktree errors and fixes.

Bundled Scripts

• scripts/migrate_to_main_layout.sh — migrate a repo root into a main/ + worktrees/ layout. Use only with explicit user confirmation.