worktree

name	worktree
description	Orchestrates implementation work in Git worktrees for isolated, parallel coding. Use when working on tickets, features, or any task that should be isolated from the main branch. Especially useful for ticket work.
user-invocable	true
argument-hint	[task slug | ticket id]

Git Worktree Workflow

Use this workflow to isolate implementation work in a dedicated Git worktree and keep the main branch clean.

Outputs

• Dedicated worktree path and feature branch
• Completed implementation with validation evidence
• Merged branch (when requested) and cleanup
• Summary: what shipped, validation results, open issues

Step 1: Pre-flight Safety

1. Confirm the current repo root and run git status --porcelain
2. If there are unrelated local changes, stop and ask before proceeding
3. Read CLAUDE.md before coding

Step 2: Sync Base Branch

1. git fetch origin --prune
2. git checkout main (or master)
3. git pull --ff-only origin main

If fast-forward fails, stop and resolve with the user.

Step 3: Create Isolated Worktree

1. Derive a sanitized slug (lowercase, hyphenated)
2. Branch name: <slug>-branch
3. Worktree root: ../worktrees/ (create if needed)
4. Worktree path: ../worktrees/wt-<slug>
5. Create: git worktree add -b <branch> ../worktrees/wt-<slug> main
6. Copy env files: cp -n .env.local ../worktrees/wt-<slug>/ || true
7. Install deps in worktree: pnpm install --frozen-lockfile

Always print the full absolute path so the user can copy it directly.

Step 4: Execute Task

1. Implement only the requested scope
2. If doing ticket work, keep ticket checkboxes and evidence updated
3. For substantial commits, run /code-review before finalizing

Step 5: Validate

Run appropriate checks:

• pnpm test
• pnpm run lint
• pnpm run build (for build-affecting changes)

Capture failures with clear next actions.

Step 6: Commit, Merge, and Cleanup

1. Commit with a clear message
2. Merge strategy is user-directed:
   • Local merge: checkout main, fast-forward/merge, push
   • PR flow: push branch and provide PR details
3. Cleanup:
   • git worktree remove ../worktrees/wt-<slug>
   • git branch -d <branch>

Output Format

• Worktree: <absolute path>
• Branch: <branch>
• Status: in progress | completed | blocked
• Validation: pass/fail per command
• Merge state: merged / PR pending
• Issues: bullet list