Roles
Built-in worker roles, harness and model selection, and project-defined role configuration.
A role is a reusable worker contract: its system prompt, tool restrictions, model default, MCP servers, permissions, and access to browser or terminal tools. The role describes the job; the spawn chooses which installed harness runs it.
Built-in roles
| Role | Purpose | Editing and tools |
|---|---|---|
builder | Implement production-ready features. | Read/write; visible terminal access. |
qa | Review a diff and give a verdict. | Write and Edit disallowed. |
validator | Compare changes with the original specification. | Write and Edit disallowed. |
backend | Work on APIs, services, and databases. | Read/write; visible terminal access. |
frontend | Work on UI, client logic, and styling. | Read/write; visible terminal access. |
devops | Work on CI/CD, infrastructure, Docker, and build tooling. | Read/write; visible terminal access. |
security | Audit authentication, injection, secrets, and common vulnerabilities. | Reports only; Write and Edit disallowed. |
browser_qa | Run visual end-to-end QA in a visible browser pane. | Source edits disallowed; writes contracted to .agent-grid/qa-specs/; browser access enabled. |
There is no built-in pr role. A project can define one in .agent-grid/roles.json; call list_roles to see the roles available in the active project.
Choose the harness and model at spawn time
Any master-capable harness can call spawn_role. Pass harness to run the role on any installed worker harness and optionally pass a harness-specific model.
spawn_role({
role: "qa",
harness: "codex",
model: "gpt-5.6-sol",
prompt: "Review the current diff and report file:line findings."
})If harness is omitted, the worker inherits the master's harness. If model is omitted, the role or harness default applies. Use list_worker_harnesses for the installed catalog and current model suggestions.
Claude backend selection
Claude workers can use one of two backends:
- SDK - streams a structured transcript through the Claude Agent SDK and can receive MCP servers.
- PTY - drives the interactive
claudeCLI and uses the configured Claude CLI account.
Roles that require MCP servers, including browser_qa, use the SDK. Other harnesses use their registered worker runtime rather than the Claude backend setting.
Custom roles
Add .agent-grid/roles.json at the project root to define a role or override a built-in one. Definitions merge over the built-ins.
{
"pr": {
"systemPrompt": "Prepare a pull request and summarize its verification.",
"allowedTools": ["Read", "Bash"],
"disallowedTools": ["Write", "Edit"]
}
}Supported role fields include systemPrompt, allowedTools, disallowedTools, model, maxTurns, maxBudgetUsd, mcpServers, permissionMode, browserAccess, terminalAccess, writePathPrefixes, and backend.
A master can also define a role at runtime with the create_role MCP tool instead of hand-editing the file. It writes to the same .agent-grid/roles.json, whitelisting the same fields (mcpServers and backend are not settable this way). Built-in role names are immutable through this tool: a name matching a built-in (builder, qa, validator, backend, frontend, devops, security, browser_qa) always hard-rejects, even with overwrite: true — pick a different name. overwrite: true only bypasses a collision with an existing custom role, replacing it. Call list_roles first to see what is already defined; its entries now include a source: "builtin" | "custom" field so you can tell the two apart.
writePathPrefixes is an advisory contract. The runtime reinforces it in the worker prompt, but it is not a filesystem sandbox. Use review and post-run auditing when a hard boundary matters.
Related
- Orchestrating agents - spawn and review-loop patterns.
- Coding harnesses - available master and worker runtimes.
- The .agent-grid folder - project-local AgentGrid configuration.