Pitch: Nébula Spec Kit — um framework open source para descobrir, especificar, executar e validar projetos com ou sem agentes de IA

Quem já trabalhou com agentes de IA em projetos reais sabe de uma frustração específica: a IA executa bem o que foi pedido, mas o que foi pedido estava incompleto. O resultado é código tecnicamente funcional que não corresponde ao que o produto precisava. Ou então: o agente entregou a task, mas não há como saber o que ele tocou, com que critério fechou, e se o que ele fez vai escalar.

O problema não é o agente. É a ausência de estrutura ao redor dele.

O Nébula Spec Kit é um framework open source que resolve essa ausência. Ele padroniza como um projeto é descoberto, especificado, planejado, executado e validado — com suporte nativo a agentes de IA, sem abrir mão de rastreabilidade, qualidade e previsibilidade.

github.com/MolinariBR/NebulaSpecKit

O diagnóstico por trás do projeto

A maioria dos projetos não falha por falta de talento técnico. Falha por acúmulo de decisões sem registro: o escopo que ficou na cabeça do dev, a arquitetura que ninguém documentou antes de implementar, o critério de "pronto" que cada um interpreta diferente.

Quando você coloca um agente de IA nesse ambiente, os problemas se amplificam. O agente executa com velocidade. Sem estrutura, executa rápido na direção errada. E porque não há contrato de entrada nem critério de saída, é difícil detectar o desvio até ele já estar propagado.

O Nébula parte de cinco princípios que respondem diretamente a esse diagnóstico:

Fidelidade       — o que está documentado é o que vai para produção
Rastreabilidade  — cada decisão e entrega têm registro
Consistência     — documentação, execução e validação falam a mesma língua
Governança       — dev e IA operam com as mesmas regras
Previsibilidade  — prazo, qualidade e manutenção deixam de ser variáveis aleatórias

Estrutura: o que existe no repositório

NebulaSpecKit/
├─ GUIDE.md              ← metodologia central (o princípio operacional)
├─ Docs/                 ← artefatos oficiais do projeto (saída real)
├─ Templates/
│  ├─ Full/              ← templates completos por artefato
│  └─ Quick/             ← templates de uso rápido
├─ Skills/               ← capacidades técnicas mapeadas
├─ Workflows/            ← fluxos executáveis
├─ Quality/              ← gates, testes e políticas de qualidade
├─ agents/               ← contrato e catálogo de agentes especializados
├─ Prototype/            ← protótipos HTML de interface
└─ Manual/               ← guia operacional completo (baseline + deltas)

A divisão entre Templates/ e Docs/ é uma regra canônica do framework, não uma convenção opcional:

• Templates/ contém modelos — são referência de estrutura, nunca saída oficial
• Docs/ contém os artefatos reais do projeto — é onde o que foi decidido fica registrado
• Prototype/ contém interfaces HTML construídas antes do código

Implementação ou refatoração só começam após a documentação mínima da demanda estar consistente em Docs/. Isso não é burocracia — é a condição que torna a execução por agente confiável.

As fases do projeto — do brief ao deploy

O GUIDE.md organiza a construção em seis fases sequenciais com mapeamento explícito de template → artefato oficial:

Fase 0 — Descoberta: captura contexto, motivação e escopo antes de qualquer decisão técnica. O template brief.md força o registro do problema real antes de falar em solução.

Fase 1 — Definição do Projeto: define produto, objetivos, restrições e stack. Dois artefatos: project.md e stack.md. A stack é documentada separadamente do projeto porque muda por razões diferentes.

Fase 2 — Requisitos Funcionais: mapeia comportamentos esperados na perspectiva do usuário via user-stories.md com critérios de aceite funcionais — não técnicos.

Fase 3 — Design de Produto: define experiência visual, navegação e sistema de design. Quatro artefatos: pages.md, flow.md, design-system.md e tokens.json. Protótipos HTML vão para Prototype/.

Fase 4 — Especificação Técnica: modela entidades, arquitetura, contrato de API e estrutura de deploy. O contrato em YAML (contract.yaml) é artefato separado porque é o que a IA vai usar para validar integração.

Fase 5 — Execução e Controle: opera com plan.md, tasks.md e control.md. Cada task tem entrada clara, critério de saída definido e registro de evidências.

O mapeamento completo de template → artefato:

Templates/Full/brief.md         → Docs/brief.md
Templates/Full/project.md       → Docs/project.md
Templates/Full/stack.md         → Docs/stack.md
Templates/Full/user-stories.md  → Docs/user-stories.md
Templates/Full/pages.md         → Docs/pages.md
Templates/Full/flow.md          → Docs/flow.md
Templates/Full/design-system.md → Docs/design-system.md
Templates/Full/tokens.json      → Docs/tokens.json
Templates/Full/entities.md      → Docs/entities.md
Templates/Full/architecture.md  → Docs/architecture.md
Templates/Full/contract.yaml    → Docs/contract.yaml
Templates/Full/structure.md     → Docs/structure.md
Templates/Full/deploy.md        → Docs/deploy.md
Templates/Full/plan.md          → Docs/plan.md
Templates/Full/tasks.md         → Docs/tasks.md
Templates/Full/control.md       → Docs/control.md

