worktree-start

Worktree Start

Start development on a single task by creating an isolated worktree, writing structured context for the new session, and bootstrapping a Claude session in that worktree.

This skill builds on top of worktrunk (wt CLI) for worktree management. It adds the workflow layer: planning, context writing, and session bootstrapping.

Prerequisites

• worktrunk CLI (wt) must be installed and configured
• git repository with a clean working tree on the main branch (or a primary worktree)
• A task to work on (issue tracker ID, URL, description, or verbal explanation)

Workflow

Work through these steps in order. Do not skip steps.

Step 1 — Gather Task Details

Collect enough information to plan the work:

1. If the user provided an issue tracker ID or URL, fetch the task details using the appropriate skill or tool (e.g., a project management integration). Extract: title, description, acceptance criteria, checklist items.
2. If the user described the task verbally, confirm your understanding before proceeding.
3. Note any constraints: dependencies on other work, merge ordering, related tasks.

Step 2 — Plan the Implementation

Enter plan mode (EnterPlanMode). Produce a brief implementation plan covering:

• What files/areas of the codebase will be touched
• The approach (high-level steps)
• Any risks or open questions
• Relevant skills or documentation to reference during implementation

Check for project-specific worktree configuration skills. Some projects provide a companion skill that adds project-specific pre-flight checks, branch naming conventions, context enrichments, and skill references. If one is available, invoke it now to incorporate its requirements into your plan.

Present the plan and wait for user approval before continuing.

Step 3 — Create the Worktree

Use worktrunk to create and switch to a new worktree:

wt switch --create <branch-name> --yes

Branch naming: Follow the project's branch naming conventions. If a project-specific configuration skill provides a convention, use it. Otherwise, derive a reasonable branch name from the task (e.g., feature/add-user-auth, fix/login-timeout).

Verify that any post-create hooks ran successfully. If any fail, stop and report before continuing.

Step 4 — Write WORKTREE_CONTEXT.md

Write a WORKTREE_CONTEXT.md file in the new worktree root. This file is the primary mechanism for transferring context to the new session. Structure it as follows:

# Task: [Title]

## Source
[Issue tracker link or "Verbal request from user"]

## Description
[Task description and acceptance criteria]

## Implementation Plan
[The plan from Step 2]

## Key Constraints
- [Any dependencies, merge ordering, or blockers]
- [Relevant skills to invoke during implementation]

## Notes
[Design decisions, context from related work, anything the new session needs to know]

The new session loads this file automatically via CLAUDE.local.md containing @WORKTREE_CONTEXT.md. If the project doesn't have this auto-load mechanism set up, note that in your report (Step 6).

Step 5 — Open a Session in the Worktree

Detect the terminal environment and open a new Claude session in the worktree:

tmux (preferred — fully automated)

If $TMUX is set, create a new window in the current tmux session:

# Derive window name from branch or task ID
window_name="<short-identifier>"
worktree_path="<absolute-path-to-worktree>"

# Create window and cd into worktree
/opt/homebrew/bin/tmux new-window -c "$worktree_path" -n "$window_name"

# Send kickoff prompt — MUST escape with printf %q to handle
# apostrophes, ?, $, and other special characters safely
kickoff="Hey Claude, do you know what we're working on?"
escaped=$(printf %q "$kickoff")
/opt/homebrew/bin/tmux send-keys -t "$window_name" "claude $escaped" Enter

Critical tmux caveats:

• Claude Code's bash shell has a restricted PATH — always use full paths: /opt/homebrew/bin/tmux, /bin/cat, /usr/bin/tr
• Always use printf %q to escape the kickoff prompt before send-keys. Apostrophes in the prompt (e.g., "we're") break single-quoted strings and expose ? as a zsh glob pattern.
• Multi-line prompts must be flattened before send-keys — newlines cause premature Enter: prompt=$(/bin/cat /tmp/kickoff.txt | /usr/bin/tr '\n' ' ')
• Test on one window before looping when creating multiple windows

zellij

If $ZELLIJ is set:

zellij run -- bash -c "cd '$worktree_path' && claude 'Hey Claude, do you know what we are working on?'"

Note: avoid contractions in zellij prompts to sidestep quoting issues.

No multiplexer (fallback)

If neither tmux nor zellij is detected:

1. Open the worktree in the user's editor: $EDITOR <worktree-path>
2. Instruct the user to start Claude Code in that directory and send the kickoff prompt: "Hey Claude, do you know what we're working on?"

Step 6 — Report

Confirm the setup:

Detail	Value
Worktree	<path>
Branch	<branch-name>
Task	<title or ID>
Session	opened in tmux/zellij / manual instructions provided
Context	WORKTREE_CONTEXT.md written
Auto-load	confirmed / not configured (manual load needed)

If there are merge ordering constraints or dependencies on other work, remind the user here.

---

What This Skill Does NOT Do

• Merge or PR management — use wt merge or your project's PR skill for that
• Project-specific pre-flight (Docker, services, auth) — handled by project-specific companion skills
• Worktree cleanup — use worktrunk directly (wt remove) or a finishing skill

Extensibility

This skill supports project-specific companion skills that provide:

• Pre-flight checks (services, auth, dependencies)
• Branch naming conventions
• Issue tracker integration
• Additional WORKTREE_CONTEXT.md content
• Skill references for the new session

If your project has a companion skill, it will be invoked during Step 2 planning. To create one for your project, model it after this pattern: provide a skill that triggers alongside worktree-start and returns project-specific configuration.