worktree

name	worktree
description	Create, list, and tear down per-issue git worktrees, each with an isolated Neon database branch and a portless dev URL, so multiple issues can be worked in parallel without DB or dev-server collisions. Use when the user says "spin up / create a worktree for issue N", "clean up the worktree", "list worktrees", invokes /worktree, or wants parallel isolated dev environments per GitHub issue.
model	sonnet
effort	low

Worktree

Manage the lifecycle of per-issue git worktrees. All state-changing logic lives in the bundled worktree.sh; this skill only routes the subcommand, opens the editor, and summarizes the result. Do not improvise around the script — it is the deterministic, idempotent contract.

Quick start

/worktree create 142          # provision + open a worktree for issue #142
/worktree list                # show all worktrees
/worktree cleanup 142         # tear down (guards against unsaved work)
/worktree cleanup --merged    # sweep all merged/closed worktrees

How it works

A worktree lives at .worktrees/<issue#>-<slug>. The directory name is a DNS-safe label, so it doubles as the portless hostname prefix (<issue#>-<slug>.rekurve.localhost) and the Neon branch name (local/<issue#>-<slug>). The Neon branch is provisioned by the post-checkout hook on create and reaped by teardown.yml on branch delete — this skill never touches the Neon API itself.

Workflow

1. Parse the argument string into <subcommand> <args>. If empty or unknown, run bash .claude/skills/worktree/worktree.sh --help and stop.
2. Run the script, streaming its output: bash .claude/skills/worktree/worktree.sh <subcommand> <args>
3. On create success only: open the editor window with code <WORKTREE_DIR> (read WORKTREE_DIR= from the script's output).
4. Summarize for the user: branch, worktree path, DEV_URL, Neon branch (local/<branch>), and the next step: cd <WORKTREE_DIR> && claude (then make start for the dev server).
5. On any failure, surface the script's error verbatim and stop. No auto-retry, no calling the Neon API by hand, no force-removing on your own initiative.

No handoff doc or issue primer is written — the developer pulls issue context themselves once claude is running in the worktree.

Guardrails

• create requires .env in the main worktree (make env_pull if missing) and must run from the repo root, not a linked worktree. The script enforces both.
• cleanup refuses to remove a worktree with uncommitted changes or unpushed commits. Only pass --force if the user explicitly confirms the work is disposable.
• A never-pushed branch never triggers teardown.yml, so its Neon branch can orphan. If that matters, push the branch first or run scripts/neon-branch.sh delete --all periodically.
• Per CLAUDE.md, never run make/yarn verification here — that flows through @agent-codebase-verification.

Verifying changes to this skill

The mutating paths touch real Neon branches (never mocked). To verify:

• Automated: worktree.sh create <N> --dry-run must print the resolved branch (<N>-<slug>), worktree dir, Neon branch, and dev URL with no mutation. Run shellcheck worktree.sh if available.
• Manual smoke: create a throwaway issue → confirm worktree, .env, Neon branch, dev URL, and code window → list shows it → cleanup blocks on a dirty file → cleanup --force removes it → teardown.yml reaps the Neon branch on delete.
• Idempotency: run create <N> twice; the second run must reuse, not duplicate or error.