speccanvas

Was macht speccanvas?

Nutze diese Skill, um Spec Canvas-Artefakte als portable YAML-Spezifikationen zu erstellen und zu pflegen oder sie über einen konfigurierten SpecCanvas MCP-Server zu persistieren.

Behandle die Spezifikation als Quelle der Wahrheit für Struktur und Absicht. Bevorzuge kompakte, wiederverwendbare Specs, die ohne zusätzliche Erklärung in Spec Canvas, eine IDE, einen Terminal-Agenten oder ein Repository eingefügt werden können.

Verwende die Format-Beschreibungs-YAML-Dateien dieser Skill als Schreibvorlage. Verwende die mitgelieferten JSON-Schema-Kopien dieser Skill sowie die lokale Validierungslogik als Nachkontrolle.

Kernphilosophie

Spec Canvas-Spezifikationen sind eine kompakte Brücke zwischen Produktabsicht und Implementierung. Sie sollen Agenten und Menschen helfen, sich über die Produktgestalt vor Codeänderungen zu einigen, aber sie sollten kein laufendes Protokoll jeder CSS-, Layout- oder Komponentenänderung werden.

• UI-Spec beschreibt Absicht und Struktur. Erfasse Bildschirme, Hauptblöcke, Navigation, wichtige Benutzeraufgaben, wichtige Zustände und sinnvolle responsive Struktur.
• Data-Spec beschreibt die logische Domäne. Erfasse Entitäten, Felder, Aufzählungen, Beziehungen und Domänenbeschränkungen; vermeide physische Datenbank- oder Framework-Details.
• Spec-first gilt für semantische Änderungen. Aktualisiere Spezifikationen vor der Implementierung, wenn die Anfrage die Produktbedeutung, Benutzerreisen oder Domänenstruktur verändert.
• Implementierungs-Mikro-Änderungen können das Spec überspringen. Wenn die Anfrage kosmetisch, layoutbezogen oder für Benutzer unsichtbar ist, ändere die Implementierung direkt und lasse das Spec unberührt.
• Kompakte Specs sind bessere Specs. Bevorzuge kurze Zweckangaben, die erklären, warum ein Bildschirm/Block existiert, gegenüber Implementierungsprosa darüber, wie er gebaut ist.

Granularitätsschranke

Bevor du ein UI-Spec bearbeitest, entscheide, ob die angeforderte Änderung semantisch genug ist, um ins Spec zu gehören.

Aktualisiere das UI-Spec, wenn die Anfrage Folgendes ändert:

• Bildschirme, Bildschirmgruppen oder Hauptblöcke;
• Benutzerreisen, Navigation, Einstiegspunkte oder verfügbare Aktionen;
• wichtige benutzerseitige Zustände, Modi, Berechtigungen oder Leer-/Fehler-/Wiederherstellungsabläufe;
• den Zweck oder das Verhalten einer Hauptkomponente;
• sinnvolle responsive Struktur, z. B. unterschiedliche Desktop-/Mobile-Erfahrungen;
• Produktterminologie oder Bezeichnungen, wenn sich ihre Bedeutung ändert;
• Grenzen zwischen öffentlichen, Admin-, Editor-, Player-, Onboarding- oder ähnlichen Produktbereichen.

Aktualisiere das UI-Spec nicht für Implementierungs-Mikro-Anpassungen:

• Abstände: Padding, Margin, Gap, Zeilenhöhe;
• exakte Größen: Pixelwerte, Schriftgröße, Breite/Höhe, sofern sie nicht das Layout auf hoher Ebene ausdrücken;
• CSS-Klassen, Tailwind-Klassen, Komponentennamen, Dateinamen oder frameworkspezifische Struktur;
• exakte Farben, Verläufe, Schatten, Rahmenradius, Symbole oder dekorative Gestaltung;
• lokale Ausrichtung, Reihenfolge, Umbruch oder kosmetischer Umbau innerhalb eines bereits beschriebenen Blocks;
• Animationszeiten, Entprellzeiten, Überblendsekunden, Toast-Positionen, Lade-Spinner-Mechaniken;
• Browser-/Plattform-Implementierungsdetails, sofern sie keine zentrale benutzerseitige Fähigkeit darstellen;
• lokale Textkorrekturen, die die Bedeutung nicht ändern;
• Refactorings, die für Benutzer unsichtbar sind.

