Skip to main content

Documentation 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.

VBW organizes every project into a three-level hierarchy. Understanding this hierarchy tells you exactly what’s happening when agents are running, why some work runs in parallel and some doesn’t, and how to configure concurrency for your situation.

​
Phases, plans, and tasks

Milestone (your project goal)
 └── Phase 1 (a logical chunk of work, e.g. "Authentication")
     ├── Plan 01 (a group of related tasks, e.g. "User model & migration")
     │   ├── Task 1: Create user model
     │   ├── Task 2: Add validation
     │   ├── Task 3: Write tests
     │   └── Task 4: Update API routes
     ├── Plan 02 (another group, e.g. "Login flow")
     │   ├── Task 1: Build login endpoint
     │   ├── Task 2: Add JWT handling
     │   └── Task 3: Write integration tests
     └── Plan 03 (e.g. "Password reset")
         ├── Task 1: Reset token generation
         └── Task 2: Email template
 └── Phase 2 ...
 └── Phase 3 ...
The rules for each level:
  • Phases execute sequentially. Phase 2 does not start until Phase 1 is done — including QA verification.
  • Plans within a phase can run in parallel (see depends_on below). The Architect designs plans to maximize wave parallelism when it’s safe.
  • Tasks within a plan always execute sequentially — one task, one commit, in order.

​
How agents execute work

When /vbw:vibe enters execute mode, Lead orchestrates everything. Lead never writes code — it spawns Dev teammates and assigns each one a plan. 
Lead (orchestrator)
 ├── spawns Dev-01 → assigned Plan 01 (tasks 1–4, sequential)
 ├── spawns Dev-02 → assigned Plan 02 (tasks 1–3, sequential)
 └── spawns Dev-03 → assigned Plan 03 (tasks 1–2, sequential)
Each Dev agent reads its assigned PLAN.md and works through tasks in order:
  1. Implement the task
  2. Run verification checks
  3. Stage files individually and commit
  4. Move to the next task
One atomic commit per task. Dev agents never batch tasks into a single commit and never split a task across multiple commits (TDD workflows are the only exception: 2–3 commits allowed). When all tasks are done, the Dev writes a SUMMARY.md and reports completion to Lead. After all Devs finish, Lead runs QA verification (unless skipped), then shuts down the team.

​
depends_on

Each plan can declare depends_on in its YAML frontmatter. If Plan 02 lists Plan 01 in depends_on, Dev-02 waits until Dev-01 finishes before starting. Plans with no depends_on start immediately. In practice, the Architect chains plans sequentially when they touch overlapping files — this eliminates file conflicts without needing worktree isolation.
File conflicts can only happen when two Dev agents work on the same files simultaneously — which requires two plans in the same phase with no depends_on between them. If your plans are chained via depends_on, there is no concurrency and no conflict risk.

​
Concurrency controls

VBW provides three mechanisms for managing concurrent Dev agents. All three have safe defaults — you only need to change them if you’re intentionally running high-parallelism builds.

​
prefer_teams

Controls whether VBW spins up Agent Teams when parallelism is useful.
ValueBehavior
"auto" (default)Spins up Agent Teams when two or more plans can run in parallel
"always"Always creates a team, even for single-plan phases
"never"Runs all plans sequentially in a single session

​
worktree_isolation

Controls filesystem isolation between concurrent Dev agents.
ValueBehavior
"off" (default)All Dev agents work in the main worktree
"on"Each Dev agent gets its own git worktree — physical filesystem isolation
Enable worktree_isolation when you have multiple plans in the same wave that genuinely need to modify overlapping files and cannot be re-sequenced with depends_on.

​
lease_locks

File-level locking that prevents two agents from writing the same file simultaneously.
ValueBehavior
true (default)Locks acquired before each file write, released on completion
falseNo locking — use only when agents are guaranteed to touch disjoint files
Keep lease_locks enabled. Disabling it removes the last safety net against concurrent writes to shared files.

​
End of phase

When all Dev agents finish their plans, Lead:
  1. Collects SUMMARY.md from each Dev
  2. Aggregates any pre-existing issue reports
  3. Runs QA verification (unless --skip-qa was passed)
  4. Shuts down the agent team
  5. Updates STATE.md to mark the phase complete
The next /vbw:vibe invocation picks up from STATE.md and starts the next phase.

Concurrency configuration

Full reference for prefer_teams, worktree_isolation, lease_locks, and when to use each.

Agents

The 7 specialized agents, their tools, and the permission model that constrains them.

Build docs developers (and LLMs) love

Get started for freeTalk to us