Git Worktree Management

Git Worktree Management

Git worktrees enable multiple coding agents to work on different tasks simultaneously without interfering with each other. Each agent gets its own working directory with its own branch.

Worktree Lifecycle

CREATE → WORK → SUBMIT → REVIEW → QA → MERGE → CLEANUP

1. Create Worktree

# From the main repo root
EPIC_BRANCH="epic/feature-name"
AGENT_NAME="coder-1"
TASK_ID="42"
TASK_SLUG="add-user-api"
WORKTREE_DIR="../worktrees/${AGENT_NAME}-task-${TASK_ID}"

# Create worktree from the epic branch
git worktree add "${WORKTREE_DIR}" "${EPIC_BRANCH}"

# Enter worktree and create feature branch
cd "${WORKTREE_DIR}"
git checkout -b "${AGENT_NAME}/${TASK_SLUG}"

2. Work in Worktree

# Stay in your worktree directory
cd "${WORKTREE_DIR}"

# Regular development workflow
# ... make changes ...
git add <specific-files>
git commit -m "feat(users): add user creation endpoint"

# Stay up to date with epic branch periodically
git fetch origin
git rebase "${EPIC_BRANCH}"

3. Submit for Review

# Ensure tests pass
npm test  # or project-specific command

# Push feature branch
git push -u origin "${AGENT_NAME}/${TASK_SLUG}"

# Update task status (via TaskUpdate tool, not git)

4. After Merge Approval

# Merge into epic branch (done by Team Lead or automation)
git checkout "${EPIC_BRANCH}"
git merge --no-ff "${AGENT_NAME}/${TASK_SLUG}"
git push origin "${EPIC_BRANCH}"

5. Cleanup

# Remove the worktree
cd /path/to/main/repo
git worktree remove "${WORKTREE_DIR}"

# Delete the feature branch (local and remote)
git branch -d "${AGENT_NAME}/${TASK_SLUG}"
git push origin --delete "${AGENT_NAME}/${TASK_SLUG}"

Branch Naming Convention

{agent-name}/{task-slug}

Examples:
  coder-1/add-user-api
  coder-2/fix-auth-middleware
  coder-1/update-payment-types

Worktree Directory Convention

project-root/
├── .git/                    # Main repo
├── src/                     # Main working directory
└── ../worktrees/            # Sibling directory for worktrees
    ├── coder-1-task-42/     # Agent 1's workspace
    ├── coder-2-task-43/     # Agent 2's workspace
    └── coder-1-task-44/     # Agent 1's next task