Agent orchestration workflow

Solo lets one lead agent coordinate several worker agents in the same project. Treat the lead agent as the orchestrator: it interviews you, writes the plan, creates todos, dispatches workers through Solo MCP, watches their progress, and brings the results back together.

This page is about the human workflow: what to ask the lead agent to do, how to keep context durable, and how to let Solo handle parallel agent work without losing control of the final integration.

For the bigger mental model behind this workflow, read The agentic metaharness.

If you already know the shape of the job, start with a concrete workflow: build, review, and land one change, debug a live application, run an independent review panel, or hand off long-running work. This page explains the general machinery behind those patterns.

Start with an interview#

Start with one lead agent. Do not begin by writing a perfect plan yourself, and do not immediately launch a group of workers. Ask the lead agent to interview you until it understands the goal and can decide whether parallel work is useful.

Useful first prompts:

• Interview me until you can write a good implementation plan. Ask one question at a time.
• Help me turn this goal into parallel work lanes. Start by finding what you need to know.
• Before doing any edits, build a plan with me, then write it into a scratchpad and split it into todos.
• Act as the orchestrator. Use Solo MCP for scratchpads, todos, timers, and spawning workers when the plan is ready.

The interview should pull context out of your head: the goal, constraints, relevant files or modules, risks, verification, deadlines, non-goals, and anything agents should avoid. If the work is vague, the interview is the first deliverable.

Ask for a scratchpad plan#

After the interview, ask the lead agent to write the plan into a project scratchpad. The scratchpad should be readable by future agents without replaying the whole conversation.

Ask the lead agent to capture:

• The goal and current understanding.
• The branch, project, or worktree everyone should use.
• Relevant code paths, docs pages, settings, or commands.
• Constraints, non-goals, and risky files.
• Proposed work lanes and which lanes can run in parallel.
• Known dependencies between lanes.
• Verification steps and handoff expectations.

The scratchpad is the shared memory for the run. When the plan changes, tell the lead agent to update the scratchpad. Do not rely on chat scrollback as the only record of the orchestration.

Useful prompt:

Write the orchestration plan into a Solo scratchpad. Keep it concise, but include enough context that worker agents can use it without asking me to repeat the background.

Ask for todos and blockers#

Next, ask the lead agent to turn the scratchpad into todos. Good todos are small enough to assign to workers, but large enough to represent meaningful work.

For each todo, have the lead agent include:

• A clear objective.
• The files, modules, docs pages, or behavior the worker owns.
• The expected output or acceptance check.
• Whether the todo can run now or is blocked.
• What should be reported back when complete.

Use blockers to represent ordering. A verification todo can be blocked by implementation todos. An integration todo can be blocked by worker handoffs. A docs update can be blocked by a code investigation todo. This lets the lead agent dispatch work that can move now while keeping dependent work visible.

Useful prompt:

Create Solo todos from the scratchpad. Set blockers where a todo depends on another lane. Mark which todos can run in parallel and which one should stay with you as the lead.

Dispatch workers through Solo MCP#

When the todos are ready, ask the lead agent to dispatch the unblocked independent lanes. The lead agent can use Solo MCP to inspect the project, list available agent tools, spawn worker agents, send each worker its assignment, and bind the work back to the relevant todo.

Useful prompt:

Use Solo MCP to spawn worker agents for the unblocked parallel todos. Give each worker one bounded task, include the scratchpad context it needs, tell it which files it owns, and ask it to report changed files, tests run, blockers, and remaining risk.

Parallel lanes work best when they have separate ownership:

• One worker edits a focused UI surface while another updates docs.
• One worker investigates current behavior while another prepares tests.
• One worker handles a service module while another updates the UI.
• One worker validates workflows while another writes human-facing guidance.

Keep work in the lead agent when the next step depends directly on the result, when the edit area is small, or when two workers would compete over the same files. Parallel agents are useful when they reduce waiting; they are expensive when they create coordination overhead.

Give workers narrow prompts#

The lead agent should not ask every worker to solve the whole problem. Each worker should receive one lane, one ownership boundary, and one expected handoff.

A useful worker prompt includes:

• The exact objective.
• The scratchpad or todo context that explains why this lane exists.
• The files or directories it owns.
• The fact that other agents may be editing nearby files.
• What it should not change.
• What to report back: files changed, tests run, blockers, and remaining risk.

Useful prompt for the lead:

For each worker, write a self-contained prompt. Make the ownership boundary explicit, mention that other agents may be editing the repo, and tell the worker not to revert unrelated changes.

Have the lead watch workers#

Once workers are running, the lead agent should watch the Solo process tree instead of waiting blindly. Worker agents appear in the project's Agents section. When an agent starts another agent through Solo's agent-channel support, Solo can nest child agents under the parent.

