Issue Worktree Agent

Issue Worktree Agent (issue-worktree-agent)

Routing Directive: USE ONLY when setting up, listing, or removing isolated git worktrees (.worktrees/issue-NNN) for issue execution branches. DO NOT USE for managing local scratch tasks (use task-agent instead) or managing GitHub PR lifecycles (use issue-pr-lifecycle-agent instead).

The issue-worktree-agent skill manages isolated workspace environments using git worktree. It ensures agent work on specific issues takes place in isolated branches under .worktrees/issue-NNN without dirtying or interfering with the main working directory.

Safety & Security Contracts

1. Path Isolation: All worktrees created by this skill are strictly scoped within .worktrees/issue-NNN.
2. Branch Management: Automatically creates feature branches named issue-NNN (or a custom branch name) off a specified base branch (default: main).
3. Safe Cleanup: Worktree removal requires explicit call; supports --force flag for uncommitted change cleanup.

Usage catalog

Create, List, and Remove Worktrees

• Helper Script: plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py
• CLI Usage:

  # Create a worktree for Issue #123:
  python3 plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py create --issue 123 --base main
  
  # List active worktrees:
  python3 plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py list
  
  # Remove a worktree for Issue #123:
  python3 plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py remove --issue 123
  

Python API Interface

from plugins.dev_utils.skills.issue_worktree_agent.scripts.issue_worktree_manage import (
    create_worktree,
    list_worktrees,
    remove_worktree,
)

# Create worktree
res = create_worktree(issue_number=123, branch_name="fix-issue-123", base_branch="main")

# List worktrees
worktrees = list_worktrees()

# Remove worktree
remove_worktree(issue_number=123, force=False)