The participant file format

The exact format of a participant file in .autodev/participants/. Its structure, each field with its type and default, how it is read, and what happens to a file that is invalid.

Structure #

A participant is one file named <id>.md in .autodev/participants/. It has two parts: optional frontmatter, then a body.

The frontmatter is the block between two --- lines, and the first --- is the first line of the file. A file that does not start that way, or whose closing --- is missing, has no frontmatter, and the whole file is the body. A participant with no frontmatter runs with every default.

The frontmatter is not read as YAML. A small reader takes it, and it accepts only these forms:

• key: value, with a value that may be in single or double quotes. The quotes are removed.
• key: [a, b, c], an inline list.
• A # that follows a space starts a comment, so a # inside a value survives.
• Blank lines and lines without a colon are skipped. A key with no value is skipped. A key the reader does not know is ignored.

A byte order mark and Windows line endings are accepted. The body is everything after the frontmatter, with the whitespace at both ends trimmed.

An example #

This file sets every field. <model> and <effort> stand for whatever the provider's own CLI accepts, and AutoDev keeps no list of them.

---
provider: codex
model: <model>
effort: <effort>
failover: [claude, antigravity]
moves: [say, work_done, handoff, wait, gate, done]
persona: .autodev/personas/reviewer.md
---
Review each change before it is called done.

The team templates #

autodev team template <name> and the panel's team setup write a whole team at once, from one of three templates. Each participant it writes has its instructions as the body and all six moves, and no provider, so it runs on the run's provider until you set one: --provider <id>=<cli> on the command, or a choice in the panel. Its failover is empty.

Applying a template replaces the team. Every participant file the project already has and the template does not name is removed, and one that shares a name is overwritten. The command lists the files it would replace, an unreadable one among them, and waits for --yes. It refuses while any participant is taking a turn. Once it has run, the team is confirmed on this machine.

Fields #

provider is not checked against a list, because a participant file travels with a clone and can name a CLI the next machine lacks. When the name is not one AutoDev knows, the participant runs on the run's provider, and the log gets <id>: provider '<name>' is not available here; running on <provider>. When the name is known but its CLI is not installed, the lane says <provider> is not available on this machine.

The id a participant has is the filename. A frontmatter id is ignored, and the schema has no other key.

Lists #

Lists are inline. failover: [codex, claude] is a list, and [] is an empty one. A list written in YAML's block style is not read:

failover:
  - codex

The failover: line has no value, so it is skipped, and the - codex line has no colon, so it is skipped too. The participant has an empty failover and no message says so. A scalar where a list belongs, such as failover: codex, is an invalid file instead.

Name and identity #

The filename without .md is the identity. It is the key of the participant's session and the name the other participants use in a handoff. The team is sorted by name, and that order decides who opens a thread.

A name cannot contain / and cannot be . or .., because it becomes a path. The panel refuses those, and it refuses a rename to a name that already has a file or is reserved.

audit, user and system are reserved for AutoDev's own voices on the thread. A file with one of those names parses, and it never joins the team. No message says so.

There is no implicit team. With no valid file the run pauses and logs No participants; run paused until a team is set up.

A team that arrived with the project does not run until you confirm it on this machine, because a participant file becomes flags and instructions for a CLI. autodev team confirm does it, and so does the panel. Adding a participant, applying a template and using the default team confirm it as well. A default team is kept in ~/.autodev/team/, in the same format, and the first team you set up is saved there by itself.

An invalid file #

A file is invalid when its fields fail the schema. That happens when a moves entry is not one of the six, when moves or failover is a scalar and not a list, and when a failover entry is empty.

AutoDev drops an invalid file from the team and says nothing about it. No message in the panel or the log names the file, and its lane is not on the grid. The one place that names it is autodev team template, which lists an unreadable file among those it would replace. A file that should be on the team and is not is the sign. If every file is invalid, the run pauses for lack of a team. A file that will not parse also reads as unpinned, which lands on the CLI's own default.

Model and effort #

model and effort are passed to the provider's own CLI as they are written, and only when they are set:

With neither field set, AutoDev passes nothing, and the CLI's own default applies. The run-level model and effort keys are not a fallback: a participant's turn never reads them. For codex, an explicit --model or -m in codexArgs, or a model_reasoning_effort= there, wins over the file. The values are read again at the start of every turn, so a change applies from the participant's next turn and never in the middle of one. On a failover hop the pin does not apply, since it names a model of the participant's own provider, and the entry's :model is used instead.

Instructions and persona #

The body is the participant's instructions. They go into the prompt of a session that is fresh or rotated. A session that is resumed already has them, so an edit to the body reaches the participant when its session starts over.

A persona names another file, and that file's body replaces the participant's own. The persona file's frontmatter, if it has any, is stripped. If the path is outside the project, or the file is missing, AutoDev uses the participant's own body and logs <id>: persona path is outside the project (<path>); using its own body or <id>: persona file not found (<path>); using its own body. With no instructions at all, the prompt says (no persona configured — use your judgment).

moves is told to the participant in its prompt as Your moves: <list>. The post tool accepts any of the six moves whatever the list says.

How the panel writes the file #

On a lane, Edit prompt opens the file in the editor. Pin and unpin write model and effort. Rename moves the file. A provider dragged onto the team writes a file named after the provider, with provider set and every other field at its default. The CLI does the same things: autodev team edit prints the file's path, pin and unpin write the two fields, rename moves the file, and add writes the file a drag would.

Each of those writes renders the frontmatter again from the fields AutoDev read. It writes them in the order provider, model, effort, failover, moves and persona, leaves out an optional field that is not set, and always writes moves. A comment or an unknown key in the frontmatter does not survive a write from the panel. The body does.

Participants and lanes covers what a participant and a lane are, and Providers and failover covers what failover does. Every config key covers the run-level provider, which a participant that names none runs on. Every CLI command lists the autodev team commands.