O formato do arquivo de participante

O formato exato de um arquivo de participante em .autodev/participants/. A estrutura, cada campo com seu tipo e padrão, como é lido, e o que acontece com um arquivo inválido.

Estrutura #

Um participante é um arquivo chamado <id>.md em .autodev/participants/. Ele tem duas partes: um frontmatter opcional e, depois, um corpo.

O frontmatter é o bloco entre duas linhas ---, e o primeiro --- é a primeira linha do arquivo. Um arquivo que não começa assim, ou cujo --- de fechamento falta, não tem frontmatter, e o arquivo inteiro é o corpo. Um participante sem frontmatter roda com todos os padrões.

O frontmatter não é lido como YAML. Um leitor pequeno o processa, e ele aceita só estas formas:

• key: value, com um valor que pode estar entre aspas simples ou duplas. As aspas são removidas.
• key: [a, b, c], uma lista em linha.
• Um # depois de um espaço começa um comentário, então um # dentro de um valor sobrevive.
• Linhas em branco e linhas sem dois-pontos são ignoradas. Uma chave sem valor é ignorada. Uma chave que o leitor não conhece é ignorada.

Uma marca de ordem de bytes e finais de linha do Windows são aceitos. O corpo é tudo o que vem depois do frontmatter, com o espaço nas duas pontas removido.

Um exemplo #

Este arquivo define todos os campos. <model> e <effort> representam o que a CLI do provedor aceitar, e o AutoDev não mantém lista deles.

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

Os modelos de equipe #

autodev team template <name> e a configuração de equipe do painel escrevem uma equipe inteira de uma vez, a partir de um de três modelos. Cada participante que ele escreve tem as instruções como corpo e as seis jogadas, e nenhum provider, então roda no provider da execução até você definir um: --provider <id>=<cli> no comando, ou uma escolha no painel. O failover dele fica vazio.

Aplicar um modelo substitui a equipe. Todo arquivo de participante que o projeto já tem e que o modelo não nomeia é removido, e um de mesmo nome é sobrescrito. O comando lista os arquivos que substituiria, inclusive um ilegível, e espera --yes. Ele recusa enquanto algum participante está em um turno. Depois de executado, a equipe fica confirmada nesta máquina.

Campos #

O provider não é conferido contra uma lista, porque um arquivo de participante viaja com um clone e pode nomear uma CLI que a próxima máquina não tem. Quando o nome não é um que o AutoDev conhece, o participante roda no provider da execução, e o log recebe <id>: provider '<name>' is not available here; running on <provider>. Quando o nome é conhecido mas a CLI não está instalada, a lane diz <provider> is not available on this machine.

O id de um participante é o nome do arquivo. Um id no frontmatter é ignorado, e o schema não tem outra chave.

Listas #

As listas são em linha. failover: [codex, claude] é uma lista, e [] é uma lista vazia. Uma lista escrita no estilo de bloco do YAML não é lida:

failover:
  - codex

A linha failover: não tem valor, então é ignorada, e a linha - codex não tem dois-pontos, então também é ignorada. O participante fica com failover vazio e nenhuma mensagem avisa. Um escalar onde cabe uma lista, como failover: codex, é um arquivo inválido.

Nome e identidade #

O nome do arquivo sem .md é a identidade. É a chave da sessão do participante e o nome que os outros participantes usam num handoff. A equipe é ordenada por nome, e essa ordem decide quem abre uma thread.

Um nome não pode conter / e não pode ser . nem .., porque vira um caminho. O painel recusa esses, e recusa renomear para um nome que já tem um arquivo ou que é reservado.

audit, user e system são reservados para as vozes do próprio AutoDev na thread. Um arquivo com um desses nomes faz parse, e nunca entra na equipe. Nenhuma mensagem avisa.

Não existe equipe implícita. Sem nenhum arquivo válido, a execução pausa e registra No participants; run paused until a team is set up.

Uma equipe que veio com o projeto não roda até você confirmá-la nesta máquina, porque um arquivo de participante vira flags e instruções para uma CLI. autodev team confirm faz isso, e o painel também. Adicionar um participante, aplicar um modelo e usar a equipe padrão também confirmam. Uma equipe padrão fica em ~/.autodev/team/, no mesmo formato, e a primeira equipe que você monta é salva ali sozinha.

Um arquivo inválido #

Um arquivo é inválido quando seus campos falham no schema. Isso acontece quando uma entrada de moves não é uma das seis, quando moves ou failover é um escalar e não uma lista, e quando uma entrada de failover está vazia.

O AutoDev tira um arquivo inválido da equipe e não diz nada sobre ele. Nenhuma mensagem no painel ou no log nomeia o arquivo, e a lane dele não aparece na grade. O único lugar que o nomeia é autodev team template, que lista um arquivo ilegível entre os que substituiria. Um arquivo que deveria estar na equipe e não está é o sinal. Se todos os arquivos são inválidos, a execução pausa por falta de equipe. Um arquivo que não faz parse também é lido como não fixado, o que cai no padrão da própria CLI.

Modelo e esforço #

model e effort são passados à CLI do próprio provedor como estão escritos, e só quando estão definidos:

Com nenhum dos dois campos definido, o AutoDev não passa nada, e vale o padrão da própria CLI. As chaves model e effort da execução não são um plano B: um turno de participante nunca as lê. Para o codex, um --model ou -m explícito em codexArgs, ou um model_reasoning_effort= ali, vale mais que o arquivo. Os valores são lidos de novo no início de cada turno, então uma mudança vale a partir do próximo turno do participante e nunca no meio de um. Num salto de failover a fixação não se aplica, já que nomeia um modelo do provedor do próprio participante, e o :model da entrada é usado no lugar.

Instruções e persona #

O corpo são as instruções do participante. Elas entram no prompt de uma sessão nova ou rotacionada. Uma sessão retomada já as tem, então uma edição no corpo chega ao participante quando a sessão dele recomeça.

Uma persona nomeia outro arquivo, e o corpo dele substitui o do próprio participante. O frontmatter do arquivo de persona, se tiver, é removido. Se o caminho está fora do projeto, ou o arquivo não existe, o AutoDev usa o corpo do próprio participante e registra <id>: persona path is outside the project (<path>); using its own body ou <id>: persona file not found (<path>); using its own body. Sem nenhuma instrução, o prompt diz (no persona configured — use your judgment).

moves é informado ao participante no prompt como Your moves: <list>. A ferramenta post aceita qualquer uma das seis jogadas, seja qual for a lista.

Como o painel escreve o arquivo #

Numa lane, Edit prompt abre o arquivo no editor. Pin e unpin escrevem model e effort. Rename move o arquivo. Um provedor arrastado para a equipe escreve um arquivo com o nome do provedor, com provider definido e todo outro campo no padrão. A CLI faz as mesmas coisas: autodev team edit imprime o caminho do arquivo, pin e unpin escrevem os dois campos, rename move o arquivo, e add escreve o arquivo que um arrastar escreveria.

Cada uma dessas escritas renderiza o frontmatter de novo a partir dos campos que o AutoDev leu. Ele os escreve na ordem provider, model, effort, failover, moves e persona, deixa de fora um campo opcional que não está definido, e sempre escreve moves. Um comentário ou uma chave desconhecida no frontmatter não sobrevive a uma escrita pelo painel. O corpo sobrevive.

Participantes e lanes trata do que são um participante e uma lane, e Provedores e failover trata do que o failover faz. Todas as chaves de configuração trata do provider da execução, em que roda um participante que não nomeia nenhum. Todos os comandos da CLI lista os comandos autodev team.