Architecture Decision Record

Composite-Build-Decomposition + Autonomie-Klausel im `/solcom-build-frontend`

Phase 1 (Triage) liefert jetzt eine geordnete Liste von Sub-Workflow-Aufrufen statt genau einen. Bei klarer Bauintention plus Quelle läuft der Skill nach einer einzigen Bestätigungs-Question die Phasen 2–7 in einem Lauf durch.

Kontext

ADR-0012 etabliert den /solcom-build-frontend Workflow-Skill als 7-Phasen-Choreographie mit drei Sub-Workflows (Greenfield, Refactor, Canvas-Page). Triage in Phase 1 wählt genau einen Sub-Workflow basierend auf einer Phrasen-Heuristik.

In der Live-Nutzung treten zwei wiederkehrende Schwächen auf:

Bauauftrag aus Figma-Frame ist häufig nicht atomic. Ein einzelner Figma-Frame referenziert oft eine Komposition aus mehreren neuen SDCs plus einem Wrapper / einer Page-Region / einem Content-Type-Template. Die aktuelle Triage zwingt den User, die Decomposition selbst vorzunehmen und mehrere Slash-Commands hintereinander abzusetzen.
Phasen-Disziplin wird als Stop-After-Each-Phase missverstanden. Die weiche Done-Mechanik (ADR-0012) wurde gelegentlich als „nach jeder Phase fragt der Skill, ob weitergebaut werden soll" interpretiert. Bei klarem Bauauftrag mit eindeutiger Quelle ist das unproduktives Konversations-Theater.

Entscheidung

Phase 1 (Triage) liefert eine geordnete Liste von Sub-Workflow-Aufrufen, nicht mehr genau einen. Bei einer atomic Aufgabe ist die Liste einelementig (rückwärtskompatibel). Bei einer zusammengesetzten Aufgabe enthält die Liste mehrere Einträge in Ausführungsreihenfolge.

Decomposition-Heuristik in der Triage:

SDC-Inventur (ls web/themes/custom/byte_theme/components/ oder list_sdc_components MCP-Tool, wenn verfügbar) wird in der Triage immer ausgeführt, sobald eine Figma-Quelle oder eine Multi-Element-Spec vorliegt.
Wenn die Quelle ≥2 noch nicht vorhandene SDCs oder (≥1 neue SDC + Wrapper/Region/Template) referenziert: Composite-Lauf.
Pro identifiziertem Element wird ein Sub-Workflow-Eintrag erzeugt: (greenfield, name), (refactor, name), oder (canvas-page, artefakt-typ).
Ausführungsreihenfolge: bottom-up — atomare SDCs zuerst, dann Komposite (Wrapper, Region, Template) zuletzt.

Neuer Sub-File composite.md orchestriert Multi-Sub-Workflow-Läufe. Loop-Schleife: für jeden Eintrag der Decomposition-Liste das passende Sub-File ab Phase 2 ausführen, am Ende ein einziges Verify-Build (Phase 5) + Review (Phase 6) + Visual-Verify (Phase 7) über die gesamte Komposition. Reviewer-Agents bekommen die Liste aller berührten Files gemeinsam.

Autonomie-Klausel als eigener Execution Discipline-Abschnitt im SKILL.md: Bei klarer Bauintention plus Quelle (Figma-URL, schriftliche Spec, eindeutiges Refactor-Ziel) durchläuft der Skill nach einer einzigen Bestätigungs-Question (Decomposition-Liste mit AskUserQuestion) die Phasen 2–7 in einem Lauf, ohne Per-Phase-Stops.

Ausnahmen, die einen Stop erzwingen (auch im autonomen Lauf):

customer-lens-reviewer Output mit P0-Findings auf der gewählten Topologie-Option.
Reviewer-Agent (Phase 6) mit P0-Finding.
Pflicht-User-Entscheidung in einem Sub-File (z. B. Refactor-Strategie a/b/c — AskUserQuestion bleibt Pflicht).
DDEV/Drush-Failure beim Verify-Build, der nicht auto-fixbar ist.

Bestehende Triage-Heuristik bleibt für Single-Sub-Workflow-Pfade unverändert.

Rejected alternatives

rejected Per-Phase-Stop bleibt Default, Autonomie-Klausel als Opt-In via Argument-Flag (/solcom-build-frontend --auto …)

