Fábrica de Software (Software Factory)

Elimine qualquer dúvida de escopo primeiro. Congele as obrigações. Delegue cada fase pesada a um subagente fresco. Prove a conclusão com um Verificador independente que não escreveu o código.

┌──────────┐   ┌──────┐   ┌────────┐   ┌───────┐   ┌────────┐
│ DISCOVER │ → │ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────────┘   └──────┘   └────────┘   └───────┘   └────────┘
 0 dúvidas      confirme   obrigações   lotes      autor != verificador

Cinco movimentos, três artefatos duráveis sob .specs/features/<feature>/, e um Orquestrador Leve (Thin Orchestrator) no chat principal que nunca infla sua janela de contexto.

DISCOVER: Um subagente scout apenas de leitura escaneia o codebase e retorna um resumo compacto (~30 linhas) de ambiguidades. O chat principal entrevista o usuário com opções concretas e padrões recomendados até que zero suposições não confirmadas permaneçam (Confirmed? y para cada linha). Consulte discovery.md.
PLAN: Um subagente planner escreve .specs/features/<feature>/plan.md (Problema, Fluxo, Impacto, Relações, Superfície, Aterrissagem, Critérios, Fora de escopo, Suposições, Observável, Fontes) e executa validate_plan.py. O usuário dá uma rápida aprovação em plan.md. Consulte plan.md.
CHECKS: Após a aprovação do plan.md, o loop autônomo pós-plano começa. Um subagente specifier deriva .specs/features/<feature>/checks.md (afirmações + provas, junção de Cobertura, Política de teste, Varrido, Aritmética de Handoff) e executa validate_checks.py. Consulte checks.md.
BUILD: Um subagente builder por fatia/lote escreve testes estritamente a partir das verificações, implementa o código, executa provas, atualiza checks.md e faz commit usando check_commit.py. Consulte build.md.
VERIFY (e loop de CORREÇÃO): Um subagente verifier independente (nunca o builder) audita <feature base>..HEAD contra cada verificação, escreve .specs/features/<feature>/verification.md e executa validate_verification.py. Se alguma verificação falhar, um subagente fixer resolve as lacunas classificadas e um novo verifier re-verifica (até 3 rodadas). Consulte verify.md e orchestration.md.

Por que este formato

Agentes de codificação falham em funcionalidades complexas por dois motivos previsíveis:

Inchaço da janela de contexto: Quando uma única sessão de chat explora o repositório, entrevista o usuário, escreve o plano, deriva verificações, escreve testes e código e verifica seu próprio trabalho, a janela de contexto se enche e aciona uma compactação com perdas.
Requisitos não confirmados e pontos cegos de auto-revisão: Adivinhar silenciosamente o comportamento do produto (Confirmed? n) ou permitir que o autor certifique sua própria conclusão entrega os próprios pontos cegos do autor.

software-factory resolve ambos:

Orquestrador Leve (<15k tokens no chat principal): O chat principal atua estritamente como coordenador e entrevistador do usuário. Toda leitura de codebase, criação de artefatos, codificação, teste e verificação são executados dentro de subagentes efêmeros isolados (scout, planner, specifier, builder, verifier, fixer) que se comunicam exclusivamente por meio de arquivos .specs/features/<feature>/ em disco e commits git. Protocolo completo de despacho: orchestration.md.
Conjunto pequeno e congelado de obrigações + Verificador independente: Não há lista de tarefas granular ou catálogo de componentes (Propósito/Localização/Interfaces por classe) que possa ficar desatualizado. Decisões irreversíveis (one-way doors) recebem uma forma literal em Landing; posicionamento reversível é decidido no diff.

Regras críticas

O conjunto fixo. Estas regras se aplicam em todos os perfis:

