Orquestração de Build Grok

Quando Usar

• Use ao delegar uma tarefa de implementação bem especificada para o Grok Build CLI da xAI rodando em modo headless.
• Use ao executar uma tarefa de plano de implementação em Markdown, tarefa por tarefa, com uma revisão de diff após cada tarefa.
• Use quando o usuário disser "use grok", "grok build", "have grok implement" ou "send to grok".

O assistente de codificação é o orquestrador: ele planeja, escreve especificações de tarefa autônomas, as envia para o Grok Build em modo headless, revisa cada diff e é responsável pelo resultado final. Grok é o executor rápido e barato. Detalhes completos da CLI e comportamentos verificados: references/cli.md.

Portão de Segurança

Antes de cada envio, mostre ao usuário a especificação exata da tarefa que será enviada para a xAI, a árvore de trabalho de destino e o modo de permissão. Obtenha aprovação explícita para divulgar esse texto e para permitir que o Grok edite a árvore de trabalho com escopo. Nunca inclua segredos, código proprietário, dados de clientes ou credenciais em uma especificação de tarefa. Não execute grok update, --always-approve, ou um comando de recuperação destrutivo sem aprovação explícita e separada.

Quando Delegar vs. Manter com o Orquestrador

Em caso de dúvida, mantenha com o orquestrador.

Verificação pré-voo da sessão (uma vez, antes do primeiro envio)

1. grok update --check --json — se updateAvailable for verdadeiro, informe o usuário. Execute grok update somente após aprovação explícita, e então confirme com grok --version.
2. grok models — se ocorrer um erro ou relatar logout, PARE e peça ao usuário para executar grok login.

Loop por tarefa (sequencial — o padrão)

1. Especificação. Escreva um arquivo de tarefa autônomo (modelo abaixo) em um diretório temporário FORA do repositório de destino — o scratchpad do harness, se disponível, caso contrário, o diretório temporário do SO. Nunca escreva dentro do repositório de destino. Grok não tem contexto de conversa: nunca prompts de uma linha.

   • POSIX: mkdir -p "${TMPDIR:-/tmp}/grok-specs", então escreva task.md lá.
   • Windows (PowerShell): New-Item -ItemType Directory -Force "$env:TEMP\grok-specs", então escreva task.md lá.

2. Estado limpo. Sem alterações de código-fonte não commitadas — comite ou salve primeiro, para que o diff pós-execução seja exatamente o trabalho do Grok. Ignore artefatos de build (__pycache__, dist/, etc.); se eles aparecerem em git status, geralmente são apenas não ignorados pelo git, não é sua preocupação. Nunca envie com uma árvore de código-fonte suja.

3. Envio.

   POSIX:

   grok --prompt-file <task-file> \
     --output-format json \
     --always-approve \
     --max-turns 30 \
     --cwd <repo>
   

   Windows (PowerShell) — caractere de continuação de linha backtick:

   grok --prompt-file <task-file> `
     --output-format json `
     --always-approve `
     --max-turns 30 `
     --cwd <repo>
   

   Analise a saída JSON e salve sessionId. (--always-approve é necessário para execuções headless — --permission-mode acceptEdits cancela silenciosamente edições sem aprovador interativo. Use-o somente após o usuário aprovar explicitamente que o Grok edite esta árvore de trabalho com escopo exato. Veja references/cli.md.) Para uma tarefa de alto risco, adicione --check para que o Grok se auto-verifique antes de você revisar; pule caso contrário (isso ~dobra a latência).

4. Portão de revisão — não negociável.

   • Leia o diff você mesmo (git diff -- <files from the spec> para pular ruído de artefatos): ele faz a tarefa, apenas a tarefa e segue as convenções do repositório?
   • Execute os comandos de aceitação da especificação.
   • Passou → comite com uma mensagem clara seguindo a convenção do repositório → próxima tarefa.
   • Falhou → pergunte ao usuário antes de uma correção ou qualquer reset. Nunca execute git checkout -- . ou git clean -fd automaticamente; preserve o diff para revisão e use um plano de recuperação não destrutivo a menos que o usuário autorize explicitamente o contrário.

Modelo de especificação de tarefa

# Tarefa: <título de uma linha>

## Contexto
- Repositório: <caminho> — <uma linha sobre o que é o projeto>
- Convenções: <executador de testes, formatador, um bom exemplo de arquivo para imitar>

## Arquivos
- Modificar: <caminho>
- Criar: <caminho>

## Tarefa
<descrição precisa da mudança>

## Restrições

…