Core Concepts

This page is the mental model behind agents-fleet. Once these five ideas click — Coordinator → Workers → Tasks → Teams, plus the extension surface — the rest of the system is just detail.

The big picture

     You
      │
      ▼
 ┌───────────┐
 │Coordinator │  ← one long-lived LLM session with orchestration tools
 └─────┬──────┘
       │ spawns / manages
  ┌────┼────┬────┬────┐
  ▼    ▼    ▼    ▼    ▼
 W1   W2   W3   W4  ...   (short-lived workers, up to 12 in parallel)

agents-fleet follows a hub-and-spoke (coordinator-worker) pattern. A single coordinator receives your prompts and orchestrates everything; workers do the focused work and report back. For the full system diagram, see the architecture overview and ARCHITECTURE.md.

Coordinator

The coordinator is one long-lived LLM session that lives for your whole REPL session. It is the brain of the fleet:

• Receives your prompts and slash commands.
• Decides how to break work into tasks.
• Spawns and manages workers, tracks their dependencies, and relays messages.
• Synthesizes worker results into a single coherent answer.

You almost always talk to the coordinator, not to individual workers.

Workers

Workers are short-lived agent sessions the coordinator spawns to do one focused job, then tears down. Each worker is an independent LLM session with its own system prompt and a tool set scoped to its job. Workers come in agent types:

Agent type	Role	Tools
explorer	Read-only investigation	grep / glob / view (no writes)
reviewer	Read-only code review	grep / glob / view (no writes)
coder	Implement changes	read + create / edit / shell
tester	Write and run tests	read + create / edit / shell
general-purpose	Anything — the default workhorse	full tool set

Read-only types can't write

explorer and reviewer workers have no create/edit/shell tools. If you need a file written, spawn a coder or general-purpose worker.

Coder-style workers run inside isolated git worktrees, so parallel workers edit files without conflicting. See Worktrees.

Tasks (the DAG)

Work is expressed as a dependency graph (DAG) of tasks. The coordinator records which tasks depend on which, and the fleet:

• Spawns a worker for a task as soon as all its blockers complete.
• Marks tasks blocked / unblocked automatically as dependencies resolve.
• Keeps the fleet saturated — the moment a dependency clears, the next ready worker starts.

Inspect the DAG live with /tasks. When verification (Definition of Done) items fail, fix tasks are created automatically.

Teams

Teams group workers logically so you can monitor and message them as a unit. Crews (below) are the common way teams get created — activating a crew configures a team of workers with specialized prompts.

The extension surface

Everything above is built-in. The four composable building blocks below let you customize agent behavior, loaded across three override tiers (bundled → user → project):

Artifact	What it is	Authoritative reference
Roles	A worker persona — its system prompt + tool set.	Composition
Skills	Atomic, reusable units of knowledge composed into a worker's prompt.	Composition
Workflows	Multi-stage execution plans with artifacts and parallel/sequential stages.	Workflows Reference · Building Workflows
Crews	Named teams that bind roles, skills, and a workflows: override map.	Crews Reference · Crews — Getting Started

When you activate a crew with /crew, the coordinator injects a composed <active-crew> and <active-workflow> block into its system prompt. When a worker spawns, the registry composes role + skills[] into that worker's prompt — so every persona and every piece of shared knowledge can evolve independently.

How commands, crews, and workflows fit together

   user types  →  /command
                      │
                      ▼
            resolveCommandWorkflow
            (consults active crew's `workflows:` map)
                      │
          ┌───────────┴───────────┐
          ▼                       ▼
       Crew                    Workflow
   roles + skills           stages + artifacts
   topology                 parallel / sequential
          │                       │
          └───────────┬───────────┘
                      ▼
         Workers spawn → execute stages
         Tasks express dependencies (DAG)
         Coordinator synthesizes results

A slash command sits on top, consults the active crew's workflows: map to pick a workflow, which spawns workers to execute stages — and tasks track the dependencies between them. The full walkthrough is in the Orchestration Tutorial.

MCP — external tools

Workers and the coordinator can call external tools through the Model Context Protocol (MCP). Project-level MCP discovery is opt-in for safety (pass --trust-project-mcp). See the MCP Integration guide.

The control plane

A control plane lets you observe and drive a long-running fleet remotely. Today the most polished front-end is Telegram remote steering — pair a bot to your fleet and issue the same slash commands from your phone, gated by confirmation prompts for anything destructive. See Telegram Remote Steering.

Putting it together

• The coordinator is the durable brain; workers are disposable hands.
• Work flows through a task DAG that schedules itself.
• Roles, skills, workflows, and crews customize how workers think and act.
• MCP and the control plane connect the fleet to the outside world.

Ready to try it? Head to Your First Fleet.