Worktree

/action:worktree

Take one or more tickets to a working branch in its own git worktree. Resolve the ticket(s) read-only, name the branch the way the team actually names branches, create the worktree beside the repo (or in a temp root), implement, and land gated commits — pushing or opening a PR only when asked.

One worktree, one branch, one deliverable — carrying one ticket by default, and several when they genuinely share a change. Crosscutting is first-class, not an error.

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. To land review findings on the current branch, use /respond:action; this command starts ticket work on a new branch.

/action:worktrees delegates to this file's phases by name and number. When renaming, renumbering, or reordering phases here, update that file's references in the same change; on any disagreement between the two files, this one wins.

Core thesis

A ticket describes an outcome; a branch is the unit of delivery. This command is the plumbing between the two, done the way the tracker and the team already expect: the branch name carries the ticket ID so linking happens server-side, the worktree keeps the main checkout untouched, and the gates keep every commit green.

Three disciplines:

1. Tickets are read-only. Resolution pulls title, description, acceptance criteria, and the branch-name field — and writes nothing back (see The Iron Rule).
2. Names follow the precedence ladder. Explicit ask > project conventions > ticket-system default > observed repo norms > slug fallback — per ../../references/ticket-detection.md.
3. The main checkout is never disturbed. All work happens in the worktree; the default exit is a gated commit, not a push.

The Iron Rule

TICKETS ARE READ-ONLY

Neither resolution nor any later phase writes to a ticket — no assign, no comment, no state transition, no label, no estimate, no gh issue develop; every tracker operation is a read. Linking rides on names, server-side, so an abandoned branch unwinds with nothing to undo. The full forbidden-operations list and rationale: ../../references/ticket-detection.md § The read-only invariant.

Red flags — STOP, you are about to violate the rule: any tracker mutation verb (assign, comment, transition, label, close); gh issue develop; an MCP tool call whose name is not read-shaped.

$ARGUMENTS contract

