Worktrees

/action:worktrees

Fan several tickets out into branches and worktrees. This command owns exactly three things: discovery (which tickets), grouping (which tickets share a branch), and fan-out (parallel subagents or a sequential loop). Everything per-unit — ticket resolution detail, branch naming, worktree creation, implementation, gates, commits, the exit axis — is /action:worktree's procedure, followed by reference, never restated here.

This skill is invoked by name, never routed to on the model’s initiative: it creates worktrees and branches, modifies files, and creates commits, so it must be user-explicit, not router-inferred.

Core thesis

N tickets rarely need N decisions — they need one plan and N executions. The plural command's value is the plan: the right ticket set, the right grouping (1:1 by default, shared branches only on clear overlap), and a fan-out that parallelizes the safe part (implementation inside isolated worktrees) while serializing the unsafe part (mutation of shared git state).

Three disciplines:

1. Delegate, don't duplicate. The per-unit procedure lives in ../worktree/SKILL.md and the shared references — this file never paraphrases it. If the two files ever disagree, worktree.md wins; if worktree.md cannot be read at runtime, stop and say so — never reconstruct its procedure from memory.
2. Group by evidence, confirm at the gate. Default 1:1 ticket-to-branch; propose a group only when tickets clearly overlap; every grouping is confirmed at the plan gate.
3. Shared git state mutates only in the main loop (see The Iron Rule).

The Iron Rule

SHARED GIT STATE MUTATES ONLY IN THE MAIN LOOP

git worktree add / remove, branch creation, and any stash or index operation on the shared repository happen serially, in the main loop, before or after fan-out — never inside parallel units. A parallel unit touches only files inside its own worktree and commits only on its own branch. The tickets themselves stay read-only throughout, per ticket-detection.md § The read-only invariant — discovery queries included.

Red flags — STOP: a git worktree or git stash command inside a subagent prompt; two units whose worktree paths collide; a unit whose branch name matches another unit's.

$ARGUMENTS contract

Non-flag text: any number of ticket references (IDs, URLs, #123). Empty → Phase 1 discovers candidates and asks.

Placement and exit flags apply uniformly to every unit; there is no per-unit override — run /action:worktree separately for a unit that needs different axes.

Phase 0: Situational awareness

As /action:worktree Phase 0 (Situational awareness) — conventions files, the five gate buckets and CI split per ../../references/verification-gates.md, ticket tooling inventory, trunk and remote detection — plus plural-specific checks:

1. Confirm git worktree is usable and there is disk headroom for N checkouts.
2. Note any setup a fresh checkout needs before gates can run (dependency install, codegen) — every unit must be able to verify.
3. Detect subagent support (Task tool or host equivalent); without it, plan for sequential main-loop execution.
4. More than 4 units → flag the fan-out size for explicit confirmation at the plan gate; a dozen worktrees is rarely what anyone wants.

Phase 1: Ticket discovery

Resolve the ticket set:

1. Explicit references in $ARGUMENTS — resolve each per ticket-detection.md (detection source ladder; read-only fetch of title, description, acceptance criteria, branch-name field).
2. Empty → mine the conversation — tickets under discussion, a pasted list, a triage the user just agreed to.
3. Still empty → query, read-only — the tracker reached by the detection ladder: assigned-to-me or current-cycle issues via tracker MCP reads, or:

gh issue list --assignee @me

Present the candidates via AskUserQuestion (multi-select) — never auto-select a whole backlog.

Phase 2: Grouping

Default: 1:1 — one ticket, one branch, one worktree.

Propose a group (several tickets, one branch) only on clear overlap evidence:

• The tickets name the same component, files, or surface.
• One ticket's acceptance criteria cannot be met without another's change.
• The tracker marks them as sub-issues or duplicates of one story.

--groups replaces proposals with the user's own grouping. Grouped units are crosscutting branches: naming skips the ticket-system rung and proposes a theme slug (ticket-detection.md § Branch-name precedence ladder), and every ticket's ID rides in the unit's commits and PR per ticket-detection.md § Server-side linking. Every grouping — proposed or explicit — is confirmed at the Phase 3 plan gate.

Phase 3: Orchestration plan

Enter plan mode if the host supports it (Claude Code: EnterPlanMode; Cursor / Codex / Gemini: /plan or Shift+Tab) and present:

1. The unit table: unit → ticket(s) → branch name (with its ladder rung) → worktree path → exit axis.
2. Grouping rationale, one line per proposed group (or "1:1 throughout").
3. Execution mode: parallel (one subagent per unit) or sequential, and why (host support, --sequential).
4. Discovered gate commands and the local-vs-CI split (shared by all units).
5. The serialization boundary: worktree/branch creation in the main loop; implement → gates → commit → exit per unit.

Wait for approval, then exit plan mode. This gate also stands in for each unit's own plan gate (/action:worktree Phase 2, Orchestration plan): units run non-interactively and must not re-prompt. If plan mode is unavailable, present the plan inline and proceed on confirmation. In a non-interactive run, record the plan in the report and proceed with 1:1 grouping only — never apply inferred groups without a human at the gate.

Phase 4: Fan-out

1. Serialize setup (main loop). For each unit in plan order, perform /action:worktree Phase 3 (Worktree & branch) exactly as written there — start point, idempotency ladder, collision halt, primer assembly. One unit at a time; never a parallel git worktree add. With --setup-only, all units stop here.
2. Delegate the work. For each unit, hand the executor — a subagent (Task) where supported, the main loop otherwise — the unit's parameters (tickets and primer content, branch, worktree path, exit axis, resolved gate commands) plus the per-unit procedure: /action:worktree Phases 4–5 (Implement; Gates & commit) and its Iron Rule, read from ../worktree/SKILL.md and quoted to the executor — not paraphrased from memory — with this standing instruction: work inside your assigned worktree only; never run git fetch, git stash, or git worktree subcommands; never touch paths outside your worktree.
3. Contain failures. A unit that cannot reach green exits with a failure note (/action:worktree Phase 5, Gates & commit — red path): it never blocks other units, and its worktree stays in place for inspection.
4. Serialize the exit axis. Remote operations are excluded from subagent scope: after the units report, run each green unit's /action:worktree Phase 6 (Exit axis — push, PR) one unit at a time in the main loop. In sequential degradation, Phase 6 folds into each unit's turn instead — nothing is concurrent there.
5. Serialize teardown decisions. No worktree is removed in this phase; removal is offered in the closing panel and executed in the main loop.

Output contract

1. Hero block (1–4 lines): ✓ N units done, M blocked + execution mode + exit axis.
2. ## Units — one row per unit: ticket(s) → branch → worktree path → created/resumed → commits landed → gate status → exit taken.
3. ## Grouping — the final grouping and its rationale (or "1:1").
4. ## Verification — shared gate commands, per-unit results summarized, the local-vs-CI split, deferred work named.
5. ## Blocked — failed units with the failure verbatim and the worktree path to inspect. Omit when none.
6. End with an AskUserQuestion panel (skip when already in plan mode): push all green units / open PRs for green units / retry blocked units / remove finished worktrees / stop. In a non-interactive run, record the question and options in the report instead of asking, and default to stopping with all worktrees kept.