The orchestrator is a Claude Code session like any other, with one addition: Fleet gives it tools that operate on real sessions in real worktrees.
Its tools
| Tool | What it does |
|---|---|
list_agents | The roster: status, cost, files changed, and the last thing each agent said |
spawn_agent | Create an agent with a name and a brief. It starts work immediately |
send_to_agent | Send a follow-up prompt to one agent |
agent_transcript | Read what an agent actually produced |
wait_for_agents | Block until agents go idle, with a timeout |
merge_agent | Merge a finished agent's branch into the orchestrator's own |
stop_agent | Interrupt an agent that is going wrong |
pending_reviews | The agents waiting to be reviewed |
review_agent | Approve an agent's work, or send it back with notes |
ask_user | Ask you a question and block until you answer |
open_pull_request | Push the integration branch and open one pull request for the round |
start_round | Begin the next feature, on a new branch, with this round's agents retired |
continue_round | Keep working in the round already delivered |
An agent, by contrast, has exactly one tool: it can request review. That asymmetry is the hierarchy.
The plan gate
An orchestrator starts in Plan mode by default, so it reads the repository and proposes a shape before any agent exists. That plan arrives at the permission layer like any other tool call, which is why the gate is a permission card rather than a separate mechanism.
Approving moves both halves at once: the agent's mode and Fleet's record of it. Setting only one gives you a session that edits while the interface still says Plan.
You can turn the default off if you would rather a squad start building immediately.
What it is told to do
The orchestrator's system prompt is two halves. Fleet owns the first, which names the tools and the invariants it cannot override. You own the second, which is a markdown file you can edit. See roles.
The invariants Fleet keeps for itself are the ones that would break the machinery rather than change the behaviour:
- One round is one feature: one integration branch, one pull request.
- An agent's work reaches the orchestrator only through
merge_agent. It never edits another agent's worktree. - The orchestrator owns the integration branch, and every agent branches from it.
- An agent that requested review is stopped until it is answered.
What the shipped role file asks of it
The editable half is where the working style lives, and Fleet's default asks for the things that actually decide whether a squad is faster than one agent:
- Read the repository before choosing agents. A plan written without reading the code produces briefs that do not survive contact with it.
- Choose the agent count from the work. Split along seams that genuinely do not touch. Two agents editing the same files will conflict, and one agent is a perfectly good answer for a small feature.
- Write briefs that stand alone. Each agent sees only its brief and the repository, so the brief states the goal, what it owns, the interfaces it must honour, and what it must not touch, including the other agents' territory by name.
- Establish shared contracts first. If two agents need the same type, the orchestrator writes it and commits it before spawning them.
- Ask you what is genuinely yours to decide, as it comes up, not saved to the end.
- Review properly. Read the transcript and the diff. "It said it was done" is not evidence.
- Merge as work lands, one agent at a time, resolving conflicts in its own worktree. Merging everything at the end is how you get an unresolvable pile.
- Verify the whole. The feature is not done because the parts are done.
You can rewrite all of that.
When it asks you something
ask_user blocks the orchestrator until you answer, and Fleet surfaces it as an interruption you
can find at a glance. Pending questions survive a window reload, because a reloaded window that
forgot one would leave the orchestrator waiting with nothing on screen to answer.