Orchestrator

The Orchestrator is an advanced task execution system that goes beyond the build mode. It decomposes complex tasks into a DAG (Directed Acyclic Graph) of subtasks, creates isolated git worktrees for each, runs verification pipelines, and escalates models on failure.

The orchestrator is accessible from the Orchestrator tab in any project. There are two ways to create orchestrator tasks:

Method 1: Create a new orchestrator task

1. 1Open your project and click the Orchestrator tab.
2. 2Click New task in the top-right corner.
3. 3Fill in the form: Title (required), Description (optional), Preferred model (optional), Escalation tiers, Escalation policy, Max attempts, Verification agent, Verification steps.
4. 4Click Create task — the planner breaks it down and queues the steps.

Method 2: Hand a build task to the orchestrator

1. 1Create tasks with readyForDev: true in the Build tab (or via --draft).
2. 2Go to the Orchestrator tab — ready-for-dev tasks appear in the Build queue section.
3. 3Click Run via orchestrator next to any task.
4. 4The planner decomposes the task and queues the steps.

Click any orchestrator task in the list to open its detail view. The detail panel shows:

• Current status and integration branch (e.g. ai/batch-abc123)
• Attempt count vs max attempts
• Escalation path (the ordered list of models tier 0→N)
• Verification agent and steps configured for the run
• All subtasks created by the planner (with their individual statuses)
• Verification results for each attempt (build, test, lint, git-diff, review with hover feedback)
• Cancel and Retry buttons for failed tasks

An orchestrator task goes through these states:

After an agent completes work, the orchestrator runs a verification pipeline in the worktree:

1. 1Build: npm run build — must exit 0
2. 2Test: npm test — must exit 0
3. 3Lint: npx eslint . — must exit 0
4. 4Git diff: git diff —stat — shows what changed
5. 5Agent review (optional): verification agent LLM-reviews the worktree diff — a rejected review fails verification

When verification fails, the orchestrator can escalate to a more capable model. You can configure the exact escalation path per run or set agent-level defaults.

Default escalation tiers

When no custom tiers are set, the built-in 4-tier ladder is used:

Custom escalation path

Set any ordered list of provider:model ids in the Escalation tiers field. Any model from the curated catalog is selectable (see Agent Models docs). Each failure escalates to the next tier.

Policies

Escalation policies: Fixed/None (never escalate), Escalate (after 2 consecutive failures), Aggressive (after 1 failure). Default: Escalate.

Per-agent defaults

Set default flow settings on any agent via the Edit dialog's 'Orchestrator flow defaults' section. These apply to every run the agent handles unless overridden at run time.

Each orchestrator task gets its own git worktree — an isolated working copy on a dedicated branch. This prevents conflicts between parallel tasks.

• Worktrees are created at ~/.teamshare-worktrees/task-<id>/.
• Each worktree has its own branch (task/<task-id>).
• After verification, the branch merges into the integration branch (ai/batch-<timestamp>).
• Worktrees are cleaned up after merge.

You can also create orchestrator tasks via the REST API. This is useful for automation and scripting.

curl -X POST https://api.teamshare.name.ng/orchestrator/tasks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <jwt>' \
  -d '{
    "projectId": "<project-id>",
    "title": "Build a Next.js landing page",
    "description": "Create a responsive landing page with hero, features, pricing, and contact form",
    "preferredModel": "opencode-go:mimo-v2.5",
    "escalationPolicy": "escalate",
    "maxAttempts": 4,
    "escalationTiers": ["opencode-go:mimo-v2.5", "deepseek:deepseek-chat", "openrouter:anthropic/claude-sonnet-4.5"],
    "verificationAgentId": null,
    "verificationSteps": ["build", "test", "lint", "git_diff"]
  }'