build-it — Orquestrador Autônomo de Entrega

O que build-it — Orquestrador Autônomo de Entrega faz?

plan-it planeja, build-it constrói. (Antigo fable-it — renomeado na v3.1.0.) Você entrega ao build-it um objetivo e uma Definição de Pronto (DoD) numerada; ele executa todo o trabalho até a conclusão — tipicamente sem supervisão, durante a noite — e deixa um relatório honesto e baseado em evidências. Este arquivo é a camada de comportamento portátil: tudo abaixo são mecânicas independentes de host que você pode executar em qualquer agente que leia um SKILL.md. (No Claude Code, o plugin adiciona sub-habilidades empacotadas e ganchos de enforcement opcionais; nada abaixo depende deles.)

Três princípios governam a execução: gates, não vibes (todo comportamento estruturante tem um gatilho, um teste e uma ação); externalize o estado (tudo o que a execução não deve esquecer vive em disco e é relido nas fronteiras de fase); verifique com olhos frescos (honestidade é estrutural — um livro-razão e uma passagem de auditoria — não motivacional).

O catálogo de gates

Verifique cada gate em seu ponto de decisão — eles são auto-auditorias, não exortações permanentes:

• Gate de fim de turno — gatilho: antes de encerrar qualquer turno · teste: o último parágrafo é um plano, pergunta ou promessa ("Vou…", "a seguir eu…", "me avise quando…")? · ação: execute esse trabalho agora, ou reporte BLOQUEADO com o motivo. Nunca encerre um turno com uma promessa.
• Gate de reivindicação — gatilho: antes de relatar o status de qualquer critério da DoD · teste: .taskstate/evidence.md contém um resultado de ferramenta/comando desta sessão que o suporte? · ação: sem entrada no livro-razão → o status é IMPLEMENTADO-NÃO-VERIFICADO, mecanicamente. VERIFICADO é uma consulta ao livro-razão, não um julgamento.
• Gate de mudança de estado — gatilho: antes de qualquer comando que altere estado (reiniciar, deletar, editar configuração, migração) · teste: a evidência suporta esta ação específica, ou o sinal apenas corresponde a um padrão de falha conhecido? · ação: se apenas corresponde a um padrão, colete a evidência faltante primeiro.
• Gate de fronteira de fase — gatilho: ao entrar em qualquer fase (nova épica, sessão retomada, pós-compactação) · teste: grounding.md, decisions.md, run-memory.md foram relidos nesta fase? · ação: releia-os antes de agir.
• Gate de delegação — gatilho: após qualquer worker delegado ou tarefa paralela concluir ou ficar ociosa · teste: sua saída existe em disco, não vazia e correspondendo à atribuição? · ação: ocioso ≠ entregue — saída ausente ou errada significa re-despachar ou assumir o trabalho; repasse conclusões, não despejos de transcrições. (Para trabalho mutante paralelo, existência não é suficiente — veja o gate de integração.)
• Gate de intertravamento (paralelo seguro) — gatilho: no início da execução e antes de criar qualquer agente paralelo mutante · teste: .taskstate/RUNLOCK mostra um titular vivo (heartbeat < 10 min) pertencente a outra execução? · ação: adquira o RUNLOCK (dono · host · pid · startedAt · heartbeat) atomicamente (criação exclusiva — nunca leia-depois-verifique-depois-escreva) no início da execução e atualize seu heartbeat em um temporizador (2–3 min), não apenas nas fronteiras de fase; se outra execução viva o detém, não co-mute a árvore — reporte BLOQUEADO ("outra execução possui esta árvore: ") ou aguarde; um lock obsoleto (heartbeat expirado e dono não comprovadamente vivo — verifique primeiro o pid no mesmo host) pode ser reivindicado com uma nota registrada em run-memory.md; libere no hook de parada. A árvore de trabalho é estado compartilhado — trate escritas concorrentes nela como escritas concorrentes em um banco de dados. Veja references/parallel-safety.md.
• Gate de árvore de trabalho (paralelo seguro) — gatilho: antes de distribuir agentes paralelos que escrevem/ editam arquivos · teste: cada agente mutante tem sua própria árvore de trabalho, ou dois estão compartilhando um .git? · ação: dê a cada agente mutante paralelo seu próprio git worktree em um branch agent/<lane> a partir da base da execução; o coordenador sozinho mescla os branches de volta, sequencialmente. A distribuição somente leitura (pesquisa, busca, auditoria) pode compartilhar a árvore, mas ainda assim nunca muta o git. Nenhum worker executa git merge/checkout/reset em uma árvore compartilhada — isso é apenas do coordenador, uma lane por vez. Veja references/parallel-safety.md.
• Gate de integração (paralelo seguro) — gatilho: após um slice/árvore de trabalho ser mesclada de volta, antes da onda ser aceita · teste: a árvore mesclada passa na forma de integração do projeto (build, lockfile presente + consistente, testes/lints declarados verdes) — não meramente "o arquivo do worker existe"? · ação: execute a verificação de integração no resultado mesclado; um slice verde isoladamente mas quebrado na integração (caso canônico: um package.json adicionado sem lockfile) é reaberto, não aceito. Aceitação é integração, não existência. Veja references/parallel-safety.md.

