Agent roles

Coroid does not use one general-purpose agent. Each stage of the path from description to pull request is handled by an agent with a narrow job and a deliberately restricted set of tools.

The restrictions are the point. An agent that cannot write code cannot accidentally write code.

The roles#

Role	Stage	Can modify your code
Architect	Specification and plan	No
Developer	Build	Yes
QA	Verify	No
Reviewer	Review	No
Web tester	Verify, browser flows	No
Explorer	Research, any stage	No
Dependency analyser	Analysis	No

The first four are the delivery agents you see on every task. In standard mode they run in this order:

Architect → Developer → QA → Reviewer

In Coordinator mode, a Coordinator decides the order as the task goes. Both are described below.

Exactly one role — the developer — can change files in your repository. Every other agent reads, runs, reports, or creates follow-up work.

Two ways a task runs#

A task runs in one of two modes. Its AI profile and your deployment decide which one.

Coordinator mode. The architect does not hand over its plan and leave. It stays on the task as the Coordinator. After planning, the Coordinator gives the developer its instructions and waits for the report. It then asks QA to verify what was built, and the reviewer to review what QA passed. After every report, the Coordinator decides what happens next: send the findings back to the developer, answer a question, revise the plan, or finish the task. Rework is one more step for the Coordinator, not a new run.

Standard mode. The platform moves the task through the four agents in a fixed order, and a failed check sends it back to the developer. Some work always runs this way, such as resolving a merge conflict, and standard mode is the fallback when Coordinator mode is not available.

In both modes the same agents do the work, with the same restrictions and the same gates. What differs is who chooses the next step: the platform in standard mode, the Coordinator in Coordinator mode.

The Coordinator#

The Coordinator is the planning agent, kept on the task. It reads your codebase and cannot change it, so everything it does is steering.

What the Coordinator does#

• Plans. The Coordinator explores the repository, then saves the plan with the acceptance criteria that decide whether the work succeeded.
• Delegates. The Coordinator works with one agent at a time. Its instructions name the objective, any acceptance criteria that need extra attention and, when it sends work back, the exact fixes to make. While the agent works, the Coordinator waits and uses no model time.
• Answers questions. An agent that hits a decision can ask the Coordinator. The Coordinator answers with the decision and the reason. It does not leave the question waiting for a person.
• Reacts. When QA fails the work or the reviewer asks for changes, the Coordinator sends the fixes to the developer, and QA verifies the new version.
• Ends the task. The Coordinator finishes the task, or fails it and says why.

What the Coordinator cannot do#

The Coordinator steers; it does not judge. The platform enforces these limits, so they do not depend on what the Coordinator decides:

1. Verdicts belong to QA and the reviewer. Only QA and the reviewer give verdicts, each through its own result. The Coordinator's instructions have no place for a verdict, and the Coordinator cannot mark a check as passed.
2. Finishing needs the gates. A task can finish only when QA has passed the exact version that will ship (or the code as it stands, when nothing changes) and, where the task needs a review, the reviewer has approved that version. If the branch changed after QA ran, finishing is refused and the new version goes back to QA.
3. Rework is bounded. Each agent can be started only a limited number of times per task, and a plan can be revised only a few times. The number of steps and the total run time are capped too. At a limit, the Coordinator can only finish or fail the task.
4. Waiting is bounded. Every wait has a deadline.

So a task steered by a Coordinator ends in one of three ways: a pull request for you to approve; QA's confirmation that the code already does what the task asks, so there is nothing to change; or a failed task that says why. It does not end because the agent in charge declared it done.

Routes a Coordinator can take#

The Coordinator chooses how a task reaches the gates. The gates above are the same on every route.

