Orchestrator

The orchestrator is a team of decent engineers who understand your codebase. Architecture is staked out by chunks, discoverable through code backreferences; a new chunk that arrives with just a defined goal can be reliably implemented by a team that already understands what it's building on. You hand them chunks; they do the work in dedicated workspaces and send each chunk back to you the moment it's done.

The orchestrator turns your understanding of a large swath of architecture into implementation while you sleep.

Mental model

When you inject a chunk, the orchestrator creates a git worktree off your project's active branch and runs the chunk's full lifecycle inside that worktree: plan, implement, review, complete. Review is optional in manual mode; the orchestrator always runs it. Once complete finishes, the orchestrator merges the worktree back to the active branch in the directory you launched it from. Each completed chunk lands as its own commit, which makes the work easy to read chunk-by-chunk afterward.

When chunks interact, declare it in their depends_on frontmatter. The orchestrator schedules them in dependency order so each chunk builds on its predecessors. When chunks don't interact, the orchestrator runs them in parallel, each in its own worktree with its own agent. The same model the chunk page describes still holds: at most one IMPLEMENTING chunk per worktree, enforced across many worktrees at once.

Starting it

$ ve orch start
$ ve orch status

The daemon runs in the background. ve orch stop shuts it down.

Injecting a chunk

A chunk has to be committed before injection. The orchestrator works from git state, not your working directory.

$ git add docs/chunks/my_chunk/
$ git commit -m "feat(chunks): add my_chunk"
$ ve orch inject my_chunk

The orchestrator creates a worktree off the active branch, picks up the chunk, and starts the lifecycle. You can keep working on the active branch in the meantime; the worktree is isolated.

The review loop

Review is the orchestrator's quality gate. After implement finishes, the orchestrator spawns a fresh subagent to compare the goal and plan against the implemented code and write a decision. On APPROVE, the chunk proceeds to complete. On FEEDBACK, the orchestrator loops back to implement with the reviewer's notes. The loop is bounded at three iterations; a fourth review escalates the chunk to NEEDS_ATTENTION for operator input.

The fresh context is what makes review catch things. An implementing agent holding goal, plan, and code in a single window for hours starts to lose the gap between what the goal asked for and what the code does. A new agent reading both side by side catches success criteria partially addressed, constraints rationalized past, edge cases never tested. See the Reviewing section on the chunks page for more.

Watching what's happening

$ ve orch ps              # all work units and their states
$ ve orch queue           # what's ready, ordered by priority
$ ve orch tail my_chunk   # stream the agent's log for one work unit
$ ve orch url             # open the dashboard

Attention items

A work unit moves to NEEDS_ATTENTION when it has a question, a conflict with another in-flight chunk, a phase that failed, or an escalated review. View the queue:

$ ve orch attention

The four kinds you'll see most often:

A question

The agent needs context only the operator (or another agent) has.

$ ve orch answer my_chunk "Use the v2 token endpoint, not v1."

A conflict

Two chunks touch the same code in incompatible ways.

$ ve orch resolve my_chunk --with other_chunk parallelize
# or
$ ve orch resolve my_chunk --with other_chunk serialize

parallelize tells the orchestrator the changes are independent enough to merge in either order. serialize says one must finish before the other starts.

A review escalation

The reviewer asked for changes three times and the implementer couldn't satisfy them. Read the latest decision file in docs/reviewers/<reviewer>/decisions/, decide what to do (refine the goal, accept the implementation as-is, abandon the chunk), and resume.

A failure

A phase failed. The worktree is preserved automatically so you can inspect it, fix the issue, and retry.

$ ve orch tail my_chunk          # see what failed
$ cd .ve/chunks/my_chunk/worktree
# investigate, commit any uncommitted work
$ ve orch retry my_chunk

/orchestrator-investigate

When something has gone wrong in the orchestrator and you don't want to figure it out yourself, run /orchestrator-investigate. The skill explores the orchestrator's state, answers questions from stalled agents, works around bugs that left work units stuck, and recovers from just about any state you can land in. Reach for it when the attention queue isn't clearing, a work unit won't move, or you'd rather have an agent triage everything than walk through the queue yourself.

Worktrees and retention

Worktrees live under .ve/chunks/<name>/worktree. By default they are removed after the work unit completes (the chunk's commit is already on your active branch by then). Use --retain to keep a worktree for inspection:

$ ve orch inject my_chunk --retain

Manage retained worktrees:

$ ve orch worktree list                # show status of all worktrees
$ ve orch worktree prune               # merges and cleans up
$ ve orch worktree prune --dry-run     # preview what would be pruned
$ ve orch worktree remove my_chunk     # drops without merging

prune is the safe operation. It merges any uncommitted work back to the base branch before removing the worktree. remove drops the worktree as-is; uncommitted changes are lost.

The orchestrator warns when retained worktrees exceed a threshold (default 10) so disk usage doesn't surprise you. Adjust with ve orch config --worktree-threshold N.

Submitting a batch of FUTURE chunks

A narrative or investigation often produces several FUTURE chunks at once. Hand them all to the orchestrator in one step:

/orchestrator-submit-future

The skill finds every committed FUTURE chunk that isn't already in the orchestrator and injects it. The orchestrator sorts the batch by depends_on and schedules accordingly: dependents wait for their predecessors, independent chunks run in parallel.

Trigger phrases

The slash commands that drive the orchestrator (/orchestrator-inject, /orchestrator-submit-future, /orchestrator-investigate, /orchestrator-monitor) are the easiest entry. When you say "in the background" to your agent, you're telling it to use the orchestrator. The agent will create or commit the chunk as needed and inject it for you.

Working with the orchestrator

A vibe engineer using the orchestrator typically hands off large bodies of work and doesn't see the code until it goes to PR. At PR time you take on the role of an engineering manager, making sure the intent is being maintained in broad strokes. Some PRs you'll review nitpickily, leaving a lot of comments and then telling your agent to resolve them all. Most of the time you accept a bit of distance from the code in exchange for the leverage.

The engineering-manager role also includes QA. Start up what was built, run it, and check that the feature actually makes sense. If the work is more like a data pipeline, prompt a separate agent to test the pipeline's invariants under a variety of scenarios and verify that the tests it writes are valid. The pattern across the role: let the agent lead the investigation, debugging, and test-writing while you verify that its methodology is sound.

What it feels like

Working with the orchestrator at full tilt feels like having a highly competent team bring your architecture vision into reality at unbelievable speed, with you serving just the role of providing judgment.