When to Map One Agent to One Worktree to One Branch

The shortcut is tempting. One workspace, multiple agents, multiple tasks in parallel. The first time you try it, it works. The second time, you spend an hour figuring out which agent pushed which commit to which branch.

The job to be done

You want parallel work. You want to know, at any moment, which agent is doing which task. You want to review one PR without reading another agent's leftovers. You want to kill one agent without affecting the others.

Those four requirements are the test. Any workspace model that fails any of them is not a workspace model. It is a shared folder with a hopeful name.

The one-to-one mapping

For each task, you create exactly one branch, exactly one worktree, exactly one workspace, exactly one agent.

Task       -> DEV-23
Branch     -> feature/dev-23-epic-add-nestjs-api
Worktree   -> ../blog-devigner-worktrees/feature/dev-23-...
Workspace  -> herdr workspace "dev-23"
Agent      -> claude spawned via herdr agent start

The chain reads in both directions. Given a task ID, you find the agent. Given an agent name, you find the task. Given a worktree path, you find the branch. The mapping is bijective: every link goes both ways, and nothing is shared.

When one-to-one earns its overhead

The overhead is real. Spawning a worktree takes seconds. Spawning a workspace takes seconds. Wiring them together takes a script. None of that is free.

One-to-one earns the overhead when any of these is true.

One: you have more than two agents running in parallel. Shared workspaces fail at three.

Two: your tasks are independent. If they touch the same files, worktree isolation does not help. Coordination is the bottleneck, not workspace shape.

Three: you review by PR, not by reading the working tree. One-to-one assumes each task produces a reviewable artifact.

If none of those is true, do not bother. A shared workspace with one agent is fine.

The exception: debugging sessions

Sometimes you do not want a worktree. You want to poke at the main workspace with one agent interactively, to debug something that does not deserve a branch.

That is a different mode. It is not parallel work. It is interactive exploration, and the rules are different. Do not confuse the two. Parallel work needs isolation. Debugging needs the main workspace.

What this model does not solve

One-to-one mapping solves attribution and isolation. It does not solve coordination.

If agent A is changing a function signature and agent B imports that function, both worktrees compile clean. Both PRs pass review. The merge of agent A breaks the merge of agent B.

The mapping gives you clean rooms. It does not give you a clean dependency graph. That part is on you, at the planning layer, before any agent spawns.

List your next three tasks

For each, write the branch, the worktree path, and the agent name. If any cell is blank or duplicated across tasks, your mapping is not one-to-one. Decide whether that is intentional before you spawn.