---
title: "How the team works"
source: "agents/README.md"
---

> Part of [botgumi docs](https://botgumi.com/docs/llms.txt). Every page: [llms.txt](https://botgumi.com/llms.txt).

# Agents

The agent team that builds an app from botgumi. Instructions are written once and work on both runtimes.

| File | What it is |
|---|---|
| `AGENTS.md` | The app's agent instructions. Copied to the app's root; its `CLAUDE.md` is only `@AGENTS.md`. |
| `orchestrator.md` | Plans, briefs, routes reviews, escalates, stops at human gates. Runs as the main session. |
| `workers/<track>.md` | One per track: backend, ios, android, landing, dashboard, design, docs. An app has only the platform tracks it chose. |
| `reviewers/reviewer.md` | Reviews a PR against `review-rules.md` and posts it with `gh pr review`. |
| `review-rules.md` | Who reviews, the fixed checks, blocking vs non-blocking, the 2-round limit, agents never merge. |
| `model-policy.md` | Default runtime and model per role, the tier rubric, the tokens-low fallback. |
| `intake.md` | How tasks arrive (issues, chat, `botgumi task`), how the runner hears about them, the trust filter. |
| `merge-policy.md` | When the orchestrator may merge, and the revert watch after a bot merge. |
| `task-brief.md` | The brief the orchestrator writes for each task, with tier, runtime and model. |
| `runtimes/` | How each runtime (claude, codex) loads the instructions and runs a role. |

Runtimes and models per role are set in `botgumi.config.ts` (`agents`): any role can use any runtime
and model. Role files carry no model, so the config stays the single source. The `AgentRuntime`
interface is `@botgumi/agent-runtime`.

`botgumi new <app>` copies `AGENTS.md` to the app's root and the role files and docs into `.claude/agents/`.