Skip to content

Fleet Dispatch

Requires a RaiSE server

This feature talks to a RaiSE server rather than working purely locally. Stand one up with the self-hosted guide, or point the CLI at an existing deployment.

Fleet dispatch is RaiSE's system for parallelizing story execution. It reads the dependency graph of your stories — specifically the blockedBy links in your backlog — resolves which stories can run concurrently, and dispatches them to available agents or worktrees.

Why Fleet?

The default story lifecycle is sequential: one story at a time, one agent, one worktree. This is the right starting point — it's simple and predictable. But large epics have independent stories that have no dependency on each other. Running them sequentially wastes time.

Fleet makes the dependency structure explicit and executable. Stories that are independent run in parallel. Stories with blockers wait for their dependencies to resolve. The result is the same governance trail as sequential work, delivered faster.

How It Works

Fleet operates in three steps:

1. Read the DAG

Fleet queries your backlog adapter for the story blockedBy links. These links define the dependency graph: Story B is blocked by Story A means Story A must complete before Story B can start.

Story A ──► Story B ──► Story D
Story C ──────────────► Story D

In this graph, A and C are independent and can run in parallel. B is blocked by A. D is blocked by both B and C.

2. Resolve Parallel-Eligible Work

Fleet computes which stories have all their blockers resolved (or have no blockers). These are the "dispatchable" stories at this moment — the ones that can start immediately.

At each dispatch cycle, this computation is re-run. When A completes, B becomes dispatchable. When both B and C complete, D becomes dispatchable.

3. Dispatch to Agents

Each dispatchable story is assigned to an agent and (optionally) a worktree. The agent receives the story pipeline configuration and runs the full lifecycle — design, plan, implement, review — without human intervention at non-HITL gates.

Fleet dispatcher
  ├── Agent 1 → Story A (worktree-epic-a)
  └── Agent 2 → Story C (worktree-epic-b)

(A completes)
  └── Agent 1 → Story B (same worktree)

(B and C complete)
  └── Agent 1 → Story D

Integration with Missions and Worktrees

Fleet is mission-scoped. You dispatch fleet for a mission, and it operates over the epics attached to that mission. The mission provides the objective context that each agent loads at session start.

Worktrees are the isolation units for fleet-dispatched work. Fleet creates or reuses worktrees per agent assignment. Each worktree is bound to the same work item, so context is consistent across all parallel agents.

See Worktrees for how worktree binding works.

MCP Tools

Fleet exposes its operations through the rai-workspace MCP server. These tools are not registered by default — see Experimental Status below.

MCP Tool Purpose
fleet_dispatch Start fleet dispatch for a mission or epic
fleet_status Show current dispatch state and agent assignments
fleet_approve Approve a HITL gate across all running agents
fleet_signal Send a signal to one or all running agents

Experimental Status

Fleet dispatch is an evolving feature. The DAG resolution and single-agent pipeline are stable. Multi-agent parallel dispatch with live worktree coordination is under active development. Expect the API surface and behavior to change in minor releases.

Because fleet is outside the shipped scope of the current release, it ships present but concealed:

  • CLI: fleet is hidden from rai --help. The commands still work when invoked by name — rai fleet --help, rai fleet dispatch ....
  • MCP: the four fleet_* tools are registered only when RAISE_EXPERIMENTAL is set to a truthy value (1, true, yes, on). Without it they never reach the client's tool list. The opt-in applies to local stdio only; it never exposes the tools over HTTP.

Setting the variable in your shell is not enough. Tools register at import time inside the MCP server — a separate, long-lived process that inherits its environment from your client's launch config, not from the shell where you run rai. The variable has to reach that process:

// .mcp.json
{
  "mcpServers": {
    "rai-workspace": {
      "command": "/path/to/.venv-mcp/bin/rai-mcp-pipeline",
      "env": { "RAISE_EXPERIMENTAL": "1" }
    }
  }
}

Then restart the client so the server is relaunched with it. A running server will not pick the variable up, and no rai command can tell you whether it did — the CLI and the MCP server do not share an environment.

Nothing is removed from the distribution — this is concealment, so that what a fresh install advertises matches what the release actually promises.

Check the CLI Reference: fleet for the current stable command set.

Next Steps