Worktree Management Skill

Manage git worktrees for parallel AI agent development.

Context Detection

First, detect which mode you're operating in:

bash
1# Check if we're in a worktree (not the main repo)
2if git rev-parse --is-inside-work-tree &>/dev/null; then
3  BRANCH=$(git branch --show-current)
4  if [[ "$BRANCH" == change/* ]]; then
5    CHANGE_ID="${BRANCH#change/}"
6    echo "Running in worktree: $CHANGE_ID"
7    MODE="worktree"
8  else
9    echo "Running in main repository"
10    MODE="main"
11  fi
12fi

Central Control Commands

Use these from the main repository to manage worktrees.

List Worktrees

bash
1wt-list

List all active worktrees with their change IDs and paths.

To see remote branches available for checkout:

bash
1wt-list --remote

Create New Worktree

bash
1wt-new <change-id>

Creates a new worktree at ../<project>-<change-id>/ with branch change/<change-id>.

If the branch exists on remote, it will be checked out and tracked automatically.

To force create a new branch even if remote exists:

bash
1wt-new <change-id> --new

Open Worktree for Work

bash
1wt-work <change-id>

Opens the worktree in Zed editor with Claude Code. This launches a new agent session in that worktree context.

To open in terminal instead:

bash
1wt-work <change-id> --terminal

Close Worktree

bash
1wt-close <change-id>

Removes the worktree. Interactive mode asks what to do with the branch:

1. Keep branch (can reopen later)
2. Delete local branch only
3. Delete local and remote branch

Non-interactive options:

bash
1wt-close <change-id> --keep-branch      # Keep the branch
2wt-close <change-id> --delete-remote    # Delete both local and remote

Merge Worktree

bash
1wt-merge <change-id>

Merges the worktree branch into the target branch (default: main/master).

Options:

bash
1wt-merge <change-id> --target develop   # Merge to specific branch
2wt-merge <change-id> --no-delete        # Keep branch after merge

Self-Control Commands

Use these from within a worktree to manage your own state.

Push Current Branch

bash
1git push -u origin $(git branch --show-current)

Pushes the current branch to remote and sets up tracking.

Get Current Change ID

bash
1CHANGE_ID=$(git branch --show-current | sed 's|change/||')
2echo "Current change: $CHANGE_ID"

Close Own Worktree

From within a worktree, you cannot directly close it (the directory is in use). Instead:

1. Commit and push your changes
2. Exit the agent session
3. From main repo, run: wt-close <change-id>

Or instruct the user:

To close this worktree after I exit:
  cd <main-repo-path>
  wt-close <change-id>

Merge Own Work

bash
1CHANGE_ID=$(git branch --show-current | sed 's|change/||')
2wt-merge "$CHANGE_ID"

This will merge your current branch to the target and optionally close the worktree.

Workflow Examples

Central Agent: Create and Delegate Work

bash
1# List current work items
2wt-list
3
4# Create new worktree for a task
5wt-new fix-login-bug
6
7# Open agent in that worktree
8wt-work fix-login-bug

Worktree Agent: Complete and Hand Off

bash
1# Check current context
2git branch --show-current  # -> change/fix-login-bug
3
4# Do work...
5# ...
6
7# Push changes
8git push -u origin change/fix-login-bug
9
10# Report back to user that work is ready for merge
11echo "Work complete. To merge: wt-merge fix-login-bug"

Full Lifecycle

bash
1# 1. Central agent creates worktree
2wt-new implement-feature
3
4# 2. Central agent opens worktree for work
5wt-work implement-feature
6
7# 3. Worktree agent does the work, pushes
8git add -A && git commit -m "Implement feature"
9git push -u origin change/implement-feature
10
11# 4. Central agent merges when ready
12wt-merge implement-feature
13
14# 5. Worktree is cleaned up automatically (or use wt-close)

Project Health Audit

Scan Project Health

bash
1wt-audit scan              # Human-readable report
2wt-audit scan --json       # Machine-readable JSON
3wt-audit scan --condensed  # Summary line only

Scans 6 project health dimensions:

• Claude Code Config — permissions, hooks, agents, rules
• Design Documentation — docs/design/*.md coverage
• OpenSpec Config — config.yaml context population
• Code Quality Signals — large files, unused code tooling
• CLAUDE.md Structure — conventions, managed sections
• Gitignore Coverage — sensitive file patterns

Output includes evidence (what exists), delta (✅/⚠️/❌), and guidance (source pointers for what the LLM should READ to create missing content).

Interactive Remediation

Use /wt:audit to scan and interactively address gaps. The skill runs the scan, presents findings, and helps create project-specific content by reading the actual codebase — not templates.

Orchestration Supervisor

Sentinel (Agent Mode)

Use /wt:sentinel to start and supervise a wt-orchestrate run with intelligent monitoring. The agent starts the orchestrator in background, polls state every 15s, and makes decisions on crashes (log diagnosis), checkpoints (auto-approve periodic), and completion (summary report).

bash
1/wt:sentinel                                    # basic supervision
2/wt:sentinel --spec docs/v5.md --max-parallel 3 # with options

Sentinel (Bash Fallback)

For environments without Claude agent access:

bash
1wt-sentinel                                      # basic crash recovery
2wt-sentinel --spec docs/v5.md --max-parallel 3   # with options

See docs/sentinel.md for full documentation.