Que fait speccanvas ?

Utilisez cette compétence pour produire et maintenir des artefacts Spec Canvas sous forme de spécifications YAML portables ou pour les persister via un serveur MCP SpecCanvas configuré.

Considérez la spécification comme la source de vérité pour la structure et l'intention. Privilégiez des spécifications compactes et réutilisables qui peuvent être collées dans Spec Canvas, un IDE, un agent en terminal ou un dépôt sans explication supplémentaire.

Utilisez les fichiers de description de format YAML de cette compétence comme guide d'écriture. Utilisez les copies de schémas JSON incluses dans cette compétence ainsi que la logique de validation locale comme vérification finale.

Philosophie centrale

Les spécifications Spec Canvas constituent un pont compact entre l'intention produit et l'implémentation. Elles doivent aider agents et humains à s'accorder sur la forme du produit avant les modifications de code, mais ne doivent pas devenir un journal de chaque ajustement CSS, de mise en page ou de composant.

La spécification UI décrit l'intention et la structure. Capturez les écrans, les blocs principaux, la navigation, les tâches utilisateur clés, les états importants et la structure responsive significative.
La spécification Data décrit le domaine logique. Capturez les entités, les champs, les énumérations, les relations et les contraintes de domaine ; évitez les détails de base de données physique ou de framework.
La spécification d'abord s'applique aux changements sémantiques. Mettez à jour les spécifications avant l'implémentation lorsque la demande modifie le sens du produit, les parcours utilisateur ou la structure du domaine.
Les micro-changements d'implémentation peuvent ignorer la spécification. Si la demande est cosmétique, uniquement de mise en page ou invisible pour les utilisateurs, modifiez l'implémentation directement et laissez la spécification inchangée.
Des spécifications compactes sont de meilleures spécifications. Préférez de courtes déclarations d'objectif expliquant pourquoi un écran/bloc existe plutôt qu'un texte d'implémentation sur la façon dont il est construit.

Barrière de granularité

Avant de modifier une spécification UI, décidez si le changement demandé est suffisamment sémantique pour figurer dans la spécification.

Mettez à jour la spécification UI lorsque la demande modifie :

les écrans, les groupes d'écrans ou les blocs principaux ;
les parcours utilisateur, la navigation, les points d'entrée ou les actions disponibles ;
les états importants visibles par l'utilisateur, les modes, les autorisations ou les flux vides/erreur/récupération ;
l'objectif ou le comportement d'un composant majeur ;
la structure responsive significative, comme des expériences distinctes desktop/mobile ;
la terminologie produit ou les libellés lorsque leur signification change ;
les frontières entre les zones publiques, admin, éditeur, joueur, onboarding ou autres zones produit.

Ne mettez pas à jour la spécification UI pour des micro-ajustements d'implémentation :

espacement : padding, marge, gap, hauteur de ligne ;
tailles exactes : valeurs en pixels, taille de police, largeur/hauteur sauf si elles expriment une intention de mise en page de haut niveau ;
classes CSS, classes Tailwind, noms de composants, noms de fichiers ou structure spécifique au framework ;
couleurs exactes, dégradés, ombres, border-radius, icônes ou styles décoratifs ;
alignement local, ordre, wrapping ou réorganisation cosmétique à l'intérieur d'un bloc déjà décrit ;
temporisations d'animation, temporisations de debounce, secondes de fondu, positions de toast, mécanismes de spinner de chargement ;
détails d'implémentation navigateur/plateforme sauf s'il s'agit d'une capacité essentielle visible par l'utilisateur ;
modifications de copie locales qui ne changent pas le sens ;
refontes invisibles pour les utilisateurs.

Si l'utilisateur demande un micro-changement cosmétique ou de mise en page, effectuez directement la modification de code et évitez explicitement de toucher à la spécification UI.

Emplacement par défaut des fichiers

Sauf si l'utilisateur demande explicitement un autre emplacement, créez et mettez à jour les fichiers Spec Canvas à la racine du projet dans spec/.

Chemin de la spécification UI : spec/ui-spec.yaml
Chemin de la spécification Data : spec/data-spec.yaml

Si le répertoire spec/ n'existe pas, créez-le. Lorsqu'un seul artefact est demandé, créez uniquement le fichier correspondant.

Mode MCP

Utilisez le serveur MCP configuré nommé speccanvas lorsque l'utilisateur demande de travailler avec un projet SpecCanvas en direct, un document, une révision, une implémentation, une archive, ou lorsque les outils MCP sont clairement disponibles dans l'environnement.

Si MCP est disponible, lisez references/mcp-workflow.md avant de créer ou de mettre à jour des données SpecCanvas en direct.
Si la tâche crée ou met à jour une spécification UI, lisez également references/ui-spec-workflow.md.
Si la tâche crée une implémentation d'écran, lisez également references/implementation-workflow.md.
Si MCP n'est pas disponible, n'inventez pas de détails de connexion. Travaillez avec des fichiers YAML portables ou demandez à l'utilisateur de configurer le serveur MCP speccanvas.
Ne stockez pas d'URL MCP, de jetons porteurs, d'hôtes de staging ou de secrets locaux dans cette compétence. Ceux-ci appartiennent à la configuration MCP et aux variables d'environnement de l'agent.