Cada template tem exatamente um destino. Não há ambiguidade sobre onde cada decisão é registrada.

A política de execução por task — a parte que muda como você trabalha com IA

Essa é a parte do projeto que mais diferencia o Nébula de outros frameworks de documentação.

Task 1 é sempre de bootstrap estrutural. É a única task autorizada a criar diretórios e arquivos. Todas as tasks seguintes apenas editam. Se um arquivo obrigatório estiver ausente ao chegar numa task downstream, você abre uma task de ajuste estrutural — não improvisa a criação no meio do fluxo.

1 task = 1 commit. Cada task concluída gera exatamente um commit. O commit registra hash, arquivos tocados e resultado do gate de qualidade. Isso cria rastreabilidade total: qualquer estado do projeto pode ser reconstruído a partir do histórico.

O gate de qualidade é obrigatório para fechar toda task. Não é checklist opcional. É condição de fechamento. O Quality/gate.md define dez critérios:

1.  Lint aprovado
2.  Typecheck aprovado (quando aplicável)
3.  Build aprovado (quando aplicável)
4.  Testes realistas executados conforme realistic-tests.md
5.  Sem mock/stub/placeholder fora de exceção formal registrada
6.  Impacto de API validado com Curl e scripts reproduzíveis
7.  Impacto de interface validado com e2e
8.  Impacto mobile validado em dispositivo físico para fluxos críticos
9.  Dependências e lockfile consistentes
10. Evidências registradas na task

Se qualquer critério falhar, a task permanece aberta. A IA não fecha o que o gate não aprova.

A política anti-mock — qualidade orientada à produção realista

O Quality/anti-mock.md é curto e direto: mock, stub e placeholder são proibidos por padrão em validações de integração, contrato, e2e e release.

A exceção existe, mas tem custo: para aprovar uma exceção, é necessário registrar na task justificativa técnica objetiva, escopo exato, prazo de remoção, risco assumido e plano para substituir por validação real. Sem esse registro, a task não fecha.

Isso muda o incentivo. Com mock permitido por padrão, a tendência natural é adiar a validação real. Com mock proibido por padrão e exceção com custo de registro, a tendência inverte: o dev e o agente resolvem o problema real em vez de contorná-lo.

Os agentes — especializados, com contrato, com handoff explícito

O agents/02CATALOG.md define sete agentes especializados com matriz de roteamento:

Agente	Domínio
ScopeAgent	Descoberta de escopo e objetivos mensuráveis
ProductAgent	Telas, fluxo, user stories, protótipos
SystemAgent	Arquitetura, entidades, contrato de API
ExecutionAgent	Planejamento e execução por tasks
QualityAgent	Validação e fechamento de tasks
ReleaseAgent	Deploy, release e rollout
RecoveryAgent	Incidentes, hotfix e estabilização

Cada agente tem definição de quando chamar, o que entregar e para qual agente fazer handoff. O handoff é explícito — não implícito. Quando a demanda cruza domínios (ex: ProductAgent entregou spec de tela → SystemAgent precisa modelar o impacto técnico), o ponto de transição é declarado, não assumido.

Todo agente opera com três camadas de contexto obrigatório na inicialização:

1. Metodologia (GUIDE.md e guias dos pilares)
2. Artefatos oficiais de execução em Docs/
3. Templates como referência de estrutura — nunca como saída

O Manual — baseline + deltas por ferramenta

O manual tem uma arquitetura que merece destaque: ele opera em camadas de baseline + delta.

O baseline define o comportamento padrão para qualquer modo de operação. Os deltas especificam variações por contexto — com agentes ou sem agentes, por ferramenta (Copilot, Cursor, Zed, e mais seis ferramentas cobertas nos arquivos 07 a 14).

Isso resolve um problema real de adoção: o mesmo framework funciona para um dev solo sem agentes (modo 03NO-AGENTS.md) e para um time com múltiplos agentes especializados (02AGENTS.md). A diferença não é no método — é no delta de execução. O método central é o mesmo.

O que o Nébula não é

O README é explícito sobre isso:

• Não é um gerador de código ou scaffolding automático
• Não é um substituto para decisão técnica — é uma estrutura para que as decisões sejam tomadas antes da execução, não durante
• Não funciona bem se usado parcialmente: pular as fases de descoberta e especificação para ir direto para tasks é o anti-padrão central que o framework foi construído para evitar
• Não garante qualidade por si mesmo — garante que os critérios de qualidade sejam aplicados de forma consistente e rastreável

Estado atual

• v1.0.0 — lançada em 05/04/2026, licença MIT
• 13 commits, 4 pull requests abertos
• Estrutura completa: Docs, Templates Full e Quick, Skills, Workflows, Quality com 6 arquivos, agents com 3 arquivos de contrato e catálogo, Manual com 22 arquivos organizados em baseline + delta, Prototype, imagens

O projeto tem site de referência em (https://nebulaweb.vercel.app/).

Contribuição

Issues, sugestões e PRs são bem-vindos. Especialmente interessado em:

• Feedback de quem usa frameworks de especificação em times com IA em produção
• Casos onde a política de 1 task = 1 commit cria atrito real e como foi resolvido
• Contextos onde o modelo de agentes especializados com handoff explícito precisou de adaptação

github.com/MolinariBR/NebulaSpecKit