/worktree

description: Worktree lifecycle management - create, list, remove, info on interactive worktrees

Worktree Management

Thin dispatcher for interactive parallel worktrees. All filesystem/git work lives in the Go subcommand `lets worktree` (`cli/internal/worktreecmd/`); this skill captures user intent via `AskUserQuestion`, shells out with `--json`, and renders the result.

**Interactive worktrees only.** Agent worktrees (`isolation: worktree`) use native Claude Code behavior — not this command.

> **IMPORTANT:** If the spec below invokes any deferred tool (e.g. `AskUserQuestion`), you MUST load and call it as specified. Never skip the call, never substitute a default answer of your own — the tool invocation is part of the contract. This is critical.

Step 1: Determine Subcommand

**If argument provided** (e.g., `/lets:worktree create auth-feature`), parse it:

• `create <name>` -> go to Create. **First strip any `--orca` / `--no-orca` / `--cmux` / `--no-cmux` / `--tmux` / `--no-tmux` / `--auto` / `--flow <value>` / `--branch <ref>` / `--title-file <path>` token** out of the argument and carry them as overrides (`--orca`/`--no-orca` = the Orca launcher, Step C0; `--cmux`/`--no-cmux`/`--tmux`/`--no-tmux` = launcher; `--auto` = autonomous permission mode; `--flow plan|plan-workflow` = which command the launch lands in — all for Steps C0 / C3.5; `--branch <ref>` decouples the attached/created branch from the dir name — Step C2; `--title-file <path>` = a file holding the task title, passed by `take-task` so the branch name is derived in Go — Step C1). Bind the remainder as `<name>` (so `create auth --flow plan-workflow --auto` => name `auth`, not the flags; `create pwa-46696 --branch feature/pwa-46696` => name `pwa-46696`, branch `feature/pwa-46696`). A `<name>` that is a bare task id (it passes the detect-task id gate and `take-task` sent it) means **From task** in Step C1 with that id.
• `list` -> go to List
• `remove <name>` -> go to Remove
• `info` -> go to Info

**If no argument**, use **AskUserQuestion**:

AskUserQuestion(
  questions=[{
    question: "What do you want to do with worktrees?",
    header: "Action",
    options: [
      { label: "Create", description: "Create a new worktree for parallel work" },
      { label: "List", description: "Show all active worktrees" },
      { label: "Remove", description: "Remove a worktree and clean up" },
      { label: "Info", description: "Show current worktree status" }
    ],
    multiSelect: false
  }]
)

---

Create

Create an interactive worktree. The Go subcommand owns the guard, name validation, `.gitignore` ensure, `git worktree add`, symlinks (`.lets/` and the tracker adapter's declared store links), verify, and rollback. The skill drives the user choices.

Optional launcher override on the argument: `--orca` / `--no-orca` / `--cmux` / `--no-cmux` / `--tmux` / `--no-tmux` force the launcher for this run (otherwise `$LETS_LAUNCHER` decides — Orca in Step C0, the others in Step C3.5).

Optional `--auto`: launch the session in `claude --permission-mode auto` (autonomous — auto-approves low-risk work, still gates push / PR / close / external per LETS AUTO MODE rules). Maps ONLY to `--permission-mode auto`, **never** `bypassPermissions`. Applies to the launcher paths in Step C3.5 / C4 (see Step C3.5).

Optional `--flow plan|plan-workflow`: which `/lets:*` command the spawned session lands in. `--flow` ONLY swaps the launch `--command` string — all other steering stays in the tracker task (the launch stays uniform/reproducible). Default (no `--flow`) → `/lets:start <id>` (today's behavior). `--flow plan` → `/lets:plan <id>` (interactive planning in the worktree; the human drives). `--flow plan-workflow` → `/lets:plan-workflow <id>` (autonomous planning). Because only the command string changes, `--flow` is **launcher-agnostic** — the cmux (C3.5) and terminal (C4) paths both inherit it (so does the future tmux launcher). Composes orthogonally with `--auto`. Requires a known task id; on a **taskless** worktree, ignore `--flow` with a one-line note (and `taskless + --flow + --auto` collapses to the existing taskless `--auto` path, `claude --permission-mode auto`). **plan-workflow is PREVIEW** (needs Claude Code ≥ 2.1.154 / paid / Dynamic Workflows) — the launch string can't probe that, so the launched `/lets:plan-workflow` is responsible: if the Workflow tool is unavailable it prints the standard PREVIEW-unavailable message and the operator re-runs `--flow plan`.

**Orchestrator binding.** When this session is a registered orchestrator, every worker it spawns is bound to it. Before building a launch prompt (C0's `--prompt`, C3.5's cmux / tmux `--command`, C4's printed terminal command), run `lets peers orchestrator --session "$CLAUDE_CODE_SESSION_ID" --json`; on `source=self` append ` --orc="<target.name>"` to the slash command of the first line - `/lets:start <id> --orc="<name>"`, and the `--flow` forms `/lets:plan <id> --orc="<name>"` / `/lets:plan-workflow <id> --orc="<name>"` (the spawned command strips it before its task-id test). The name comes from the registry through Go, so it already passed the name grammar; inside the single-quoted launch string it stays double-quoted, e.g. `claude --permission-mode auto '/lets:plan-workflow {task-id} --orc="MAIN PWA"'`. Any other `source`, a taskless worktree, or no binary -> the prompt is unchanged.

Step C1: Get Name

If name not provided via argument, use **AskUserQuestion**:

AskUserQuestion(
  questions=[{
    question: "Name for the worktree? (lowercase, no spaces - used for directory and branch)",
    header: "NameMode",
    options: [
      { label: "From task", description: "Auto-generate from the current or a selected tracker task" },
      { label: "Custom", description: "Enter a custom name" }
    ],
    multiSelect: false
  }]
)

**From task:** Show the tracker's `ready` view (top 5) and let user pick a task or use the current in-progress task (skipp