Comandos CLI

Comandos principais

Comando	O que faz
`spellcomp compile .`	Compila o projeto inteiro — descobre o arquivo-índice por convenção de nome
`spellcomp compile <arquivo>`	Compila um arquivo específico (arquivo-índice ou módulo)
`spellcomp check .`	Valida a spec e verifica integridade dos .md gerados — sem gerar nenhum arquivo
`spellcomp info`	Exibe mapa do projeto: fases, módulos, blocos declarados, status
`spellcomp add <projeto> <modulo.spell>`	Cria um módulo e registra no bloco `Arquivos { }` do arquivo-índice
`spellcomp remove <projeto> <modulo.spell>`	Remove um módulo após verificar dependências
`spellcomp --version`	Exibe a versão instalada do spellcomp
`spellcomp --help`	Exibe ajuda dos comandos disponíveis

Flags do compile

Flag	Efeito
`--output pasta/`	Especifica a pasta de saída para os arquivos gerados. Padrão: diretório do projeto.
`--readable`	Gera output legível por humanos. Padrão: formato compacto (~40–63% menos tokens).
`--force`	Sobrescreve `.md` modificados diretamente sem abortar. As edições diretas são perdidas.

Exemplos de uso

# Compilar projeto no diretório atual
spellcomp compile .

# Compilar com output legível para revisão
spellcomp compile . --readable

# Compilar e colocar output em pasta específica
spellcomp compile . --output ./dist

# Sobrescrever .md modificados diretamente (edições serão perdidas)
spellcomp compile . --force

# Compilar um módulo específico
spellcomp compile modulo-usuarios.spell

# Validar sem gerar arquivos (CI/CD)
spellcomp check .

# Ver mapa completo do projeto
spellcomp info

# Adicionar módulo e registrar no índice
spellcomp add agendamedica modulo-exames.spell

# Remover módulo (com verificação de dependências)
spellcomp remove agendamedica modulo-exames.spell

Símbolos de diagnóstico

O spellcomp usa quatro símbolos para classificar as mensagens de diagnóstico. Aparecem nos comandos compile, check e info:

Símbolo	Significado	Ação necessária
`✅ OK`	Tudo em ordem	Nenhuma
`ℹ️ INFO`	Inferência aplicada — o compilador tomou uma decisão por ausência de declaração	Verificar se a inferência está correta
`⚠️ AVISO`	Situação ambígua — pode funcionar, mas merece revisão	Arquiteto deve revisar
`❌ ERRO`	Impede a geração correta do output	Deve ser corrigido antes de compilar

Formato dos arquivos gerados

Para um projeto chamado agendamedica, o compilador gera:

Arquivo	Conteúdo	Formato
`CLAUDE.md`	Arquivo de entrada do agente (nome varia pelo campo `agente`)	Sempre legível
`LEIAME.txt`	Instruções para o arquiteto humano	Legível
`agendamedica-padroes.md`	Padrões de Engenharia consolidados	Compacto ou `--readable`
`agendamedica-dados.md`	Todos os blocos `Dados`	Compacto ou `--readable`
`agendamedica-regras.md`	Todos os blocos `Regras`	Compacto ou `--readable`
`agendamedica-endpoints.md`	Todos os blocos `Endpoints`	Compacto ou `--readable`
`agendamedica-telas.md`	Todos os blocos `Telas`	Compacto ou `--readable`
`agendamedica-servicos.md`	Todos os blocos `Servicos`	Omitido se não declarado
`agendamedica-seguranca.md`	Todos os blocos `Seguranca`	Omitido se não declarado

Valores do campo agente

O campo agente no sub-bloco Backend { } do bloco Tecnologia controla o nome do arquivo de entrada gerado:

Valor	Arquivo gerado
`claude-code` (padrão)	`CLAUDE.md`
`cursor`	`.cursor/rules`
`aider`	`CONVENTIONS.md`
`copilot`	`.github/copilot-instructions.md`
`nenhum`	(sem arquivo de entrada do agente)

Erros comuns e soluções

Erro	Causa	Solução
`❌ bloco Projeto é singleton`	Bloco `Projeto { }` declarado em mais de um arquivo	Manter o bloco apenas no arquivo-índice
`❌ campo padroes duplicado`	Campo `padroes` declarado mais de uma vez no mesmo `Projeto { }`	Remover a declaração duplicada
`❌ bloco X é de Padrões de Engenharia`	Bloco de Padrões de Engenharia (ex: `Tecnologia`) declarado fora do padroes.spell	Mover o bloco para o arquivo declarado em `padroes:`
`❌ tabela X declarada mais de uma vez`	Mesmo nome de tabela em dois módulos diferentes	Renomear uma das tabelas ou consolidar num único módulo
`❌ arquivo-índice não encontrado`	Nenhum arquivo com mesmo nome do diretório + extensão .spell	Renomear o arquivo-índice ou passar o caminho explicitamente