# Custom Agent Roles

Beyond the 7 built-in roles, you can define custom agent roles with specific system prompts, tool permissions, and trust levels.

## File Locations

- **User-global roles:** `~/.coalcode/agents/roles/<name>.md`
- **Project-local roles:** `.coals/agents/<name>.md`

Project-local roles override user-global roles of the same name.

## Markdown Format

Each role is defined in a markdown file with three sections:

```markdown
# Security Auditor

Audits code for security vulnerabilities and produces a structured report.

## System Prompt

You are a security-focused code reviewer. Your job is to identify:
- SQL injection vulnerabilities
- Authentication and authorization flaws
- Insecure direct object references
- XSS and CSRF risks
- Hardcoded secrets or credentials

Organize findings by severity: Critical, High, Medium, Low.
Include the file path and line number for each finding.
Suggest specific fixes for each issue.

## Configuration

- trust_level: readonly
- token_budget: 80000
- time_limit: 180000
- allowed_tools: read_file, glob, grep, list_dir, web_search
- can_spawn_children: false
```

### Sections

1. **`# Role Name`** — The display name. The filename is used as the role identifier for commands.
2. **Description** — Text between the heading and the first `##`. Shown in `/roles` output.
3. **`## System Prompt`** — The full system prompt injected into the agent's context. This defines the agent's personality, expertise, and task approach.
4. **`## Configuration`** — Key-value pairs controlling the agent's permissions and limits.

## Configuration Options

| Key | Values | Default | Description |
| --- | --- | --- | --- |
| `trust_level` | `readonly`, `supervised`, `autonomous` | `supervised` | Controls tool approval behavior |
| `token_budget` | Number | `128000` | Maximum tokens for this agent's session |
| `time_limit` | Milliseconds | `300000` (5 min) | Maximum wall-clock time before timeout |
| `allowed_tools` | Comma-separated tool names | All tools | Tools the agent can use |
| `denied_tools` | Comma-separated tool names | None | Tools explicitly blocked |
| `can_spawn_children` | `true` or `false` | `false` | Whether the agent can spawn child agents |

### Trust Levels

- **readonly** — Cannot write files, edit files, or run commands. Safe for analysis tasks.
- **supervised** — Can use all allowed tools but pauses for approval on writes and commands (unless in Auto mode).
- **autonomous** — Runs without interruption. All tool calls execute immediately.

### Tool Names

Available tool names for `allowed_tools` and `denied_tools`:

`read_file`, `write_file`, `edit_file`, `bash`, `python`, `applescript`, `glob`, `grep`, `list_dir`, `web_search`, `http_request`, `todo_update`, `spawn_agent`, `delegate`

Wildcards are supported:

- `mcp__*` — All MCP tools from all servers
- `mcp__github__*` — All tools from the GitHub MCP server
- `*` — All tools

## Managing Roles

### Create a new role

```
/role create security-auditor
```

This scaffolds a template markdown file and shows you the path.

### Edit an existing role

```
/role edit security-auditor
```

Shows the file path so you can open it in your editor.

### Delete a role

```
/role delete security-auditor
```

Only user-defined roles can be deleted. Built-in roles cannot be removed.

### List all roles

```
/roles
```

Shows every available role with its source (`builtin`, `user`, or `project`), trust level, and allowed tools.

## Using Custom Roles

Once created, use custom roles exactly like built-in ones:

```
/agent security-auditor review the payment processing module
@security-auditor check src/api/ for OWASP top 10 issues
```

Custom roles also work in team presets if referenced by name.

## Examples

### Documentation Writer

```markdown
# Doc Writer

Generates comprehensive documentation for code modules.

## System Prompt

You are a technical documentation specialist. When given a module or directory:
1. Read all source files to understand the API
2. Document every exported function, class, and type
3. Include usage examples for each public API
4. Note any configuration or environment requirements
5. Write in clear, concise language suitable for other developers

Output format: Markdown with code examples.

## Configuration

- trust_level: readonly
- token_budget: 100000
- time_limit: 300000
- allowed_tools: read_file, glob, grep, list_dir, web_search
- can_spawn_children: false
```

### Migration Helper

```markdown
# Migration Helper

Assists with codebase migrations and upgrades.

## System Prompt

You help migrate codebases between framework versions or technology stacks. Your approach:
1. Analyze the current codebase to understand what needs to change
2. Research the target version's migration guide
3. Make changes incrementally, testing after each step
4. Preserve existing behavior — don't refactor beyond what the migration requires

Always run tests after changes. If tests fail, fix the issue before moving on.

## Configuration

- trust_level: supervised
- token_budget: 128000
- time_limit: 600000
- allowed_tools: read_file, write_file, edit_file, bash, glob, grep, list_dir, web_search, http_request
- can_spawn_children: false
```