# Roles

URL: /code/file-conventions/roles · Id: `page:code/file-conventions/roles`

> A Role file in agents/ holds one Role contract, key for key, and the Worker filling it.

A [Role](/business/nouns/role) file in `agents/[team]/` is one [Role](/business/nouns/role), written as its contract, and the [Worker](/business/nouns/worker) filling it. It implements [Roles](/agents/roles).

```text
agents/customer/
└── success-manager.mdx      the Role and its agent
```

## Reference
MDX. Frontmatter is the [Role contract](/agents/roles), key for key, plus `instructions`; the body is the Worker's instructions.

| Key | Type | Holds |
| --- | --- | --- |
| `worker` | `{ agent }` or `{ human }` | Who fills the seat; unset, its role agent |
| `purpose` | string | Why the seat exists, in one sentence |
| `responsibilities` | list | Its standing duties, each one checkable |
| `results` | [Metric](/business/nouns/metric) ids | The numbers that judge the seat |
| `standards` | list | Response times and quality bars |
| `limits` | list of `{ verb, amount, count, percent, period }` | The most it does per [Verb](/business/nouns/verb) before an [Approval](/business/nouns/approval) |
| `mandates` | list of `{ id, grants, definition }` | Verbs it calls without asking each time |
| `autonomy` | `{ default, byClass }` | Its rung, `assist`, `supervised` or `full`, per decision class |
| `approvals` | Verb ids | Verbs that wait for the founder's yes before they run |
| `schedule` | cadence | When it works unprompted, such as `daily` |
| `channels` | list | Where it answers: `email`, `chat`, `sms`, `phone`, `social` |
| `aliases` | list | The founder's words for the seat, such as `CFO` |
| `handsOffTo`, `escalatesTo` | Role paths | Where its work goes next, and where it goes past its [Limits](/business/nouns/limit) |
| `instructions` | prompt path | A file in [`prompts/`](/code/file-conventions/prompts) used in place of the body |

A seat's [Processes](/business/nouns/process) are not a key. Each [Process file](/code/file-conventions/processes) names its `owner`, and the Role page lists them.

## Examples
### Minimal
```mdx title="agents/customer/success-manager.mdx"
---
purpose: Every resident answers before the renewal date.
---
```

### Leaseline
```mdx title="agents/customer/success-manager.mdx"
---
worker: { agent: Rae }
purpose: Every resident answers before the renewal date.
responsibilities:
  - Send each renewal notice at 60 days.
  - Answer residents' questions about the new terms.
  - List every resident who has not answered after a week.
results: [renewals-answered]
standards:
  - Answers a resident's question within one business day.
limits:
  - { verb: Message.create, count: 300, period: 1d }
approvals: [Lease.notify]
autonomy: { default: supervised, byClass: { high: assist } }
schedule: daily
channels: [email, sms]
escalatesTo: founding/founder
---
Write as the property manager's assistant. Never promise a rent the manager has not set.
```

## What it builds
The [StartupBuilder](/code/builders/startup) compiles the file and staffs the seat with `Role.staff`.

- a `Role` and a `Worker`, an [Agent](/business/nouns/agent) or a [Human](/business/nouns/human)
- a [Mandate](/business/nouns/mandate) and its [Limits](/business/nouns/limit); a call past a Limit waits as an [Approval](/business/nouns/approval)
- the agent's [Tools](/business/nouns/tool): the Verbs the Role may call
- the [Event](/business/nouns/event) `Role.staffed`

## Good to know
- Moving a seat from a person to an agent is a one-line edit to `worker`. No caller sees it.
- Autonomy climbs per Verb on the Role's [tests](/code/file-conventions/role-tests).