Règle d'identité du modèle MCP

Lors de l'enregistrement d'une implémentation d'écran rédigée par un agent via MCP, fournissez toujours une identité de modèle stable sous la forme { identityKey, provider, model, version }.

Résolvez le modèle actif à partir des règles globales de l'agent, des variables d'environnement ou de la session en cours avant d'appeler add_implementation.
Pour add_implementation, transmettez modelIdentity directement. Ne le remplacez pas par agentName.
agentName n'est qu'un repli manuel/legacy. Utilisez-le uniquement avec modelIdentity: null lorsque l'implémentation est téléchargée par un humain ou que l'identité du modèle est intentionnellement indisponible.
Si le modèle actif est inconnu, ambigu ou non enregistré, arrêtez-vous et demandez une clarification au lieu d'enregistrer silencieusement avec agentName.

Workflow

Identifiez les limites de l'artefact. Déterminez si la tâche nécessite :

une spécification UI uniquement
une spécification Data uniquement
les deux spécifications
une explication, une révision, un nettoyage ou une validation d'une spécification existante
aucun changement de spécification car la demande est un micro-ajustement d'implémentation
une persistance MCP en direct pour les projets, spécifications, révisions, implémentations ou archives

Appliquez la barrière de granularité. Pour un travail UI, déterminez si la demande modifie l'intention/la structure du produit ou uniquement des détails d'implémentation. S'il s'agit uniquement d'un micro-ajustement, laissez la spécification inchangée.
Rassemblez le matériel source. Utilisez uniquement les entrées qui définissent la structure :

idée produit ou demande de fonctionnalité
captures d'écran ou descriptions UI existantes
structure de la base de code
spécification YAML actuelle
listes d'entités, notes d'API ou règles de domaine

Lisez les références de workflow et de format requises.

Pour la création ou la révision d'une spécification UI, lisez references/ui-spec-workflow.md.
Pour la création d'une implémentation d'écran, lisez references/implementation-workflow.md.
Pour la persistance MCP en direct, lisez references/mcp-workflow.md.
Pour l'écriture d'une spécification UI, lisez references/ui-spec-format-0-0-3.yaml.
Pour l'écriture d'une spécification Data, lisez references/data-spec-format-0-0-1.yaml.
Pour le comportement de validation locale et les heuristiques de révision, lisez references/workflow.md, references/validation-rules-ui.md et references/validation-rules-data.md si nécessaire.
Les schémas actuels fournis se trouvent dans schemas/ui-spec.schema.json et schemas/data-spec.schema.json.

Rédigez ou révisez la spécification. Gardez le document en YAML valide et restez dans les champs du format. N'inventez pas de sections de niveau supérieur personnalisées sauf si le format les autorise explicitement. Effectuez la plus petite mise à jour sémantique qui préserve l'intention ; n'élargissez pas la spécification avec des notes d'implémentation au niveau du pixel.
Validez le résultat. Si scripts/validate-spec.mjs est disponible, exécutez-le sur le YAML final avant de renvoyer le résultat. Corrigez les erreurs de validation avant de renvoyer la spécification.
Retournez le résultat. Retournez le YAML validé ou, pour les tâches de révision, retournez d'abord les problèmes, puis le snippet corrigé ou le fichier corrigé.

Règles essentielles

Utilisez le fichier de format comme source d'écriture

Les fichiers YAML de description de format sont la référence d'écriture principale pour cette compétence. Suivez d'abord leur structure, le nommage des champs, les exemples et les conseils. Pour la spécification UI, references/ui-spec-format-0-0-3.yaml est la source de vérité locale actuelle et est censée rester alignée avec le schéma et le validateur fournis.

Utilisez la validation de schéma comme vérification finale

La validation de schéma n'est pas le guide d'écriture. C'est l'étape de vérification finale.

Écrivez la spécification à partir du fichier de format.
Validez la spécification écrite avec scripts/validate-spec.mjs.
Corrigez les échecs de schéma et de règles de validation avant de renvoyer le YAML final.

Les schémas fournis dans schemas/ doivent rester synchronisés avec l'implémentation de Spec Canvas et avec les références de description de format de cette compétence. S'ils semblent différer, traitez cela comme un bug de compétence et signalez-le explicitement au lieu d'inventer silencieusement un compromis.

Gardez UI et Data alignés

Lorsque les deux spécifications existent :

faites correspondre les noms entre les écrans, les entités et les actions
assurez-vous que les actions UI impliquent des entités ou des workflows réels
assurez-vous que les relations de la spécification Data supportent la structure UI
signalez les lacunes au lieu d'inventer silencieusement des concepts backend

Gardez le format portable