Wenn der Benutzer nach einer kosmetischen oder Layout-Mikro-Änderung fragt, führe die Codeänderung direkt durch und vermeide explizit, das UI-Spec zu berühren.

Standard-Dateiablage

Sofern der Benutzer nicht explizit einen anderen Ort wünscht, erstelle und aktualisiere Spec Canvas-Dateien im Projektstamm unter spec/.

• UI-Spec-Pfad: spec/ui-spec.yaml
• Data-Spec-Pfad: spec/data-spec.yaml

Wenn das spec/-Verzeichnis nicht existiert, erstelle es. Wenn nur ein Artefakt angefordert wird, erstelle nur die entsprechende Datei.

MCP-Modus

Verwende den konfigurierten MCP-Server namens speccanvas, wenn der Benutzer bittet, mit einem Live-SpecCanvas-Projekt, -Dokument, -Revision, -Implementierung, -Archiv zu arbeiten oder wenn MCP-Tools in der Umgebung eindeutig verfügbar sind.

• Wenn MCP verfügbar ist, lies references/mcp-workflow.md, bevor du Live-SpecCanvas-Daten erstellst oder aktualisierst.
• Wenn die Aufgabe ein UI-Spec erstellt oder aktualisiert, lies auch references/ui-spec-workflow.md.
• Wenn die Aufgabe eine Bildschirmimplementierung erstellt, lies auch references/implementation-workflow.md.
• Wenn MCP nicht verfügbar ist, erfinde keine Verbindungsdetails. Arbeite mit portablen YAML-Dateien oder bitte den Benutzer, den speccanvas-MCP-Server zu konfigurieren.
• Speichere keine MCP-URLs, Bearer-Tokens, Staging-Hosts oder lokale Geheimnisse in dieser Skill. Diese gehören in die MCP-Konfiguration und Umgebungsvariablen des Agenten.

MCP-Modellidentitätsregel

Beim Speichern einer agentenverfassten Bildschirmimplementierung über MCP gib immer eine stabile Modellidentität als { identityKey, provider, model, version } an.

• Löse das aktive Modell aus globalen Agentenregeln, Umgebungsvariablen oder der aktuellen Sitzung auf, bevor du add_implementation aufrufst.
• Übergib modelIdentity direkt an add_implementation. Ersetze es nicht durch agentName.
• agentName ist nur ein manueller/veralteter Fallback. Verwende ihn nur mit modelIdentity: null, wenn die Implementierung von einem Menschen hochgeladen wird oder die Modellidentität absichtlich nicht verfügbar ist.
• Wenn das aktive Modell unbekannt, mehrdeutig oder nicht registriert ist, stoppe und bitte um Klärung, anstatt stillschweigend mit agentName zu speichern.

Arbeitsablauf

1. Identifiziere die Artefaktgrenze. Bestimme, ob die Aufgabe Folgendes benötigt:

   • Nur UI-Spec
   • Nur Data-Spec
   • Beide Specs
   • Erklärung, Überprüfung, Bereinigung oder Validierung eines vorhandenen Specs
   • Keine Spec-Änderung, da die Anfrage ein Implementierungs-Mikro-Tweak ist
   • Live-MCP-Persistenz für Projekte, Specs, Revisionen, Implementierungen oder Archive

2. Wende die Granularitätsschranke an. Entscheide bei UI-Arbeiten, ob die Anfrage die Produktabsicht/-struktur oder nur Implementierungsdetails ändert. Wenn es nur ein Mikro-Tweak ist, lasse das Spec unberührt.

3. Sammle Quellmaterial. Verwende nur die Eingaben, die die Struktur definieren:

   • Produktidee oder Funktionsanfrage
   • vorhandene Screenshots oder UI-Beschreibungen
   • Codebasis-Struktur
   • aktuelles YAML-Spec
   • Entitätslisten, API-Notizen oder Domänenregeln

4. Lies die erforderlichen Arbeitsablauf- und Format-Referenzen.

   • Für die Erstellung oder Überarbeitung eines UI-Specs lies references/ui-spec-workflow.md.
   • Für die Erstellung einer Bildschirmimplementierung lies references/implementation-workflow.md.
   • Für die Live-MCP-Persistenz lies references/mcp-workflow.md.
   • Zum Verfassen eines UI-Specs lies references/ui-spec-format-0-0-3.yaml.
   • Zum Verfassen eines Data-Specs lies references/data-spec-format-0-0-1.yaml.
   • Für lokales Validierungsverhalten und Überprüfungsheuristiken lies bei Bedarf references/workflow.md, references/validation-rules-ui.md und references/validation-rules-data.md.
   • Die aktuellen gebündelten Schemas befinden sich unter schemas/ui-spec.schema.json und schemas/data-spec.schema.json.

