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.
Creates isolated git worktrees for simultaneous work on multiple tasks using bd worktree.
/plugin marketplace add ivankristianto/k2-dev/plugin install k2-dev@k2-dev-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
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.
For each task:
../beads-{id}/feature/beads-{id}Beads provides integrated worktree management:
bd worktree create beads-123
This creates:
../beads-123/feature/beads-123Location: Worktrees created at ../beads-{id}/ (sibling to main repo) for easy organization and management.
# 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.
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
# Navigate to worktree
cd ../beads-123
# Verify location
pwd
git branch --show-current
# Check status
git status
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
cd - # Or use absolute path
cd ~/projects/my-project
# 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]
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
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
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)"
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
Standard pattern: feature/beads-{id}
Examples:
feature/beads-123
feature/beads-456
feature/beads-789
Why this pattern:
Reference: See k2-dev-reference.md#branch-naming
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
Rebase on main:
cd ../beads-123
git fetch origin
git rebase origin/main
Merge main (if preferred):
cd ../beads-123
git merge origin/main
✅ 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 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
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
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
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
Scenario: Worktree directory deleted but git still tracks it
Solution:
git worktree prune # Prune stale entries
git worktree list # Verify cleanup
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:
Standard k2-dev workflow:
Technical Lead: Create worktree
bd worktree create beads-123
cd ../beads-123
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
Engineer: Create PR
gh pr create --title "feat: Feature (beads-123)"
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.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.