Cleave Orchestrator

Cleave decomposes complex tasks into independent subtasks and executes them in parallel across isolated git worktree branches. Each child runs in its own worktree with its own branch, its own agent process, and its own provider routing. Results are merged back with per-file conflict detection, dependency-ordered merge, and optional adversarial review.

Cleave architecture: split plan feeds orchestrator, which dispatches waves into isolated git worktrees. Completed branches merge with conflict detection, pass through adversarial review, and land on main.

How Is This Different from Subagents?

Claude Code's subagents and similar tools run child agents in the same working directory with the same file system. Two subagents editing the same file produce race conditions. There's no isolation, no merge strategy, and no conflict detection — it's optimistic concurrency without the concurrency control.

Cleave is fundamentally different:

Subagents (Claude Code, etc.)	Cleave (Omegon)
Children share the working directory	Each child gets its own git worktree on its own branch — fully isolated file system
No file scope enforcement	File scope declarations prevent children from touching the same files. Violations are caught at plan time.
No dependency ordering	Children declare `depends_on` relationships. The orchestrator dispatches in dependency waves — a child won't start until its dependencies complete.
No merge strategy	Git merge with per-file conflict detection. Conflicts are never bulk-resolved — each conflicted file is reviewed individually.
No post-merge verification	Adversarial review checks each child's output for bugs, security issues, and spec compliance. Churn detection bails if the same issues keep reappearing.
Single provider	Each child can route to a different provider. The orchestrator uses the routing engine to assign providers based on capability tier and availability.
Implicit parallelism	Explicit plan: labels, descriptions, file scopes, dependencies, max parallelism (default 4). The operator sees and approves the plan before execution.
Results lost on error	Each child's branch persists in the worktree. If a child fails, its partial work is preserved. The operator can inspect, fix, and re-merge manually.

The short version: subagents are cooperative multitasking with no isolation. Cleave is preemptive multitasking with full isolation, a merge protocol, and a verification gate.

How It Works

Assess — cleave_assess evaluates task complexity. The formula is systems x (1 + 0.5 x modifiers). If the score exceeds the threshold (default 2.0), decomposition is recommended.
Plan — the agent creates a split plan: children with labels, descriptions, file scopes, and dependency ordering. The operator sees and can modify this plan before execution.
Dispatch — the orchestrator creates git worktrees, assigns branches (clv-<label>), enriches each child with task context, and dispatches waves in dependency order. Up to 4 children execute in parallel by default.
Execute — each child is a full agent process running in its isolated worktree. It has access to the same tools (read, edit, write, bash) but can only see its own branch's files. It receives design context from OpenSpec if a change is bound.
Merge — completed children are merged back in dependency order. Conflicts are detected per-file. The orchestrator never uses --ours or --theirs — every conflict requires explicit resolution.
Review — if enabled, an adversarial reviewer checks each child's diff for bugs, security issues, and spec compliance. Severity-gated fix iterations with churn detection prevent infinite loops.

Usage

# The agent suggests cleave when complexity is high:
"Implement the provider routing engine with routing.rs, ollama.rs, and per-child config"
# Agent runs cleave_assess, gets complexity 3.0, recommends decomposition

# Or trigger explicitly:
/cleave

# The agent produces a plan with children, scopes, and dependencies.
# You review the plan, then it executes in parallel.

With OpenSpec

When an OpenSpec change exists (from design_tree_update(implement)), cleave integrates with the spec lifecycle:

Each child receives design context from design.md — architecture decisions, file scope, constraints
tasks.md is reconciled after merge — completed tasks are checked off, new tasks from child work are added
Post-merge: /assess spec runs the acceptance scenarios from the specs against the merged code
If specs pass, /opsx:archive closes the change. If they fail, the feedback loop sends you back to the spec stage.

Child Isolation

Each child runs in a separate git worktree on its own branch. This is real file system isolation, not namespace tricks:

Separate working tree — each child has its own directory with its own checkout of the repository. File writes in one child are invisible to others.
Same starting state — every child starts from the parent branch HEAD. No child sees another child's in-progress changes.
File scope enforcement — the plan declares which files each child is allowed to touch. If two children need the same file, the plan must either merge them into one child or declare a dependency.
Dependency waves — children with depends_on relationships are dispatched in waves. A child in wave 2 doesn't start until all its dependencies in wave 1 have completed and merged.
Submodule support — worktrees automatically initialize git submodules so children can access vendored dependencies.
Per-child provider routing — each child can be assigned to a different inference provider. The orchestrator routes based on capability tier and provider availability, so children can use cheaper providers for simple tasks.

Adversarial Review

Enable with review: true on cleave_run. After each child completes, a separate reviewer agent examines the diff:

Bug detection — logic errors, off-by-ones, missing error handling
Security audit — injection, path traversal, unsafe patterns, credential exposure
Spec compliance — if an OpenSpec change is bound, the reviewer checks that the child's changes satisfy the relevant acceptance scenarios
Churn detection — if the reviewer flags the same issues after a fix iteration, it bails rather than looping. Configurable thresholds: review_max_critical_fixes (default 2), review_max_warning_fixes (default 1), review_churn_threshold (default 0.5)

Failure Handling

If a child fails:

Its branch and worktree are preserved. You can inspect the partial work, fix it manually, and re-merge.
Other children that don't depend on the failed child continue executing.
Children that depend on the failed child are skipped (not dispatched).
The orchestrator reports which children succeeded, which failed, and which were skipped — with durations and error messages.
An idle timeout (default 3 minutes) kills children that stop producing events, preventing hangs from consuming resources.