El formato del archivo de participante

El formato exacto de un archivo de participante en .autodev/participants/. La estructura, cada campo con su tipo y valor predeterminado, cómo se lee, y qué pasa con un archivo inválido.

Estructura #

Un participante es un archivo llamado <id>.md en .autodev/participants/. Tiene dos partes: un frontmatter opcional y, después, un cuerpo.

El frontmatter es el bloque entre dos líneas ---, y el primer --- es la primera línea del archivo. Un archivo que no empieza así, o cuyo --- de cierre falta, no tiene frontmatter, y el archivo entero es el cuerpo. Un participante sin frontmatter se ejecuta con todos los valores predeterminados.

El frontmatter no se lee como YAML. Lo procesa un lector pequeño, que acepta solo estas formas:

key: value, con un valor que puede ir entre comillas simples o dobles. Las comillas se quitan.
key: [a, b, c], una lista en línea.
Un # que sigue a un espacio empieza un comentario, así que un # dentro de un valor sobrevive.
Las líneas en blanco y las líneas sin dos puntos se omiten. Una clave sin valor se omite. Una clave que el lector no conoce se ignora.

Se aceptan una marca de orden de bytes y los finales de línea de Windows. El cuerpo es todo lo que viene después del frontmatter, con el espacio de ambos extremos recortado.

Un ejemplo #

Este archivo define todos los campos. <model> y <effort> representan lo que acepte la CLI del proveedor, y AutoDev no mantiene una lista de ellos.

.autodev/participants/reviewer.md

---
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.

Las plantillas de equipo #

autodev team template <name> y la configuración de equipo del panel escriben un equipo entero de una vez, a partir de una de tres plantillas. Cada participante que escriben tiene sus instrucciones como cuerpo y las seis jugadas, y ningún provider, así que corre en el provider de la ejecución hasta que definas uno: --provider <id>=<cli> en el comando, o una elección en el panel. Su failover queda vacío.

Plantilla	Participantes	Qué hacen
`solo`	`builder`	Un participante se ocupa del objetivo desde la planificación hasta commits revisables.
`builder-reviewer`	`builder`, `reviewer`	El constructor entrega cada cambio y dice qué comprobar. El revisor lo comprueba antes de que la ejecución siga, y lo da por bueno o lo devuelve al constructor con el archivo y la línea.
`manager-builder-reviewer`	`manager`, `builder`, `reviewer`	El gestor no escribe código: divide el objetivo en bloques, entrega cada uno entero al constructor, y decide cuándo algo está atascado y cuándo la ejecución terminó. El constructor y el revisor trabajan como en la plantilla anterior.

Aplicar una plantilla reemplaza el equipo. Todo archivo de participante que el proyecto ya tiene y que la plantilla no nombra se elimina, y uno con el mismo nombre se sobrescribe. El comando lista los archivos que reemplazaría, también uno ilegible, y espera --yes. Se niega mientras algún participante está en un turno. Cuando termina, el equipo queda confirmado en esta máquina.

Campos #

Campo	Tipo	Predeterminado	Qué acepta
`provider`	cadena	El `provider` de la ejecución	Cualquier cadena. `claude`, `codex` y `antigravity` son los que AutoDev ejecuta.
`model`	cadena	Ninguno: el valor predeterminado de la propia CLI	Cualquier cadena. Nunca se comprueba.
`effort`	cadena	Ninguno: el valor predeterminado de la propia CLI	Cualquier cadena. Nunca se comprueba.
`failover`	lista en línea de `provider[:model]`	Una lista vacía	Entradas en orden. Una entrada que nombra una CLI que esta máquina no tiene se omite cuando la ejecución la necesita.
`moves`	lista en línea	Las seis	Cualquiera de `say`, `work_done`, `handoff`, `wait`, `gate` y `done`.
`persona`	cadena, una ruta	Ninguno	Una ruta relativa al proyecto, que debe quedarse dentro de él.

provider no se comprueba contra una lista, porque un archivo de participante viaja con un clon y puede nombrar una CLI que la siguiente máquina no tiene. Cuando el nombre no es uno que AutoDev conoce, el participante se ejecuta en el provider de la ejecución, y el log recibe <id>: provider '<name>' is not available here; running on <provider>. Cuando el nombre es conocido pero su CLI no está instalada, la lane dice <provider> is not available on this machine.

El id de un participante es el nombre del archivo. Un id en el frontmatter se ignora, y el schema no tiene otra clave.

Listas #

Las listas son en línea. failover: [codex, claude] es una lista, y [] es una lista vacía. Una lista escrita en el estilo de bloque de YAML no se lee:

not read

failover:
  - codex

La línea failover: no tiene valor, así que se omite, y la línea - codex no tiene dos puntos, así que también se omite. El participante queda con failover vacío y ningún mensaje lo avisa. Un escalar donde va una lista, como failover: codex, es un archivo inválido.

Nombre e identidad #