Ask the lead agent to use Solo MCP to monitor worker state:

• Check which workers are running, idle, blocked, or waiting for input.
• Read worker output or summaries before deciding that a lane is complete.
• Update todos when a worker starts, blocks, finishes, or needs human input.
• Record important decisions in the scratchpad or todo comments.

Useful prompt:

Monitor the worker agents through Solo. Keep the todos current, record decisions in the scratchpad, and tell me only when you need input or when an integration decision is ready.

Set wake-up timers#

Long-running agent work should not depend on you remembering to check back. Ask the lead agent to set timers through Solo when it needs to resume after workers go idle.

Useful timer prompts:

• Set a Solo timer to wake you when any worker goes idle, then inspect that worker and update its todo.
• Set a Solo timer to wake you when all current workers are idle, then summarize their results and decide the next dispatch.
• If a worker is waiting on a long command, set a timer to check back after a reasonable delay.

Idle timers are especially useful when the lead has spawned several workers. The lead can wait for any watched worker to go idle—or for the guard to expire—then inspect worker output and state before deciding that a worker is ready for review. The lead can also wait for all watched workers to go idle before doing an integration pass.

Keep the plan live#

The lead agent should keep the scratchpad and todos current while work is happening. Treat them as the source of truth, not just setup artifacts.

Ask the lead to update them when:

• A worker discovers new context.
• A todo becomes blocked or unblocked.
• A lane is no longer worth doing.
• A worker changes files that another worker needs to know about.
• Verification fails and the plan needs another pass.

Useful prompt:

Before dispatching more work, reconcile the scratchpad and todos with what the workers have learned. Update blockers and tell me what changed in the plan.

Integrate one lane at a time#

When workers finish, ask the lead agent to integrate deliberately. The lead should not merge every result mentally at once.

Useful prompt:

Integrate the completed worker lanes one at a time. Check git status first, review the smallest safe change first, run focused checks after meaningful steps, and ask workers to adapt to existing edits instead of reverting work they did not make.

A good integration loop:

1. Inspect each completed worker handoff.
2. Update the related todo with files changed, tests run, and risk.
3. Review the actual diff or output, not only the summary.
4. Run focused verification.
5. Unblock the next todo or dispatch the next worker.

If a worker is still running while another result is integrated, ask the lead to tell that worker about relevant file changes before it continues.

Use summaries as triage, not evidence#

Auto-summaries are useful for scanning the process tree. They are not proof that work is correct.

Ask the lead agent to use summaries to decide where to look first:

• Which worker is probably waiting?
• Which worker appears to be editing, testing, or blocked?
• Which collapsed parent has hidden subagents? Expand it and inspect the child rows or output to determine their activity.

Then have it open the actual worker output, inspect the changed files, and update the scratchpad or todo with facts. Summaries can lag, be skipped for very short activity, or be unavailable if auto-summarization is disabled.

Capture handoffs before cleanup#

Before closing a worker, ask the lead agent to capture its handoff outside the worker session.

Useful lead prompts:

• Ask each finished worker for changed files, tests run, blockers, and remaining risk. Save the useful parts to the relevant todo.
• Write a concise integration note in the scratchpad before closing workers.
• Do not close a worker until its useful context is captured somewhere durable.

Closing an agent removes the session from the sidebar; it should not be the only place where important coordination state lives.

Close finished workers#

When a worker's handoff has been captured and its work no longer needs an interactive session, ask the lead agent to clean up. Running agents are stopped and removed when closed. In the interactive UI, Solo asks whether to close nested subagents too. Solo MCP's close_process closes only the target: it keeps the descendants and detaches the direct children from the closed target. Close descendants individually if the lead also wants them removed.

Useful prompt:

Close finished worker agents whose handoffs are captured. Keep any worker that is still producing useful work. If a worker has descendants, inspect them before deciding whether to close the whole group.

Closing does not undo filesystem edits that already happened. The lead should review partial changes before removing an agent that was mid-task.

Avoid losing control#

Use these habits when the lead agent is orchestrating other agents:

• Start with an interview, not a premature worker swarm.
• Keep one shared source of truth: scratchpad plus todos.
• Use blockers so the lead knows what can run now and what must wait.
• Ask the lead to spawn workers through Solo MCP only for independent lanes.
• Ask the lead to set Solo idle wake-up timers when workers may finish later.
• Have the lead inspect real output and diffs, not only summaries.
• Capture worker handoffs in todos or scratchpads before closing sessions.
• Keep final integration controlled and verified.

The goal is not to maximize the number of agents. The goal is to let one lead agent preserve context, coordinate independent work, and bring the result back to you in a form you can review.