Zero suposições não confirmadas (Confirmed? y). Nunca adivinhe comportamento do produto ou escopo silenciosamente. Toda área cinzenta descoberta durante DISCOVER deve ser perguntada com opções concretas e um padrão recomendado, ou delegada explicitamente pelo usuário (Confirmed? y). validate_plan.py rejeita qualquer linha onde Confirmed? seja n ou esteja em branco.
Orquestrador Leve e Limite Estrito de 1 Subagente por Fase (scout != planner != specifier != builder != verifier). Mantenha o chat principal abaixo de ~15k tokens. Nunca mescle duas fases em uma única chamada de subagente:
- scout APENAS explora e retorna o resumo de ambiguidade de ~30 linhas.
- planner APENAS escreve plan.md + executa validate_plan.py, então para e sai.
- specifier APENAS escreve checks.md + executa validate_checks.py, então para e sai (NUNCA deve escrever arquivos de teste ou código de implementação ou continuar para BUILD).
- builder APENAS executa depois que specifier retornou. Para funcionalidades com múltiplas fatias (S1, S2, ...), despache um subagente builder separado por fatia sequencialmente para que cada fatia execute em uma janela de contexto nova e relate o progresso ao usuário.
- verifier APENAS executa em um subagente novo após o commit final do builder.
Toda verificação é uma afirmação observável com um valor concreto mais a prova — o seletor de teste exato ou comando cujo código de saída a resolve. Sem prova, sem verificação.
Testes afirmam o que as verificações dizem, nunca o que o código por acaso faz. Nunca escreva um teste lendo a implementação.
Nunca enfraqueça uma afirmação, delete um teste ou pule um para fazer uma suíte passar. Uma verificação genuinamente errada é uma parada-e-pergunta, não uma edição.
Verificações e linhas de Política de teste são fixadas uma vez aprovadas. Em plan.md, Landing, Relations e Surface são aditivos — uma porta descoberta durante a construção ganha uma linha antes do código que a fecha, e uma linha aprovada pelo usuário nunca é reescrita. Flow e Impact são mantidos verdadeiros no commit que altera o caminho.
O Verificador é um subagente novo, nunca o autor, nunca opcional, nunca esperando para ser chamado. O Orquestrador o despacha imediatamente após o último commit da funcionalidade chegar em <feature base>..HEAD com todas as verificações.
O perfil é um piso e é imposto por validate_verification.py.
O portão de conclusão é um script, não um sentimento: validate_verification.py deve sair com código 0.
Raio de explosão: uma especificação aprovada autoriza edições locais e commits locais. git push, deploy e alterações em dados de produção precisam de uma autorização explícita para essa ação.

Perfil

O projeto declara quanto é executado em AGENTS.md ou equivalente. Na ausência de declaração: light.

## software-factory

profile: light
budget: 150k

Perfil	Adiciona	Não pode capturar
`light` (padrão)	provas executadas em `HEAD` com cada teste nomeado mostrado como existente e executado, uma afirmação localizada por verificação, lacunas de nível e amostragem, `Varrido existente` relido	um membro do conjunto sem prova; um teste que passaria sob uma implementação errada
`standard`	a junção de `Cobertura` recalculada, linhas de `Política de teste` com um veredito cada, uma falha por superfície de afirmação	uma verificação que contradiz uma fonte vinculante; uma tela que ninguém construiu
`ui`	fontes vinculantes abertas e comparadas, enumeração por tela de cópia e arranjo	apenas espaçamento, cor e peso de tipo, enumerados por tela

validate_verification.py falha em um relatório cujo perfil difere daquele sob o qual checks.md foi aprovado, falha em um relatório standard sem linhas de falha ou cobertura recalculada, e falha em um relatório ui sem seção de fontes vinculantes.

Artefatos

.specs/
├── STATE.md                    # Registro de decisões (AD-NNN) + snapshot de Handoff
├── LESSONS.md                  # renderizado por scripts/lessons.py - nunca editar manualmente
├── lessons.json                # de propriedade da máquina
└── features/<feature>/
    ├── plan.md                 # problema, fluxo, impacto, relações, superfície, aterrissagem, critérios, suposições (todas y), observável
    ├── checks.md               # afirmações + provas, junção de cobertura, política de teste, varrido, lotes de handoff
    └── verification.md         # relatório do Verificador independente

Crie cada arquivo quando sua fase produzir conteúdo. Para uma alteração de aproximadamente três arquivos sem porta irreversível e zero ambiguidade de escopo, escreva apenas checks.md com um parágrafo ## Intenção e pule plan.md.

Cinco seções de design delimitadas em `plan.md`

Seção	Revisa	Mantém fora
`Flow`	o caminho, uma linha por salto	qualquer módulo que nem existe nem é criado por uma porta — isso é posicionamento
`Impact`	o que muda por baixo: termos e dados existentes	registros de risco
`Relations`	entidades, cardinalidade, restrições unidirecionais	colunas e tipos
`Surface`	rota, entrada, saída, status	especificação do corpo da requisição e IDs de verificação — estes ainda não existem
`Landing`	as portas irreversíveis, com a forma literal e a alternativa rejeitada	qualquer coisa que uma refatoração reverta