Verworfen, weil die Default-Erfahrung dann weiterhin Konversations-Theater liefert. Klare Bauintention ist der Common-Case bei Figma-Aufträgen, nicht der Edge-Case.

rejected Composite-Logik in greenfield.md einbauen statt eigenem Sub-File

greenfield.md müsste dann eine Inner-Loop über mehrere Sub-Workflows haben und die Phase-Definitionen zwischen „atomic Greenfield" und „Composite-Lauf" würden verschwimmen. Eigenes Sub-File ist konsistent mit dem Sub-File-Pattern aus ADR-0012.

rejected Ein neuer Slash-Command /solcom-build-composite

Verworfen aus demselben Grund wie ADR-0012 → drei separate Slash-Commands: Discoverability-Verfall.

rejected Decomposition durch separaten Decomposition-Agent vor der Triage

Decomposition ist Wissens-leicht (Inventur + Element-Zählung) und ein eigener Agent addiert nur Latenz und Komplexität ohne Mehrwert.

rejected Ausführungsreihenfolge top-down (Komposite zuerst, atomare SDCs zuletzt) mit Stub-Komponenten als Platzhalter

Verworfen, weil das genau das TDD-Stub-Anti-Pattern aus CLAUDE.md → „Refactor ≠ Rewrite" einlädt. Bottom-up vermeidet Stubs vollständig.

rejected Reviewer-Agents pro Sub-Workflow einzeln aufrufen

Verworfen, weil die Reviewer dann Findings produzieren, die sich überschneiden und nicht in den größeren Composition-Kontext einbetten. Single-Pass am Ende ist kohärenter.

rejected Hartes Pass/Fail-Gate beim Verify-Build vor Composition

Verworfen, weil das die bestehende weiche Done-Policy aus ADR-0012 bricht. Fix-and-continue mit User-Absprache bleibt Linie.

Consequences

Composite-Lauf ist die neue Default-Erfahrung bei Figma-Bauaufträgen. Der User gibt einen Figma-Link, der Skill macht die SDC-Inventur, schlägt eine Decomposition vor (AskUserQuestion mit der Liste), und läuft dann die Sub-Workflows in Reihenfolge ab.
Autonomie-Klausel reduziert Konversations-Theater. Per-Phase-Stops sind nicht mehr Default. Pflicht-Stops sind dokumentiert (P0-Findings, Refactor-Strategie-Wahl, DDEV-Failure). Eingriffe via Stop-Worte (stop, halt, warte) bleiben jederzeit möglich.
Bottom-up-Reihenfolge ist neue Konvention. Atomare SDCs werden zuerst gebaut, Komposite zuletzt. Komposite-Phase findet die atomaren SDCs bereits Canvas-registriert vor, Visual-Verify sieht von Anfang an die echte Komposition.
Single-Pass-Review am Ende kann lange werden. Bei einem Composite-Lauf mit 4 neuen SDCs + 1 Region bekommt der Brand-Reviewer alle Files in einem Lauf. Output kann größer sein, aber kohärenter im Composition-Kontext. Optional pro Sub-Workflow re-reviewen via /review.
Decomposition-Heuristik kann Fehlschüsse haben. SDC-Inventur erkennt nicht jede feinkörnige Wiederverwendung. Die AskUserQuestion-Bestätigung der Decomposition-Liste ist genau dafür da: User korrigiert, bevor der Lauf startet.
Refactor-Sub-Workflows in Composite-Läufen brauchen Strategie-Wahl. Wenn die Decomposition (refactor, button) enthält, fragt der Sub-Lauf nach Strategie a/b/c — Pflicht-Stop, Ausnahme von der Autonomie-Klausel.
composite.md setzt Verify-Build und Review erst nach allen Sub-Workflows ab. Zwischendrin keine Theme-Builds, keine drush cr, keine drush cim. Ein Fehler in Sub-Workflow N wird erst beim finalen Verify-Build sichtbar.
ADR-0012 bleibt gültig. Dieses ADR erweitert ADR-0012 um eine Phase-1-Output-Generalisierung (Liste statt Skalar) und ein neues Sub-File. Phasen-Skelett, Reviewer-Agent-Map und Sub-Workflow-Definitionen aus ADR-0012 bleiben unverändert.