# Role definition

URL: /code/project-structure/role-definition · Id: `convention:role-definition`

> A Role definition seats one Worker, Human or Agent, in a Role with its Mandate and Limits; Agents have no folder of their own.

A [Role](/business/nouns/role) definition seats one [Worker](/business/nouns/worker), [Human](/business/nouns/human) or [Agent](/business/nouns/agent), in a Role with its [Mandate](/business/nouns/mandate) and [Limits](/business/nouns/limit); Agents have no folder of their own.

| Property | Value |
| --- | --- |
| Path | `agents/[team]/[role].mdx` |
| Holds | [Role](/business/nouns/role) |
| Kind | file |
| Leaders | db-first, git-first |
| Team | [People Team](/agents/people) |
| Written by | [Role.staff](/business/nouns/role/staff), [Change.merge](/business/nouns/change/merge) |
| Compiled by | [StartupBuilder](/code/builders/startup) |

### Example
`agents/finance/controller.mdx` in a Startup repository. Closewise, a sample business, declares a `Close` Noun.

```mdx title="agents/finance/controller.mdx"
---
worker: { agent: Cora }
purpose: Every client's books close on time and tie out.
responsibilities:
  - Reconciles every client account by the third business day.
  - Explains every difference over $50 before the close.
results: [days-to-close]
standards:
  - Closes each client's month within three business days of month end.
limits:
  - { verb: Mandate.spend, amount: 200, period: 1m }
approvals: [Close.close]
autonomy: { default: supervised, byClass: { high: assist } }
schedule: daily
channels: [email]
escalatesTo: founding/founder
---
Close each client's books within three business days of month end.
Escalate any difference over $50 you cannot explain.
```

### Props
The frontmatter keys the file takes. The body is its prose.

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `worker` | `json` | No | Who fills it: `{ agent: <name> }` or `{ human: <id> }`. Unset, the seat’s role agent fills it. |
| `purpose` | `text` | Yes | Why the Role exists, in one sentence. |
| `responsibilities` | `string[]` | No | Its standing duties, one checkable sentence each. |
| `results` | list of [Metric](/business/nouns/metric) | No | The Metrics that judge the seat; each Metric names this Role as its owner. |
| `standards` | `string[]` | No | How well the work is done: service levels and quality bars, one sentence each. |
| `limits` | `json` | No | Per Verb, the most it does per call or per period before an Approval: `{ verb, amount, count, percent, period }`. |
| `mandates` | `json` | No | Standing grants it calls without asking each time: `{ id, grants, definition }`. |
| `autonomy` | `json` | No | Its rung on the ladder, with a different rung per decision class where it differs: `{ default, byClass }`. |
| `approvals` | list of [Verb](/business/nouns/verb) | No | Verbs of this seat that wait for the founder’s yes before they run. |
| `schedule` | `string` | No | When it works unprompted: a cadence such as `daily`. |
| `channels` | `string[]` | No | Where it answers: `email`, `chat`, `sms`, `phone` or `social`. |
| `aliases` | `string[]` | No | The founder’s words for the seat, such as `CFO`; each resolves to this Role. |
| `handsOffTo` | list of [Role](/business/nouns/role) | No | The Roles it passes work to. |
| `escalatesTo` | [Role](/business/nouns/role) | No | The Role it hands off to when it cannot decide. |
| `skills` | list of [Skill](/business/nouns/skill) | No | The Skills its agent has, each with the instructions that teach it. |
| `evaluator` | [Evaluator](/business/nouns/evaluator) | No | The Evaluator that grades its work. |

### Generates
[StartupBuilder](/code/builders/startup) compiles it into these records, Verbs and routes.

| Kind | What |
| --- | --- |
| Records | [Role](/business/nouns/role), [Worker](/business/nouns/worker), [Mandate](/business/nouns/mandate), [Limit](/business/nouns/limit) |
| Verbs | [Role.staff](/business/nouns/role/staff) |
| Routes | None. |