/worktree-manager

name: worktree-manager
description: Create, list, and tear down git worktrees following Kanopi's branch naming conventions so developers and agents can work multiple tickets in parallel without clobbering each other's working tree. Creates a new branch, or attaches a worktree to a branch that already exists locally or on origin. Handles DDEV isolation automatically (folder-derived project name, no pinned ports) for Drupal and WordPress, and plain worktree setup for Next.js. Invoke when the user wants to start a ticket in a fresh worktree, run more than one Claude Code or Claude Desktop session at once, says "create a worktree", "new worktree for tw1234", "spin up a parallel branch", "work on two tickets at once", "worktree for an existing branch", "check out this branch in a worktree", "pick up a teammate's branch", "resume a branch I already have", "/worktree-manager", or asks how to clean up a finished worktree. Use this skill even if the user only says "I need to work on another ticket without losing my current one."

Worktree Manager

Create and tear down git worktrees that follow Kanopi's branch conventions and stay isolated at the DDEV layer, so multiple tickets — and multiple AI sessions — can run side by side from a single clone.

Why this exists

A worktree checks out a second branch into its own directory while sharing one `.git`. That is the primitive that lets two Claude Code sessions (or one CLI session and one Claude Desktop "code" session) work different tickets at the same time without `git checkout` thrash or stepping on each other's files. It maps one-to-one onto Kanopi's "one branch per ticket" rule.

Usage

• `/worktree-manager create <ticket-id> <short-desc> [--type feature|bug|hotfix|devops] [--base <default-branch>]` — create a worktree on a **new** branch
• `/worktree-manager create --branch <existing-branch> [<ticket-id>] [--dir <path>]` — attach a worktree to a branch that **already exists** (locally or on origin)
• `/worktree-manager list` — show active worktrees and their DDEV status
• `/worktree-manager remove <ticket-id|branch|path> [--delete-branch]` — tear down a worktree (destructive; requires confirmation)

If the user gives a Teamwork URL or task ID, parse the numeric ID from it: `tw1234` and a Teamwork task URL both yield `1234`. Branch names use the bare number.

**Default branch.** Never assume `main` — many Kanopi repos use `master`. Resolve it once and use it wherever this skill says `<default-branch>`:

DEFAULT=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null \
  || git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')

`--branch` is mutually exclusive with `<short-desc>`, `--type`, and `--base` — all three exist only to *derive* a new branch name, and there is nothing to derive when the branch is given. If the user supplies both, use `--branch` and say in the report that the others were ignored.

Naming convention

Branch — Kanopi standard, the bare Teamwork ID with no `tw` prefix:

<type>/<ticketID>-<short-desc>
# feature/1234-hero-block
# bug/1235-menu-fix
# hotfix/1236-login-error
# devops/1237-add-ddev

Types: `feature`, `bug`, `hotfix`, `devops` (infrastructure, tooling, CI/CD, dev environment). `commit-message-generator` reads the `Refs:` footer from this shape, so keep it exact.

For a sub-task or dependent feature, use the **parent** task ID, matching the complex-feature parent/child model.

Worktree directory — a sibling of the main clone, named for the ticket. The directory keeps the `tw` prefix: it becomes the DDEV project name and hostname, where `tw` makes the ticket readable at a glance.

<repo>/                       # main clone, stays on the default branch
<repo>-tw1234/                # worktree for feature/1234-hero-block
<repo>-tw1235/                # worktree for bug/1235-menu-fix

Keep worktrees as siblings (not nested inside the main clone) so build tooling, IDE indexers, and DDEV file mounts don't recurse into them.

Directory name when there is no ticket ID

`--branch` may point at a branch with no ticket ID in it — a colleague's branch, a long-lived `develop`, a branch that predates the convention. Resolve `<worktree-dir>` in this order:

1. `--dir` if the user gave one. 2. `<repo>-tw<id>` if a ticket ID was supplied, or the branch name carries one — `<type>/<digits>-…`, or the older `<type>/tw<digits>-…`:

   ID=$(printf '%s' "$BRANCH" | sed -nE 's@^[a-z]+/(tw)?([0-9]+)-.*@\2@p')

3. Otherwise `<repo>-<branch-slug>`, where the slug lowercases the branch and collapses every run of non-alphanumeric characters to a single `-`:

SLUG=$(printf '%s' "$BRANCH" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | tr -s '-' | sed 's/^-//; s/-$//')
# update/worktree-manager-existing-branch  →  update-worktree-manager-existing-branch
# ../<repo>-update-worktree-manager-existing-branch

Prefer the ticket-ID form whenever one is available: the DDEV project name is folder-derived, so the directory name is what the developer will see in `ddev list` and type into teardown.

Environment Detection

Tier 1 — Portable (Claude Desktop, Codex, any environment)

When `Bash`/git execution is unavailable, output the exact commands for the user to run, then explain how to point their environment at the new directory:

• **Claude Code CLI:** `cd ../<worktree-dir>` then launch a session there.
• **Claude Desktop (code section):** open the worktree directory as the project folder. Run one Desktop project per worktree if working two in parallel.

Tier 2 — Enhanced (Claude Code with Bash/git)

Run the steps directly, pausing at the confirmation gate for destructive actions.

Create workflow

1. **Resolve inputs.**

With `--branch`, that name is `BRANCH` verbatim — do not normalize it, do not add a `<type>/` prefix, do not correct its spelling to match the convention. Otherwise derive `BRANCH=<type>/<id>