New Feature

Every task gets its own worktree and branch, created from the latest origin/main. Never build on main, and never reuse another agent's worktree or branch.

Harness deltas — read first

• Claude Code: the harness creates and manages worktrees itself (under

.claude/worktrees/<name>). Skip steps 3–4 below (no manual git worktree add / remove), and keep the harness-assigned branch name. Steps 1–2 and 5 still apply.

• Cursor-managed worktrees (branches named worktree-*): same idea —

keep the assigned branch and worktree, apply steps 2 and 5.

• Any other harness: follow all steps.

Steps

1. Sync: git fetch origin.

1. Scope check: run gh pr list and skim the open PRs' changed files

(gh pr diff <n> --name-only). If your task needs files another open PR is editing, stop and ask for direction instead of proceeding. Also check for uncommitted work in the checkout — another agent may be mid-task.

1. Name the task: lowercase-with-hyphens plus a short unique suffix,

e.g. user-auth-0816a. If git worktree add fails because the name exists, pick a different name — never force or reuse.

1. Create the worktree from the repo root:

``bash git worktree add <worktrees-dir>/<task-name> \ -b <branch-prefix>/<task-name> origin/main ``

Use a gitignored directory for worktrees (e.g. .claude/worktrees/ or .worktrees/) so they can never be committed by accident, and a consistent branch prefix (e.g. agent/). Follow the repo's conventions if it defines them.

1. Enter and verify:

``bash cd <worktrees-dir>/<task-name> git branch --show-current # must print your new branch, not main ``

Then install dependencies fresh inside the worktree (worktrees don't share node_modules/virtualenvs) and confirm the runtime version the repo requires before running anything.

Remember

• Worktrees do not isolate shared resources: dev-server ports, shared

databases, and dependency lockfiles are global. Confirm a port answers your process (lsof -i :<port>) before trusting what it serves, and resolve lockfile conflicts by regenerating, never by hand-merging.

• Keep the worktree until the PR is merged or closed. Cleanup after merge:

``bash git worktree remove <worktrees-dir>/<task-name> git branch -D <branch-prefix>/<task-name> ``

-D is expected: after a squash- or rebase-merge, -d refuses even though the work is merged.