Skip to content

Orchestrated tasks

An orchestrated task is run by an orchestrator agent instead of one agent you fly by hand. The orchestrator agrees the goal with you, proposes a breakdown you approve in the side panel, launches specialist agents, merges their branches and opens one PR after the repo's tests pass. The board shows the task as one group with a rolled-up status.

Types

Pick a Type when you create a task, instead of Solo. The built-in types are direct (one step) and structured (brainstorm, plan, one specialist per task, a review step).

Flow

flowchart LR
    A[Agree the goal] --> B[propose_breakdown]
    B --> C{You approve?}
    C -->|changes requested| B
    C -->|approved| D[spawn_specialist per step]
    D --> E[Merge each step into the task branch]
    E --> F[open_pr runs the checks]
    F -->|a check fails| B
    F -->|all pass| G[Push and open the PR]
  1. New task: pick the Type, the persona and one repo; the roster (the specialists it may use) comes from the repo.
  2. You talk to the orchestrator in its terminal until the goal is agreed.
  3. It proposes a breakdown; the task goes to Needs you. Approve it or request changes in the side panel.
  4. It launches one specialist per step. Each is a normal agent on the board with its own worktree, on a sub-branch of the task branch; the orchestrator merges each finished step back.
  5. When the steps are done it calls open_pr: the daemon runs the checks the repo's workflow file lists for the change, and only if they pass pushes the task branch and opens the PR. The default stop is an open PR; nothing is merged.

Every question and permission prompt still reaches you; there is no autopilot yet. Orchestrators and specialists cannot spawn in-chat subagents, and an orchestrated task has exactly one repo.

The workflow file

A repo needs a .fleet/workflow.yml on its base branch on origin before an orchestrated task can use it: it lists the checks the gate runs before a pull request, and is fetched when the task is created.

Internal resources

Each product has a private notes repo: a local git repo at <state_dir>/internal/<product-id> with no remote. Nothing pushes it. Designs, plans and decisions go there instead of into the code repo. It is made with the product, or on the first orchestrated task of an older product.

  • Orchestrator: gets a read-write worktree at <task workdir>/internal, on the branch task/<task-name>. Its CLAUDE.md has an "Internal resources" section naming the path and the task's folder in it, tasks/<task-name>/. The structured orchestrator writes tasks/<task-name>/design.md and tasks/<task-name>/plan.md there and commits them with git -C <path> add -A && git -C <path> commit -m "<message>". Solo tasks get no internal worktree.
  • Specialists: get a read-only, detached snapshot at <task workdir>/internal-snapshots/<n>-<slug>, as of the orchestrator's last commit when the specialist was spawned. Their briefs name the design and plan by their paths relative to the notes folder, such as tasks/<task-name>/plan.md. spawn_specialist is refused while the orchestrator's internal worktree has uncommitted changes: commit your internal resources first: git -C <path> add -A && git -C <path> commit -m "<message>".
  • Merging: each successful open_pr merges task/<task-name> into the product's main notes. The log says internal notes merged into the product's notes, or nothing when there is nothing new. On a conflict it says internal notes not merged: conflict in <paths>; the next pull request retries, and the PR is still opened. A merge that stops for another reason is aborted the same way and logged as internal notes not merged: <git's message>; the next pull request retries.
  • Archive: removes the worktrees and keeps the task/<task-name> branch.

The read-only access is not a security boundary, like the push block below. A specialist gets an Edit(//<path>/**) deny rule, which covers the built-in file-editing tools, plus the snapshot as an additional directory. It runs as the same OS user, so a shell command can still write there.

Read them in Management → Products → a product → Internal resources: a branch picker, the files and, for a file, its text and last commit. It is read-only. The daemon serves the same data over HTTP:

Route Returns
GET /api/products/{id}/internal/branches The branches
GET /api/products/{id}/internal/files?branch= The files on a branch
GET /api/products/{id}/internal/file?branch=&path= One text file
GET /api/products/{id}/internal/history?branch=&path=&limit= Commits, newest first

branch defaults to main; limit defaults to 50 and is at most 200. Files are text up to 1 MiB. A .. component, an absolute path or a symlink is refused with 400; an unknown product, branch or path is 404.

Limits

Three limits stop a task that loops or grows without end.

Limit Default What it caps
max_breakdown_versions 8 The breakdown versions one task may accumulate
max_steps 20 The steps one breakdown may declare
max_parallel_specialists 3 The specialists one orchestrator may have running at once

When a limit is hit, the daemon refuses the call and tells the orchestrator why:

  • max_breakdown_versions: the task already has that many breakdowns, so a new one is refused. The orchestrator stops and asks you.
  • max_steps: the proposed breakdown has more steps than the limit. Every proposal restates the carried steps, so its length is the task's whole step count. The orchestrator stops and asks you.
  • max_parallel_specialists: that many specialists are running. This is not a failure. The orchestrator waits for one to finish, then starts the next step.

For the first two, a limit reached refusal is a hard stop: the orchestrator stops and tells you, and you either raise the limit in Management → Products (see Overrides) or end the task. Versions and steps count over the whole task; the parallel cap counts only the specialists running now.

The refusal names the limit, its value and where the value came from.

Set the global limits in Settings, on the General tab, under Limits. Save writes them to config.toml and restarts the daemon; running agents keep going. A product can override each limit: see Overrides. The key names are also in the configuration reference.

Push blocking

Pushes and PRs by the agents themselves are blocked on a best-effort basis, not as a security boundary: text deny rules on git push, gh pr create and gh api, plus an env block that points origin's push URL nowhere. They stop the model's ordinary attempts. Known bypasses: git push <url> hidden from the text rules (in bash -c or a script), env -u GIT_CONFIG_COUNT git push, and a repo whose own config sets remote.origin.pushurl. open_pr is the only push the daemon makes, and only after the tests pass.

Definitions

Definitions live in the binary (built-ins, read-only) plus your files in fleet/ in the config folder (orchestrators/, specialists/, skills/); a user file with a built-in's name overrides it and keeps its own text: it has no internal-resources wording unless you add it. Edit them in Management: see Management. A definition can set a model:; see Models.