5. Entwerfe oder überarbeite das Spec. Halte das Dokument als gültiges YAML und bleibe innerhalb der Formatfelder. Erfinde keine benutzerdefinierten Top-Level-Abschnitte, es sei denn, das Format erlaubt sie explizit. Führe die kleinstmögliche semantische Aktualisierung durch, die die Absicht bewahrt; erweitere das Spec nicht um pixelgenaue Implementierungsnotizen.

6. Validiere das Ergebnis. Wenn scripts/validate-spec.mjs verfügbar ist, führe es gegen das endgültige YAML aus, bevor du das Ergebnis zurückgibst. Behebe Validierungsfehler, bevor du das Spec zurückgibst.

7. Gib das Ergebnis zurück. Gib validiertes YAML zurück oder, bei Überprüfungsaufgaben, zuerst die Probleme und danach das korrigierte Snippet oder die Datei.

Kernregeln

Verwende die Formatdatei als Schreibvorlage

Die Format-Beschreibungs-YAML-Dateien sind die primäre Verfassungsreferenz für diese Skill. Folge zuerst ihrer Struktur, Feldbenennung, Beispielen und Anleitung. Für UI-Spec ist references/ui-spec-format-0-0-3.yaml die aktuelle lokale Wahrheitsquelle und sollte mit dem gebündelten Schema und Validator übereinstimmen.

Verwende Schema-Validierung als Nachkontrolle

Schema-Validierung ist nicht die Schreibvorlage. Sie ist der letzte Verifikationsschritt.

• Schreibe das Spec aus der Formatdatei.
• Validiere das geschriebene Spec mit scripts/validate-spec.mjs.
• Behebe Schema- und Validierungsregelfehler, bevor du das endgültige YAML zurückgibst.

Die gebündelten Schemas in schemas/ sollten mit der Spec Canvas-Implementierung und den Format-Beschreibungsreferenzen dieser Skill synchronisiert bleiben. Wenn sie abzuweichen scheinen, behandle dies als Skill-Fehler und weise explizit darauf hin, anstatt stillschweigend einen Kompromiss zu erfinden.

Halte UI und Daten abgestimmt

Wenn beide Specs existieren:

• gleiche Benennung zwischen Bildschirmen, Entitäten und Aktionen ab
• stelle sicher, dass UI-Aktionen reale Entitäten oder Arbeitsabläufe implizieren
• stelle sicher, dass Data-Spec-Beziehungen die UI-Struktur unterstützen
• markiere Lücken, anstatt stillschweigend Backend-Konzepte zu erfinden

Halte das Format portabel

Erstelle einfache YAML-Dateien, die in einem Repository leben und von jedem Agenten wiederverwendet werden können. Mache das Spec nicht abhängig von Spec Canvas-UI-Zustand, versteckten Metadaten oder Chat-spezifischen Annahmen.

Halte UI-Spec oberhalb der Implementierungsdetails

Verwende UI-Spec nicht als Ersatz für CSS, Komponentendokumentation oder Änderungsprotokolle. Ein gutes purpose erklärt, wofür der Bildschirm oder Block aus Benutzersicht da ist. Es sollte keine genauen Abstände, Klassennamen, Pixelgrößen, vorübergehende Implementierungsmechaniken oder jedes kleine Steuerelement aufzählen, wenn diese Details die Produktbedeutung nicht ändern.

Aufgabenmuster

Erstelle ein neues UI-Spec

• Beginne mit docType, format_version und metadata.
• In UI-Spec ist metadata.description erforderlich und sollte die Produktabsicht auf oberster Ebene tragen.
• Füge screens hinzu, sobald die Haupt-App-Form bekannt ist.
• Füge blocks hinzu, wenn der Benutzer eine sichtbare Struktur wünscht; blocks können in der Erkundungsphase weggelassen werden.
• Füge templates, navigation oder responsive Felder nur hinzu, wenn sie wesentlich helfen.
• Die vom aktuellen lokalen Format unterstützte responsive UI-Erstellung umfasst metadata.breakpoints, adaptives screen.template, adaptives block.columns und block.visible.
• Bewahre die ursprünglichen Formatdatei-Konventionen, einschließlich der Anführungszeichen-Hinweise aus der UI-Formatdatei.
• Validiere die fertige Datei mit scripts/validate-spec.mjs, wenn verfügbar.

