@iapro/orquestrador-maestro-cli

Orquestrador Maestro

English · Skills · Instalar · Benchmark · Contribuir

Use o mesmo processo com diferentes ferramentas de IA: entender o pedido, ler o contexto necessário, executar com limites, verificar o resultado e deixar um rastro útil para a próxima sessão.

O Orquestrador Maestro é para quem usa Codex, Claude, OpenCode, Cursor, Gemini e outras ferramentas de IA em projetos reais. Ele não é um modelo nem substitui sua ferramenta favorita: prepara o ambiente para que ela trabalhe com menos desperdício, mais previsibilidade e evidência antes de dizer que terminou.

Escolha seu próximo passo

Você quer…	Vá direto para…
Começar do zero em 10 minutos	Comece aqui
Entender a ideia em 1 minuto	Como funciona
Instalar agora	Comece em dois minutos
Entender a evolução 0.5 → V1	Veja o que mudou e por quê
Ver o benchmark	Veja os números
Descobrir qual skill usar	Escolha por objetivo
Configurar memória e contexto	Guias técnicos
Conhecer CLI, workflows e adaptadores	Referência completa

Por que usar

Quando uma IA recebe só um prompt, ela pode abrir contexto demais, improvisar o processo e declarar uma tarefa pronta sem prova suficiente. O Maestro organiza o caminho antes da execução.

Sem orquestração	Com Orquestrador Maestro
A IA decide sozinha o que ler	Ela começa pelas regras, pelo estado e pela skill certa
Contexto cresce sem critério	Lê o mínimo suficiente e aprofunda sob demanda
“Pronto” pode ser apenas uma afirmação	Verificação e handoff fazem parte do trabalho
Cada ferramenta cria seu próprio ritual	O processo se mantém entre ferramentas e sessões

O que muda na prática

• Menos contexto desnecessário. Índices compactos e documentação de projeto evitam carregar catálogos e históricos inteiros.
• Menos surpresa na entrega. Regras, escopo e verificação entram antes da mudança, não no fim.
• Conclusão verificável. O Maestro Resolution Engine diferencia processo encerrado de Validated Outcome, preservando Evidence, Proof Bundle, budget e histórico de resolução.
• Menos recomeço entre sessões. O estado útil fica no projeto, legível por pessoas e por outras ferramentas.

Comece em dois minutos

Requer Node.js 20.19 ou superior.

npm install -g @iapro/orquestrador-maestro-cli@latest
orquestrador-maestro install
orquestrador-maestro verify

Prefere instalar pelo repositório? Use o guia de instalação, que inclui Windows, Linux, macOS, bootstrap, dry-run e rollback.

A V1 estável (1.1.1) é a versão padrão: branch v1, release v1.1.1 e canal npm latest. Para atualizar uma instalação existente, rode orquestrador-maestro update, seguido de orquestrador-maestro verify e orquestrador-maestro version --check. O update faz backup e consolida o núcleo em .orquestrador, preservando memória/configuração ao migrar de .orquestrador-maestro. Veja a migração para V1.

Próximo passo: verifique a instalação e configure o primeiro projeto.

Depois, abra sua ferramenta de IA no projeto e peça:

Use o Orquestrador Maestro. Leia as instruções do usuário e do projeto,
abra somente o contexto necessário, resolva esta tarefa, verifique o resultado
e registre o estado útil para a próxima sessão.

Um processo, várias ferramentas

O Maestro começa com instruções globais e locais, encontra a skill adequada e usa DEV/ para manter objetivo, decisões, verificação e próximo passo no próprio projeto. Assim, você não depende de a conversa anterior ainda estar disponível — nem de trocar de ferramenta sem perder o método.

Ele integra fluxos para Codex, Claude Code, OpenCode, Freebuff, Cursor, Gemini CLI, Grok CLI, MiMo Code, Kimi Code, Windsurf e Antigravity. Cada ferramenta continua responsável pelo próprio runtime, login, modelo e credenciais.