Fluxo

Discover — Despache o subagente scout apenas de leitura para inspecionar o repositório, .specs/STATE.md e .specs/LESSONS.md e retornar um resumo de ambiguidade de ~30 linhas. Conduza o usuário por áreas cinzentas genuínas de produto e escopo (no máximo 2 perguntas por turno, opções concretas com padrão recomendado) através das superfícies Observável e das 9 dimensões implícitas até que 0 dúvidas permaneçam: discovery.md.
Plan — Despache o subagente planner com as decisões de descoberta confirmadas para escrever .specs/features/<feature>/plan.md e passar em validate_plan.py. Apresente plan.md ao usuário para aprovação rápida: plan.md.
Checks — Uma vez que plan.md esteja aprovado, execute autonomamente. Despache um subagente specifier dedicado para derivar .specs/features/<feature>/checks.md (afirmações + provas, junção de Cobertura, Varrido e dimensionamento de lote ## Handoff) e passar em validate_checks.py, então termine esse subagente antes que qualquer código ou testes sejam escritos: checks.md.
Build — Depois que specifier terminar, despache um subagente builder novo por fatia (S1, S2, ...) sequencialmente. Cada builder escreve testes a partir das verificações para sua fatia designada, implementa, executa provas, registra Boundary em checks.md, faz commit com check_commit.py e sai: build.md.
Verify & Fix — Despache um subagente verifier novo sobre <feature base>..HEAD para escrever verification.md e executar validate_verification.py. Se FALHAR, despache um subagente fixer e re-verifique (até 3 rodadas): verify.md.
Orquestração e Despacho de Subagentes — Regras do Orquestrador Leve, orçamentos de janela de contexto e mapeamentos multiagente (antigravity, claude, codex): orchestration.md.
Memória Durável — Decisões do projeto (STATE.md), handoff de sessão e lições baseadas em verificação (lessons.py): memory.md.

Scripts

Resolva <skill-dir> como o diretório que contém este SKILL.md e invoque python3 <skill-dir>/scripts/<nome>.py. Passe --root quando o diretório de trabalho atual (cwd) diferir da raiz do projeto. Uma saída diferente de zero significa PARE e corrija.

Quando	Comando
Inspecionar fase do pipeline e próximo papel do subagente	`orchestrate.py status <feature> --root <dir>`
Gerar prompt isolado do subagente	`orchestrate.py prompt --role <scout
Executar portão de fase via orquestrador	`orchestrate.py gate --phase <plan
Despachar subagente via CLI (ou `--dry-run`)	`orchestrate.py dispatch --role --agent <antigravity
Antes de apresentar `plan.md`	`validate_plan.py <feature>`
Antes de iniciar `BUILD`	`validate_checks.py <feature>`
Antes de cada commit	`check_commit.py --message "<msg>"`
Antes de declarar concluído	`validate_verification.py <feature>`
Na destilação	`lessons.py add ...`
Após editar um validador, script ou template	`selftest.py`

Subagentes e handoff

Cada fase é estritamente isolada em sua própria invocação de subagente (scout -> planner -> specifier -> builder [S1] -> builder [S2] -> ... -> verifier -> fixer). Nunca combine specifier (CHECKS) e builder (BUILD) no mesmo subagente. Durante BUILD, quando uma funcionalidade tem múltiplas fatias (S1, S2, ...), despache um subagente builder separado por fatia sequencialmente para que cada builder comece com uma janela de contexto limpa, termine rapidamente, faça commit de sua fatia com verde e retorne uma atualização de progresso ao Orquestrador Leve.

Quando a fatia final do builder retornar verde, o Orquestrador imediatamente despacha o subagente verifier independente no mesmo turno sem perguntar ao usuário.

Cadeia de conhecimento

Em ordem estrita: código existente e convenções, documentos do projeto, documentação de bibliotecas (Context7 quando disponível), pesquisa na web, então sinalize como incerto. Nunca invente uma API, uma flag, um comando ou um comportamento.

Comportamento de saída

Produza o artefato; não narre a fase. Lidere com o veredito. Declare decisões de forma definitiva. Corte preenchimento e hesitação mecânica. Mantenha os cabeçalhos das seções em inglês (eles são um esquema verificado pelos portões).

brenoacker/agent-skills

O que é agent-skills?

Perguntar na sua IA favorita

Documentação