agentsclimarketplace

Git worktree workflow

Skill ivankristianto/k2-dev/skills/git-worktree-workflow

This skill should be used when the user asks to "create a worktree", "manage git worktrees", "work on multiple branches simultaneously", "isolate task work", "use bd worktree", or needs guidance on git worktree patterns for task isolation in k2-dev workflows.From its SKILL.md

Install
npx -y skills add ivankristianto/k2-dev --skill git-worktree-workflow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

8.1 KB, as published. Nobody here has run it

Git Worktree Workflow Skill

Overview

Git worktrees enable working on multiple branches simultaneously by creating separate working directories. In k2-dev, each task gets its own worktree for complete isolation.

Key Benefits: Work on multiple tasks without branch switching, complete isolation prevents conflicts, clean separation of concerns, easy context switching, safe cleanup without losing work.

Reference: See k2-dev-reference.md#git-worktree-basics for core git worktree concepts and commands.

K2-Dev Worktree Pattern

For each task:

  1. Create worktree: ../beads-{id}/
  2. Branch: feature/beads-{id}
  3. Work in isolation
  4. PR and merge
  5. Remove worktree

Creating Worktrees

Using bd worktree (Recommended)

Beads provides integrated worktree management:

bd worktree create beads-123

This creates:

  • Directory: ../beads-123/
  • Branch: feature/beads-123
  • Links to main repository
  • Updates beads context

Location: Worktrees created at ../beads-{id}/ (sibling to main repo) for easy organization and management.

Using Git Directly (Manual Control)

# Create worktree with new branch
git worktree add ../beads-123 -b feature/beads-123

# Create from existing branch
git worktree add ../beads-123 feature/beads-123

Reference: See k2-dev-reference.md#git-worktree-basics for complete git worktree commands.

Multiple Tickets in One Worktree

When /k2:start receives multiple tickets:

# Use first ticket ID for worktree name
bd worktree create beads-123

# Work on beads-123, beads-234, beads-345 in same worktree
# All changes go to feature/beads-123 branch

Working in Worktrees

Switching Context

# Navigate to worktree
cd ../beads-123

# Verify location
pwd
git branch --show-current

# Check status
git status

Making Changes

Work normally in worktree:

# Edit files
vi src/auth/middleware.ts

# Stage and commit
git add src/auth/middleware.ts
git commit -m "Add JWT middleware"

# Push to remote
git push -u origin feature/beads-123

Returning to Main Repo

cd -  # Or use absolute path
cd ~/projects/my-project

Managing Worktrees

Listing Worktrees

# Using bd worktree
bd worktree list

# Using git directly
git worktree list

Output example:

/Users/dev/project           abc1234 [main]
/Users/dev/beads-123         def5678 [feature/beads-123]
/Users/dev/beads-456         ghi9012 [feature/beads-456]

Removing Worktrees

After PR is merged:

# Using bd worktree (recommended)
bd worktree remove beads-123

# Using git directly
git worktree remove ../beads-123

# If worktree directory was manually deleted
git worktree prune

Force remove (if needed):

git worktree remove --force ../beads-123

K2-Dev Workflow Integration

Technical Lead Responsibilities

Creating worktree:

# After validating ticket
bd worktree create beads-123

# Navigate to worktree
cd ../beads-123

# Verify setup
pwd
git branch --show-current
bd show beads-123

Cleanup after merge:

# Return to main repo
cd ~/projects/my-project

# Remove worktree
bd worktree remove beads-123

# Verify removal
git worktree list

Engineer Workflow

Start working:

# Should already be in worktree (Tech Lead created it)
pwd  # Verify: ../beads-123

# Read task context
bd show beads-123
bd comments beads-123

# Start implementation
vi src/feature.ts

During implementation:

# Regular git workflow
git add .
git commit -m "Implement feature X"
git push

Create PR:

# From worktree
gh pr create --title "feat: Add feature X (beads-123)" \
             --body "$(cat PR_TEMPLATE.md)"