Erstelle ein neues Data-Spec

• Beschreibe das logische Domänenmodell, nicht die physische Datenbank.
• Füge enums nur hinzu, wenn gemeinsame kontrollierte Vokabulare wichtig sind.
• Definiere entities mit geschäftsrelevanten fields.
• Verwende relations für logische entitätsübergreifende Struktur.
• Vermeide das Durchsickern von implementierungsspezifischen Belangen wie Indizes, Migrationen oder ORM-spezifischer Syntax, es sei denn, der Benutzer bittet explizit darum außerhalb des Specs.
• Validiere die fertige Datei mit scripts/validate-spec.mjs, wenn verfügbar.

Überprüfe oder repariere ein vorhandenes Spec

Prüfe auf:

• ungültige oder nicht unterstützte Felder
• fehlende erforderliche Abschnitte
• kaputte Bildschirm-, Vorlagen- oder Navigationsreferenzen
• Aufzählungs-, Fremdschlüssel- oder Beziehungsfehler im Data-Spec
• benutzerdefinierte Validierungsfehler, die von den lokalen Validierungsregeln aufgedeckt wurden
• Schema-Format-Diskrepanzen zwischen der ursprünglichen Formatdatei und der aktuellen lokalen Implementierung
• übermäßig detaillierte UI-purpose-Texte, die Implementierungsmechaniken anstelle von Produktabsicht beschreiben

Bewahre beim Reparieren die ursprüngliche Produktabsicht und nimm die kleinste Korrektur vor, die die Klarheit wiederherstellt.

Verdichte ein übermäßig detailliertes UI-Spec

• Behalte vorhandene Bildschirm-, Vorlagen-, Regions- und Block-IDs stabil, es sei denn, die Produktstruktur ändert sich wirklich.
• Ersetze lange purpose-Absätze durch Ein-Satz-Zusammenfassungen der benutzerseitigen Absicht.
• Bewahre Bildschirme, Hauptblöcke, Navigation, wichtige Zustände und sinnvolle Modi.
• Entferne CSS/Layout-Mikrodetails, Plattform-Besonderheiten, genaue Zeitangaben, Protokollierungsverhalten und komponenteninterne Mechanismen.
• Vermeide eine Neuformatierung der gesamten YAML-Datei; verwende gezielte Bearbeitungen, damit Diffs überprüfbar bleiben.
• Validiere nach der Bearbeitung.

Rekonstruiere ein Spec aus einer vorhandenen App

• leite Bildschirme aus sichtbaren Arbeitsabläufen ab
• leite Blöcke aus wiederholten Regionen und Benutzeraufgaben ab
• leite Entitäten aus Domänennomen und Zustandsänderungen ab
• trenne, was beobachtet wird, von dem, was vermutet wird
• benenne Unsicherheiten explizit, wenn das Quellmaterial unvollständig ist

Validierung

Verwende scripts/validate-spec.mjs, wenn verfügbar.

• Eingabe: Pfad zu einer YAML-Spec-Datei
• Erkenne den Dokumenttyp aus docType
• Validiere gegen das gebündelte JSON-Schema dieser Skill
• Führe die relevanten benutzerdefinierten Validierungsregeln aus
• Behandle Warnungen als Hinweise
• Behandle Fehler als Blockierer für die endgültige Ausgabe, wenn du ein korrigiertes Spec zurückgibst

Wenn das Skript nicht ausgeführt werden kann, weil die lokalen Spec Canvas-Abhängigkeiten fehlen, sage dies kurz und falle auf eine manuelle Überprüfung unter Verwendung der Formatdatei und der Validierungsregel-Referenzen zurück.

Ausgabeerwartungen

Beim Zurückgeben von Specs:

• gib gültiges YAML an
• behalte IDs in snake_case bei, wo das Format sie erwartet
• behalte Feldnamen genau so bei, wie sie von der Formatdatei definiert sind
• erwähne Annahmen, wenn sie die Struktur wesentlich beeinflussen
• erwähne, ob eine Validierung durchgeführt wurde

Beim Zurückgeben einer Überprüfung anstelle einer neu geschriebenen Datei:

• liste strukturelle Probleme zuerst auf
• gib dann konkrete Korrekturen an
• gib dann ein korrigiertes Snippet oder das vollständige Spec an, falls nützlich