Referência
Configuração.
Quase tudo que muda o comportamento da fábrica está no t25.yaml da raiz —
roteamento de agentes, limites, risco, GitHub, autenticação. Esta página é o mapa das
seções; a referência campo a campo é
docs/CONFIGURATION.md.
O merge raso é por seção, não por chave aninhada. Uma seção presente no
YAML substitui o default naquele nível — ela não é fundida em profundidade. Declarou
routing? Declare os papéis que quer, porque os que faltarem não voltam do
default.
Segredo não entra no YAML versionado. A URL do banco vem de
DATABASE_URL, a credencial de worker vem de
FACTORY_WORKER_CREDENTIAL, e os segredos de OAuth vêm do ambiente. Um valor
real commitado é incidente, não deslize.
As seções
| Seção | Para quê |
|---|---|
factory | Nome, diretório de estado, diretório de worktrees, tempo máximo por ordem, retries, exigência de aprovação de plano. |
repository | O repositório que a fábrica opera e o branch padrão de onde os worktrees saem. |
projects | Outros checkouts locais registrados, para operar mais de um repositório. |
routing | Papel do pipeline → cadeia de CLIs, em ordem de preferência. |
skills | Substitui a lista de skills de um papel específico. |
timeouts | Teto de minutos por papel; quem não aparece usa o teto global. |
limits | Guardrails anti-loop e anti-runaway. |
risk | Nível de risco → quanto a fábrica automatiza. |
sandbox_image | Imagem Docker para os papéis de dev quando o nível pede sandbox. |
github | Importação de issues e abertura de PR. |
server | Porta, chaves de API e, opcionalmente, login por GitHub ou OIDC. |
cost e observability | Contabilidade de custo por run e telemetria. |
control_plane | Banco e artifact store. A URL vem do ambiente, sempre. |
Roteamento: uma cadeia, não um CLI fixo
É o conceito que mais gera engano. Cada papel recebe uma lista ordenada, e a T25 usa o primeiro CLI que estiver disponível na máquina. Não é escolha por qualidade nem sorteio: é a primeira porta que abre.
routing: triage: [kimi, claude, codex] planner: [claude, codex, kimi] research: [kimi, claude] dev-frontend: [claude, kimi, codex] dev-backend: [codex, claude, kimi] qa-frontend: [claude, kimi] qa-backend: [codex, claude, kimi] reviewer: [claude, codex, kimi] security: [claude, codex] docs: [kimi, claude, codex] release: [claude, codex]
São onze papéis, e cada lista precisa ser um array não vazio — lista vazia ou de tipo
errado é rejeitada no carregamento, não descoberta em execução. Os adapters disponíveis
hoje são claude, codex, kimi, gemini,
opencode, cursor, pi, vibe e
mock.
Risco: quanto ela anda sozinha
risk:
low: { approval: none, sandbox: none }
medium: { approval: plan, sandbox: none }
high: { approval: plan_and_pr, sandbox: none }
critical: { approval: human_required, sandbox: none }
| Nível | O que muda |
|---|---|
low | Abre o PR sem gate de plano. |
medium | Exige aprovação do plano. |
high | Exige aprovação do plano e do PR. |
critical | Sempre exige intervenção humana. |
Nenhum nível automatiza o merge. A configuração de risco mexe em quanto a
fábrica anda sem perguntar até o PR; o merge é sempre seu, pelo cockpit ou pela CLI. E a
aprovação do briefing em SPEC é obrigatória em todos os níveis — não existe
chave que a desligue.
Uma ordem de tipo chore sem --risk explícito assume
low. É o caminho de adoção deliberado: upgrade, CVE, lint — critério
verificável e custo de erro baixo.
Limites: o freio
limits: max_runtime_minutes: 60 max_queue_attempts: 5 max_failed_commands: 8 max_same_error_retries: 2 max_files_changed: 40 max_diff_lines: 2000 max_duplicate_line_ratio: 0.5
Os dois primeiros da segunda metade são o guardrail contra o agente que resolveu reescrever
o mundo: teto de arquivos alterados e de linhas de diff, conferidos depois da
implementação. Passou, a ordem falha. O max_duplicate_line_ratio pega
copy-paste excessivo e é o único que se desliga sozinho em modo bootstrap, onde repetição
legítima dispararia falso positivo.
Autenticação
Chaves de API funcionam sem nenhuma configuração extra e são o caminho de scripts e CLI. O login de pessoas por GitHub ou OIDC é opcional: quando ligado, exige segredo de sessão e o conjunto completo de um dos dois provedores. Os usuários autorizados começam declarados no YAML e passam a viver num overlay local depois da primeira edição no cockpit — não existe banco de usuários. Token de acesso do GitHub nunca é persistido, e tirar a pessoa da lista revoga a sessão dela na requisição seguinte.
Antes de mexer
- Rode
npm run t25 -- doctor: ele confere o ambiente e sai com erro se algo estiver quebrado. - Referência a papel ou skill que não existe é rejeitada no carregamento — o erro aparece ao subir, não no meio de uma ordem.
- Nenhum segredo no YAML versionado. Nenhum.