O Freebuff usa o mesmo contrato de AGENTS.md e .agents/skills que o Maestro já sincroniza. Veja o guia de integração do Freebuff para instalação persistente, MCP, agentes locais e publicação para outros usuários.

Codex Desktop e ChatGPT Work

A V1 inclui uma integração oficial por plugin para superfícies locais compatíveis com lifecycle hooks. Ela usa Router v3 + Complexity Gate, um Context Ledger por sessão, policy deduplicada, Tool Governor e um MCP local sob demanda. A mesma policy não é reinjetada a cada turno e o catálogo completo de skills não é carregado no plugin.

orquestrador-maestro desktop-plugin install
orquestrador-maestro desktop-plugin status
orquestrador-maestro desktop-plugin doctor

Depois, abra/reinicie o ChatGPT Desktop ou Codex, habilite o plugin Orquestrador Maestro no marketplace pessoal e aprove os hooks quando o cliente solicitar confiança. A integração continua fail-open para indisponibilidade do CLI e preserva o runtime nativo do host.

Veja Integração OpenAI Desktop para Context Ledger, MCP progressivo, desktop-plugin stats, modos observe|optimize|strict, budgets e limites.

Para o funcionamento técnico, consulte como o Orquestrador funciona, economia de contexto, memória de projeto com DEV/ e perfis de ferramentas.

Próximo passo: aprenda o fluxo que a IA deve seguir ou configure um workflow declarativo.

Skills: você pede o resultado, o Maestro escolhe a capacidade

Você não precisa decorar o nome das Skills para usar o Maestro. Na V1, elas funcionam como capacidades especializadas que o Router v3 seleciona conforme a intenção, a complexidade, a stack, os arquivos alterados, o risco e o contexto disponível.

O fluxo normal é:

pedido em linguagem natural
        ↓
Complexity Gate
        ↓
sinais do projeto + Skill Contract
        ↓
Router v3
        ↓
1 Skill principal
+ apoios somente quando justificados
        ↓
contexto mínimo suficiente
        ↓
execução + verificação

Comece pelo objetivo, não pelo catálogo

Quero…	Capacidade que o Maestro tende a procurar	Exemplos de Skills
Entender um projeto	baseline, arquitetura, riscos e documentação	skill-preflight, skill-repo-health, skill-deep-wiki, skill-adr
Construir ou evoluir produto	engenharia, frontend e UX coerentes com o projeto	skill-engineering-quality, skill-frontend-excellence, skill-product-ux-architecture
Melhorar uma interface	direção visual, hierarquia, acabamento e motion	skill-open-design-ui, skill-impeccable, skill-design-engineering-craft, skill-motion-design-principles
Investigar e corrigir	causa raiz, mudança focada e prova da correção	skill-systematic-debugging, skill-verification-before-completion
Entregar com segurança	migração, release, CI, rollback e segurança	skill-database-migrations, skill-release-engineering, skill-security-hooks, skill-threat-modeling
Trabalhar com IA/agentes	providers, budgets, observabilidade e delegação	skill-ai-orchestration, skill-agent-observability, skill-multiagent-orchestration
Integrar serviços específicos	conhecimento de domínio carregado sob demanda	Stripe, AbacatePay, Google Workspace, WhatsApp, mídia e outras Skills de domínio

Esses exemplos são portas de entrada, não combinações obrigatórias. O Router não carrega todas as Skills de uma linha e não encadeia capacidades apenas porque elas parecem relacionadas.

Veja a decisão antes de executar

Você pode perguntar ao próprio Router o que ele faria:

orquestrador-maestro route explain "investigue por que este teste começou a falhar"
orquestrador-maestro route explain "refaça a arquitetura de UX deste produto"
orquestrador-maestro route explain --json "prepare esta aplicação para release"

A explicação mostra, conforme aplicável:

• complexidade estimada;
• Skill principal;
• Skills encadeadas;
• confiança;
• evidência que levou à seleção;
• sinais de stack/escopo;
• rotas rejeitadas;
• contexto estimado e budget máximo.

Isso transforma Skills de uma coleção de prompts em um sistema de decisão inspecionável.

Core, Domain e Skills externas

Origem	Papel	Como entra no fluxo
Maestro Core	capacidades transversais de engenharia e governança	Skill Contract V2 obrigatório; elegíveis para routing automático
Maestro Domain	capacidades especializadas, como frontend, segurança, IA e integrações	Skill Contract V2 obrigatório; roteadas quando há evidência específica
Library / External	catálogo reutilizável mantido fora do núcleo	normalizado na fronteira; sem routing confiável permanece explicit-only
User / Project	conhecimento local criado pelo usuário ou pelo repositório	permanece local e não precisa adotar o manifesto interno do Maestro

O catálogo atual possui 56 Skills canônicas Maestro e 79 Skills públicas únicas, mas o objetivo da arquitetura é justamente evitar que esse catálogo inteiro seja colocado no prompt ou apresentado ao usuário como uma lista que precisa ser aprendida.

As Skills de design não fazem a mesma coisa

Uma área em que uma lista plana confundia bastante era design/frontend. Na V1 elas têm papéis diferentes:

Skill	Use principalmente para
skill-product-ux-architecture	estruturar produto, fluxos, informação, estados e arquitetura de UX
skill-open-design-ui	sair de UI genérica/template e definir direção visual
skill-impeccable	auditar hierarquia, spacing, consistência, legibilidade e acessibilidade
skill-design-engineering-craft	elevar acabamento de implementação e detalhes que fazem a interface parecer madura
skill-motion-design-principles	revisar e projetar animações, transições e comportamento de movimento
skill-frontend-excellence	coordenar implementação frontend, Design Profile e Visual QA dentro do produto real
skill-melhorar-ux-ui-por-referencia	trabalhar especificamente a partir de screenshots ou referências visuais

O Router usa useWhen, doNotUseWhen, capabilities e sinais do projeto para evitar que essas capacidades concorram apenas por palavras como “design” ou “frontend”.

Explore conforme sua necessidade

• Escolher por objetivo — melhor ponto de entrada para humanos.
• Portal de Skills — entenda o modelo, routing, disponibilidade e contrato.
• Receitas operacionais — veja quando várias capacidades realmente precisam trabalhar em sequência.
• Referência completa — consulte as 56 Skills canônicas e seus metadados.
• Catálogo público — fonte estruturada das Skills públicas deduplicadas.

Da 0.5.0 à V1: contexto e roteamento proporcionais ao problema

A 0.5.0 consolidou a base de execução confiável do Maestro: Resolution Engine, Evidence, Proof Bundle, memória, telemetria, persistência e integração provider-neutral. Essa fundação resolveu uma pergunta essencial: “o processo terminou ou o resultado foi realmente validado?”

A próxima limitação estava antes da execução. O fluxo ainda tinha decisões mais estáticas do que o produto precisava: roteamento centrado principalmente em triggers e um orçamento de exploração de codebase próximo de 8k tokens no caminho legado, independentemente de a tarefa ser um typo ou uma mudança arquitetural.

A V1 move essa decisão para o início do fluxo:

pedido
  ↓
Complexity Gate
  ↓
Router v3
  ↓
Skill Intelligence
  ↓
Context Budget
  ↓
Provider
  ↓
Verification / Resolution

O objetivo não é simplesmente “usar menos contexto”. É usar contexto proporcional ao problema: reduzir agressivamente o que é carregado em tarefas pequenas e permitir mais profundidade quando a evidência indica uma tarefa realmente complexa.

Complexidade	0.5.0 — fluxo legado	V1	Mudança de teto
MICRO	~8.000	1.500	−81,3%
SIMPLE	~8.000	3.000	−62,5%
STANDARD	~8.000	6.000	−25%
COMPLEX	~8.000	10.000	+25%
DEEP	~8.000	16.000	+100%

