Spec-Lite

Um processo "spec-driven" leve, sem framework, que preserva os benefícios de alto ROI (pensar antes de codar, critérios de aceite, edge cases, gate de governança) descartando a cerimônia de baixo ROI (múltiplos artefatos para features simples).

Funciona em opencode, Claude Code, Cursor, Codex e Antigravity — a partir de uma fonte única (templates/), um instalador projeta os arquivos no layout nativo de cada ferramenta.

Filosofia: a cerimônia escala com o risco/complexidade, não é fixa. Trivial = fast-path + gate. Médio = 1 arquivo de spec. Complexo = expanda o arquivo.

Estrutura

speclite/
├── README.md
├── CONTEXT.md                         ← memória/histórico de decisões
├── package.json                       ← npm package (bin: speclite)
├── templates/                         ← FONTE ÚNICA DE VERDADE
│   ├── gate.md
│   ├── commands/                      ← corpos neutros + frontmatter do instalador
│   │   ├── constitution.md  spec.md  refine.md  build-feature.md  review.md
│   └── engineering/
│       ├── constitution.md            ← semente (placeholder até /constitution)
│       ├── definition-of-done.md
│       ├── spec-lite-template.md  tasks-template.md
│       └── examples/                  ← constituições de referência por stack (instalação opcional)
└── install/
    └── install.js                     ← Node.js 18+, zero dependências

Os arquivos nativos de cada ferramenta não vivem no repositório — são gerados pelo instalador no projeto-alvo (veja a tabela abaixo).

Instalação

O instalador é um script Node.js 18+ sem dependências. Use npx para rodar diretamente (após publicação no npm), ou node para uso local.

# via npx — sem instalar nada (requer Node 18+)
npx speclite --tools all
npx speclite --tools opencode,cursor

# ou localmente (clonando este repo)
node ./install/install.js --tools all --path /caminho/do/projeto
node ./install/install.js --tools opencode,claude

Ferramentas válidas: opencode, claude, cursor, codex, antigravity, ou all.

Durante a instalação interativa (terminal TTY), o instalador lista as constituições de exemplo disponíveis (ex.: flutter, typescript-node) e pergunta quais instalar — elas servem só de MODELO para o /constitution. Instale apenas as relevantes à sua stack; o padrão (Enter) é não instalar nenhuma, para não deixar lixo no projeto. Em modo não-interativo (CI, pipe, --dry-run) nenhum exemplo é instalado.

Flags disponíveis:

| Flag | Descrição | |---|---| | --tools <lista> | Ferramentas a instalar, separadas por vírgula, ou all | | --path <dir> | Raiz do projeto-alvo (padrão: .) | | --dry-run | Mostra o plano sem escrever nada | | --force | Sobrescreve arquivos do speclite modificados localmente | | --uninstall | Remove os arquivos/blocos instalados (combine com --tools para remover só uma ferramenta) |

O que é gerado por ferramenta

