Como o builder funciona

Spec / do contrato à entrega

Descreva a intenção

O texto C4 explica o negócio. O bloco builder: no front-matter define campos, API, persistência e critérios de aceite.

dotnet builder new feature Dock dock-docas --entity Dock

Explorar esta etapa →

Lint / do contrato à entrega

Valide o contrato

Encontre inconsistências antes de gerar. Corrija os diagnósticos BLD com seus caminhos JSON e próximos passos.

dotnet builder spec lint

Explorar esta etapa →

Plan / do contrato à entrega

Revise a mudança

Veja os arquivos, regiões e deltas de schema. Mudanças no banco precisam de task, autor e link da migration.

dotnet builder spec plan <feature>

Explorar esta etapa →

Apply / do contrato à entrega

Gere a fatia

Aplique o plano depois de revisar. Hashes e regiões sil-business protegem o código editado pelo desenvolvedor.

dotnet builder spec apply <feature>

Explorar esta etapa →

Check / do contrato à entrega

Prove o resultado

Confira build, testes e regras. Um resultado incomplete precisa de investigação; não equivale a uma aprovação.

dotnet builder check --ci

Explorar esta etapa →

PR / do contrato à entrega

Entregue evidências

Gere o resumo, revise o diff e abra o PR no seu fluxo Git. O builder prepara o resumo; não publica o PR.

dotnet builder pr summary --base origin/main

Explorar esta etapa →

Três partes, responsabilidades claras

Parte	Entrada	Saída
Dev + agente	Intenção e contexto	Spec C4, decisões e lógica de negócio
Builder	Bloco `builder:` e workspace	Plano, código, migrations, contratos e diagnósticos
Backend	HTTP + dados	Regras de negócio sobre o runtime próprio

CLI e MCP chamam o mesmo BuilderEngine. A IA escolhe o próximo passo; geração e verificações são determinísticas.

O ciclo de uma alteração

Edite a spec com add field, add filter ou diretamente no Markdown.
Rode spec lint e corrija os diagnósticos.
Revise spec plan; forneça os metadados da migration se houver delta no banco.
Aplique com spec apply. Preserve as regiões sil-business.
Rode spec sync, checks, testes e verificações de banco/contrato pertinentes.
Revise o diff, gere pr summary --base origin/main e abra o PR pelo fluxo da equipe.

Leia o resultado, não só o exit code

Exit	Significado	Próximo passo
`0`	Completo, sem erros	Avance e revise a evidência
`1`	Violações encontradas	Corrija os diagnósticos
`2`	Incompleto, inválido ou cancelado	Resolva a causa e repita

--dry-run não grava. --no-build deixa o check incompleto. --changed ainda usa full scan como fallback. plan arquivo.json e apply arquivo.json tratam planos de arquivos; spec plan/apply tratam specs de feature.