Esses números são limites configurados no runtime, não uma promessa de consumo real. O uso efetivo depende do repositório, provider, tarefa e contexto encontrado.

Como chegamos a esse desenho

A evolução foi incremental:

• Primeiro, confiabilidade de conclusão. A linha 0.5 passou a separar processo encerrado de Validated Outcome, preservando verificação e evidência.
• Depois, identidade e contrato das Skills. A V1 introduz Manifest V3 e Skill Contract V2 para que routing, contexto necessário, outputs e verificação tenham uma fonte canônica.
• Em seguida, complexidade antes de contexto. O Complexity Gate classifica MICRO | SIMPLE | STANDARD | COMPLEX | DEEP antes de decidir quanto carregar.
• Router v3 como caminho padrão. O Router v3 considera evidência positiva e negativa, capabilities, aliases, sinais do projeto e budget. O Router v2 permanece apenas como comparação/rollback explícito durante a pré-release.
• Fan-out continua deliberado. Complexidade alta não cria automaticamente vários agentes. Multiagent exige intenção explícita e complexidade compatível para evitar amplification desnecessária.

A mudança no catálogo é pequena em quantidade e grande em contrato:

Indicador	0.5.0	V1 proposta
Skills canônicas Maestro	52	56
Skills públicas únicas	75	79
Manifest canônico	V2	V3
Skill Contract V2 nativo	parcial/não canônico	obrigatório para maestro/*
Negative routing	limitado	explícito
Context requirements por skill	não canônico	explícito
Outputs / verification por skill	distribuídos	canônicos

Ou seja: a principal mudança não é ter mais quatro Skills. É tornar a seleção explicável, versionada e verificável.

O que já conseguimos provar

O conjunto comportamental versionado hoje contém 16 intents rotuladas usadas para comparar Router v2 e Router v3. O gate atual exige que ambos acertem os 16 casos e que o v3 não introduza regressões nesses cenários conhecidos.

Isso é evidência de não regressão na baseline atual, não prova de superioridade do v3. Por isso este README não publica uma porcentagem inventada de “melhoria de roteamento”.

Também conseguimos verificar diretamente no código e nos manifests:

• Router v3 é o default da linha V1;
• Router v2 é rollback explícito;
• Complexity Gate governa o budget normal de contexto;
• tarefas MICRO e SIMPLE não habilitam subagents;
• mesmo COMPLEX e DEEP só permitem subagents quando multiagent foi solicitado explicitamente;
• Skills externas sem routing confiável permanecem explicit-only;
• o catálogo canônico não depende de carregar todas as Skills no prompt.

Como isso deve melhorar o uso real

Se o desenho se comportar como esperado, a V1 deve melhorar quatro dimensões:

• Eficiência: tarefas pequenas deixam de pagar o mesmo custo de contexto de tarefas arquiteturais.
• Precisão: positive/negative routing e capabilities reduzem seleção por coincidência textual.
• Profundidade quando necessário: tarefas complexas podem usar budgets maiores sem obrigar todo o sistema a trabalhar sempre no pior caso.
• Explicabilidade: orquestrador-maestro route explain mostra intenção, complexidade, Skill escolhida, evidência e budget estimado em vez de esconder a decisão.

O resultado desejado é este:

menos tarefa simples → contexto demais
menos tarefa complexa → contexto de menos
menos skill irrelevante → prompt
menos fan-out automático → custo

mais decisão explicável
mais contexto quando a evidência pede
mais verificação antes de "done"

O que ainda precisa de benchmark A/B

Há métricas que não devem virar claim público apenas porque a arquitetura sugere melhora. Para comparar 0.5.0 e V1 de forma válida, o benchmark precisa usar as mesmas tarefas, repositórios, provider/modelo e critérios de aceitação.

As próximas comparações devem medir:

Métrica	Pergunta que ela responde
TTVO — Tokens To Validated Outcome	Quantos tokens foram necessários até um resultado realmente validado?
Context tokens por tarefa	A V1 carregou menos contexto onde não precisava?
First-pass validation	Mais tarefas passaram sem retry?
Validation rate	A economia manteve ou melhorou a qualidade?
Skills selecionadas por tarefa	O Router v3 evitou carregar capacidades irrelevantes?
Retries / provider calls	Houve menos retrabalho e amplification?
Time To Validated Outcome	O caminho até conclusão válida ficou mais curto?
Fan-out por tarefa	Tarefas simples permaneceram solo?
Regressões v2 → v3	Algum caso conhecido piorou?

Esses resultados só devem ser publicados quando passarem pelo mesmo evidence gate usado pelo benchmark do projeto.

Resumo: a V1 muda o Maestro de um fluxo com contexto mais uniforme para um sistema que tenta gastar o mínimo suficiente por tarefa, sem reduzir os requisitos de validação. A economia é uma consequência esperada; a regra principal continua sendo chegar a um Validated Outcome com evidência.

Benchmark: veja os números na sua máquina

O benchmark compara condições com o mesmo cenário, modelo e critérios de aceitação. Ele mede tokens apenas em tarefas aceitas e preserva evidência para auditoria.

Exemplo ilustrativo. Os valores no gráfico não são uma promessa nem um resultado oficial. O efeito real varia por modelo, tarefa e ambiente. Rode o benchmark para produzir e inspecionar sua própria evidência.

O evidence gate impede que resultados sem verificação apropriada virem claim público. Em vez de pedir confiança, o projeto mostra como conferir modelo, cenário, execução e evidência.

Para preparar o ambiente e executar uma comparação, siga o quick start do benchmark. A metodologia explica limites, métricas e o que os resultados não permitem concluir.

Próximo passo: inspecione a evidência gerada antes de transformar qualquer número em claim.

Guias técnicos

Se você quer…	Comece aqui
Instalar ou atualizar	Guia de instalação · migração para V1 · opções
Entender o método	Guia operacional para IAs · referência técnica
Reduzir custo de contexto	Economia de contexto
Exigir qualidade verificável	Engenharia guiada · Resolution Engine
Avaliar privacidade	Modelo de privacidade
Retomar tarefas longas	Workflows · contratos
Organizar memória	Hierarquia DEV/ · escopos
Trabalhar com skills	Portal · escolher · catálogo
Consultar CLI, arquitetura e comandos avançados	Referência técnica completa
Resolver problemas	Troubleshooting
Ver tudo	Índice de documentação

Privacidade por padrão

Este é um snapshot público e sanitizado: compartilha estrutura e comportamento, não conteúdo privado da máquina que o originou. Credenciais, sessões, logs, caches, caminhos locais e memórias privadas ficam fora do repositório.

Leia o modelo de privacidade para saber exatamente o que entra, o que fica local e como a telemetria anônima funciona.

A telemetria vem desabilitada por padrão (opt-in via orquestrador-maestro telemetry enable). Quando ativada, o CLI mede instalações anônimas ativas, nunca pessoas únicas. Envia somente comando, resultado, versão e ambiente técnico ao endpoint configurado; não envia caminhos, argumentos, prompts, arquivos, nomes, IP armazenado pelo produto ou credenciais. Desative com orquestrador-maestro telemetry disable ou ORQUESTRADOR_MAESTRO_TELEMETRY=0.

Próximo passo: confira o modelo completo de privacidade antes de sincronizar uma instalação pública.

Próximo passo

Instale em dois minutos para usar o mesmo processo nas suas ferramentas de IA. Depois, rode o benchmark para ver os dados no seu ambiente. Encontrou algo que pode melhorar? Contribua.

Licença

Consulte LICENSE. Este projeto organiza o processo de trabalho; decisões, credenciais e efeitos externos continuam sob controle humano.