Architecture Decision Record

Workflow-Skill `/solcom-build-frontend` für UI-Build-Disziplin

Ein neuer Skill /solcom-build-frontend konsolidiert die UI-Build-Disziplin als 7-Phasen-Choreographie und ruft die existierenden Skills/Agents an den richtigen Stellen auf. Ausschließlich Slash-triggerbar (disable-model-invocation: true).

Kontext

CLAUDE.md und die zwölf solcom-/drupal-* Skills im Repo schreiben mehrere Pflicht-Konsultationen für UI-Bau vor, die in der Praxis verstreut sind und einzeln vergessen werden:

customer-lens-reviewer-Agent vor Code bei jeder Komponenten-Topologie-Entscheidung mit ≥2 Optionen (CLAUDE.md → „Component-Design Reviews", solcom-adr-workflow).
Brand-Compliance gegen theme.brand.css und ADR-0003 (solcom-styleguide).
13 byte_theme Twig/CVA-Regeln (drupal-twig-sdc-authoring + byte_theme/AGENTS.md).
Canvas-Eligibility-Konventionen für neue SDCs (drupal-canvas, plus config/sync/canvas.component.sdc.*.yml).
Diff-time Reviewer-Agents (solcom-brand-reviewer, drupal-twig-sdc-reviewer, drupal-config-architecture-reviewer).
Verifikations-Choreographie nach jeder Theme-Änderung: npm run format && npm run build im byte_theme + ddev drush cache:rebuild. Nach config-Änderung: config:status → config:import → cache:rebuild.

Auto-Trigger der Skills feuern unzuverlässig — eine Phrase wie „bau mir eine neue Card" lädt oft drupal-twig-sdc-authoring, aber nicht solcom-styleguide, ruft nicht customer-lens-reviewer und vergisst die Verifikations-Sequenz.

Drei UI-Build-Anlässe, die wiederkehren:

Greenfield — neue SDC-Komponente von Spec bis live (Default: Canvas-fähig).
Refactor — bestehende SDC erweitern (Variant, Slot, Prop) unter Pattern-Schutz (CLAUDE.md → „Refactor ≠ Rewrite").
Canvas-Page — Page-Composition aus bestehenden SDCs. Im Solcom-Repo teils Code-First in config/sync/canvas.*.yml, teils Browser-Pflicht in Content-Entities.

Entscheidung

Ein neuer Skill /solcom-build-frontend konsolidiert die UI-Build-Disziplin als 7-Phasen-Choreographie und ruft die existierenden Skills/Agents an den richtigen Stellen. Skill liegt project-local unter .claude/skills/solcom-build-frontend/, ausschließlich Slash-triggerbar (disable-model-invocation: true), keine Auto-Trigger.

Architektur: Orchestrator + drei Sub-Files. Schlanke SKILL.md enthält Triage-Heuristik und die drei common-Phasen (Triage, Verify-Build, Visual-Verify). Drei Sub-Markdown-Files (greenfield.md, refactor.md, canvas-page.md) enthalten je die workflow-spezifischen Phasen Spec, Decide, Build, Review.

Phasen-Skelett (sieben distinct Phasen, drei common, vier sub-file-spezifisch):

Triage (common) — Heuristik aus /solcom-build-frontend <argument>, mit AskUserQuestion-Fallback bei Mehrdeutigkeit.
Spec (sub-file) — was wird gebaut, mit welcher Quelle (Figma MCP, bestehende Komponente, Ziel-Layout).
Decide (sub-file) — Topologie-Optionen aufzählen; bei ≥2: customer-lens-reviewer Pflicht; ggf. ADR.
Build (sub-file) — Skills aktivieren, Files erzeugen oder editieren.
Verify-Build (common) — npm run format && npm run build + ddev drush cache:rebuild. Bei Canvas-Page ohne Theme-Änderung: config:status → config:import → cache:rebuild.
Review (sub-file) — Reviewer-Agents parallel.
Visual-Verify (common) — Browser-Sichtkontrolle via agent-browser.

Triage-Heuristik (Initial-Default):

Argument enthält …	→ Sub-Workflow
`page`, `layout`, `region`, `seitenlayout`, `composition`, `content type template`	`canvas-page.md`
`refactor`, `bestehende`, `erweitern`, `Variante hinzufügen`, `Slot ergänzen`, `update component`, `edit component`	`refactor.md`
`neu`, `neue`, `erstellen`, `bauen`, `add new`, `brand new`, `from figma`, `aus figma`	`greenfield.md`
sonst, leer, mehrere Treffer	AskUserQuestion (3 Optionen)

Erste-Match-wins von oben nach unten. Pattern-Liste wird nach 2–3 Live-Läufen nachgezogen.

Customer-lens-Aufruf-Mechanik. Skill listet in der Decide-Phase explizit Topologie-Optionen auf. Bei ≥2 Optionen wird customer-lens-reviewer immer aufgerufen. Bei genau 1 sinnvollen Option wird Skip-Begründung notiert.

Refactor-Edit-Strategie. Sub-Workflow refactor.md fragt in der Spec-Phase via AskUserQuestion nach Strategie a/b/c (CLAUDE.md → „Refactor ≠ Rewrite"). Bestehende Files werden ausschließlich mit Edit-Tool modifiziert, niemals mit Write-Tool — Schutz gegen die TDD-Stub-Anti-Pattern.

Canvas-Awareness. drupal-canvas Skill ist in Greenfield default-on, in Refactor bedingt, in Canvas-Page Hauptpfad. Sub-Workflow canvas-page.md differenziert zwischen Code-First-fähigen Artefakten und Browser-Pflicht-Artefakten.

Rejected alternatives

rejected Auto-Trigger via Phrasen-Match

Skill mit YAML-Triggers hätte Auto-Loading ermöglicht. Verworfen, weil Auto-Trigger bei normalen Drupal-Tasks falsch feuern und mit unaufgeforderter Triage-Frage stören. Slash-Command-only ist vorhersehbarer. disable-model-invocation: true ist die Konsequenz.

rejected Single SKILL.md mit If/Else-Branches für die drei Sub-Workflows

Verworfen wegen Lesbarkeits-Verfall (500+ Zeilen mit gegenseitig störenden Branches). Sub-Files-Pattern ist etabliert.

rejected Drei separate Slash-Commands (/solcom-greenfield-sdc, /solcom-refactor-sdc, /solcom-canvas-page)

Verworfen, weil drei Slash-Commands die Discoverability verschlechtern und der ursprüngliche Wunsch explizit einen Skill war. Sub-Files bleiben jederzeit re-extrahierbar.

rejected Den globalen ui-Skill (uidotsh-remote) einbinden

Verworfen, weil er für die React/Tailwind-Welt designed ist und mit dem byte_theme/Twig/CVA/Canvas-Stack kollidieren würde.

rejected Hartes Done-Pass/Fail pro Phase oder /go-Pattern (autonomer Lauf)

Verworfen, weil der Workflow substantielle User-Entscheidungspunkte hat und Skills konzeptionell Markdown-Anweisungen sind, nicht Test-Frameworks. Pseudo-Pass/Fail wäre nur Konversations-Theater.

rejected Heuristische Strategie-Wahl im Refactor (Skill misst Refactor-Größe → Strategie)

Verworfen wegen Heuristik-Fragilität — Diff-Größen-Schätzung im Voraus ist unzuverlässig. User-Entscheidung via AskUserQuestion ist eindeutiger.

rejected 1:1-Übernahme der offiziellen drupal-canvas/skills als Pflicht-Konsultation

Verworfen, weil die offiziellen Skills die JS/React-Variante adressieren (index.jsx, pages/*.json, Workbench) und eine direkte Anwendung im Twig-SDC-Stack falsche File-Pfade einschleppen würde. Stattdessen: Konzepte adaptieren, File-Examples Twig-SDC-spezifisch.

rejected Den ganzen Solcom-Theme-Pfad auf JS/React-Canvas umstellen

Riesiger Eingriff in das byte_theme + 11 ADRs + 12 Skills, weit außerhalb des Skill-Scopes. Würde eigenes ADR-Programm brauchen.

Consequences

Pflicht-Konsultationen sind reproduzierbar. Wer /solcom-build-frontend startet, durchläuft die ≥2-Optionen-Lens-Pflicht, die Brand-Reviewer-Konsultation, die npm- bzw. config:import-Verifikation und die Browser-Sichtkontrolle in derselben Reihenfolge.
disable-model-invocation: true heißt: Auto-Trigger feuern nicht. Wer den Skill nicht als Slash-Command aufruft, läuft weiterhin Gefahr, Pflicht-Schritte zu vergessen. Der Skill ist Disziplin-Werkzeug, kein Sicherheitsnetz.
Triage-Heuristik ist anfänglich grob. Edge-Cases (z. B. „neue Variante zur bestehenden Card hinzufügen" — neue matched Greenfield, bestehende matched Refactor) werden via Erste-Match-Regel auf Refactor geschickt. Falsch-Triagen werden über AskUserQuestion-Fallback aufgefangen.
Skill ersetzt nicht die einzelnen Skills/Agents. solcom-styleguide, drupal-canvas, customer-lens-reviewer etc. sind weiterhin unabhängig nutzbar. Der Workflow-Skill ist Choreographie, nicht Substitution.
Canvas-Page-Sub-Workflow hat Code-First-Grenze. Page-Trees pro Einzel-Node liegen in Content-Entities und sind nicht via config:export greifbar — der Sub-Workflow gibt für Page-Tree-Building Schritt-für-Schritt-Anleitungen für das Canvas-UI im Browser aus.
Refactor-Pattern-Schutz hängt am Edit-Tool-Verbot für Write. Sub-Workflow refactor.md schreibt explizit vor, dass bestehende Files nur mit Edit-Tool modifiziert werden. Ein Verstoß ist nicht maschinell verhindert — aber der Verbots-Hinweis im Sub-File senkt die Wahrscheinlichkeit.
Die offiziellen drupal-canvas/skills driften möglicherweise weiter als die Solcom-Adaption mitziehen kann. Update-Trigger wäre ein neuer ADR mit höherer Nummer.
ADR-Erwartung beim Skill-Update. Größere Workflow-Änderungen (neue Phase, neuer Sub-Workflow, Drop eines Reviewer-Agents) erzeugen neuen ADR mit höherer Nummer, der ADR-0012 zitiert. Kleine Heuristik-Tunings am Triage sind ADR-frei.