Pipelines

Pipelines orchestrate multi-stage workflows across your agent fleet. Each stage can involve one or more agents, with automatic progression, approval gates, and failure recovery.

Configuration

Pipelines are defined in your .fleet/config.yaml alongside agent definitions:

pipelines:
  - name: deploy
    description: "Full deployment pipeline"
    stages:
      - name: develop
        agents:
          - frontend-dev
          - backend-dev
        parallel: true

      - name: review
        agents:
          - tech-lead
          - qa-lead
        parallel: true
        approval_required: true

      - name: ship
        agents:
          - release-manager
        approval_required: false

  - name: hotfix
    description: "Emergency hotfix pipeline"
    stages:
      - name: fix
        agents:
          - backend-dev
      - name: review
        agents:
          - tech-lead
        approval_required: true
      - name: ship
        agents:
          - release-manager

Stage fields

Field	Type	Description
name	string	Stage identifier
agents	[]string	Agent names assigned to this stage
parallel	bool	Run agents in parallel (default: false, sequential)
approval_required	bool	Require all agents to approve before advancing

Stage Lifecycle

Each pipeline run progresses through stages. Here is the state machine for a single stage:

                                                 ┌─────────────────────────────────────────────┐
                                                 │ PENDING  │
                                                 └─────────────────────────────────────────────┘
                                                        │ run starts / agents launched
                                                        ▼
┌─────────────────────────────────────────────┐
│PENDING  │
└─────────────────────────────────────────────┘
  │ run starts / agents launched
  ▼
┌─────────────────────────────────────────────┐
│ RUNNING  │◀─────────────────────────────────┐
│          │  signal / eval   │  retry         │
│          │     ▼                         │
│          │  APPROVAL GATE  (rejected ↦ reroute)
│          │     ▼           ▼
│          └─────────────────────────────────────────────┐
│          │  approved
│          │     ▼
│          └─────────────────────────────────────────────┐
│ COMPLETE  │
│          └─────────────────────────────────────────────┐
│          │
│ FAILED │ (dead session detected)
└─────────────────────────────────────────────┘

PENDING

Initial state. The stage is waiting for the previous stage to complete before agents are launched.

RUNNING

Agents have been started in tmux sessions. The sweep loop monitors their progress.

APPROVAL GATE

All agents have signaled completion. If approval_required is true, the system waits for approval/rejection.

COMPLETE

The stage has finished successfully. The next stage's agents are launched.

FAILED

A dead session was detected or an unrecoverable error occurred. Retries may be attempted.

Approval Gates

When approval_required: true is set on a stage, all assigned agents must complete and approve before the pipeline advances. This is how code review stages work:

Approval flow

Pipeline reaches an approval stage
All assigned agents (e.g., tech-lead, qa-lead) are started
Each agent reviews, then signals completion via fleet pipeline signal or the FLEET_SIGNAL_CMD env var
The agent publishes a decision event (pr_approved or pr_changes_requested)
If all agents approve, the pipeline advances to the next stage
If any agent rejects, the pipeline routes back to the appropriate stage for fixes

Rejection routing

When an agent rejects at an approval gate, the pipeline engine routes the run back to the development stage. The original agents are restarted with the review feedback included in their task context. This creates a natural review-fix-review loop without manual intervention.

Sweep Loop

The pipeline engine runs a sweep loop that processes all active runs. You can target a specific run or sweep everything:

// Sweep all active runs
pipeline.Sweep()

// Advance a specific run
pipeline.AdvanceRun(runID)

What sweep does on each tick

Checks each active run for completed signals
Detects dead tmux sessions (agents that crashed)
Processes approval gates (checks all agents approved)
Advances to the next stage when the current stage is complete
Starts agents for newly-active stages
Marks runs as complete when all stages finish

Dead Session Detection

Agent status is determined at runtime by checking tmux.HasSession(). If an agent's tmux session disappears during a pipeline run, the sweep loop detects it and can:

Retry

Restart the agent and reassign the task

Fail

Mark the stage as failed and stop the pipeline

Skip

Continue to the next stage if the dead agent is not critical

CLI Usage

Start a pipeline run

fleet pipeline run deploy --title "Release v1.13"

Signal stage completion

fleet pipeline signal --run 42 --agent tech-lead

Watch a run live

fleet pipeline watch 42