Maestro
Orquestrador local de agentes de IA para desenvolvimento: CLI e API que planejam, implementam e testam código em worktrees Git isolados
$ maestro task "Adicionar validação de CPF"
> plano criado, repositório limpo, aguardando confirmação
$ maestro run <id-do-plano> --confirm
> branch maestro/<id> criada em worktree isolado
> pipeline: contexto → requisitos → implementação → testes → revisão
$ maestro job <id-do-plano>
> status: concluídoVisão Geral
Maestro é uma ferramenta local que coordena tarefas de desenvolvimento assistidas por IA em qualquer projeto que declare um maestro.yaml. A CLI (Typer) fala por HTTP com uma API FastAPI local, que aciona um Orchestrator responsável por selecionar contexto, montar um plano, exigir confirmação explícita e só então executar a escrita em uma branch e worktree Git isolados. A integração de produção com o modelo é feita exclusivamente pela CLI Codex já instalada na máquina; os testes usam fakes e nunca chamam um provider real.
O que a ferramenta faz
Pipeline em fases
Máquina de estados fixa (contexto → plano → decisão arquitetural → execução → testes/revisão). Fases futuras como DOCUMENTING e ROLLED_BACK já estão declaradas para expansão.
26 agentes especializados
Do ContextAgent ao SecurityAgent, cada um resolve uma única etapa e devolve um SubAgentResult estruturado, nunca histórico de conversa bruto.
Escrita isolada em worktrees
Toda tarefa que escreve roda numa branch e worktree Git próprios, exigindo repositório limpo e confirmação explícita antes de tocar no checkout principal.
CLI + API local
Comandos Typer conversam por HTTP com uma API FastAPI restrita a 127.0.0.1:8765. Sem autenticação, sem rede externa, sem multiusuário, por design.
O Desafio
- Garantir que agentes com permissão de escrita nunca corrompam o checkout principal nem pisem no trabalho um do outro durante uma tarefa.
- Impedir que um objetivo mal especificado dispare sozinho uma mudança estrutural (autenticação, migração de banco, contrato público) sem revisão humana.
- Selecionar contexto suficiente para cada agente sem estourar o orçamento de tokens nem vazar instruções irrelevantes para o agente errado.
A Solução
- O Orchestrator serializa as fases de escrita com um lock de processo, e toda execução roda em uma branch maestro/<id> dentro de um worktree Git próprio, criado só depois de confirmar repositório limpo e consentimento explícito do usuário.
- Termos estruturais no objetivo forçam o formato DECISÃO ARQUITETURAL NECESSÁRIA: a execução fica bloqueada até uma decisão ser registrada, mesmo com --confirm passado.
- O ContextAgent monta um ContextPacket por tarefa: o AGENTS.md raiz sempre entra, um AGENTS.md aninhado só entra se um arquivo do seu diretório foi selecionado, e os contextos especializados em agent-context/ só carregam quando o objetivo ou os caminhos batem nas palavras-chave do link.
Arquitetura do Sistema
A CLI nunca instancia agentes diretamente: ela é só um cliente HTTP da API local, que encaminha para o Orchestrator. Ele lê contexto e catálogo de agentes, delega ferramentas de filesystem, Git, terminal e testes, e conversa com o provider Codex por trás de um protocolo próprio, independente de modelo.
Autonomia com Freio de Mão
O objetivo do Maestro é dar autonomia real a agentes de IA sem abrir mão de controle sobre o que eles podem fazer sozinhos:
- Nenhuma escrita acontece sem repositório Git limpo e confirmação explícita; nenhum agente faz push ou altera configuração Git global.
- Um redator dedicado evita gravar segredos, chaves ou conteúdo de .env em logs, contexto, planos ou respostas.
- A API local não implementa autenticação nem isolamento multiusuário de propósito: ela nunca deve ser exposta além de 127.0.0.1, e o CORS aceita só dois dev servers locais.