Roles: Specialized Agents for Implementation

When it comes to the implementation phase of the Agent OS spec-driven development workflow, every feature implementation is unique, requiring different specialized skills. This is where Agent OS' system of specialized role assignment comes into play.

This page covers:

• What is a role (a.k.a. agent)?
• The implementer-verifier pattern
• How task assignment works
• Execution process
• Agent configuration
• Creating custom roles (a.k.a. agents)
• Best practices

What is a role (a.k.a. agent)?

The term 'role' is used interchangeably with the term 'agent'. That's because they're used in slightly different ways, depending on whether you're using Agent OS in multi-agent mode or single-agent mode:

• In Multi-agent mode, each "role" gets compiled to an actual subagent, which will have tasks assigned and delegated to it.
• In Single-agent mode, each "role" gets compiled to a numbered prompt, which will be fed into your AI tool sequentially.

Same concept and useage, slightly different execution.

The implementer-verifier pattern

Agent OS uses two types of specialized agents:

Implementer agents

Implementers are the builders, each specializing in a specific technical domain:

• database-engineer: Handles migrations, models, schemas, and queries
• api-engineer: Creates endpoints, controllers, and business logic
• ui-designer: Builds frontend components and user interfaces
• testing-engineer: Writes tests and ensures coverage

You can add and customize your own implementer roles to your profile's roles/implementers.yml file (see Creating custom agents below).

Agent OS will intelligently assign tasks to the appropriate implementer based on the task's requirements and the implementer's skills. Each implementer only sees their task's instructions and the most relevant standards they should align to when implementing their work.

Verifier agents

Verifiers review the work of implementers to ensure:

• Standards compliance
• Completeness of requirements
• Code quality and maintainability

Common verifiers include:

• backend-verifier: Reviews database and API implementations
• frontend-verifier: Checks UI components and user experience

How task assignment works

Task assignment is done automatically and intelligently by the agent instructions built into Agent OS. Here is a breakdown of what's actually happening when it comes to planning and executing a feature's spec:

1

Task assignment during spec creation

When you reach the spec creation phase, Agent OS will intelligently assign task groups to the appropriate implementer based on the task's requirements and the implementer's skills.

These implementer role assignments are documented in the spec's tasks.md file and used in implementation phase to direct the delegation of tasks to the appropriate implementer.

1. Agent OS reads through your spec's tasks.md file
2. Tasks are grouped based on their technical domain
3. Each group is assigned to the appropriate implementer

2

Implementation of tasks by implementers

When you reach the spec implementation phase, Agent OS delegates the implementation of each task group to the appropriate implementer based on the specified assignemnts in the spec's tasks.md file.

It also finds each implementer's associated verifier and assigns the task group to that verifier for review.

1. Agent OS reads through your spec's tasks.md file
2. Task groups are delegated to the specified implementers
3. Each implementer has assigned verifier(s) as specified in roles/implementers.yml. These associations are used to assign the task group to the appropriate verifier for review.

Example task assignment

Here's a simplified example. Given a user authentication feature task list:

## Database Tasks
- Create users table migration
- Add password hashing to User model

## API Tasks
- Create /auth/login endpoint
- Create /auth/register endpoint

## Frontend Tasks
- Build login form component
- Add registration page

Agent OS automatically assigns:

• Database tasks → database-engineer → verified by backend-verifier
• API tasks → api-engineer → verified by backend-verifier
• Frontend tasks → ui-designer → verified by frontend-verifier

Execution process

Multi-agent mode

Execution process:

In multi-agent mode, an entire spec's implementation can be run with a single command.

1. Run /implement-spec command
2. Main agent reads this spec's task list (agent-os/specs/[this-spec]/tasks.md) and analyzes task group assignments
3. Main agent delegates task groups to assigned subagents
4. Subagents implement their tasks, document their implementation, and report back to main agent
5. Main agent delegates task groups to assigned verifiers
6. Verifiers review completed work, document their report, and report back to main agent
7. Main agent reports back to you once complete

Single-agent mode

Execution process:

In single-agent mode, you begin the implementation of a spec by running:

agent-os/commands/implement-spec/1-implement-spec.md run this

This will instruct your AI tool's agent to:

1. Read this spec's task list (agent-os/specs/[this-spec]/tasks.md) and analyzes task group assignments
2. Create a prompt for each task group and saves it to agent-os/specs/[this-spec]/implementation/prompts/, each with a number indicating the order in which they should be run. Each prompt includes the specific task group details, instructions and standards that your agent should follow when you give them this prompt.

You then run each of the generated prompts sequentially in your AI tool. You can simply @ reference the prompt markdown file and append "run this" (or similar) to your prompt to instruct your AI tool to read and run the instructions in that file.

@agent-os/specs/[this-spec]/implementation/prompts/1-database-engineer-setup.md run this

Continue with remaining prompts in order. These will cover implementation of each task group along with verification of the work.

For full control, you can run each prompt individually and review the work before proceeding to the next prompt. But if your AI tool supports it, you can also queue them all up to run one after another automatically.

Role (a.k.a. agent) configuration

Agents are defined in your profile's roles folder, located in your base installation. Your profile's role files are then copied into your project installation, making them available for use in your spec implementations.

Here are the role files for the default profile in your base installation:

• ~/agent-os/profiles/default/roles/implementers.yml
• ~/agent-os/profiles/default/roles/verifiers.yml

Those get installed in your project installation at:

• your-project/agent-os/roles/implementers.yml
• your-project/agent-os/roles/verifiers.yml

Anatomy of a implementer and verifier

Implementers and verifies are defined using a very similar .yml format which includes the following pieces of information:

Here's an example of an implementer role, defined in ~/agent-os/profiles/default/roles/implementers.yml:

implementers:
  - id: database-engineer
    description: Handles migrations, models, schemas, database queries
    your_role: You are a database engineer. Your role is to implement database migrations, models, schemas, and database queries.
    tools: Write, Read, Bash, WebFetch
    model: opus
    color: orange
    areas_of_responsibility:
      - Create database migrations
      - Create database models
      - Create database queries
      - Create database seed data
      - Create database indexes
      - Create database associations
    example_areas_outside_of_responsibility:
      - Create API endpoints
      - Create UI components
      - Create API responses
      - Create frontend components
      - Write backend business logic
    standards:
      - global/*
      - backend/*
      - testing/*
    verified_by:
      - backend-verifier

Here's an example of a verifier role, defined in ~/agent-os/profiles/default/roles/verifiers.yml:

verifiers:
  - id: backend-verifier
    description: Verifies database and API implementations
    your_role: You are a backend verifier. Your role is to verify the implementation of database migrations, models, schemas, database queries, API endpoints, controllers, and backend business logic.
    tools: Write, Read, Bash, WebFetch
    model: sonnet
    color: pink
    areas_of_responsibility:
      - Verify database migrations
      - Verify database models
      - Verify database schemas
      - Verify database queries
      - Verify API endpoints
      - Verify API responses
      - Verify backend business logic
      - Verify authentication/authorization
    example_areas_outside_of_responsibility:
      - Verify UI components
      - Verify frontend components
      - Verify styling and layouts
      - Verify responsive design
    standards:
      - global/*
      - backend/*
      - testing/*

Creating custom roles (a.k.a. agents)

To create a custom role (a.k.a. agent), you can use the create-role.sh script to add a new role a profile in your base installation.

~/agent-os/scripts/create-role.sh

The script's wizard walks you through defining the agent's expertise, setting areas of responsibility, selecting relevant standards, and pairing with verifiers. All of the information shown in the configurations above will be automatically populated for you using this wizard.

After the wizard is complete, the new role will be added to your profile's roles/implementers.yml or roles/verifiers.yml. You're welcome to edit those files to further customize your role, just be sure to keep their format and structure intact.

Best practices

• Keep agents focused: Each agent should have a clear, narrow area of expertise
• Match your tech stack: Create agents that align with your technology choices
• Pair thoughtfully: Match implementers with verifiers who understand their domain
• Iterate and improve: Create new agents to handle recurring specialized needs