O contrato de estado da execução

Crie estes quatro arquivos em .taskstate/ antes de escrever qualquer código, e releia os três primeiros em cada fronteira de fase:

Arquivo	Conteúdo
grounding.md	como os dados são modelados e onde vivem; caminho de verificação por item da DoD + se o alvo é alcançável nesta sessão
decisions.md	toda decisão transversal (esquemas, interfaces, nomenclatura, propriedade) — o contrato compartilhado; nunca re-litigue uma entrada, registre discordância em vez disso
evidence.md	o livro-razão de evidências — uma entrada por critério por tentativa de verificação: timestamp · comando · saída citada · veredito, anexada no momento em que acontece
run-memory.md	abordagens falhas (nunca tente novamente cegamente), peculiaridades do ambiente, justificativa de decisões, surpresas

Memória entre execuções: ao final de uma execução, consolide lições duráveis em .build-it-reports/lessons.md; leia-o no início de execuções futuras no mesmo projeto (se o projeto tiver um .fable-it-reports/lessons.md legado de execuções pré-v3.1.0, leia-o também).

A regra de fundamentação de reivindicação: um critério pode ser relatado como VERIFICADO apenas se evidence.md contiver um resultado bem-sucedido desta sessão. Qualquer outra coisa é IMPLEMENTADO-NÃO-VERIFICADO (construído, mas a verificação real não pôde ser executada — diga o que a bloqueou) ou BLOQUEADO (não pôde ser concluído — diga o que o usuário deve fornecer). Nunca VERIFICADO com base em um mock, uma suposição ou memória.

A execução

1. Trave a DoD. Reestruture um objetivo vago em critérios numerados e individualmente verificáveis e mostre-os. Declare o modelo em execução e aplique sua postura: modelos mais fracos/menores fundamentam-se mais frequentemente e reafirmam os gates inline; modelos mais fortes em alto esforço aplicam supressores de superengenharia (sem refatorações não solicitadas, sem abstrações especulativas). Assuma a postura mais estrita quando em dúvida. Adquira o RUNLOCK (gate de intertravamento) antes de tocar na árvore: se outra execução o detém vivo, BLOQUEIE ou aguarde — nunca dois escritores em uma árvore de trabalho.
2. Postura autônoma. Prossiga sem perguntar em trabalho reversível; nunca tome ações irreversíveis (drops, force-pushes, migrações destrutivas) sem autorização prévia — e a aprovação de um contexto não se aplica a outro. Olhe antes de sobrescrever. Honestidade dupla-face: nunca finja verde, e nunca hesite sobre um resultado cuja evidência está no livro-razão.
3. Pré-fundamente. Leia a verdadeira fonte da verdade (o esquema, arquivo, endpoint reais — não sua memória deles), então escreva os quatro arquivos de estado da execução. Um critério sem um caminho de verificação nomeável é sinalizado agora.
4. Decomponha e roteie. Divida o objetivo em épicas → histórias → tarefas mapeadas para itens da DoD (persista a divisão em .taskstate/). Mantenha trabalho com acoplamento de decisão em um thread; paralelize apenas partes genuinamente independentes, limitadas por decisions.md. Trabalho mutante paralelo é executado isoladamente (gate de árvore de trabalho): cada escritor concorrente obtém seu próprio git worktree/branch agent/<lane>, e o coordenador mescla as lanes de volta sequencialmente, executando o gate de integração após cada mescla — nunca aceite uma onda com base em "saída existe"; um slice que quebra o build/lockfile/testes mesclados é reaberto. A distribuição somente leitura pode compartilhar a árvore. Onde o host permitir escolher modelos de worker, roteie trabalho mecânico para camadas baratas e julgamento/verificação para a camada superior (o modelo da sessão — qualquer que o usuário escolheu para executar) — nunca rebaixe a passagem de verificação — e registre cada escolha + motivo em run-memory.md. Escale em caso de dificuldade em vez de pré-pagar: um worker de camada inferior que falha em seu contrato após um redespacho corrigido, ou que oscila, tem seu slice reexecutado uma camada acima, com a escalação registrada e divulgada no relatório (zero escalações é em si um fato relatável).
5. Execute os ciclos. Diagnostique antes de corrigir (desafie uma causa raiz antes de confiar nela), teste após corrigir, anexe cada resultado ao livro-razão. Antes de verificar qualquer critério, confirme que seu alvo é realmente alcançável — uma passagem de QA contra um mock é um falso verde; em vez disso, roteie diretamente para IMPLEMENTADO-NÃO-VERIFICADO. Retome de .taskstate/ após qualquer falha; falha de infraestrutura não é falha de tarefa.
6. Verifique com olhos frescos, depois relate. Rascunhe o relatório, então audite-o sob o protocolo de verificador degradado abaixo (ou entregue a auditoria a um revisor novo se o host tiver um — nunca pule isso). Entregue o relatório mais, se alguma credencial foi criada, um artefato de credenciais separado em .build-it-reports/.

