--- 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 [--type feature|bug|hotfix] [--base main]` — create a worktree on a **new** branch - `/worktree-manager create --branch [] [--dir ]` — 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 [--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 (e.g. `tw1234`). `--branch` is mutually exclusive with ``, `--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 (unchanged from Kanopi standards): ``` /tw- # feature/tw1234-hero-block # bug/tw1235-menu-fix # hotfix/tw1236-login-error ``` 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 to mirror the branch: ``` / # main clone, stays on main -tw1234/ # worktree for feature/tw1234-hero-block -tw1235/ # worktree for bug/tw1235-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 `` in this order: 1. `--dir` if the user gave one. 2. `-tw` if a ticket ID was supplied *or* the branch name contains `tw`. 3. Otherwise `-`, where the slug lowercases the branch and collapses every run of non-alphanumeric characters to a single `-`: ```bash 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 # ../-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 ../` 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 `/` prefix, do not correct its spelling to match the convention. Otherwise derive `BRANCH=/tw-` from the ticket ID, short description (kebab-case, ≤4 words), and type (default `feature`), branching from `--base` (default `main`). Then resolve `` per **Directory name when there is no ticket ID** above. 2. **Sync** so a new branch starts current and a remote-only branch is visible locally: ```bash git fetch origin ``` 3. **Determine whether the branch already exists.** Check — do not infer from whether the user passed `--branch`. A user can name an existing branch without the flag, and `--branch` pointed at a typo should fail loudly rather than silently create a branch under a misspelled name: ```bash if git show-ref --verify --quiet "refs/heads/$BRANCH"; then echo local elif git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then echo remote-only else echo new fi ``` If the user passed `--branch` and the result is `new`, **stop**. Do not create the branch, do not fall back to the new-branch form, and do not proceed to step 4. `--branch` means "attach to what exists"; a missing branch is almost always a typo or a missing fetch, and creating it silently produces an empty branch off the wrong base. Report it in exactly this form, then offer the new-branch command as the fix and wait: ``` BRANCH NOT FOUND: ``` This holds no matter how confident the user is that the branch exists. Their certainty is not a substitute for `show-ref`, and "make it work" is not authorization to create a different thing than the one they named. 4. **Check whether the branch is already checked out somewhere.** Git refuses to check out one branch in two worktrees, and the raw error is opaque. Look first: ```bash git worktree list --porcelain \ | awk -v b="refs/heads/$BRANCH" '$1=="worktree"{p=$2} $1=="branch"&&$2==b{print p}' ``` If that prints a path, **do not create a second worktree**. Report the existing path — the branch is already available there, which is usually the whole answer. The main clone counts: if it is sitting on the requested branch, that is the hit. Only if the user explicitly wants a duplicate checkout is `--force` appropriate, and it should be their call, not the default. 5. **Create the worktree**, using the form that matches step 3: **New branch** (the common case) — branch off the up-to-date remote base: ```bash git worktree add ../ -b "$BRANCH" origin/ ``` **Existing local branch** — omit `-b` so git checks the branch out instead of trying to recreate it: ```bash git worktree add ../ "$BRANCH" ``` **Existing remote-only branch** — the same form works: git's DWIM creates a local branch tracking the remote when the name matches exactly one remote, which the fetch in step 2 guarantees is current. Be explicit if you'd rather not rely on DWIM: ```bash git worktree add ../ -b "$BRANCH" --track "origin/$BRANCH" ``` Do **not** write `git worktree add ../ "origin/$BRANCH"` — that checks out the remote-tracking ref and leaves the worktree in **detached HEAD**, where commits belong to no branch and a later `git worktree remove` discards them without warning. 6. **Report freshness on an existing branch** (skip for a new branch — it was just cut from a fetched base): ```bash git -C ../ status -sb | head -1 # ## branch...origin/branch [behind 3] ``` State the ahead/behind counts. If the branch is behind, **offer** the fast-forward rather than running it: ```bash git -C ../ merge --ff-only "origin/$BRANCH" ``` Never silently `pull` or `rebase` a branch the user did not create in this session — local-only commits and in-progress work are exactly what an existing branch tends to carry. 7. **Run platform setup** — see Platform Notes below. 8. **Report** the directory path, branch name, whether the branch was created or attached, freshness if attached, any flags ignored, and (for DDEV projects) the local URL from `ddev describe`, plus the Tier 1 instructions for attaching a CLI or Desktop session. ## Platform Notes ### Drupal & WordPress (DDEV) DDEV isolation is automatic when the project name is folder-derived — i.e. `name:` is omitted from `.ddev/config.yaml`, so DDEV uses the directory name. Each worktree then gets its own hostname, database, and auto-assigned host ports, and the shared router keeps them from colliding. This is DDEV's documented recommendation for worktrees. If a project still commits a `name:` (or pins host ports), the second worktree will collide when it runs `ddev start`. Don't try to fix that repo-wide as part of this skill — surface the collision clearly and let the developer resolve it in their own config when they hit it. The quick local fix is a gitignored `config.local.yaml` in the worktree with a unique `name:`; the cleaner long-term fix is dropping the committed `name:` line on that project, but that's the team's call, not this skill's. Setup inside the new worktree: ```bash cd ../ ddev start ddev composer install ddev theme-install # WP/Drupal theme deps + build ddev db-refresh # each worktree gets its own DB ``` > Cost note: a worktree starts with an empty database, so it needs its own `ddev db-refresh` (or an imported snapshot). `vendor/` and `node_modules/` are directory-local, so they install per worktree — isolation by design, at the cost of disk + setup time. On push, CircleCI spins up a per-branch Pantheon multidev, so each worktree's branch also gets its own remote preview without extra steps. ### Next.js (headless/decoupled) No DDEV. Create the worktree, then install and run the dev server on a distinct port: ```bash cd ../ npm install npm run dev -- -p 3001 # use a different port per parallel worktree ``` If platform is ambiguous (no `.ddev/`, no `next.config.*`), ask which platform is in scope before running setup. ## Remove workflow (destructive — confirm first) The target may be a ticket ID, a branch name, or a directory path. Resolve it to one worktree before doing anything else, and stop if it matches none or more than one: ```bash git worktree list --porcelain # match on the worktree path or its branch line ``` **Confirmation gate.** Your response **must start immediately** with the removal header — no preamble, no "I'll go ahead and". List exactly what will be deleted and wait for explicit approval: ``` === WORKTREE REMOVAL READY FOR APPROVAL === Worktree: ../ Branch: (merged into main: yes/no) DDEV project: (database will be deleted) Local branch: KEEP / DELETE Uncommitted: file(s) (list them, or "clean") ``` Then run the steps in this order: 1. **Verify the branch is merged** (or the user confirms abandoning it): ```bash git branch --merged main --format='%(refname:short)' | grep -Fx "$BRANCH" ``` Use `--format`, not bare `git branch --merged` — the plain output pads names with two spaces and marks the current branch with `* `, so a naive `grep` on the branch name misses it. 2. **Tear down DDEV** for that project (snapshot kept by default for safety): ```bash ddev delete -Oy # omit -O to keep a recovery snapshot ``` Do this before removing the directory — the project name is folder-derived, so it is harder to resolve once the folder is gone. 3. **Remove the worktree and prune:** ```bash git worktree remove ../ git worktree prune ``` 4. **Delete the local branch — only if the user opted in.** Default to `KEEP`. Delete only when the user passed `--delete-branch` or approved a gate that said `DELETE`: ```bash git branch -d "$BRANCH" ``` Use `-D` only with explicit confirmation — it discards unmerged work. **Default to `KEEP` for any branch this worktree did not create.** Removing a worktree is a statement about a directory; deleting a branch is a statement about the work. For a branch that already existed — a teammate's, a shared long-lived one, one with an open PR — those come apart, and a branch deleted on the developer's behalf is the one loss in this workflow that a re-run cannot undo. ## Quality Gates Before reporting a create as complete: 1. ✅ Worktree directory exists and is on the expected branch (`git -C ../ branch --show-current`) — and is **not** in detached HEAD 2. ✅ **New branch:** `git fetch origin` ran, and the branch was cut from `origin/` 3. ✅ **Existing branch:** the branch resolved (local or remote-only, never silently created), was not already checked out in another worktree, has a local tracking branch rather than a detached HEAD, and its ahead/behind state was reported — along with any `--type` / `--base` / `` that were ignored 4. ✅ For DDEV projects: the site responds (`ddev describe`) Before a remove: 1. ✅ Target resolved to exactly one worktree 2. ✅ User explicitly approved the deletion, after seeing the removal header 3. ✅ Branch is merged, or user confirmed abandoning unmerged work 4. ✅ DDEV project torn down before the directory is removed 5. ✅ The local branch was deleted only on explicit opt-in ## Notes - Never create a worktree inside the main clone's working tree. - Don't reuse a ticket ID across two live worktrees. - Never leave a worktree in detached HEAD — commits made there are unreachable once the worktree is removed. - This skill changes local state only; it never force-pushes or deletes remote branches. ## Red flags (self-talk — stop if you catch yourself thinking these) - "The branch probably exists, I'll just omit `-b`" (CANT-14) — check with `show-ref` first; guessing wrong produces either an opaque error or a branch created under a typo. - "They said the branch exists but it doesn't — I'll create it so the command succeeds" (CANT-24). A `--branch` that doesn't resolve is a stop, not a fallback; creating it redefines the task as whatever was achievable. - "`origin/` is close enough" — it is a detached HEAD, and the difference only surfaces after the developer has committed into it. - "It's behind origin, I'll just pull to be helpful" — an existing branch is the case most likely to carry local-only work. - "They're removing the worktree, so they obviously want the branch gone too" (CANT-1). Two different decisions; the second one needs its own approval.