worktree_skill

Overview

This skill creates a new git worktree for a branch immediately after a plan is approved, completed, or when a task starts. It automates local workspace setup using the GitHub CLI and hands off to the commit-push-pr-flow after implementation. It enforces simple branch naming to avoid issues.

How this skill works

When triggered, the skill runs gh wt add <branch> to create a new worktree for the requested branch. It validates the branch name to ensure no slashes are present and returns an error if the name is invalid. After the worktree is created and the implementation is done, the skill invokes commit-push-pr-flow to continue the change lifecycle.

When to use it

• A plan has just been approved and you need a dedicated workspace.
• A plan is marked completed and you must begin implementation.
• When starting a new task that requires a separate branch workspace.
• Whenever you want an isolated working tree for feature development or bug fixes.
• When coordinating automated workflows that require sequential steps (worktree → commit → push → PR).

Best practices

• Use simple branch names without slashes to avoid validation errors and filesystem conflicts.
• Run this skill as the first step in the implementation phase, before making local edits.
• Confirm the repository is up to date and the target branch exists or can be created remotely.
• Keep the working tree lifecycle short: create, implement, then invoke commit-push-pr-flow to finalize changes.
• Handle errors from gh (authentication, missing repo, or permission issues) and report clear remediation steps.

Example use cases

• Plan approved for a new feature: create a worktree named feature-x and start implementation.
• Task begins for a bugfix: spawn a worktree named bugfix-123, apply the fix, then call commit-push-pr-flow.
• Automated pipeline: after plan completion, automatically prepare a worktree so a developer can immediately start coding.
• Multiple parallel tasks: create isolated worktrees per task to avoid branch conflicts and speed up context switching.