O que speccanvas faz?

Use esta skill para produzir e manter artefatos Spec Canvas como especificações YAML portáteis ou para persistí-los através de um servidor MCP SpecCanvas configurado.

Trate a especificação como a fonte da verdade para estrutura e intenção. Prefira especificações compactas e reutilizáveis que possam ser coladas no Spec Canvas, em um IDE, em um agente de terminal ou em um repositório sem necessidade de explicação extra.

Use os arquivos YAML de descrição de formato nesta skill como guia de escrita. Use as cópias de esquemas JSON agrupadas nesta skill mais a lógica de validação local como pós-verificação.

Filosofia Central

As especificações Spec Canvas são uma ponte compacta entre a intenção do produto e a implementação. Elas devem ajudar agentes e humanos a concordar sobre a forma do produto antes das mudanças de código, mas não devem se tornar um registro contínuo de cada ajuste de CSS, layout ou componente.

Especificação de UI descreve intenção e estrutura. Capture telas, blocos principais, navegação, tarefas-chave do usuário, estados importantes e estrutura responsiva significativa.
Especificação de Dados descreve o domínio lógico. Capture entidades, campos, enumerações, relacionamentos e restrições de domínio; evite detalhes físicos de banco de dados ou framework.
Especificação primeiro aplica-se a mudanças semânticas. Atualize as especificações antes da implementação quando a solicitação alterar o significado do produto, as jornadas do usuário ou a estrutura do domínio.
Micro-mudanças de implementação podem pular a especificação. Se a solicitação for cosmética, apenas de layout ou invisível para os usuários, altere a implementação diretamente e deixe a especificação intocada.
Especificações compactas são melhores especificações. Prefira declarações curtas de propósito que expliquem por que uma tela/bloco existe em vez de prosa de implementação sobre como é construído.

Portão de Granularidade

Antes de editar uma Especificação de UI, decida se a mudança solicitada é semântica o suficiente para estar na especificação.

Atualize a Especificação de UI quando a solicitação alterar:

telas, grupos de telas ou blocos principais;
jornadas do usuário, navegação, pontos de entrada ou ações disponíveis;
estados importantes voltados ao usuário, modos, permissões ou fluxos de vazio/erro/recuperação;
o propósito ou comportamento de um componente principal;
estrutura responsiva significativa, como experiências distintas de desktop/mobile;
terminologia ou rótulos do produto quando seu significado muda;
limites entre áreas públicas, admin, editor, player, onboarding ou similares do produto.

Não atualize a Especificação de UI para micro-ajustes de implementação:

espaçamento: padding, margin, gap, line-height;
tamanhos exatos: valores de pixel, font-size, largura/altura, a menos que expressem intenção de layout de alto nível;
classes CSS, classes Tailwind, nomes de componentes, nomes de arquivos ou estrutura específica de framework;
cores exatas, gradientes, sombras, border-radius, ícones ou estilo decorativo;
alinhamento local, ordenação, quebra de linha ou refluxo cosmético dentro de um bloco já descrito;
temporizações de animação, temporizações de debounce, segundos de crossfade, posições de toast, mecânica de spinner de carregamento;
detalhes de implementação de navegador/plataforma, a menos que sejam uma capacidade central voltada ao usuário;
edições locais de texto que não alteram o significado;
refatorações invisíveis para os usuários.

Se o usuário pedir uma micro-mudança cosmética ou de layout, faça a mudança de código diretamente e evite explicitamente tocar na Especificação de UI.

Localização Padrão de Arquivos

A menos que o usuário peça explicitamente um local diferente, crie e atualize arquivos Spec Canvas na raiz do projeto sob spec/.

Caminho da Especificação de UI: spec/ui-spec.yaml
Caminho da Especificação de Dados: spec/data-spec.yaml

Se o diretório spec/ não existir, crie-o. Quando apenas um artefato for solicitado, crie apenas o arquivo relevante.

Modo MCP

Use o servidor MCP configurado chamado speccanvas quando o usuário pedir para trabalhar com um projeto SpecCanvas ao vivo, documento, revisão, implementação, arquivo, ou quando ferramentas MCP estiverem claramente disponíveis no ambiente.

Se o MCP estiver disponível, leia references/mcp-workflow.md antes de criar ou atualizar dados SpecCanvas ao vivo.
Se a tarefa criar ou atualizar uma Especificação de UI, leia também references/ui-spec-workflow.md.
Se a tarefa criar uma implementação de tela, leia também references/implementation-workflow.md.
Se o MCP não estiver disponível, não invente detalhes de conexão. Trabalhe com arquivos YAML portáteis ou peça ao usuário para configurar o servidor MCP speccanvas.
Não armazene URLs MCP, tokens de portador, hosts de staging ou segredos locais nesta skill. Eles pertencem à configuração MCP e às variáveis de ambiente do agente.

