AgentSkillsCN

git-worktree-setup

为并行功能开发创建隔离的 Git 工作树。当用户希望“并行”“在侧边”“单独”“不影响当前工作”或“在新分支中”实现、构建或开发某项功能时，可使用此技能。此外，当用户提到“并行”开发某项功能或某个任务时，也应优先使用此技能。

SKILL.md
--- frontmatter
name: git-worktree-setup
description: Create isolated git worktrees for parallel feature development. Use when the user asks to implement, build, or work on a feature "in parallel", "on the side", "separately", "without affecting current work", or "in a new branch". Also triggers on "start a new ticket", "create a worktree", "set up isolated development", or working on multiple things simultaneously. If the user says "in parallel" about any feature or ticket, ALWAYS use this skill.

Git Worktree Setup

When the user asks to work on something in parallel or separately, always create a git worktree. This ensures the new work is fully isolated in its own directory and Cursor window, without affecting any in-progress work.

Worktree location

All worktrees live in ../worktrees/ relative to the repository root.

Workflow

1. Choose branch prefix

Every branch must use one of these prefixes:

PrefixUse when
featureNew functionality, new screens, new flows. Default when unclear.
bugfixFixing a bug, crash, or incorrect behaviour.
qolQuality of life: UI polish, small improvements, refactors, DX.

Derive from the user's request (e.g. "fix the PDF crash" → bugfix, "tweak the invoice list" → qol).

2. Determine ticket context

  • •Ticket number provided (e.g. "ticket 1234", "AB#1087"): use it. The branch name will include the ticket (e.g. feature/AB-1234-facturen-export).
  • •No ticket, just a description: use --no-ticket. Branch has no ticket number (e.g. feature/login-page-redesign).
  • •Ambiguous: ask if they want to link an ADO ticket, or proceed with --no-ticket.

3. Run the setup script

Execute from the repository root. First argument is always the prefix (feature, bugfix, or qol).

With a ticket number (branch includes ticket):

bash
bash scripts/worktree/new-worktree.sh <prefix> <ticket-number> <short-description>

Examples:

  • •bash scripts/worktree/new-worktree.sh feature 1234 facturen-export → feature/AB-1234-facturen-export
  • •bash scripts/worktree/new-worktree.sh bugfix 5678 pdf-crash-fix → bugfix/AB-5678-pdf-crash-fix
  • •bash scripts/worktree/new-worktree.sh qol 1087 ui-tweaks → qol/AB-1087-ui-tweaks

Without a ticket number:

bash
bash scripts/worktree/new-worktree.sh <prefix> --no-ticket <short-description>

Examples:

  • •bash scripts/worktree/new-worktree.sh feature --no-ticket login-page-redesign → feature/login-page-redesign
  • •bash scripts/worktree/new-worktree.sh bugfix --no-ticket pdf-crash → bugfix/pdf-crash

Short description: lowercase, kebab-case, 2–4 words. Examples: facturen-export, login-page-redesign, pdf-crash-fix.

The script will:

  1. •Fetch latest from remote (git fetch origin)
  2. •Resolve the latest origin/develop SHA and verify no stale local branch exists
  3. •Create a new branch starting from the latest origin/develop — always a fresh checkout, never a local or outdated develop
  4. •Copy .env into the worktree
  5. •Run npm install
  6. •Run npx prisma generate (if prisma/schema.prisma exists)
  7. •Open the worktree in a new Cursor window via the cursor CLI

4. Confirm to the user

Report:

  • •The worktree path
  • •The branch name (with prefix: feature/, bugfix/, or qol/; with ticket number when one was used)
  • •That a new Cursor window has been opened
  • •Remind them they can start working in the new window

5. (Optional) Set ADO ticket to Active

Only if a ticket number was provided or resolved. Use user-ado MCP:

code
wit_update_work_item(id, updates: [{ op: "add", path: "/fields/System.State", value: "Active" }])

Listing existing worktrees

bash
git worktree list

Important notes

  • •Never check out the same branch in two worktrees.
  • •Each worktree has its own node_modules and .env — they are not shared.
  • •The .cursor/ directory (rules, skills, agents) is part of the repo and available in every worktree automatically.
  • •If the worktree directory already exists, the script will abort — remove the old one first or choose a different name.