Produisez des fichiers YAML simples qui peuvent résider dans un dépôt et être réutilisés par n'importe quel agent. Ne rendez pas la spécification dépendante de l'état de l'interface utilisateur de Spec Canvas, de métadonnées cachées ou d'hypothèses de chat uniquement.

Gardez la spécification UI au-dessus des détails d'implémentation

N'utilisez pas la spécification UI comme remplacement pour le CSS, la documentation des composants ou les journaux de modifications. Un bon purpose explique à quoi sert l'écran ou le bloc du point de vue de l'utilisateur. Il ne doit pas énumérer l'espacement exact, les noms de classes, les tailles en pixels, les mécanismes d'implémentation transitoires ou chaque petit contrôle si ces détails ne changent pas le sens du produit.

Modèles de tâches

Créer une nouvelle spécification UI

Commencez par docType, format_version et metadata.
Dans la spécification UI, metadata.description est obligatoire et doit porter l'intention produit de haut niveau.
Ajoutez screens dès que la forme principale de l'application est connue.
Ajoutez blocks lorsque l'utilisateur souhaite une structure visible ; blocks peut être omis lors de la phase d'exploration.
Ajoutez templates, navigation ou des champs responsives uniquement s'ils aident matériellement.
La rédaction responsive UI supportée par le format local actuel inclut metadata.breakpoints, screen.template adaptatif, block.columns adaptatif et block.visible.
Préservez les conventions du fichier de format original, y compris les instructions de citation du fichier de format UI.
Validez le fichier terminé avec scripts/validate-spec.mjs lorsque disponible.

Créer une nouvelle spécification Data

Décrivez le modèle de domaine logique, pas la base de données physique.
Ajoutez enums uniquement lorsque des vocabulaires contrôlés partagés sont importants.
Définissez entities avec des fields ayant une signification métier.
Utilisez relations pour la structure logique entre entités.
Évitez de divulguer des préoccupations d'implémentation uniquement comme les index, les migrations ou la syntaxe spécifique à l'ORM, sauf si l'utilisateur les demande explicitement en dehors de la spécification.
Validez le fichier terminé avec scripts/validate-spec.mjs lorsque disponible.

Réviser ou réparer une spécification existante

Vérifiez :

les champs invalides ou non supportés
les sections obligatoires manquantes
les références cassées vers écran, template ou navigation
les erreurs d'énumération, de clé étrangère ou de relation dans la spécification Data
les échecs de validation personnalisés remontés par les règles de validation locales
les décalages schéma-format entre le fichier de format original et l'implémentation locale actuelle
le texte purpose UI trop détaillé qui décrit les mécanismes d'implémentation au lieu de l'intention produit

Lors de la réparation, préservez l'intention produit originale et apportez la plus petite correction qui rétablit la clarté.

Compacter une spécification UI trop détaillée

Gardez les identifiants d'écran, template, région et bloc existants stables sauf si la structure du produit change réellement.
Remplacez les longs paragraphes purpose par des résumés d'une phrase de l'intention orientée utilisateur.
Préservez les écrans, les blocs majeurs, la navigation, les états importants et les modes significatifs.
Supprimez les micro-détails CSS/mise en page, les particularités de plateforme, les temporisations exactes, le comportement de journalisation et les mécanismes internes des composants.
Évitez le reformatage YAML du fichier entier ; utilisez des modifications ciblées pour que les diffs restent examinables.
Validez après l'édition.

Reconstruire une spécification à partir d'une application existante

inférez les écrans à partir des workflows visibles
inférez les blocs à partir des régions répétées et des tâches utilisateur
inférez les entités à partir des noms de domaine et des changements d'état
séparez ce qui est observé de ce qui est deviné
signalez explicitement l'incertitude lorsque le matériel source est incomplet

Validation

Utilisez scripts/validate-spec.mjs lorsque disponible.

Entrée : chemin vers un fichier de spécification YAML
Détectez le type de document à partir de docType
Validez par rapport au schéma JSON Schema fourni par cette compétence
Exécutez les règles de validation personnalisées pertinentes
Traitez les avertissements comme indicatifs
Traitez les erreurs comme des bloqueurs pour la sortie finale lorsque vous retournez une spécification corrigée

Si le script ne peut pas s'exécuter car les dépendances locales de Spec Canvas sont manquantes, mentionnez-le brièvement et revenez à une révision manuelle en utilisant le fichier de format et les références de règles de validation.

Attentes de sortie

Lorsque vous retournez des spécifications :

fournissez du YAML valide
gardez les identifiants en snake_case là où le format les attend
gardez les noms de champs exactement comme définis par le fichier de format
mentionnez les hypothèses lorsqu'elles affectent matériellement la structure
mentionnez si la validation a été exécutée

Lorsque vous retournez une révision au lieu d'un fichier réécrit :

listez d'abord les problèmes structurels
donnez ensuite des corrections concrètes
fournissez ensuite un snippet corrigé ou la spécification complète si utile

speccanvas

Qu'est-ce que speccanvas ?

Demander à votre IA préférée

Documentation