Smart Worktree Management

You are managing git worktrees for the USOPC Athlete Support Agent monorepo. The argument is: $ARGUMENTS.

Parse the argument to determine the subcommand:

• create <issue-number> — Create a new worktree for an issue
• list — List active worktrees with status
• cleanup — Remove worktrees whose branches have been merged

If no subcommand is provided or the argument is empty, print the usage:

Usage: /worktree <command> [args]
  create <issue-number>  — Create worktree for a GitHub issue
  list                   — List active worktrees with branch status
  cleanup                — Remove merged worktrees and prune refs

Subcommand: create <issue-number>

Step 1: Validate the issue exists

Run gh issue view <issue-number> --json number,title,state to confirm the issue exists and is open. If the issue doesn't exist or is closed, warn the user and stop.

Step 2: Determine paths

• Get the main repo root: git rev-parse --show-toplevel (if in a worktree, use git worktree list to find the main repo)
• Worktree path: ../usopc-issue-<number> relative to the main repo (i.e., a sibling directory)
• Derive a short branch name from the issue title: feat/<kebab-case-summary> (max 50 chars, lowercase, hyphens only)

Step 3: Fetch latest main

Run git fetch origin main to ensure we branch from the latest main.

Step 4: Create the worktree

bash
1git worktree add <worktree-path> -b <branch-name> origin/main

If the worktree path already exists, warn and stop.

Step 5: Install dependencies

bash
1cd <worktree-path> && pnpm install

Step 6: Print summary

Worktree created:
  Path:   <worktree-path>
  Branch: <branch-name>
  Issue:  #<number> — <title>

Dependencies installed.
Navigate with: cd <worktree-path>

Subcommand: list

Step 1: List worktrees

Run git worktree list and parse the output.

Step 2: For each worktree (excluding bare/main)

• Show the path, branch name
• Run git -C <path> log --oneline -1 for latest commit
• Run git -C <path> rev-list --left-right --count origin/main...<branch> for ahead/behind status

Step 3: Print formatted table

Active worktrees:
  ../usopc-issue-42  feat/add-auth        +3 / -0  (latest: abc1234 Add auth middleware)
  ../usopc-issue-55  fix/query-perf       +1 / -2  (latest: def5678 Fix slow query)

Subcommand: cleanup

Step 1: List worktrees

Run git worktree list and identify non-main worktrees.

Step 2: Check each branch

For each worktree branch, check if it has been merged into origin/main:

bash
1git branch --merged origin/main | grep <branch-name>

Step 3: Remove merged worktrees

For each merged worktree, remove it:

bash
1git worktree remove <path>

Print which worktrees were removed.

Step 4: Prune and clean up

bash
1git worktree prune
2git fetch --prune origin

Step 5: Print summary

Cleaned up:
  Removed: ../usopc-issue-42 (feat/add-auth — merged)
  Removed: ../usopc-issue-55 (fix/query-perf — merged)
  Pruned stale worktree references.

If no worktrees were eligible for cleanup, say so.

Important notes

• Always use absolute paths when running git commands to avoid confusion between worktree and main repo.
• The main repo root can be found via git worktree list — it's the first entry (the one without [branch] or with [main]).
• scripts/update-hours.mjs and scripts/stamp-readme-hours.mjs are tracked in git, so they'll be available in worktrees automatically — no copying needed.