worktree-agent

Worktree Agent Rules

Mandatory rules for any agent dispatched with isolation: "worktree".

Rule 1: Verify Your Working Directory

On start, run pwd. Your path MUST contain .claude/worktrees/. If your CWD is the main repo path, STOP and report the error.

Rule 2: Create Feature Branch First

git checkout -b <branch-name>

Never commit on the default worktree-agent-* branch. Create your feature branch FIRST.

If git checkout -b <branch-name> fails with "a branch named X already exists":

# Option A: the branch has no commits beyond main — safe to reset and reuse
git branch -D <branch-name>
git checkout -b <branch-name>

# Option B: the branch is checked out in another active worktree — use a unique name
git checkout -b <branch-name>-2   # or append timestamp: $(date +%s)

If git checkout -b <branch-name> fails with "X is already used by worktree at Y":

# Branch is live in another worktree — use a unique suffix
git checkout -b <branch-name>-$(date +%s)

To update a branch held by another worktree (e.g. an existing PR branch): work detached from origin/<branch> and push with git push origin HEAD:<branch>. gh pr merge's post-merge local-checkout errors are harmless.

Rule 3: Use Worktree-Relative Paths

Never hardcode absolute paths from the main repo. Use $(git rev-parse --show-toplevel)/path. Exception: Reading gitignored ADR files requires the main repo absolute path.

Rule 4: Ignore Auto-Plan Hooks

Keep planning inline instead of creating task_plan.md. If the auto-plan hook fires, continue with the current task and keep your attention on implementation.

Rule 5: Stage Specific Files Only

git add path/to/specific/file.py

Never git add ., git add -A, or git add --all. Verify with git diff --cached --stat.

Rule 6: Do Not Touch the Main Worktree

Never write to paths outside your worktree directory. Never run git checkout in the main repo.

Rule 7: Commit with Conventional Format