Non-flag text is the ticket reference(s): IDs (TEA-123, #45), URLs, or free text describing the goal. Several references in one invocation mean one branch carrying all of them (crosscutting). With no references at all, resolve per the detection source ladder in ticket-detection.md (conversation context before lookups) and ask rather than invent.

Two axes: placement is --local xor --temp; exit escalates (commit only → --push → --pr). --setup-only short-circuits the exit axis — combining it with --push or --pr is a contradiction: ask, don't pick. Full path derivations for both placements are in ticket-detection.md § Worktree placement & path sanitization; when that reference cannot be read at runtime, derive from the summaries in this file and name the gap in the report.

Phase 0: Situational awareness

1. Read AGENTS.md / CLAUDE.md / .github/CONTRIBUTING.md for quality checks, commit format, and any branch-naming conventions (these feed rung 2 of the ladder).
2. Resolve the five gate buckets and the CI-coverage split per ../../references/verification-gates.md.
3. Inventory ticket tooling: tracker MCP tools, the gh CLI. Detect the trunk branch and remotes (git remote -v, git symbolic-ref refs/remotes/origin/HEAD).
4. Record main-checkout state (git status -sb). A dirty main tree is not a blocker — the worktree isolates the work — but note it, and never stash or otherwise touch the user's uncommitted work.

Phase 1: Ticket resolution

Per ../../references/ticket-detection.md:

1. Identify the tracker and ticket(s) via the detection source ladder.
2. Fetch each ticket read-only: title, description, acceptance criteria, and (Linear) the gitBranchName field.
3. Resolve the branch name via the precedence ladder. Record which rung produced it and any observed-norms adjustment applied.
4. Multi-ticket: the ladder skips the ticket-system rung — propose a theme slug for the plan gate to confirm.
5. Derive the worktree path from the placement axis.

A reference that resolves to nothing (ID matches no issue, URL 404s) halts with a question — never guess a ticket's content.

Phase 2: Orchestration plan

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

1. Ticket(s): ID, title, source (prompt / conversation / lookup), one line each; for multi-ticket, why they share a branch.
2. The branch name and the ladder rung that produced it, naming any observed-norms adjustment; the theme slug, for confirmation, when multi-ticket.
3. The worktree path, placement axis, start point, and the idempotency prediction — fresh / resume / attach / collision — probed read-only (git worktree list --porcelain, branch existence) ahead of Phase 3.
4. The implementation shape: acceptance criteria restated as the definition of done, files expected to change, planned commit subject(s) in the project's format.
5. Discovered gate commands and the local-vs-CI split.
6. The exit axis in effect: commit only / --push / --pr / --setup-only.

Wait for approval, then exit plan mode. If plan mode is unavailable, present the same plan inline and proceed on confirmation. In a non-interactive run (CI, subagent — including /action:worktrees fan-out, which holds its own plan gate), record the plan in the report and proceed.

Phase 3: Worktree & branch

Start point: the remote trunk head — git fetch origin, then origin/<trunk> — falling back to the local trunk, then HEAD; the plan states which.

Resolve idempotently, first match wins — collision checks come before any attach or create:

1. Branch already checked out in a worktree — git worktree list --porcelain names its path (which may differ from the computed target; honor the existing one). Resume: inspect its state (git -C <path> status --short, commits ahead of the start point) and continue from the first incomplete phase — uncommitted changes → resume Phase 4; green commits present → continue to Phase 6; primer only → start Phase 4 (or report no-op under --setup-only). Report "resumed", not "created".
2. Directory collision — the computed path exists on disk but is not a worktree of this branch (unregistered directory, or registered to a different branch) — halt with AskUserQuestion: pick another path, let the user clear it, or abort. Never delete or overwrite a directory this command did not create.
3. Branch exists, no worktree — attach one:

git worktree add <path> <branch>

4. Fresh — create both:

git worktree add -b <branch> <path> <start-point>

Then assemble the ticket primer — per ticket: ID, title, description, acceptance criteria, link. The primer lives in this command's report (## Primer), not in files inside the worktree: an untracked primer file would haunt git status and risk riding into a commit. With --setup-only, skip ahead to the output contract now.

Phase 4: Implement

Inside the worktree only:

1. Work the acceptance criteria in the project's idiom.
2. Verify with the cheapest signal that moves you forward — the one test file or smoke command exercising the change. Full passes wait for Phase 5.
3. Stay in ticket scope. Adjacent problems go in the report's "observed, not addressed" list, not in the diff.
4. Multi-ticket: keep each ticket's work separable — every commit in Phase 5 must be attributable to its ticket ID(s).

Phase 5: Gates & commit

1. Run the fast local buckets exactly as discovered — format, lint, typecheck, scoped test; build only when plausibly affected — per verification-gates.md right-sizing. Gates run as discovered, including mutating ones (--fix-style): fold autofixes into the commit under test and re-run the scoped test once when a gate changed files.
2. Green → commit in the project's format. Each commit body names the ticket ID(s) it advances (exact form per project conventions; closing keywords are reserved for the PR body — see ticket-detection.md § Server-side linking). Multi-ticket branches land one commit per separable unit of work where practical.
3. Red → fix and re-run. A gate that cannot be brought green stops the exit axis before any push/PR; report the failure verbatim in ## Verification.

Phase 6: Exit axis

• Default — stop after the gated commit(s). No push; the branch and worktree stay local for the user.
• --push — publish with an upstream:

git push -u origin <branch>

• --pr — push as above, then open the PR with the tickets linked per ticket-detection.md § Server-side linking: GitHub closing keywords (Fixes #123) in the body; Linear IDs already in the branch name and repeated in the PR title for auto-attach:

gh pr create --title "<title>" --body "<body linking the tickets>"

On non-GitHub forges use the forge's CLI equivalent when present; otherwise report the prepared title and body for manual creation. After opening, offer gh pr checks --watch when CI is observable.

Output contract

1. Hero block (1–4 lines): ✓ <branch> ready — N commit(s), <exit> or ⚠ blocked at <phase>, plus ticket ID(s) and worktree path.
2. ## Tickets — one row per ticket: ID, title, tracker, source; note that nothing was written back.
3. ## Worktree — path, branch, start point, created vs resumed.
4. ## Primer — only with --setup-only: the ticket context (title, description, acceptance criteria, link), ready to hand to the next session.
5. ## Commits — one row per commit: SHA, subject, ticket ID(s), gate result. Omitted with --setup-only.
6. ## Verification — gate commands run and results; the local-vs-CI split; deferred work named; the watch command when observable.
7. End with an AskUserQuestion panel (skip when already in plan mode): push now / open a PR / keep it local / remove the worktree. In a non-interactive run, record the question and options in the report instead of asking, and default to keeping the branch local.