Referência

CLI.

O comando é t25, com factory mantido como alias durante a migração de nome. Do repositório, invoque por npm run t25 -- <comando> — o -- é o que faz os argumentos chegarem ao programa em vez de ao npm.

O ciclo de uma ordem

# abrir
npm run t25 -- create "Adicionar endpoint de métricas" \
  --body "Expor latência por rota" --type feature --risk medium

# o briefing: ler, então liberar
npm run t25 -- spec TASK-0001
npm run t25 -- spec-approve TASK-0001

# o gate de go/no-go
npm run t25 -- approve TASK-0001

# acompanhar e corrigir o rumo
npm run t25 -- list
npm run t25 -- retry TASK-0001
npm run t25 -- cancel TASK-0001

spec-approve e approve são portões diferentes: o primeiro libera o briefing para virar plano, o segundo é o go/no-go do plano. Nenhum dos dois dá merge — isso continua sendo você, pelo cockpit ou por t25 merge.

Ambiente e diagnóstico

Comando	O que faz
`t25 doctor`	Relatório JSON de pré-flight — autenticação do bind, Docker, cliente PostgreSQL, `state_dir`, `web/dist`. Sai com erro se algum check estiver em `error`. É o primeiro lugar a olhar quando algo não sobe.
`t25 snapshot`	Manifesto JSON somente leitura dos arquivos do diretório de estado: caminho relativo, bytes e SHA-256.
`t25 list`	As ordens e em que estado cada uma está.

Worktree da ordem

npm run t25 -- workspace TASK-0001  # onde o worktree está
npm run t25 -- cleanup TASK-0001    # remover o worktree

O cleanup recusa a remoção se houver alteração não commitada, e nunca força. Se ele reclamou, olhe a árvore antes de insistir — normalmente há trabalho real lá dentro.

Múltiplos projetos

npm run t25 -- projects
npm run t25 -- create "Título" --project outro-servico

Workers

Execução distribuída: o control plane emite leases e cada host roda um worker que as reivindica. A credencial vive só em variável de ambiente (FACTORY_WORKER_CREDENTIAL, com o bootstrap inicial em FACTORY_WORKER_BOOTSTRAP) — nunca no t25.yaml.

npm run t25 -- worker-bootstrap --project default
npm run t25 -- worker run --control-plane-url https://localhost:8443 --worker-id worker-a
npm run t25 -- worker-approve worker-a
npm run t25 -- workers

O runbook de dois hosts, TLS e reclaim de lease está em GO-LIVE.md.

MCP: o seu agente operando a fábrica

npm run t25 -- api-key create --label "meu-agente" --role viewer --read-only
export T25_MCP_API_KEY=<segredo impresso acima>
export T25_MCP_SCOPE=read
npm run mcp   # stdio: aponte a config de MCP do seu agente para este comando

O catálogo tem 52 tools em quatro camadas cumulativas, filtradas por T25_MCP_SCOPE (default read): 21 de leitura, 30 em operate, 38 em approve e 52 em admin. A chave continua sendo a autoridade — o escopo só esconde tools no processo stdio.

operate cobre pause/resume/cancel/retry, briefs e respostas. approve acrescenta criar ordem, spec, plan gate, merge e rollback. admin cobre frota, API keys, triggers, usuários e políticas. Worker protocol, shell, secrets e Postgres direto ficam fora.

O que o MCP não substitui. Spec e merge continuam gates de capability na API. Sem papel approver/admin a tool aparece no catálogo amplo e a API recusa. O protocolo interno do worker (HMAC, lease, heartbeat) não passa pelo MCP.

Revisar um PR existente

npm run t25 -- review-pr 42
npm run t25 -- review-pr 42 --comment

Revisa e não implementa nem faz merge.

Verificação do repositório

npm run typecheck
npm test
npm run web:build

São os três comandos que a T25 considera "pronto" para trabalho de backend — e o web:build serve também como conferência de que o cockpit ainda compila.

Próximo Especificações: onde cada decisão ficou registrada →