Regra de Identidade de Modelo MCP

Ao salvar uma implementação de tela de autoria do agente através do MCP, sempre forneça identidade de modelo estável como { identityKey, provider, model, version }.

Resolva o modelo ativo a partir das regras globais do agente, variáveis de ambiente ou da sessão atual antes de chamar add_implementation.
Para add_implementation, passe modelIdentity diretamente. Não o substitua por agentName.
agentName é apenas um fallback manual/legado. Use-o apenas com modelIdentity: null quando a implementação for carregada por um humano ou a identidade do modelo estiver intencionalmente indisponível.
Se o modelo ativo for desconhecido, ambíguo ou não registrado, pare e peça esclarecimentos em vez de salvar silenciosamente com agentName.

Fluxo de Trabalho

Identifique o limite do artefato. Determine se a tarefa precisa de:
- Apenas Especificação de UI
- Apenas Especificação de Dados
- ambas as especificações
- explicação, revisão, limpeza ou validação de uma especificação existente
- nenhuma alteração de especificação porque a solicitação é um micro-ajuste de implementação
- persistência MCP ao vivo para projetos, especificações, revisões, implementações ou arquivos
Aplique o portão de granularidade. Para trabalho de UI, decida se a solicitação altera a intenção/estrutura do produto ou apenas detalhes de implementação. Se for apenas um micro-ajuste, deixe a especificação como está.
Reúna material de origem. Use apenas as entradas que definem estrutura:
- ideia de produto ou solicitação de funcionalidade
- capturas de tela existentes ou descrições de UI
- estrutura do código-fonte
- especificação YAML atual
- listas de entidades, anotações de API ou regras de domínio
Leia os fluxos de trabalho e referências de formato necessários.
- Para criação ou revisão de Especificação de UI, leia references/ui-spec-workflow.md.
- Para criação de implementação de tela, leia references/implementation-workflow.md.
- Para persistência MCP ao vivo, leia references/mcp-workflow.md.
- Para autoria de Especificação de UI, leia references/ui-spec-format-0-0-3.yaml.
- Para autoria de Especificação de Dados, leia references/data-spec-format-0-0-1.yaml.
- Para comportamento de validação local e heurísticas de revisão, leia references/workflow.md, references/validation-rules-ui.md e references/validation-rules-data.md conforme necessário.
- Os esquemas agrupados atuais estão em schemas/ui-spec.schema.json e schemas/data-spec.schema.json.
Esboce ou revise a especificação. Mantenha o documento YAML válido e permaneça dentro dos campos do formato. Não invente seções personalizadas de nível superior, a menos que o formato permita explicitamente. Faça a menor atualização semântica que preserve a intenção; não expanda a especificação com notas de implementação de nível de pixel.
Valide o resultado. Se scripts/validate-spec.mjs estiver disponível, execute-o contra o YAML final antes de retornar o resultado. Corrija erros de validação antes de retornar a especificação.
Retorne o resultado. Retorne YAML validado ou, para tarefas de revisão, retorne primeiro os problemas e, em seguida, o trecho ou arquivo corrigido.

Regras Centrais

Use o arquivo de formato como fonte de escrita

Os arquivos YAML de descrição de formato são a referência principal de autoria para esta skill. Siga sua estrutura, nomeação de campos, exemplos e orientações primeiro. Para Especificação de UI, references/ui-spec-format-0-0-3.yaml é a fonte da verdade local atual e espera-se que permaneça alinhada com o esquema e validador agrupados.

Use a validação de esquema como pós-verificação

A validação de esquema não é o guia de escrita. É a etapa de verificação final.

Escreva a especificação a partir do arquivo de formato.
Valide a especificação escrita com scripts/validate-spec.mjs.
Corrija falhas de esquema e regras de validação antes de retornar o YAML final.

Os esquemas agrupados em schemas/ devem permanecer sincronizados com a implementação Spec Canvas e com as referências de descrição de formato nesta skill. Se parecerem diferentes, trate isso como um bug da skill e destaque-o explicitamente em vez de inventar silenciosamente um compromisso.

Mantenha UI e dados alinhados

Quando ambas as especificações existirem:

corresponda a nomeação entre telas, entidades e ações
garanta que ações de UI impliquem entidades ou fluxos de trabalho reais
garanta que as relações da Especificação de Dados suportem a estrutura da UI
sinalize lacunas em vez de inventar silenciosamente conceitos de backend

Mantenha o formato portátil

