worktree-workflow

Manage Git worktrees with Worktrunk for ticket branches, PR reviews, and isolated dev servers.

1|Updated Sep 11, 2026
One-click install
npx skills add https://github.com/rebuildup/my-web-2026 --skill worktree-workflow-rebuildup
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktree-workflow
Source: https://github.com/rebuildup/my-web-2026/tree/main/skills/worktree-workflow
Command: npx skills add https://github.com/rebuildup/my-web-2026 --skill worktree-workflow-rebuildup

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Running multiple ticket branches or PR reviews on a shared WSL/Linux host causes port collisions, orphaned dev server processes, and leaked mutable state between worktrees. This Skill defines a disciplined Worktrunk-based workflow for creating, switching, listing, and cleaning up Git worktrees while keeping branch naming, port allocation, and process lifecycle safe. ## Core Features & Use Cases - Worktree lifecycle management: Create ticket worktrees from issue numbers (wt switch --create 123), check out PRs for review (wt switch pr:123), list worktrees, and remove them after landing. - Deterministic port allocation: Use {{ branch | hash_port }} in a committed .config/wt.toml so each worktree's dev server binds a distinct host port on shared machines. - Process lifecycle tethering: Attach long-running dev servers to the worktree lifecycle with wt step tether to prevent orphan processes and stale port ownership. - Use Case: On a shared WSL2 host, you need to review PR #45 while your own ticket branch dev server keeps running. Use this Skill to spin up an isolated review worktree on its own hashed port, then remove it cleanly after the review. ## Quick Start Ask the AI to create a new Worktrunk worktree for issue 123 with its own dev server port and show the resulting worktree list.

Frequently Asked Questions about worktree-workflow

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Git worktree for a ticket branch with Worktrunk?

Run `wt switch --create <issue-number>` from the expected base branch to create a ticket worktree named by issue number. For PR review, use `wt switch pr:<number>` to check out the pull request in an isolated workspace.

How to run multiple dev servers on one host without port conflicts?

Use Worktrunk's `{{ branch | hash_port }}` template in `.config/wt.toml` to derive a deterministic port per branch. Hash-based allocation is not a uniqueness guarantee, so the dev server must detect bind failures and resolve collisions explicitly.

Does Worktrunk work on Windows or only WSL and Linux?

This workflow targets WSL2/Linux and Linux hosts as the primary platforms; native Windows is not a required target. On WSL, place high-frequency build worktrees on the Linux filesystem rather than /mnt/c.

What happens to dev server processes when a worktree is removed?

Start long-running servers with `wt step tether -- <command>` so the process is tied to the worktree lifecycle. This reduces orphaned processes and stale port ownership after `wt remove <branch>`.

Can I use git worktree directly instead of Worktrunk?

Yes, falling back to native `git worktree` is allowed when Worktrunk is unavailable. You must preserve the same semantics: branch naming, isolated runtime state, unique ports, and the Draft PR delivery lifecycle.

When should I not use wt merge for integration?

Do not use `wt merge` to bypass GitHub PRs, release integration, or explicit merge authorization. Worktrunk commands are only an ergonomic frontend; ticket PRs, release PRs, and protected main remain the canonical delivery path.