Multiple Worktrees Simultaneously

Engineer can work on multiple tasks:

# Terminal 1: Work on beads-123
cd ../beads-123
vi src/auth.ts

# Terminal 2: Work on beads-456
cd ../beads-456
vi src/profile.ts

# Each worktree is independent - no branch switching needed

Branching Strategy

Branch Naming

Standard pattern: feature/beads-{id}

Examples:

feature/beads-123
feature/beads-456
feature/beads-789

Why this pattern:

  • Clear association with task
  • Easy to identify in PR list
  • Consistent and predictable
  • Sortable and searchable

Reference: See k2-dev-reference.md#branch-naming

Base Branch

Create worktrees from main/master:

# Ensure main is up to date first
cd ~/projects/my-project
git checkout main
git pull

# Now create worktree
bd worktree create beads-123

Keeping Up to Date

Rebase on main:

cd ../beads-123
git fetch origin
git rebase origin/main

Merge main (if preferred):

cd ../beads-123
git merge origin/main

Best Practices

DO

✅ Create worktree per task - Each beads ticket gets its own worktree for complete isolation

✅ Use consistent naming - ../beads-{id}/ for location, feature/beads-{id} for branch

✅ Clean up after merge - Remove worktree after PR merged to keep workspace tidy

✅ Verify before creating:

git worktree list | grep beads-123  # Check doesn't already exist

✅ Stay in worktree context - Work entirely in worktree until PR merged

DON'T

❌ Don't nest worktrees - Keep flat structure, don't create worktree inside another

❌ Don't manually delete worktree directories:

# Wrong:
rm -rf ../beads-123

# Right:
bd worktree remove beads-123

❌ Don't reuse worktree for different tasks - One worktree = one task, create new for new task

❌ Don't forget to push:

# Before creating PR, push changes
git push -u origin feature/beads-123

Troubleshooting

Worktree Already Exists

Error: fatal: '../beads-123' already exists

Solution:

git worktree list  # Check existing worktrees
git worktree remove ../beads-123  # Remove if stale
git worktree prune  # If directory deleted manually

Branch Already Exists

Error: fatal: a branch named 'feature/beads-123' already exists

Solution:

git worktree list  # Check if worktree exists
git branch -D feature/beads-123  # Delete branch if no worktree
bd worktree create beads-123  # Recreate

Can't Remove Worktree

Error: fatal: validation failed, cannot remove working tree

Solution:

cd ../beads-123
git status  # Check for uncommitted changes
git add . && git commit -m "WIP"  # Commit or stash changes

# Or force remove (caution: loses changes)
git worktree remove --force ../beads-123

Lost Worktree Directory

Scenario: Worktree directory deleted but git still tracks it

Solution:

git worktree prune  # Prune stale entries
git worktree list  # Verify cleanup

Integration with Beads

Beads tracks worktree association:

# Create worktree via beads
bd worktree create beads-123

# Beads knows about the worktree
bd show beads-123  # Shows worktree info

# List task worktrees
bd worktree list

When reading task context, bd show beads-123 may include:

  • Worktree location
  • Branch name
  • Work status

Workflow Summary

Standard k2-dev workflow:

  1. Technical Lead: Create worktree

    bd worktree create beads-123
    cd ../beads-123
    
  2. Engineer: Work in worktree

    # Already in ../beads-123
    # ... implement feature ...
    git add . && git commit -m "feat: Add feature" && git push -u origin feature/beads-123
    
  3. Engineer: Create PR

    gh pr create --title "feat: Feature (beads-123)"
    
  4. After merge, Technical Lead: Clean up

    cd ~/projects/my-project
    bd worktree remove beads-123
    bd update beads-123 --status closed
    bd sync
    

Follow this pattern for consistent, isolated task development with clean separation of concerns.

Reference: See k2-dev-reference.md for git worktree commands, branch naming, and common patterns.

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.