Produza arquivos YAML simples que possam viver em um repositório e ser reutilizados por qualquer agente. Não faça a especificação depender do estado da UI do Spec Canvas, metadados ocultos ou suposições apenas de chat.

Mantenha a Especificação de UI acima do detalhe de implementação

Não use a Especificação de UI como substituta para CSS, documentação de componentes ou changelogs. Um bom purpose explica para que serve a tela ou bloco do ponto de vista do usuário. Não deve enumerar espaçamento exato, nomes de classes, tamanhos de pixel, mecânicas de implementação transitórias ou cada pequeno controle se esses detalhes não alterarem o significado do produto.

Padrões de Tarefa

Criar uma nova Especificação de UI

Comece com docType, format_version e metadata.
Na Especificação de UI, metadata.description é obrigatório e deve carregar a intenção do produto de nível superior.
Adicione screens assim que a forma principal do aplicativo for conhecida.
Adicione blocks quando o usuário quiser estrutura visível; blocks podem ser omitidos na fase de exploração.
Adicione templates, navigation ou campos responsivos apenas quando ajudarem materialmente.
A autoria responsiva de UI suportada pelo formato local atual inclui metadata.breakpoints, screen.template adaptativo, block.columns adaptativo e block.visible.
Preserve as convenções do arquivo de formato original, incluindo orientações de citação do arquivo de formato de UI.
Valide o arquivo completo com scripts/validate-spec.mjs quando disponível.

Criar uma nova Especificação de Dados

Descreva o modelo de domínio lógico, não o banco de dados físico.
Adicione enums apenas quando vocabulários controlados compartilhados forem importantes.
Defina entities com fields significativos para o negócio.
Use relations para estrutura lógica entre entidades.
Evite vazar preocupações apenas de implementação, como índices, migrações ou sintaxe específica de ORM, a menos que o usuário peça explicitamente por elas fora da especificação.
Valide o arquivo completo com scripts/validate-spec.mjs quando disponível.

Revisar ou reparar uma especificação existente

Verifique:

campos inválidos ou não suportados
seções obrigatórias ausentes
referências quebradas de tela, modelo ou navegação
erros de enum, chave estrangeira ou relação na Especificação de Dados
falhas de validação personalizada exibidas pelas regras de validação locais
incompatibilidades esquema-formato entre o arquivo de formato original e a implementação local atual
texto purpose de UI excessivamente detalhado que descreve mecânicas de implementação em vez de intenção do produto

Ao reparar, preserve a intenção original do produto e faça a menor correção que restaure a clareza.

Compactar uma Especificação de UI excessivamente detalhada

Mantenha IDs de tela, modelo, região e bloco existentes estáveis, a menos que a estrutura do produto realmente mude.
Substitua parágrafos longos de purpose por resumos de uma frase da intenção voltada ao usuário.
Preserve telas, blocos principais, navegação, estados importantes e modos significativos.
Remova microdetalhes de CSS/layout, peculiaridades de plataforma, temporizações exatas, comportamento de registro e mecânicas internas de componente.
Evite reformatação YAML de arquivo inteiro; use edições direcionadas para que os diffs permaneçam revisáveis.
Valide após a edição.

Reconstruir uma especificação a partir de um aplicativo existente

infira telas a partir de fluxos de trabalho visíveis
infira blocos a partir de regiões repetidas e tarefas do usuário
infira entidades a partir de substantivos de domínio e mudanças de estado
separe o que é observado do que é adivinhado
mencione incerteza explicitamente quando o material de origem estiver incompleto

Validação

Use scripts/validate-spec.mjs quando disponível.

Entrada: caminho para um arquivo de especificação YAML
Detecta o tipo de documento a partir de docType
Valida contra o Esquema JSON agrupado desta skill
Executa as regras de validação personalizadas relevantes
Trata avisos como consultivos
Trata erros como bloqueadores para a saída final quando você está retornando uma especificação corrigida

Se o script não puder ser executado porque as dependências locais do Spec Canvas estão ausentes, diga isso brevemente e recorra à revisão manual usando o arquivo de formato mais as referências de regras de validação.

Expectativas de Saída

Ao retornar especificações:

forneça YAML válido
mantenha IDs em snake_case onde o formato as espera
mantenha nomes de campos exatamente como definidos pelo arquivo de formato
mencione suposições quando elas afetarem materialmente a estrutura
mencione se a validação foi executada

Ao retornar uma revisão em vez de um arquivo reescrito:

liste problemas estruturais primeiro
depois forneça correções concretas
depois forneça um trecho corrigido ou especificação completa se útil

speccanvas

O que é speccanvas?

Perguntar na sua IA favorita

Documentação