<!-- GERADO AUTOMATICAMENTE PELO SPELLCOMP v2.0 — NÃO EDITE ESTE ARQUIVO -->
<!-- Fonte: spell.spell | Para modificar: edite o .spell e recompile -->
<!-- spellcomp compile spell.spell -->
#SPELL|Spec Programming & Execution Logic Language|v2.0
##DEF|SPELL=linguagem estruturada de especificação de software. Elo entre visão do arquiteto e trabalho da IA geradora de código. NÃO é linguagem de programação. É linguagem de especificação.
##PRINCIPIO|O arquiteto descreve o que o sistema deve fazer. A IA decide como implementar.
##FLUXO|1:arquiteto cria .spell > 2:spellcomp audita semanticamente > 3:arquiteto revisa relatório > 4:spellcomp gera arquivos por módulo > 5:IA gera código
##RESPONSABILIDADES|arquiteto:define regras de negócio,define entidades e campos (total ou parcial),NÃO precisa saber algoritmos,NÃO escreve configuração,NÃO escreve código-fonte,responde perguntas|IA:NÃO inventa regras de negócio,completa campos não declarados,decide algoritmos e padrões técnicos,gera configuração automaticamente,gera código após confirmação,faz perguntas antes de gerar
##SINTAXE|hierarquia:numeração decimal|comentarios://linha|idiomas:português e inglês equivalentes e intercambiáveis no mesmo arquivo
##HIERARQUIA|1. → bloco raiz|1.1. → sub-bloco|1.1.1. → sub-item|campo: valor → atributo|campo: recomendar → delega à IA|- texto → instrucao implícita|// texto → comentário ignorado
##OBSERVACOES|parser reconhece blocos raiz pelo nome não pelo número|numeração não precisa ser sequencial|linhas com - em qualquer bloco são instrucoes implícitas|adaptar sozinho numa linha em Wireframes permite à IA adaptar layout
##KEYWORDS|pt:Projeto,Banco de Dados,Regras de Negócio,Endpoints,Telas,Segurança,Serviços,Stack,Convenções,Skills,Configuração,Tabela,Regra,Endpoint,Tela,Serviço,Relacionamentos,Wireframes,Dados de Entrada,Respostas|mod:obrigatorio,opcional,privado,recomendar,unico,indexado,unico-indexado,chave-primaria,auto-incremento,adaptar
##BLOCOS|1.Projeto:obrigatorio,identidade+tecnologias|2.Banco de Dados:recomendado,tabelas do banco|3.Regras de Negócio:recomendado,regras e validações|4.Endpoints:recomendado,operações da API|5.Telas:recomendado,interfaces do usuário|6.Segurança:opcional,intenções de proteção|7.Serviços:opcional,processos em background|8.Configuração:NUNCA ESCREVER,gerado automaticamente
##BLOCO:Projeto|campos:nome,versao,descricao,instrucoes|sub-blocos:1.1.Stack,1.2.Convenções,1.3.Skills|obrigatorio:sim
##BLOCO:Stack(1.1.)|campos:frontend,backend,banco,autenticacao,agente|agente:claude-code(CLAUDE.md),cursor(.cursor/rules),aider(CONVENTIONS.md),copilot(.github/copilot-instructions.md),nenhum(sem arquivo de entrada)|agente omitido:assume claude-code
##BLOCO:Convenções(1.2.)|campo:idioma-do-codigo(texto, ex: português)|instrucoes:convenções organizacionais em linguagem natural|NÃO entra aqui:convenções técnicas que a IA já sabe (PascalCase, etc.)|ENTRA:restrições organizacionais ("sufixo Service", "prefixo buscar")
##BLOCO:Skills(1.3.)|uso:cada skill é uma linha com -|comportamento duplo:arquiteto lista skills + spellcomp sugere por gatilhos|catálogo embutido no binário via go:embed|skills comuns:pdf-reading,xlsx,docx,charts,frontend-design,oauth-integration
##BLOCO:Banco de Dados(2.)|sub-blocos:2.0.Configuração(especial),2.N.Tabela NomeDaTabela,2.N.1.Relacionamentos
##BLOCO:Configuração(2.0.)|numero reservado:2.0. parser rejeita tabela com esse número|campos:multitenancy(schema-por-tenant,banco-por-tenant,coluna-tenant,nao),escopo(global,por-tenant,hibrido),migracao(flyway,liquibase,goose,etc)|instrucoes:restrições arquiteturais|escopo hibrido ativa validação do auditor
##BLOCO:Tabela(2.N.)|niveis:1=totalmente especificado,2=parcialmente especificado,3=totalmente delegado|nivel3:estrutura:recomendar + instrucoes descrevendo a entidade
##TIPOS|inteiro:número sem casas decimais|decimal:número com casas decimais|decimal(P,S):precisão ex:decimal(10,2)|texto:qualquer tamanho|texto(N):tamanho máximo N|booleano:verdadeiro ou falso|data:apenas data|data-hora:data e hora completas|hora:apenas hora|arquivo:referência a arquivo armazenado|json:estrutura flexível
##MODIFICADORES|chave-primaria:identificador único|auto-incremento:gerado pelo banco|unico:sem duplicatas|obrigatorio:não pode ficar em branco|opcional:pode ser nulo|padrao\:valor:preenchido automaticamente ex:padrao\:agora,padrao\:sim,padrao\:0|privado:criptografado em repouso,IA decide método|indexado:índice de busca|unico-indexado:unico+indexado
##RELACIONAMENTOS|convencao:campos com mesmo nome em tabelas diferentes → IA infere automaticamente|explicito:sub-bloco Relacionamentos obrigatório quando convenção não resolve (dois campos da mesma tabela apontando para a mesma outra)|sintaxe:campo_id -> Entidade.id
##BLOCO:Regras de Negócio(3.)|IMPORTANTE:regras de negócio são insubstituíveis — a IA NÃO inventa regras não declaradas
##BLOCO:Regra(3.N.)|campos:contexto(operação ou momento),condicao(quando dispara),acao(o que acontece),excecao(opcional),motivo(opcional,recomendado)|acao múltipla: várias linhas com -|referencia em endpoint:regras: NomeDaRegra
##BLOCO:Endpoints(4.)|sub-blocos:4.N.Endpoint NomeDoEndpoint,4.N.1.Dados de Entrada,4.N.2.Respostas
##BLOCO:Endpoint(4.N.)|campos:rota(METODO /caminho),autenticacao(obrigatoria|nao-requerida),regras(NomeDaRegra)|metodos:GET(buscar/listar),POST(criar/executar),PUT(substituir),PATCH(alterar parcial),DELETE(remover)
##BLOCO:Dados de Entrada(4.N.1.)|campos com tipo e modificadores: obrigatorio,opcional,privado
##BLOCO:Respostas(4.N.2.)|sintaxe: codigo: descricao ex: 201: Criado com sucesso|cobrir:200,201,400,404,401,403 conforme aplicável
##BLOCO:Telas(5.)|sub-blocos:5.N.Tela NomeDaTela,5.N.1.Wireframes
##BLOCO:Tela(5.N.)|campos:rota,autenticacao(obrigatoria|nao-requerida),layout(recomendar ou caminho do wireframe)
##BLOCO:Wireframes(5.N.1.)|campos:mobile(caminho),desktop(caminho)|adaptar:palavra sozinha na linha permite à IA adaptar layout para mobile ou acessibilidade|formatos aceitos:jpg,png,svg|pasta:wireframes/ na raiz
##BLOCO:Segurança(6.)|REGRA:linguagem de intenção de negócio NÃO técnica|arquiteto NÃO precisa saber JWT,OAuth,bcrypt,AES-256|campos:acesso(descrição de quem acessa),instrucoes(restrições em linguagem natural)
##BLOCO:Serviços(7.)|sub-blocos:7.N.Serviço NomeDoServico
##BLOCO:Serviço(7.N.)|campos:periodicidade("1 hora","24 horas","toda segunda-feira"),horario("HH:MM" opcional),instrucoes
##OUTPUT|estrutura:pasta com nome do projeto|arquivos:<nome>-projeto.md,<nome>-dados.md,<nome>-regras.md,<nome>-endpoints.md,<nome>-telas.md,<nome>-servicos.md(se declarado),<nome>-seguranca.md(se declarado),arquivo de entrada(nome depende do campo agente)
##ARQUIVO_ENTRADA|conteúdo:nome+versão+descrição,índice de arquivos,skills requeridas e sugeridas,instruções de dependência para o agente,avisos do compilador,relatório semântico|NÃO é o documento completo — é o arquivo de entrada do agente
##AUDITOR|ativado por padrão|flag:--nosemantic desativa|detecta:gaps(campo status sem regra de transição),contradições(regras conflitantes),referências mortas(endpoints referenciando regras inexistentes),entidades órfãs(sem endpoint que as escreva),cobertura de erros(endpoint GET por ID sem 404)
##DIAGNOSTICOS|❌ ERRO:impede geração correta|⚠️ AVISO:ambíguo, arquiteto revisa|ℹ️ INFO:inferência aplicada, verificar|✅ OK:tudo em ordem
##AUTH_CASCATA|1:variável de ambiente ANTHROPIC_API_KEY|2:credenciais do Claude Code (~/.claude/.credentials.json)|3:arquivo local (~/.spell_api_key)|4:prompt interativo|nunca gravar credenciais no diretório do projeto
##CLI|spellcomp new <nome>:cria .spell com todos os blocos|spellcomp compile <arquivo.spell>:compila e gera arquivos|spellcomp compile <arquivo.spell> --nosemantic:pula auditor semântico|spellcomp compile <arquivo.spell> --output <pasta/>:pasta de saída customizada|spellcomp check <arquivo.spell>:valida sem gerar nada|spellcomp info <arquivo.spell>:exibe resumo
##RECOMENDAR|uso:qualquer campo opcional|efeito:delega decisão à IA|exemplos:frontend:recomendar,estrutura:recomendar,layout:recomendar
##INSTRUCOES|presente em TODOS os blocos|aceita texto livre em linguagem natural|uso:comportamentos,navegação,regras de apresentação,qualquer intenção que não caiba em sintaxe formal|regra de ouro:se você sabe descrever em palavras, escreva em instrucoes
##BOAS_PRATICAS|1:priorize bloco Regras de Negócio — entidades e endpoints podem ser inferidos, regras não|2:use instrucoes sem medo — IA interpreta texto natural com alta precisão|3:nomeie tabelas no idioma do negócio|4:documente motivo das regras — ajuda em decisões de borda|5:um .spell por projeto na raiz do repositório|6:revise inferências da IA antes de gerar código|7:declare agente em Stack para nomear o arquivo de entrada corretamente
##ESTRUTURA_PASTAS|projeto/|..<nome>-projeto.md|..<nome>-dados.md|..<nome>-regras.md|..<nome>-endpoints.md|..<nome>-telas.md|..<nome>-servicos.md (se declarado)|..<nome>-seguranca.md (se declarado)|..CLAUDE.md (ou arquivo equivalente do agente declarado)|..wireframes/|....login.png|....dashboard.png