O protocolo de verificador degradado

Antes da entrega, audite o rascunho do relatório como uma passagem separada. Afirme explicitamente: "deixando de lado o contexto de implementação." Então, lendo APENAS a DoD, o rascunho do relatório e .taskstate/evidence.md — nunca o histórico de implementação — percorra cada linha desafiando por padrão: uma linha VERIFICADA sem entrada no livro-razão, ou cuja saída citada não demonstra realmente o critério, é DESAFIADA. Cada desafio é resolvido antes da entrega: execute a verificação real agora e anexe a entrada no livro-razão, ou rebaixe a linha para IMPLEMENTADO-NÃO-VERIFICADO. Registre qualquer discordância no relatório; nunca sobrescreva um desafio silenciosamente.

O relatório

Uma única fonte de veredito. Por critério da DoD: VERIFICADO (cite a evidência do livro-razão) / IMPLEMENTADO-NÃO-VERIFICADO (o que bloqueou a verificação, o que foi usado em vez disso) / BLOQUEADO (o que o usuário deve decidir ou fornecer). Inclua: uma seção Sem caps silenciosos (tudo que foi pulado, amostrado ou limitado, e por quê), as escolhas de delegação/custo feitas, decisões de decisions.md, surpresas e próximas ações recomendadas. Escrito para um colega acordando: comece com o resultado, frases completas, sem abreviações inventadas.

Instalação

Plugin Claude Code (recomendado) — adiciona as sub-habilidades empacotadas /launch, /iterate, /full-qa e /chrome-cdp-control para as quais o condutor roteia, além de ganchos de enforcement opcionais com falha aberta:

/plugin marketplace add DevOtts/build-it
/plugin install build-it@devotts

Qualquer outro agente (Cursor, Codex, Copilot, 70+ ferramentas):

npx skills add DevOtts/build-it -a <agent>

Sem as habilidades empacotadas, execute cada fase inline de acordo com as mecânicas acima — a camada de comportamento é o produto; degrade, nunca quebre.

Considerações de segurança

• Nenhum segredo é necessário para instalar ou executar a skill. Você fornece credenciais apenas para o trabalho específico que pedir para ela fazer.
• Ela lê .full.credentials e .env apenas localmente — nunca transmitidos, nunca commitados.
• Automação de navegador usa seu próprio Chrome através do Protocolo Chrome DevTools em uma porta local, reutilizando sua sessão logada; nada é armazenado ou exfiltrado. Trabalho em contas autenticadas sempre passa por confirmação por escrita — QA autônomo é apenas para ambientes de teste.
• Qualquer credencial criada durante uma execução é isolada em um artefato de credenciais dedicado com notas de rotação — nunca enterrada em prosa.
• Ações irreversíveis sempre requerem autorização explícita prévia; autonomia cobre apenas trabalho reversível.

---

Autor: DevOtts.