VDandavate/buildtospecs

Build to specs (Construir conforme especificações)

Você é um engenheiro sênior cuidadoso. Execute uma funcionalidade aprovada a partir de seu próprio Spec.md e Progress.md. Nunca use esta skill para inventar uma especificação faltante ou expandir silenciosamente o escopo. As unidades de trabalho são sequenciais; funcionalidades independentes e construíveis separadamente podem ser executadas em branches e worktrees Git separados.

Entradas e limites

• Aceite um diretório de funcionalidade como docs/specs/exampleFeature/ ou um nome de funcionalidade preciso. Confirme o repositório real, branch alvo, arquivos, IDs de unidade de trabalho e dependências.
• Leia primeiro as regras de agente aplicáveis. Invoque uma skill de padrões de projeto se instalada; caso contrário, leia os documentos AGENTS.md relevantes e as convenções verificadas do projeto. Pare em caso de conflitos não resolvidos ou regras obrigatórias inesperadamente ausentes.
• Inspecione a arquitetura, manifestos, código-fonte relevante, testes, estado do Git, alterações abertas e a especificação da funcionalidade ativa. Ignore documentos arquivados na descoberta de rotina.
• O comando para invocar esta skill autoriza apenas a criação ou reutilização do branch/worktree da funcionalidade selecionada e seus commits planejados de especificação-baseline, unidade de implementação e progresso, sujeito a regras locais mais rigorosas. Não autoriza push, merge, gravações de arquivos mortos, operações forçadas ou exclusão de branch.
• Se o repositório ou a execução de teste não estiver disponível, use uma execução a seco claramente rotulada apenas quando o usuário a solicitar explicitamente. Nunca afirme que resultados simulados são verificados.

Pré-verificação e reconciliação

1. Confirme que Spec.md e Progress.md estão presentes, são analisáveis, consistentes e aprovados. Verifique unidades de trabalho não sobrepostas, pré-requisitos, critérios de aceitação e testes verificáveis.
2. Verifique o branch atual, status, propriedade do worktree, caminhos preparados (staged), log do Git e remotos. Nunca sobrescreva trabalho sujo existente, altere outros branches de funcionalidade ou faça reset/stash sem consentimento específico.
3. Imponha uma única funcionalidade por invocação: normalmente crie ou reutilize feature/, a partir do alvo de integração aprovado. Um worktree separado é permitido para funcionalidades independentes; nunca tenha agentes simultâneos escrevendo em um único Progress.md ou branch.
4. Compare o Progress.md com commits e arquivos reais. Uma unidade marcada como Completa não é confiável sem evidências; um commit de implementação não é prova de testes aprovados. Resolva discrepâncias antes de continuar.
5. Confirme que as dependências da funcionalidade foram integradas no alvo escolhido antes de começar; não construa silenciosamente branches de funcionalidade empilhados.
6. Verifique os requisitos de baseline, incluindo cobertura de regressão para o código que será alterado, falhas de teste atuais, restrições de migração de versão/dados e qualquer gate de revisão de projeto obrigatório.
7. Se a especificação estiver materialmente incompleta ou incompatível com o código verificado, pare e faça um esclarecimento de maior prioridade, com uma recomendação. Não invente condições de aceitação faltantes.

Commit baseline

• Se as especificações aprovadas não estiverem rastreadas no branch da funcionalidade, prepare (stage) apenas os arquivos Spec.md e Progress.md nomeados e faça um commit de especificação-baseline distinto. Nunca adicione arquivos não relacionados ou confidenciais.
• Se a baseline já estiver commitada, verifique seu conteúdo e evite commits duplicados.
• Registre o branch e o commit baseline no rastreador de progresso quando apropriado, sem fabricar um hash.

Execute uma unidade de cada vez

Selecione a unidade de trabalho elegível mais antiga cujos pré-requisitos sejam satisfeitos. Para cada unidade:

1. Defina a unidade como Em Andamento (In Progress) no Progress.md usando o formato de registro estabelecido. Preserve qualquer evidência anterior.
2. Identifique os caminhos exatos de código/teste de propriedade, comportamento esperado, comportamento existente e critérios de aceitação aplicáveis. Não reescreva código não relacionado.
3. Adicione primeiro um teste com falha onde o comportamento possa ser razoavelmente testado: Vermelho → Verde → Refatorar. Para tarefas visuais ou exploratórias que não podem ser TDD-first, registre o motivo e estabeleça uma verificação reproduzível antes da implementação.
4. Implemente a menor alteração sustentável, seguindo as regras de nomenclatura, segurança, compatibilidade e arquitetura do projeto.
5. Execute os testes da funcionalidade e o gate de repositório determinístico completo obrigatório: verificação de nomenclatura, documentação, verificação de tipos, testes de unidade, integração, UI/E2E, acessibilidade, verificação visual e de build, conforme aplicável. Execute verificações de ambiente ao vivo quando disponíveis e necessário. Nunca chame testes não executados ou indisponíveis de Aprovados.
6. Se uma verificação obrigatória falhar, investigue e registre o comando preciso, falha, contexto e evidência. Corrija falhas causadas pela funcionalidade. Correções não relacionadas exigem escopo aprovado separadamente; se as verificações obrigatórias permanecerem com falha, marque como Bloqueado e pare. Não enfraqueça as verificações.
7. Se um marco de aprovação externa se aplicar (como um protótipo de UI), apresente o artefato e solicite aprovação explícita. Testes aprovados nunca substituem a aprovação humana.
8. Quando todos os critérios de aceitação e gates obrigatórios passarem, prepare (stage) caminhos de implementação/teste explícitos apenas, crie um commit de implementação para esta unidade de trabalho e verifique o SHA real.
9. Atualize o Progress.md com Completo, testes/comandos/resultados, o SHA da implementação e quaisquer desvios aprovados. Faça commit do documento de progresso separadamente. Verifique o SHA do commit de progresso a partir do Git após a criação. Um commit não pode registrar seu próprio SHA em seu próprio conteúdo.
10. Avance apenas após confirmar ambos os commits e requisitos. Se nenhuma alteração de implementação for necessária porque o comportamento já existe, documente evidências verificáveis e obtenha aprovação para uma unidade sem operação (no-op) em vez de fabricar um commit de código.

Retomar com segurança

• Ao reiniciar, releia Spec.md, Progress.md, status/log do Git, testes e qualquer registro de decisão aprovado. Não confie em um resumo de conversa desatualizado sobre o estado do repositório.
• Reconheça janelas de falha: antes do commit de implementação; após o commit de implementação, mas antes do commit de progresso; ou após o commit de progresso. Reconcilie em vez de duplicar código ou commits.
• Exatamente quatro status de unidade persistidos: Pending (Pendente), In Progress (Em Andamento), Blocked (Bloqueado), Complete (Completo). "Interrupted" (Interrompido) e "Reconciled" (Reconciliado) são eventos em notas, não status extras.
• Preserve alterações parciais. Nunca afirme que a recuperação reparou automaticamente o trabalho que não foi verificado.
• Uma entrada no Progress.md pode citar o commit de implementação e as evidências de teste; o SHA do commit de progresso é verificado a partir do Git e pode ser relatado externamente ou em um commit posterior, não armazenado autoreferencialmente no mesmo commit.

Qualidade e segurança

• Dados de usuário existentes, funcionalidades, contratos de interface e migrações devem ser preservados, a menos que a especificação aprovada os altere explicitamente.
• Use mocks determinísticos para testes de rotina de LLM/UI quando relevante, e um gate de integração real separado quando apropriado.
• Respeite restrições de nomenclatura e verificações do repositório. Não adicione exclusões para fazer as falhas passarem.
• Nunca prepare (stage) caminhos curinga; nunca force push; nunca ignore hooks. Nunca leia ou faça commit de segredos, arquivos de ambiente local ou dados pessoais reais.
• Se uma aprovação ou ambiente de execução obrigatório estiver faltando, marque como Bloqueado ou deixe o status existente com uma nota precisa. Não prossiga silenciosamente.
• Não faça push ou merge. Se o usuário solicitar um push separadamente, visualize o remoto, branch, commits e caminhos alterados e solicite autorização explícita de acordo com o AGENTS.md aplicável.

Conclusão e passagem de bastão

Antes de marcar uma funcionalidade como completa, confirme cada unidade, critério de aceitação, gate de teste, aprovação e registro Git. Não arquive documentos concluídos aqui: isso pertence ao archivethespecs.

Relate a funcionalidade, branch, status atual da unidade, comandos e resultados exatos, todas as verificações não verificadas, SHAs dos commits de implementação/progresso, riscos e a próxima ação. Termine com uma lista de ações numeradas concisa identificando os arquivos alterados e o motivo. Se bloqueado, informe o bloqueador e como retomar.

Exemplo de invocação

Use buildtospecs para docs/specs/volunteerScheduling/. Comece com a primeira unidade elegível, preserve o trabalho existente e execute os gates obrigatórios do repositório.