Quick Start

Get started with ROLES.md in under a minute.

Create the file

Create a ROLES.md file in your project root:

# Implementer

## Responsibilities
- Write code based on provided specifications
- Follow project conventions and patterns
- Keep changes focused and minimal

## Allowed
- Create and modify source files
- Run tests and linters
- Ask clarifying questions

## Forbidden
- Approve or merge changes
- Modify CI/CD configuration
- Make architectural decisions

## Handoff
- Pass to Reviewer when implementation is complete
- Escalate to Architect for design questions

Reference the role

Tell your AI assistant to use the role:

Use the Implementer role from ROLES.md for this task.

Or configure your tool to automatically read the file. See the Configure section for tool-specific instructions.

Add more roles

Expand your ROLES.md with additional roles as needed:

# Reviewer

## Responsibilities
- Review code for correctness
- Identify potential bugs
- Check conventions

## Allowed
- Read all files
- Run tests
- Comment on quality

## Forbidden
- Modify files directly
- Approve own changes

## Handoff
- Return to Implementer with feedback

Best practices

Start simple. Begin with one or two roles. Add complexity only when needed.

Be specific. Vague responsibilities lead to unpredictable behavior. "Write good code" is less useful than "Write code that follows the project's TypeScript conventions".

Define boundaries clearly. The Forbidden section is often more important than Allowed.