# Roles

A role is a Markdown file in `~/.agents/agents/` that tackroom renders into each harness's native agent format. Edit the canonical `.md`; sync regenerates the rendered files and every one carries a `Generated by tackroom` marker.

```bash
tackroom doctor     # validates every role: name, description, instructions
tackroom sync       # renders roles into each harness
```

## Write a role

The file has YAML frontmatter and the system prompt as body. Required: `name` (lowercased), `description` and a non-empty body. Optional: `model`, `effort`, `tools` (a list or a comma-separated string), `color`, and per-harness override blocks.

```markdown
---
name: reviewer
description: Reviews diffs against the spec. Read-only.
model: sonnet
tools: [Read, Glob, Grep]
codex:
  model: <exact-model-id>
---

You review code changes. Report findings; do not edit files.
```

`setup` copies six starter roles (`architect`, `builder`, `general`, `researcher`, `reviewer`, `tester`) into a new config root only. After that they are your files: sync never overwrites them, and a role you delete stays deleted.

## Where each harness gets its role

| Harness | Format | Path |
|---|---|---|
| Claude Code | Markdown | `~/.claude/agents/<name>.md` |
| Codex | TOML | `~/.codex/agents/<name>.toml` |
| Factory Droid | Markdown | `~/.factory/droids/<name>.md` |
| OpenCode | Markdown | `~/.config/opencode/agents/<name>.md` |
| Pi (`pi-subagents`) | Markdown | `~/.pi/agent/agents/<name>.md` |
| OMP | Markdown | `~/.omp/agent/agents/<name>.md` |
| Qwen Code | Markdown | `~/.qwen/agents/<name>.md` |
| Cursor | Markdown | `~/.cursor/agents/<name>.md` |
| GitHub Copilot CLI | Markdown | `~/.copilot/agents/<name>.agent.md` |
| Grok Build | Markdown | `~/.grok/agents/<name>.md` |
| Gemini CLI | Markdown, `kind: local` | `~/.gemini/agents/<name>.md` |
| Kimi Code | Markdown | `~/.kimi-code/agents/<name>.md` |

Paths follow each harness's `agent_root` in `tackroom.yaml`.

- Amp, Antigravity CLI, Devin and DeepSeek Harness have no role surface tackroom can render, so it writes them none.
- Devin loads the role files in `~/.agents/agents/` itself when that is your config root, with their tool names as written ([harnesses.md](harnesses.md#devin)).
- Pi role files do nothing unless the `pi-subagents` package is installed; declare it under the Pi agent's `packages:` in `tackroom.yaml`.

## Choose a model

`model` takes a tier (`haiku`, `sonnet`, `opus`) or an exact id. Each harness handles a tier differently:

| Harness | A tier becomes | Exact override |
|---|---|---|
| Claude Code | written as given | `claude.model` |
| Factory Droid | `custom:gpt-5.5(low)`, `(medium)` or `(high)`; no model gives `inherit` | `droid.model` |
| Codex | omitted, so Codex uses its own default | `codex.model` |
| OMP | written as given | `omp.model` |
| Pi, OpenCode, GitHub Copilot CLI, Grok Build, Gemini CLI | omitted, so the harness inherits | `pi.model`, `opencode.model`, `copilot.model`, `grok.model`, `gemini.model` |
| Cursor, Qwen Code | `inherit` | `cursor.model`, `qwen.model` |
| Kimi Code | no model is written | none |

An exact id in `model` is passed through to every harness except Kimi Code. To pin one model for all roles that declare none, set `role_model` on the agent entry in `tackroom.yaml`; a role's own `model` or per-harness override always wins.

Other per-harness keys: `codex.model_reasoning_effort`, `omp.thinking-level`, `pi.thinking`, `droid.reasoning_effort`, `droid.tools`, `opencode.temperature`, `opencode.mode`, `qwen.approval_mode`, `qwen.tools`, `cursor.readonly`, `gemini.tools`.

## Tools

Canonical tool names are mapped per harness. Claude Code and Grok Build keep the names as written (Grok Build resolves them itself).

Gemini CLI, Qwen Code, GitHub Copilot CLI, Pi, OMP, Factory Droid and Kimi Code get their own built-in names, for example `read_file`, `replace` and `run_shell_command` for Gemini CLI, and `read`, `edit` and `execute` for GitHub Copilot CLI. Names without an equivalent are dropped; Factory Droid falls back to read-only tools when none map.

Kimi Code grants every tool to an agent with no `tools` key, so a role whose tools all lack a Kimi Code equivalent fails to render instead of widening. Cursor has no per-agent tool list; `cursor.readonly: true` is its only restriction.

`tools: []` (or `tools: ""`) gives a role no tools, for example a judge that only reads the text it is given. Leaving `tools` out gives the harness default, which is usually every tool.

- Claude Code, GitHub Copilot CLI, Gemini CLI, Kimi Code and OMP get `tools: []`, and Pi gets a bare `tools:`.
- Codex, Cursor, Factory Droid, OpenCode, Qwen Code and Grok Build have no way to give an agent no tools, so their copy of such a role gets that harness's default.
