orchestrate

Manage the full orchestration of a dispatched agent: dispatch it to a worktree, wait for it to finish in the background, run review agents on its output, and report a verdict. The user continues working while the agent runs — a background subagent handles the wait and triggers the review pipeline automatically.

Step 1: Determine Working Directory

Infer the repository root directory by running:

git rev-parse --show-toplevel

If the command fails (not inside a git repository), stop and tell the user:

Cannot determine git repository root. Run this command from within a git repository.

Step 2: Generate Branch Name

Derive the branch name from the user's task description using the convention agent/<kebab-case-summary>.

Branch naming rules:

1. Take the task description (or a concise summary if the description is long).
2. Convert to lowercase.
3. Replace spaces, underscores, and other non-alphanumeric characters with hyphens.
4. Collapse consecutive hyphens into a single hyphen.
5. Strip leading and trailing hyphens.
6. Truncate to 50 characters maximum. If truncation lands in the middle of a word, back up to the previous hyphen boundary.
7. Prepend agent/.

If the user explicitly provides a branch name, use that name verbatim instead of generating one.

Pre-flight: Check for Existing Branch/Session

After determining the branch name, call mcp__zwerm__list_sessions and check if a session already exists for this branch. If it does:

1. Tell the user: "Branch agent/<name> already has an active session (<session_id>). Clean up and re-dispatch?"
2. Use AskUserQuestion with options: Clean up and re-dispatch / Pick a different branch name
3. If cleanup: call cleanup_session(session_id, delete_worktree=true, delete_branch=true) then continue to dispatch.
4. If different name: append -v2, -v3 etc. to the branch name and re-check.

CRITICAL: NEVER skip dispatch. Even if a branch already exists with commits, you MUST dispatch a fresh agent. Do not go "straight to review" or assume previous work is valid. The orchestrator's job is dispatch → wait → review → merge. Every step is mandatory.

After the branch name is determined, create a single tracking task for this orchestration:

TaskCreate(subject: "[<branch>] Dispatching",
  activeForm: "[<branch>] Dispatching",
  description: "<task description>")
  → save as taskId
TaskUpdate(taskId, status: "in_progress")

Update this task as the orchestration progresses:

Phase	subject	activeForm
After dispatch	[<branch>] Waiting for agent	[<branch>] Waiting for agent
Review starts	[<branch>] Reviewing (round N)	[<branch>] Reviewing (round N)
Feedback sent	[<branch>] Waiting for agent (round N)	[<branch>] Waiting for agent (round N)
Merging	[<branch>] Merging	[<branch>] Merging
Done	—	status: completed
Cancelled	—	status: completed

Step 3: Dispatch the Agent

Call mcp__zwerm__dispatch_agent with:

Parameter	Value	Source
branch	Generated or user-specified branch name	Step 2
task	The user's task description (raw text, NOT the full prompt)	User message
working_dir	Git repository root path	Step 1
profile	Profile name override, or omit to use default	User override or omit

The server handles profile resolution and prompt assembly. You do NOT need to call get_config or construct the prompt yourself.

Save the session_id and branch from the result — both are needed for the wait and review steps.

After successful dispatch, update the task:

TaskUpdate(taskId, subject: "[<branch>] Waiting for agent",
  activeForm: "[<branch>] Waiting for agent")

CRITICAL: Do NOT stop after dispatch. You MUST immediately continue to Step 4 below.

Step 4: Start Background Wait

This step is MANDATORY. Without it, orchestrate is just a dispatch. After the agent is dispatched, IMMEDIATELY spawn a background subagent to wait for the agent to finish. Do this in the same response as reporting the dispatch to the user.

Use the Task tool with run_in_background: true to spawn a background subagent. The subagent's prompt should instruct it to call mcp__zwerm__wait_for_completion with the session_id returned from dispatch, then return the result. The wait_for_completion tool long-polls until the agent reports complete, blocked, or the timeout expires (default 600 seconds).

Do not wait synchronously. Calling wait_for_completion in the foreground blocks the entire conversation for up to 10 minutes. Always use the background pattern.

After spawning the background wait, tell the user:

Agent is working on branch agent/<name> (session: <session_id>). You can continue working — I will report back when it finishes.

Step 5: Handle Completion

When the background wait returns, the result contains a status field. Handle each status:

Status: complete

The agent finished its work and called report_complete. Before starting review, check the completion result for branch_stats and rebase_status.

Pre-review checks:

If rebase_status == "conflict":

• Send agent feedback: "Your branch has conflicts with <base_branch>. Please run git rebase <base_branch>, resolve conflicts, and call report_complete again."
• Use post_feedback with ack_timeout=5. If acked is false, fall back to send_input.
• Update task and spawn new background wait. Do NOT proceed to review.

If branch_stats.commit_count == 0:

• Skip review entirely.
• Report: "Agent on branch <branch> completed with no commits."
• Use AskUserQuestion: "Cleanup and re-dispatch" / "Inspect manually" / "Dismiss"
• Handle each option accordingly. Do NOT proceed to review.

Otherwise: proceed with review as normal.

Update the task:

