Instalar

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 T25_WORKER_CREDENTIAL, e os segredos de OAuth vêm do ambiente. Um valor real commitado é incidente, não deslize.

As seções

SeçãoPara quê
t25Nome, diretório de estado, diretório de worktrees, tempo máximo por ordem, retries, exigência de aprovação de plano.
repositoryO repositório que a fábrica opera e o branch padrão de onde os worktrees saem.
projectsOutros checkouts locais registrados, para operar mais de um repositório.
routingPapel do pipeline → cadeia de CLIs, em ordem de preferência.
skillsSubstitui a lista de skills de um papel específico.
timeoutsTeto de minutos por papel; quem não aparece usa o teto global.
limitsGuardrails anti-loop e anti-runaway.
riskNível de risco → quanto a fábrica automatiza.
teamModo time: mapa de conhecimento por área, alerta de pessoa só e rodízio de revisores. Desligado por padrão.
live_docsInstrução de documentação viva para dev e QA. Ainda não entrega ferramenta ao agente (#444 aberto).
sandbox_imageImagem Docker para os papéis de dev quando o nível pede sandbox.
githubImportação de issues e abertura de PR.
serverPorta, chaves de API e, opcionalmente, login por GitHub ou OIDC.
cost e observabilityContabilidade de custo por run e telemetria.
control_planeBanco 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 doze 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 de CLI disponíveis hoje são claude, codex, kimi, gemini, grok, opencode, cursor, pi e vibe; mock é o adapter de teste.

Risco: quanto ela anda sozinha

risk:
  low:      { approval: none, sandbox: docker }
  medium:   { approval: plan, sandbox: docker }
  high:     { approval: plan_and_pr, sandbox: docker }
  critical: { approval: human_required, sandbox: docker }
NívelO que muda
lowAbre o PR sem gate de plano.
mediumExige aprovação do plano.
highExige aprovação do plano e do PR.
criticalSempre 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, salvo a chave t25.auto_approve_spec, que nasce desligada (ver a seção de aprovações abaixo).

O padrão isola o estágio. O código, o t25 init e o t25.yaml deste repositório usam sandbox: docker nos quatro níveis. sandbox: none é escape explícito: o agente roda no host com o ambiente do worker, e o Claude usa --dangerously-skip-permissions quando T25_CLAUDE_SKIP_PERMISSIONS não está definida. Em máquina compartilhada, rode o worker num usuário ou VM dedicados, sem segredos pessoais, ou defina T25_CLAUDE_SKIP_PERMISSIONS=0 para o Claude aceitar só edições de arquivo (acceptEdits).

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.

Aprovações: spec, plano e merge

São as chaves que decidem onde a fábrica para e espera uma pessoa. Os nomes são os do t25.yaml; as chaves por projeto ficam dentro de cada entrada de projects.

ChavePadrãoEfeito
t25.auto_approve_specfalseAssina sozinha a spec de risco low ou medium, desde que não haja gate de spec, comentário aberto nem critério de aceite faltando. high e critical continuam manuais.
t25.require_plan_approvaltrueGate global do plano. Só vale para riscos cujo approval não é none.
projects[].requirePlanApprovalausente (herda a global)Overlay do projeto: true mantém o gate com a flag global desligada; false tira o gate com ela ligada.
projects[].planApprovalLowRiskausenteFaz o gate do plano valer também no risco low, que tem approval: none. Só age com o gate ligado.
delegation (e projects[].delegation)enabled: falseDelegação institucional por ação: merge, approve-spec, approve-plan e apply-improvement. Ligar a delegação e promover uma ação não tira a pessoa do merge: a execução do merge delegado não é chamada pelo pipeline.
semantic_decisionsenabled: false, mode: shadowCamada de decisões semânticas (JEV). Nasce desligada, com provedor fake, send_code: false (só aceita false) e routing: manual. Também tem overlay por projeto, com enabled e routing.

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

Próximo CLI: operar a fábrica pela linha de comando →