El nombre del archivo sin .md es la identidad. Es la clave de la sesión del participante y el nombre que los demás participantes usan en un handoff. El equipo se ordena por nombre, y ese orden decide quién abre un hilo.

Un nombre no puede contener / y no puede ser . ni .., porque se convierte en una ruta. El panel rechaza esos, y rechaza renombrar a un nombre que ya tiene un archivo o que está reservado.

audit, user y system están reservados para las voces del propio AutoDev en el hilo. Un archivo con uno de esos nombres se analiza, y nunca entra en el equipo. Ningún mensaje lo avisa.

No existe un equipo implícito. Sin ningún archivo válido, la ejecución se pausa y registra No participants; run paused until a team is set up.

Un equipo que llegó con el proyecto no corre hasta que lo confirmes en esta máquina, porque un archivo de participante se convierte en flags e instrucciones para una CLI. autodev team confirm lo hace, y el panel también. Añadir un participante, aplicar una plantilla y usar el equipo predeterminado también lo confirman. Un equipo predeterminado se guarda en ~/.autodev/team/, con el mismo formato, y el primer equipo que armas se guarda allí solo.

Un archivo inválido #

Un archivo es inválido cuando sus campos no pasan el schema. Ocurre cuando una entrada de moves no es una de las seis, cuando moves o failover es un escalar y no una lista, y cuando una entrada de failover está vacía.

AutoDev saca del equipo un archivo inválido y no dice nada de él. Ningún mensaje en el panel o en el log nombra el archivo, y su lane no aparece en la cuadrícula. El único lugar que lo nombra es autodev team template, que lista un archivo ilegible entre los que reemplazaría. Un archivo que debería estar en el equipo y no está es la señal. Si todos los archivos son inválidos, la ejecución se pausa por falta de equipo. Un archivo que no se puede analizar también se lee como no fijado, lo que cae en el valor predeterminado de la propia CLI.

Modelo y esfuerzo #

model y effort se pasan a la CLI del propio proveedor tal como están escritos, y solo cuando están definidos:

Proveedor	`model`	`effort`
`claude`	`<cli> --model <model>`	`<cli> --effort <effort>`
`codex`	`<cli> -m <model>`	`<cli> -c model_reasoning_effort=<effort>`
`antigravity`	`<cli> --model <model>`	`<cli> --effort <effort>`

Sin ninguno de los dos campos definido, AutoDev no pasa nada, y vale el valor predeterminado de la propia CLI. Las claves model y effort de la ejecución no son un plan B: el turno de un participante nunca las lee. Para codex, un --model o -m explícito en codexArgs, o un model_reasoning_effort= allí, vale más que el archivo. Los valores se leen de nuevo al inicio de cada turno, así que un cambio vale desde el siguiente turno del participante y nunca a mitad de uno. En un salto de failover la fijación no se aplica, ya que nombra un modelo del proveedor del propio participante, y se usa en su lugar el :model de la entrada.

Instrucciones y persona #

El cuerpo son las instrucciones del participante. Entran en el prompt de una sesión nueva o rotada. Una sesión retomada ya las tiene, así que una edición del cuerpo llega al participante cuando su sesión vuelve a empezar.

Una persona nombra otro archivo, y el cuerpo de ese archivo reemplaza el del propio participante. El frontmatter del archivo de persona, si lo tiene, se quita. Si la ruta está fuera del proyecto, o el archivo falta, AutoDev usa el cuerpo del propio participante y registra <id>: persona path is outside the project (<path>); using its own body o <id>: persona file not found (<path>); using its own body. Sin ninguna instrucción, el prompt dice (no persona configured — use your judgment).

moves se le informa al participante en su prompt como Your moves: <list>. La herramienta post acepta cualquiera de las seis jugadas, diga lo que diga la lista.

Cómo escribe el panel el archivo #

En una lane, Edit prompt abre el archivo en el editor. Pin y unpin escriben model y effort. Rename mueve el archivo. Un proveedor arrastrado al equipo escribe un archivo con el nombre del proveedor, con provider definido y todo otro campo en su valor predeterminado. La CLI hace lo mismo: autodev team edit imprime la ruta del archivo, pin y unpin escriben los dos campos, rename mueve el archivo, y add escribe el archivo que escribiría un arrastre.

Cada una de esas escrituras renderiza de nuevo el frontmatter a partir de los campos que AutoDev leyó. Los escribe en el orden provider, model, effort, failover, moves y persona, deja fuera un campo opcional que no está definido, y siempre escribe moves. Un comentario o una clave desconocida en el frontmatter no sobrevive a una escritura desde el panel. El cuerpo sí.

Participantes y lanes trata de qué son un participante y una lane, y Proveedores y failover trata de lo que hace failover. Todas las claves de configuración trata del provider de la ejecución, en el que corre un participante que no nombra ninguno. Todos los comandos de la CLI lista los comandos autodev team.