Agents & Roles

Sub-agents are ephemeral Claude Code processes spawned by the orchestrator to perform specific tasks. Each agent has a role — builder, reviewer, scout, or coordinator — that determines its system prompt, behaviour, and the tools it receives. Understanding agent roles helps you build a team that covers all the work your project needs.

Agent lifecycle

Every agent goes through the following states from spawn to completion:

idleWaiting in queue, not yet started

→

runningClaude Code process active

→

doneCompleted successfully

errorExited with an error

cancelledStopped by cancel cascade

Spawn process

When the orchestrator calls spawn_agent, Agenties:

Spawn sequence

1. Reserves a slot in the agent pool (default max: 4 concurrent agents)
2. Resolves the team member: looks up memberId in team.json to get model, effort, instructions
3. Builds the system prompt: baseInstructions + role-specific prompt + task context
4. Posts a task-assigned message to the mailbox for the agent to read at turn start
5. Spawns a new Claude Code process with:
   — MCP server pointing to the project's Agenties server
   — Working directory set to the project root
   — CLAUDE_SESSION_ID env var (for continuity if the agent needs multiple turns)
6. Registers the agent in shared/state.json under activeAgents[]
7. Streams stdout to the Agents tab in the UI

Roles in detail

Builder

The builder is the workhorse of the team. It receives a concrete implementation task and is expected to: read the relevant code, write the implementation, run tests, fix any failures, and post a completion summary to the mailbox.

// Builder system prompt excerpt
You are a specialist software engineer. Your job is to implement the assigned task completely and correctly. You MUST run all relevant tests before marking the task done. Do not ask clarifying questions — use your judgment and note any assumptions in your completion message.

Attribute	Value
Typical model	claude-sonnet-4-6 or claude-opus-4-7
Effort	high or xhigh
Max turns	1 (re-spawned by orchestrator if follow-up needed)
Key MCP tools	read/write files, run shell, create_issue, send_message

Reviewer

The reviewer reads a diff or a set of files and evaluates them against the original requirements. It posts a review-result message with one of three verdicts: approved, changes-requested, or blocked. The orchestrator uses this verdict to decide whether to re-assign to the builder or close the task.

Attribute	Value
Typical model	claude-haiku-4-5 (fast and cheap for reviews)
Effort	medium
Key MCP tools	read files, read_messages, send_message
Output	review-result message with verdict + specific comments

Scout

The scout researches the codebase, documentation, or the web and writes its findings to the vault. Scouts are spawned when the orchestrator needs context before delegating implementation — for example, "understand how authentication works in this codebase before having the builder add OAuth."

Attribute	Value
Typical model	claude-haiku-4-5 or claude-sonnet-4-6
Effort	low or medium
Key MCP tools	read files, grep, write_vault_note, send_message
Output	Vault note with findings + task-done message pointing to it

Coordinator

The coordinator is a mini-orchestrator for complex tasks that require multiple sequential steps. It can spawn its own builders and reviewers up to a configurable maximum of MAX_COORDINATOR_TURNS(default: 10). This is useful for multi-file refactors, feature development across multiple layers, or long research-and-implement loops.

Coordinator loop

turn 1: coordinator reads task, spawns scout to understand codebase
turn 2: scout reports → coordinator spawns builder for layer 1
turn 3: builder done → coordinator spawns reviewer
turn 4: reviewer approved → coordinator spawns builder for layer 2
...
turn N: all layers done → coordinator posts task-done to mailbox

Warning:Coordinators can be expensive. Each turn spawns at least one sub-agent, and coordinators themselves use a non-trivial context window. Only use coordinators for tasks that genuinely require multiple sequential agent steps. For simple tasks, a single builder is faster and cheaper.

System prompts

Each agent receives a system prompt composed of three layers:

Layer 1 — Role prompt

Hardcoded in Agenties. Defines the fundamental behaviour of the role (builder/reviewer/scout/coordinator).

Layer 2 — Member instructionsYou edit this

The baseInstructions you write when hiring a team member. Use this to specialise the agent: language preferences, coding standards, project-specific conventions.

Layer 3 — Task context

Injected by the orchestrator at spawn time via the context parameter of spawn_agent. Contains the specific task, relevant files, and links to open issues.

Agent statuses in the UI

Status	Meaning
idle	Process allocated but not yet started. Will start when a slot is free.
running	Claude Code process active, streaming output.
done	Completed successfully. Review output in the Agents panel.
error	Exited non-zero. Check the output for the error. The orchestrator will read the failure and decide how to recover.
cancelled	Stopped by a cancel cascade (user clicked Stop or orchestrator cancelled all children).

← PreviousOrchestrator Next →Team System