Files

feat: add parallel issue implementation capability with worktrees

Add complete capability set for orchestrating parallel issue implementation
with automated review cycles using git worktrees.

Components:
- worktrees skill: Git worktree patterns + bundled scripts for reliable operations
- spawn-issues skill: Event-driven orchestrator (Haiku) for parallel workflow
- issue-worker agent: Implements issues autonomously (Sonnet)
- code-reviewer agent: Reviews PRs with quality checks (Haiku, read-only)
- pr-fixer agent: Addresses review feedback automatically (Haiku)

Workflow: /spawn-issues creates worktrees → spawns workers → reviews PRs →
fixes feedback → iterates until approved → cleans up worktrees

Scripts handle error-prone worktree operations. Orchestrator uses event-driven
approach with task notifications for efficient parallel execution.

Co-Authored-By: Claude Code <noreply@anthropic.com>

2026-01-12 15:51:10 +01:00

5.4 KiB

Raw Blame History

name, description, user-invocable

name	description	user-invocable
worktrees	Git worktree patterns for parallel development workflows. Use when managing multiple concurrent branches, implementing issues in parallel, or isolating work contexts.	false

Git Worktrees

Patterns and scripts for managing git worktrees in parallel development workflows.

What are Worktrees?

Git worktrees allow multiple working directories from a single repository. Each worktree can have a different branch checked out, enabling true parallel development.

Use cases:

Implementing multiple issues simultaneously
Isolated review environments for PRs
Switching contexts without stashing

Naming Conventions

Directory structure:

project/
├── .git/                    # Main repo
├── src/                     # Main working tree
└── ../worktrees/            # Sibling worktrees directory
    ├── project-issue-42/    # Issue implementation
    ├── project-issue-43/    # Another issue
    └── project-review-55/   # PR review

Naming patterns:

Issue work: ${REPO_NAME}-issue-${ISSUE_NUMBER}
PR review: ${REPO_NAME}-review-${PR_NUMBER}
Feature work: ${REPO_NAME}-feature-${FEATURE_NAME}

Why sibling directory:

Keeps main repo clean
Easy to identify worktrees
Simple bulk operations
Works with tooling that scans parent directories

Creating Worktrees

For Issue Implementation

REPO_PATH=$(pwd)
REPO_NAME=$(basename "$REPO_PATH")
WORKTREES_DIR="${REPO_PATH}/../worktrees"
ISSUE_NUMBER=42

# Create worktrees directory
mkdir -p "$WORKTREES_DIR"

# Fetch latest
git fetch origin

# Get issue title for branch name
ISSUE_TITLE=$(tea issues $ISSUE_NUMBER | grep -i "title" | head -1 | cut -d: -f2- | xargs)
BRANCH_NAME="issue-${ISSUE_NUMBER}-$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-' | cut -c1-50)"

# Create worktree with new branch from main
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-${ISSUE_NUMBER}" \
  -b "$BRANCH_NAME" origin/main

For PR Review

# For reviewing existing PR branch
PR_NUMBER=55
BRANCH_NAME="issue-42-feature-name"  # Get from PR details

git fetch origin
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-${PR_NUMBER}" \
  "origin/${BRANCH_NAME}"

Bundled Scripts

Use bundled scripts for error-prone operations:

Create Worktree

# Usage: ./scripts/create-worktree.sh issue <issue-number>
# Usage: ./scripts/create-worktree.sh review <pr-number> <branch-name>

./scripts/create-worktree.sh issue 42
./scripts/create-worktree.sh review 55 issue-42-feature-name

Returns worktree path on success.

List Worktrees

./scripts/list-worktrees.sh

Shows all active worktrees with their branches.

Cleanup Worktrees

# Remove specific worktree
./scripts/cleanup-worktrees.sh "${WORKTREES_DIR}/${REPO_NAME}-issue-42"

# Remove all worktrees in directory
./scripts/cleanup-worktrees.sh "${WORKTREES_DIR}"

# Force remove even if dirty
./scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"

Patterns

Pattern: Parallel Issue Implementation

Orchestrator creates all worktrees upfront:

for issue in 42 43 44; do
  worktree_path=$(./scripts/create-worktree.sh issue $issue)
  # Spawn worker with worktree_path
done

Worker uses provided worktree:

cd "$WORKTREE_PATH"  # Provided by orchestrator
# Do work
git add -A && git commit -m "..."
git push -u origin $(git branch --show-current)

Orchestrator cleans up after all complete:

./scripts/cleanup-worktrees.sh "${WORKTREES_DIR}"

Pattern: Review in Isolation

Create review worktree:

worktree_path=$(./scripts/create-worktree.sh review $PR_NUMBER $BRANCH_NAME)
cd "$worktree_path"
git diff origin/main...HEAD  # Review changes

Pattern: Error Recovery

List stale worktrees:

./scripts/list-worktrees.sh

Force cleanup:

./scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"

Best Practices

Always provide worktree paths to agents:

Orchestrator creates worktrees
Agents receive path as parameter
Agents work in provided path
Orchestrator handles cleanup

Never nest cleanup:

Only orchestrator cleans up
Agents never remove their own worktree
Cleanup happens after all work complete

Track worktree paths:

# In orchestrator
declare -A worktrees
worktrees[42]=$(./scripts/create-worktree.sh issue 42)
worktrees[43]=$(./scripts/create-worktree.sh issue 43)

# Pass to agents
spawn_agent --worktree="${worktrees[42]}"

Handle errors gracefully:

Use scripts (they handle errors)
Always cleanup, even on failure
Force-remove if necessary

Common Issues

Worktree already exists:

# Remove old worktree first
./scripts/cleanup-worktrees.sh "${WORKTREES_DIR}/${REPO_NAME}-issue-42"

# Then create new one
./scripts/create-worktree.sh issue 42

Branch already exists:

# Delete branch if safe
git branch -d issue-42-old-name

# Or force delete
git branch -D issue-42-old-name

Stale worktrees after crash:

# List and force remove
./scripts/list-worktrees.sh
./scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"

Tips

Keep worktrees short-lived (hours, not days)
Clean up regularly to avoid clutter
Use scripts for reliability
Let orchestrator manage lifecycle
Check git worktree list if unsure about state

5.4 KiB Raw Blame History