worktree

name: worktree description: Launch one or more tasks in new git worktrees using workmux. disable-model-invocation: true allowed-tools: Bash, Write

Launch one or more tasks in new git worktrees using workmux.

Tasks: $ARGUMENTS

You are a dispatcher, not an implementer

HARD RULE — NO EXCEPTIONS: Do NOT explore, read, grep, glob, or search the codebase. Do NOT use the Task/Explore agent. Do NOT investigate the problem. You are a thin dispatcher — your ONLY job is to write prompt files and run workmux add. The worktree agent will do all the exploration and implementation.

If the user's message contains enough context to write a prompt, write it immediately. If not, ask the user for clarification — do NOT try to figure it out by reading code.

If tasks reference earlier conversation (e.g., "do option 2"), include all relevant context in each prompt you write.

If tasks reference a markdown file (e.g., a plan or spec), re-read the file to ensure you have the latest version before writing prompts.

For each task:

1. Generate a short, descriptive worktree name (2-4 words, kebab-case)
2. Write a detailed implementation prompt to a temp file
3. Run workmux add <worktree-name> -b -P <temp-file> to create the worktree

The prompt file should:

• Include the full task description
• Use RELATIVE paths only (never absolute paths, since each worktree has its own root directory)
• Be specific about what the agent should accomplish

Skill delegation

If the user passes a skill reference (e.g., /auto, /plan-review), the prompt should instruct the agent to use that skill instead of writing out manual implementation steps.

Skills can have flags. If the user passes /auto --gemini, pass the flag through to the skill invocation in the prompt.

Example prompt:

[Task description here]

Use the skill: /skill-name [flags if any] [task description]

Do NOT write detailed implementation steps when a skill is specified — the skill handles that.

Flags

--merge: When passed, add instruction to use /merge skill at the end to commit, rebase, and merge the branch.

...
Then use the /merge skill to commit, rebase, and merge the branch.

Only instruct worktree agent to /merge if explicitly requested by user in task.

--fork: When passed, add --fork to the workmux add command. This copies the current conversation into the new worktree so the agent resumes with full context of what was discussed. Useful when the current conversation has built up context that the new worktree agent needs.

When --fork is used, prepend this to the prompt file so the forked agent does not recursively dispatch more worktrees:

You are now running INSIDE a git worktree created by the /worktree skill. The
prior conversation context (including any /worktree dispatch instructions) is
ancestry only. Do NOT invoke the /worktree skill, do NOT run `workmux add`, and
do NOT create further worktrees. Your job is to implement the task below
directly in this worktree.

Cross-project dispatch

If the task mentions another repository, absolute project path, or work that clearly spans multiple repositories, adapt the dispatch to the target project instead of assuming the current repository.

For each target project:

1. Use the project path provided by the user, or the project path already present in the conversation. Do not explore that repository.
2. Derive the default tmux session name from the repository directory basename. For /Users/me/code/api-server, use api-server.
3. Check whether a tmux session already exists for that project with tmux list-sessions -F '#{session_name} #{session_path}'. Prefer a session whose path matches the target project. Otherwise use the derived session name.
4. If no session exists, create one with tmux new-session -d -s <session> -c <project-path>.
5. Run workmux add from that project's tmux session by creating a window rooted at the project path:

tmux new-window -t <session> -c <project-path> \
  "workmux add <worktree-name> -b -P <prompt-file>; exit"

If a task touches both the current repository and another repository, create one prompt and worktree per repository. Each prompt should explain the cross-repo context and reference the other repository by absolute path when useful, but the agent assigned to a repository should make changes only in its own worktree unless the user explicitly asks for a different arrangement.

If the user's request does not provide enough information to identify the target project path or session name, ask for clarification instead of searching.

Workflow

Write ALL temp files first, THEN run all workmux commands.

IMPORTANT: For same-repository tasks, run workmux add from the CURRENT directory. Do NOT cd to the main repo or any other directory. The new worktree branches from whatever branch is checked out in the current directory. For cross-project tasks, run workmux add inside the target project's tmux session as described above.

Step 1 - Write all prompt files (in parallel):

tmpfile=$(mktemp).md
cat > "$tmpfile" << 'EOF'
Implement feature X...
EOF
echo "$tmpfile"  # Note the path for step 2

Step 2 - After ALL files are written, run workmux commands (in parallel):

workmux add feature-x -b -P /tmp/tmp.abc123.md
workmux add feature-y -b -P /tmp/tmp.def456.md

After creating the worktrees, inform the user which branches were created.

Remember: Your task is COMPLETE once worktrees are created. Do NOT implement anything yourself.