Concurrency only matters when two or more Dev agents work simultaneously on overlapping files. This happens when a phase contains two or more plans with noDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/swt-labs/vibe-better-with-claude-code-vbw/llms.txt
Use this file to discover all available pages before exploring further.
depends_on relationship between them. If your plans are chained via depends_on (the common case), agents run sequentially and there is no concurrency risk.
VBW provides three mechanisms to control parallel execution: team creation, filesystem isolation, and file-level locking.
prefer_teams — team creation
Controls whether VBW creates an Agent Team (multiple Dev agents running in parallel) or uses a single agent.
| Value | Behavior |
|---|---|
auto | Creates a team only when 2+ plans exist in a phase. Single plan = single agent, lower overhead. Smart routing may further downgrade simple plans. Default. |
always | Creates a team for every phase, even with 1 plan. Maximum agent visibility. |
never | Never creates teams. All agents run as sequential subagents. Disables parallel execution entirely. |
when_parallel is an alias for auto. Planning always uses sequential subagents (Scout → Lead) regardless of this setting — prefer_teams only affects Execute and debug/map modes.worktree_isolation — filesystem isolation
When enabled, each Dev agent gets its own git worktree — a physically separate copy of your repository on a dedicated branch. Agents work in different directories and cannot overwrite each other’s files.
How it works
Before execution
For each plan, VBW creates a worktree at
.vbw-worktrees/{phase}-{plan} on branch vbw/{phase}-{plan}:During execution
Each Dev agent works exclusively in its assigned worktree directory. All file edits and commits happen on the worktree’s branch, completely isolated from other agents.
After execution
Once all Dev agents finish, the Lead merges each worktree branch back into the main branch using
git merge --no-ff.- Clean merge: The worktree is removed and the branch is deleted.
- Merge conflict: The merge is aborted, the worktree is left in place, and VBW reports:
⚠ Worktree merge conflict for plan 02. Resolve conflicts in .vbw-worktrees/01-02/
worktree-create.sh, worktree-merge.sh, worktree-cleanup.sh, worktree-status.sh, worktree-target.sh, and worktree-agent-map.sh.
Merge conflicts only occur when two parallel Dev agents edited the same file on different branches. The Architect assigns disjoint file sets to each plan to minimize this, but it is not guaranteed.
worktree_isolation is off by default for backward compatibility. Enable it when you are running effort: "thorough" with complex phases where the Architect creates genuinely independent plans with overlapping file ownership.
lease_locks — file-level locking
A lighter-weight alternative to worktrees. Instead of filesystem isolation, lease locks track which files each task has claimed. If two tasks try to claim the same file, the second is blocked until the first releases its lock.
lease_locks is true by default.
How it works
Before each task
control-plane.sh calls lease-lock.sh acquire with the task’s file list. A lock file is written to .vbw-planning/.locks/{task-id}.lock containing the claimed files and a TTL (default 300 seconds).Conflict detection
If another task already holds a lock on an overlapping file, the acquisition fails and the task is blocked. Expired locks (past TTL) are cleaned up automatically.
depends_on in plan frontmatter
The recommended way to prevent conflicts is to declare plan dependencies explicitly. When Plan 02 lists Plan 01 in depends_on, Dev-02 waits until Dev-01 finishes before starting.
depends_on whenever one plan’s output is another plan’s input, or when two plans touch overlapping files. Chained plans eliminate concurrency by design — no worktrees or lease locks needed.
file-guard.sh hook
At runtime, before any filesystem access, the file-guard.sh hook blocks writes to files not declared in the active plan’s file ownership list. This enforcement happens regardless of worktree or lease lock settings.
Choosing the right mechanism
| Scenario | Recommendation |
|---|---|
Plans always chained via depends_on | Neither worktrees nor lease locks needed — no concurrency, no conflicts |
| Parallel plans, want strongest isolation | worktree_isolation: "on" — separate directories and branches |
| Parallel plans, want lightweight protection | lease_locks: true (default) — file-level claims, no branch overhead |
| Both enabled | Works without conflict, but redundant — worktrees already prevent what lease locks detect |