Maestro

Estúdio visual de prototipagem sobre um repo: sessões em worktree, conversa com Claude ou Codex e preview vivo. O Maestro não define método, agentes ou skills e não prepara o repo para outras ferramentas.

Fronteira

O repo é a fonte. O Maestro:

• descobre agentes já comitados em .claude/agents/; sem eles oferece um host neutro;
• deixa AGENTS.md, CLAUDE.md, .agents/ e .claude/ intactos durante os turnos;
• mantém uma conversa por sessão e permite alternar Claude/Codex entre turnos; cada agente preserva seu próprio resume e recebe o catch-up do que ainda não viu;
• mantém conversa, preview e vínculo opcional de tarefa como fluxo principal, sem transferir as capacidades de engenharia para outro produto;
• ao marcar um protótipo como pronto, sincroniza o refinamento da conversa na descrição da tarefa vinculada, sem mudar status, label ou ciclo de vida;
• tenta atualizar uma sessão com a main por Git e, se houver conflito, pode encaminhar a resolução ao agente ativo; a IA segue as regras do repo e nunca recebe autorização implícita para push.

Ele não copia artefatos, não usa skip-worktree e não é necessário para clone, instalação, CI ou desenvolvimento por outra IDE.

maestro pull foi removido. Use no próprio repo:

pnpm exec base setup
pnpm exec opus setup   # somente em projeto Opus

Instalação opcional

pnpm add -D @softize/maestro
pnpm exec maestro serve

Requer Node 22+ e ao menos um provider (claude ou codex) autenticado no usuário que roda o serviço.

Produção consome uma versão exata do pacote a partir do repo de cada workspace. O fluxo de release, atualização, restart e smoke test está no deploy/RUNBOOK.md.

Desenvolvimento

pnpm install
pnpm --filter @softize/maestro typecheck
pnpm --filter @softize/maestro test
pnpm --filter @softize/maestro dev
pnpm --filter @softize/maestro-web dev

O supervisor continua dono do ciclo da interface: cria worktree, instala dependências, sobe preview e mantém a sessão. Capacidades de engenharia continuam pertencendo ao Maestro e podem ser expostas progressivamente; essa fronteira está detalhada em docs/studio-boundary.md.

A fronteira da atualização assistida está registrada em docs/ai-assisted-main-sync.md.