| Ferramenta | Comandos/skills | Subagente revisor | Gate sempre-ativo | |---|---|---|---| | opencode | .opencode/commands/*.md | .opencode/agent/standards-reviewer.md | opencode.json → instructions[] | | Claude Code | .claude/commands/*.md | .claude/agents/standards-reviewer.md | CLAUDE.md (bloco com @import) | | Cursor | .agents/skills/<n>/SKILL.md | skill review | .cursor/rules/speclite-gate.mdc | | Codex | .agents/skills/<n>/SKILL.md | skill review | AGENTS.md (bloco read-first) | | Antigravity | .agents/skills/<n>/SKILL.md | skill review | AGENTS.md (bloco read-first) |

Sempre, em qualquer ferramenta: docs/engineering/** na raiz do projeto (uma cópia, todas apontam para ela) e um manifesto em .speclite/install-manifest.json.

O gate (constituição + definition of done) é injetado em TODA sessão (fast-path, plan, qualquer fluxo) — não só quando você usa os comandos. É isto que torna o processo confiável sem framework.

Pós-instalação

1. Reinicie/recarregue a ferramenta (config/comandos raramente são hot-reload): opencode e Claude Code exigem reinício; Cursor/Codex/Antigravity recarregam as skills de .agents/skills.
2. Verifique que /constitution, /spec, /refine, /build-feature, /review aparecem.
3. Rode /constitution (obrigatório). A constituição vem como placeholder (marcador 0.0.0-PLACEHOLDER) e os outros comandos se recusam a rodar até ela ser gerada. O /constitution inspeciona o projeto, faz uma entrevista curta (≤6 perguntas) e escreve docs/engineering/constitution.md adaptado à sua stack. Em seguida, gera automaticamente docs/engineering/definition-of-done.md derivada da constituição (com ≤3 perguntas extras para pontos não resolvidos — ex.: se o projeto tem UI, padrão de erro, gates adicionais). Revise ambos — são a fonte de verdade do gate.
4. (Recomendado) Camada determinística: lint estrito, CI rodando analyze/test, hooks versionados. Veja "Trilhos determinísticos" abaixo.

Atualizar / desinstalar

O instalador é idempotente: re-rodar não duplica nada. Faz merges seguros em opencode.json/CLAUDE.md/AGENTS.md (bloco delimitado >>> speclite >>>, nunca clobera seu conteúdo) e rastreia tudo em .speclite/install-manifest.json. Para remover:

npx speclite --uninstall                  # remove tudo
npx speclite --uninstall --tools cursor   # remove só o Cursor

Arquivos compartilhados (.agents/skills) só são removidos quando nenhuma ferramenta restante os usa (ref-count via manifesto). O merge de opencode.json usa JSON.parse/JSON.stringify nativos — sem dependência de jq.

Uso no dia a dia

| Comando | O que faz | Quando usar | |---|---|---| | /constitution [dica] | Inspeciona o projeto, entrevista você e gera a constituição adaptada à stack (remove o placeholder) | Uma vez, na configuração; ou para regenerar/emendar | | /spec <descrição> | Cria a branch NNN-nome + specs/NNN-nome/spec.md (o quê/porquê) + tasks.md (tarefas rastreáveis); faz até 3 perguntas; não escreve código | Criar feature nova | | /refine <nº> <o que falta> | Atualiza no lugar o spec.md/tasks.md de uma feature existente; anexa tarefas faltantes como [ ] | Corrigir/complementar uma spec | | /build-feature <nº> | Implementa test-first lendo specs/NNN-nome/, marcando cada tarefa [x] no tasks.md ao concluir; roda analyze/test | Após revisar a spec | | /review <nº> | Audita o código contra constituição + DoD + critérios de aceite + estado do tasks.md; reporta file:line + regra | Antes de commit/PR | | /explain <pergunta> | Só leitura — responde dúvidas sobre o código existente, ancorando em file:line; corrige premissa falsa; nunca edita; sugere /spec//refine se for pedido de mudança. Funciona sem constituição. | Qualquer dúvida sobre o código | | /debt [caminho] | Só leitura — lista atalhos deliberados marcados com # speclite-debt: no código (ceiling + upgrade); marca no-trigger (sem gatilho) e malformed | Auditar dívida deliberada antes de commit/release |

Fluxo típico (feature média):

/spec <descrição em linguagem natural da feature>
   → cria branch NNN-nome + specs/NNN-nome/{spec.md,tasks.md}; revise ambos
   → faltou algo? /refine NNN <o que ajustar>  (NUNCA re-rode /spec p/ a mesma feature)
/build-feature NNN
/review NNN

Regra de ouro: /spec = criar feature nova · /refine = ajustar feature existente. Re-rodar /spec para a mesma feature criaria número/branch duplicado.

Para algo trivial (refactor, 1 widget pequeno): pule o /spec. O gate (constituição + DoD injetados + lint + CI) já garante o piso de qualidade.

Como escalar a cerimônia

• Trivial: fast-path direto. Gate garante o piso.
• Médio (uma tela, um caso de uso): spec-lite de 1 arquivo + /build-feature + /review.
• Complexo (domain/data, regra de negócio, integração): adicione arquivos extras NA MESMA pasta da feature (specs/NNN-nome/plan.md, contracts/), ou adote o processo completo de desenvolvimento baseado em especificações.

Trilhos determinísticos (recomendado, independem de agente)

O Spec-Lite alinha o agente. Para garantir qualidade independente de quem escreve o código (humano ou IA), adicione no projeto:

• Lint estrito: o lint mais rígido da sua stack (ex.: very_good_analysis no Flutter, ESLint/Biome strict no TS, Ruff no Python).
• Guardrail tests: testes que falham em violações estruturais (valor mágico fora dos tokens; import de framework na camada de domínio).
• CI: rodando o lint/análise + a suíte de testes em todo PR.
• Hooks versionados: lefthook/husky rodando analyze+test no pre-commit.

Esses são a rede de segurança final que nenhum fluxo de implementação burla.

O que você abre mão em relação a um processo completo

• Tooling mantido por terceiros.
• Análise de consistência cruzada automática (vira papel do /review).
• Geração de issues no GitHub automática. (Numeração de feature e criação de branch JÁ são feitas pelo /spec.)
• Padronização forte entre múltiplos times.

Em troca: alta eficiência com peso mínimo.