• The full route. Plan, build, verify, review, finish. This is how a task runs unless the Coordinator has a reason to take another route.
• Sending work back. When QA fails the work or the reviewer asks for changes, the fixes go back to the developer. The new version then has to pass QA before the task can finish. A pass on the earlier version does not carry over to the new one.
• Already done. The code may already do what the task asks. The Coordinator can then have QA verify the unchanged code against the acceptance criteria instead of building anything. When QA passes it, and the reviewer approves where a review applies, the task finishes without a pull request, because there is nothing to merge. QA's verification is the result. This route is closed once the run has produced a change of its own, because QA would otherwise pass code that is not what ships.

Two shorter routes are optional. Coroid does not use them by default. They change the Coordinator's route, never the gates:

• A quick change. For a small fix in a known place, the Coordinator writes a shorter plan and gives the developer a focused instruction that names the files the change belongs in. The developer works within a smaller step budget, and anything it changes outside those files is reported to QA and the reviewer.
• A narrower re-check. After a small fix for something QA or the reviewer found, QA starts from that finding and the project's tests. It still gives its verdict on the whole new version.

When a reviewer is required#

By default, a task you run on its own always goes through the reviewer. Whatever route the Coordinator takes, including when nothing needed changing, the task cannot finish until the reviewer has approved the version QA passed. QA always verifies, with or without a review, and a review never replaces QA's pass. Tasks that are part of a plan follow the rules of their lane.

Coroid also has an optional, risk-based policy. It is not on by default. Under it, a task you run on its own can finish without a reviewer when its change is small and ordinary. The reviewer is still required when:

• a reviewer was already started on the task, or your project's review rules or your organisation's Quality Graph call for one;
• the change touches authentication, sessions, permissions, secrets or cryptography, database migrations, build and deploy configuration, dependency files, or code that talks to outside services;
• the change is large (by default, more than 80 changed lines), or includes binary files, symbolic links or submodules;
• Coroid cannot read the policy or the change itself. When in doubt, the reviewer is required.

A change that alters nothing never needs a reviewer. Code makes this decision, not the Coordinator, and the Coordinator cannot talk its way past it. A line at the end of the pull request description says which way it went and why. It begins with "Reviewer required" or "Reviewer not required".

Architect#

Turns your description into a specification, and the specification into a plan. It reads the codebase to ground the plan in what is actually there, but it writes no code.

Its output is the thing you approve before the build starts. In Coordinator mode, this agent then carries on as the Coordinator.

Developer#

Does the work: reads the relevant code, makes the change, writes or updates tests, and runs them locally in the workspace until they pass.

When the Reviewer sends findings back, the Developer is the role that acts on them. In Coordinator mode, the Coordinator passes the findings on, with the fixes to make.

QA#

Runs verification independently of the agent that wrote the code — your test suite, the quality gates configured for the project, and the acceptance criteria from the specification.

QA reports a verdict. It does not fix what it finds; failures go back to the Developer as rework.

Reviewer#

Reads the finished diff and produces findings, applying any review rules your organisation has configured. Findings are either routed back to the developer as rework or attached to the pull request for you.

Web tester#

Drives a real browser against a running preview of your application to check user flows end to end. It is used where an assertion about behaviour cannot be made from the code alone.

Explorer#

A read-only research role. Other agents use it to answer questions about a codebase without loading everything into their own context — "where is authentication handled", "what calls this function".

Dependency analyser#

Examines dependencies and how changes ripple across a codebase, including across projects where cross-project dependencies are configured.

Why the separation matters#

Four properties follow from splitting the work this way:

1. Verification is independent. The agent that checks the work is not the agent that wrote it, so it has no stake in the result.
2. Blast radius is bounded. Only the developer role holds code-writing tools, so a failure in review or analysis cannot corrupt your repository.
3. Each role runs a model suited to it. Planning rewards breadth of world knowledge; writing code that compiles rewards something else again. An AI profile carries one model per role for exactly this reason.
4. Completion is decided by checks, not by the agent in charge. In Coordinator mode, the agent that steers the task cannot end it without QA's and the reviewer's verdicts.

Next#

Return to How a task becomes a pull request for the stages these roles map onto, or What is Coroid for the shorter overview.