TaskUpdate(taskId, subject: "[<branch>] Reviewing (round N)",
  activeForm: "[<branch>] Reviewing (round N)")

First, call mcp__zwerm__get_config with the working_dir to get the review_agents list. For each entry, spawn a Task with subagent_type set to that value. Spawn all of them in parallel (single message, multiple Task calls). Each review agent's prompt should include:

• The agent's worktree path (from the dispatch result working_dir) so it can read the actual code on the branch
• The branch name and repo root so it can run ${CLAUDE_PLUGIN_ROOT}/scripts/branch-diff.sh <branch> <repo_root> to get the diff

Once all review agents have returned, synthesize their verdicts into an overall assessment and act on it (Step 6).

Status: blocked

The agent got stuck and called report_blocked. Retrieve diagnostic information:

1. Call mcp__zwerm__read_output with the session_id to get the agent's output log. Use max_bytes=65536 for a substantial amount of recent output.
2. Read the block reason from the wait_for_completion result.
3. Report the block reason and relevant output to the user.

Automatically post guidance to the agent via post_feedback with ack_timeout=5 to help it get unblocked. If acked comes back false, the agent is not polling — fall back to send_input to paste the guidance directly into the tmux pane. Spawn a new background wait. Only clean up and re-dispatch if the user explicitly asks.

Status: unacked_timeout

The agent never called ack_task within the grace period. The MCP connection may be broken, the prompt may have been mangled, or the agent failed to start.

1. Call mcp__zwerm__read_output with the session_id to check what happened.
2. Report to the user immediately with the output:

   Agent on branch agent/<name> never acknowledged — MCP may not be connected.

3. Let the user decide: retry, check manually, or clean up.

Status: timeout

Call mcp__zwerm__read_output to check whether the agent is still active.

• Agent still active: Spawn another background wait. Don't bother the user.
• Agent idle or stalled: Report the timeout with output. Suggest checking the tmux window.

Step 6: Report Verdict and Act

1. Agent summary: Branch name, session ID, commit count, files changed.

2. Review results: For each review agent, summarize findings.

3. Overall verdict:

• Merge-ready: No critical issues. Use AskUserQuestion to ask "Merge <branch>?" with options "Merge" / "Request changes" / "Manual review".

  If Merge:

  1. Update: TaskUpdate(taskId, subject: "[<branch>] Merging", activeForm: "[<branch>] Merging")
  2. Call cleanup_session(session_id, delete_worktree=true) — keep the branch for merge.
  3. Rebase and fast-forward merge: git rebase main <branch> && git checkout main && git merge --ff-only <branch>.
  4. Delete the branch: git branch -d <branch>.
  5. Complete: TaskUpdate(taskId, status: "completed")

  If Request changes: Ask the user what changes they want via AskUserQuestion (free text). Post their feedback to the agent via post_feedback with ack_timeout=5. If acked is false, fall back to send_input. Update task and spawn a new background wait:

  TaskUpdate(taskId, subject: "[<branch>] Waiting for agent (round N)",
    activeForm: "[<branch>] Waiting for agent (round N)")
  

  If Manual review: Leave the session, worktree, and branch running. The user will review and merge manually.

  TaskUpdate(taskId, status: "completed")
  

• Needs-work (clear fixes): Post findings to the agent via post_feedback with ack_timeout=5. If acked is false, fall back to send_input. Update task and spawn a new background wait:

  TaskUpdate(taskId, subject: "[<branch>] Waiting for agent (round N)",
    activeForm: "[<branch>] Waiting for agent (round N)")
  

  Do NOT fix issues yourself.

• Needs-work (ambiguous): Use AskUserQuestion for guidance first, then post to agent via post_feedback with ack_timeout=5. If acked is false, fall back to send_input. Update task and spawn a new background wait as above.

• Blocked: Post guidance via post_feedback with ack_timeout=5. If acked is false, fall back to send_input. Update task and spawn new wait. Ask user if design decisions needed.

When an orchestration ends early (user cancels, cleanup, or unrecoverable failure):

TaskUpdate(taskId, status: "completed")

CRITICAL: The orchestrator NEVER implements fixes directly. The agent owns its branch.

Handling User Overrides

Profile override: "orchestrate with claude" sets the profile parameter.

Branch override: Explicit branch name used verbatim.

Review override: "skip review" or "no review" skips the review pipeline.

Worktree Cleanup

• Pre-merge (delete_worktree=true): Removes tmux window and worktree, keeps branch for merge.
• Full cleanup (delete_worktree=true, delete_branch=true): Removes everything.

Ensure your shell is NOT inside the worktree directory before cleanup.

Error Recovery

If dispatch fails due to an existing worktree or branch, run the pre-flight cleanup (Step 2) and retry. If dispatch fails for other reasons, report the error. If background wait fails unexpectedly, call read_output and list_sessions to diagnose.

NEVER improvise by skipping steps. If something goes wrong, either fix it and retry the step, or ask the user. Do not skip dispatch, do not skip wait, do not review stale branches.

Cross-Reference

For review workflow details, see references/review-integration.md.