Agent Roles and Specialization: One Agent, One Job

The single most reliable predictor of fleet output quality is not the model you use. It is how cleanly you have separated agent roles.

A builder agent that is also asked to research the problem, review its own output, and handle deployment logistics produces code of consistently lower quality than a builder agent given only one mandate: write the code, write it well, write it to spec. The research context pollutes the build context. The review mindset conflicts with the creation mindset. The deployment concern pulls attention away from correctness.

This is not a theory. I have watched it play out in production multi-agent pipelines where adding clarity to a single agent's role produced measurable quality improvements with zero model changes.

The Role Taxonomy

Four specialist roles cover the vast majority of production multi-agent workflows. The orchestrator sits above them, coordinating without executing.

Orchestrator — receives intent, decomposes work, routes to specialists, tracks state, merges results. Does not write code. Does not search. Does not deploy. Its only job is coordination.

Researcher — gathers information. Web search, API calls, document parsing, data extraction. Returns structured output: facts, sources, summaries. Has no write access to production files. Does not synthesize beyond its research mandate.

Builder — transforms input specifications into working artifacts. Code, configurations, content. Reads the researcher's output as context. Has file write access. Does not review its own work.

Reviewer — audits output against acceptance criteria. Runs tests, reads code, checks content quality. Returns pass/fail signals with specific notes. Explicitly does not fix what it finds — that loops back to the builder. Separation of build and review is not bureaucracy. It is quality architecture.

Deployer — acts on reviewer approval. Commits code, opens PRs, publishes content, sends Discord notifications. Fires only after the reviewer has cleared the output. No deployer should ever act on unreviewed work.

System Prompt Design: The Role Constraint

The system prompt is the mechanism that enforces specialization. A researcher's system prompt should include an explicit constraint against writing code. A builder's system prompt should include an explicit constraint against browsing the web. A reviewer's system prompt should include an explicit constraint against modifying files.

This sounds restrictive. It is. That is the point.

The practical system prompt structure for each role:

Researcher:

You are a research agent. Your only job is to gather information and return structured JSON.
Do not write code. Do not make file edits. Do not provide opinions.
Return everything in the schema provided. If information is unavailable, say so explicitly.

Builder:

You are a builder agent. You receive a specification and produce the artifact described.
Do not search the web. Do not review your own output beyond basic syntax checks.
Write to the files specified. Return a summary of what you created.

Reviewer:

You are a reviewer agent. You assess output against the provided acceptance criteria.
Do not modify files. Do not write new code. Your output is a structured report: pass/fail per criterion, specific issues, severity ratings.

Context Pollution: The Hidden Quality Killer

Context pollution occurs when an agent's working context contains information relevant to a different role. A builder reading a full research report, when it only needed the top-level specifications from that report, is operating with polluted context.

The practical effects:

• The builder's reasoning allocates attention to research details that do not affect the build task
• Irrelevant details crowd out details that do matter
• The builder may attempt to "help" by modifying specifications based on its read of the research — crossing into the orchestrator's coordination role
• Build quality degrades subtly, in ways that are hard to trace back to context composition

The fix is surgical context delivery. The orchestrator does not pass the researcher's full output to the builder. It extracts the relevant fields from the research JSON and passes only those. The builder sees: specification, acceptance criteria, file paths. Not the 40-page research report.

The Persona Design Principle

Each agent needs a persona that reinforces its role. The persona is not cosmetic. It shapes the tone and priorities of the agent's reasoning.

A researcher's persona: precise, sourced, structured. Returns facts with citations. Flags uncertainty explicitly.

A builder's persona: craftsman, focused on correctness and spec-adherence. No editorializing. Produces the artifact and documents what it built.

A reviewer's persona: skeptical, systematic, specific. Every "fail" verdict includes a precise location and a severity rating. No vague critiques. Reproducible findings.

A deployer's persona: procedural, cautious. Confirms the reviewer has passed before acting. Logs every action. Notifies downstream systems.

The analogy: clear roles with clear authority and clear mandates produce cohesive operation. Ambiguous roles produce confusion, overlap, and missed work.

Persona Injection in Practice

In an OpenClaw-style agent fleet, persona injection happens at the skill level. Each skill file (blog-autopilot, signal-drop, sentinel) has a built-in system prompt that is injected when the skill spawns a coding agent. The coding agent receives not just the task spec but its role identity.

For a content pipeline: the research skill injects a researcher persona. The write skill injects a writer persona. The review skill injects an editor persona. Each spawned agent operates with a fully formed role identity from the first token.

The result: predictable behavior, predictable output format, predictable quality criteria. The orchestrator can reliably interpret the output from each role because the role was enforced at spawn.

Lesson 65 Drill

For each agent in a workflow you are planning or already running:

1. Write a one-sentence role definition: "This agent's only job is X."
2. List two things this agent explicitly does not do.
3. Define the output schema: what structured format does this agent return?
4. Write the constraint clause for its system prompt.

If you cannot write a clean one-sentence role definition, the role is not yet clear enough to build against. Clarify the role first. The agent is easy once the role is right.

Bottom Line

Role discipline is the architecture of quality.

One agent. One job. One system prompt that enforces the job. Surgical context delivery. Hard separation between build and review. Explicit persona that reinforces the role's priorities.

The fleet's quality ceiling is set at design time, in the role definitions. That is where the work happens. Everything else is execution.