ROLES.md

Introduction

ROLES.md is a simple, open convention for defining the responsibilities an AI agent is operating under. Create your own roles that fit your workflow.

Where AGENTS.md provides project-specific context and instructions, ROLES.md answers a different question: what role is the agent responsible for fulfilling while it works.

What is a role?

A role describes responsibility, authority, and constraints rather than personality or tone. It defines:

  • What the agent should focus on
  • What it is allowed to do
  • What it must avoid
  • When work should be handed off

Core principles

Separation of concerns

Roles separate what an agent can do from what it is responsible for doing. An agent may have the capability to modify any file, but the Reviewer role restricts it to evaluation only.

Explicit boundaries

Every role should clearly state what actions are allowed and forbidden. Ambiguity leads to unpredictable behavior.

Handoff rules

Roles define when work should transfer to another role. This prevents scope creep and ensures the right expertise is applied at each stage.

Roles vs Subagents

A role is not a subagent. Subagents are autonomous entities delegated by a primary agent to handle specific tasks, each with their own context window and decision-making scope.

A role is a behavioral contract that any agent operates under. The same agent can switch roles without spawning a new entity.

Roles vs Skills

Skills describe what an agent knows how to do. A skill might be "write TypeScript" or "analyze logs". Roles describe what the agent is accountable for in a given context.

File structure

A minimal ROLES.md file contains role definitions in Markdown:

# Implementer

## Responsibilities
- Write code based on specifications
- Follow project conventions

## Allowed
- Create and modify source files
- Run tests

## Forbidden
- Approve changes
- Modify CI/CD

## Handoff
- Pass to Reviewer when complete