CompanyOS Phase 1 Implementation

Dieses Dokument übersetzt die CompanyOS-Strategie in konkrete technische Arbeit für die erste Umsetzungsphase.

Der Fokus von Phase 1 ist:

Make Brezel systems explainable.

Das bedeutet:

bestehende Systeme inventarisieren
Ressourcen und Workflows strukturiert indexieren
fachliche Semantik ergänzen
eine Grundlage für sichere AI-Änderungen schaffen
Workflow-Testing als tragende Produkt- und Plattformfähigkeit aufbauen

Phase-1-Ziele

Am Ende von Phase 1 soll Brezel:

ein System maschinenlesbar beschreiben können
Module, Felder, Rollen, Menüs und Workflows erklärbar machen
semantische Metadaten standardisiert speichern können
Änderungen an Geschäftslogik besser absichern können
eine belastbare Testpyramide für Workflows besitzen

Nicht-Ziele

Phase 1 ist noch nicht:

ein vollwertiger generativer AI-Builder
ein kompletter SaaS-Launch
ein freies Prompt-to-ERP-System
eine vollständige Migration aller Bestandskunden

Arbeitsströme

Stream 1: System Scanner

Ziel: Bestehende Brezel-Systeme automatisch erfassen.

Scope:

Erkennung von systems/<system>/
Indexierung von Bakery-Ressourcen
Erkennung von Modulen, Feldern, Layouts, Rollen, Menüs und Workflows
Ableitung von Referenzen und Abhängigkeiten
Ausgabe als strukturierte Artefakte

Erwartete Artefakte:

system inventory
identifier map
workflow catalog
resource graph

Stream 2: Semantic Metadata

Ziel: Ein kanonisches semantisches Modell für Brezel-Ressourcen einführen.

Erste Zielobjekte:

Module
Workflows
Rollen
Menüs
Entscheidungen und Spezifikationen

Minimaler semantischer Kern:

purpose
business_owner
summary
inputs
outputs
invariants
risks
related_resources
change_notes

Entscheidung: Die Semantik sollte möglichst nah an bestehenden deklarativen Ressourcen liegen und nicht in einem komplett separaten Metasystem versteckt werden.

Stream 3: Explainability

Ziel: Ein System, ein Modul oder ein Workflow soll erklärbar sein, ohne Rohdateien lesen zu müssen.

Erste Ausgaben:

System Summary
Workflow Summary
Modul Summary
Trigger- und Seiteneffektübersichten
Abhängigkeitslisten

Beispielhafte Fragen:

Welche Workflows gibt es in diesem System?
Was passiert beim Erstellen eines Auftrags?
Welche Rollen sind an einem Prozess beteiligt?
Welche Module sind kritisch für die Fakturierung?

Stream 4: Workflow Testing

Ziel: Workflows werden als produktionskritische Geschäftslogik testbar und regressionssicher.

Dieser Stream ist nicht optional. Wenn Brezel CompanyOS werden soll, muss Geschäftslogik so testbar sein wie normaler Anwendungscode.

Testpyramide

Ebene 1: Workflow-Element-Unit-Tests

Zweck: Absicherung einzelner Workflow-Element-Typen in Isolation.

Beispiele:

flow/if
op/set
action/save
action/run
source/entities

Zu prüfen:

Optionsvalidierung
Eingangs- und Ausgangsport-Verhalten
Datenmanipulation
Fehlerfälle
deterministische Seiteneffekte

Technische Ausrichtung:

PHPUnit/Pest auf Klassen- und Elementebene
keine komplette Business-Instanz nötig
schnell und engmaschig ausführbar

Ebene 2: Workflow-Engine- und Integrations-Tests

Zweck: Absicherung des Zusammenspiels von Workflow-Builder, Dispatch, Events, Queue-Verhalten, Persistenz und Ports.

Zu prüfen:

Workflow-Aufbau aus Definitionen
Port-Verbindungen
Triggering über Events
synchrones und asynchrones Dispatching
Persistenzänderungen
Fehlerweitergabe
Observability und Diagnostik

Technische Ausrichtung:

Feature-/Integration-Tests in brezel/api
mit realem Workflow-Lauf gegen Testdaten
nah an bestehenden Tests wie tests/Feature/Workflow/WorkflowTest.php

Ebene 3: Business-Workflow-Tests auf Systemebene

Zweck: Konkrete Unternehmenslogik in realen Brezel-Instanzen prüfen.

Das ist die entscheidende zusätzliche Ebene. Hier wird nicht nur das Framework getestet, sondern die Business-Implementierung eines konkreten Systems.

Beispiele:

OrderCreated erzeugt erwartete Folgeoperationen
GenerateInvoicePDF erstellt die richtigen Artefakte
CreateCustomerFromOrder befüllt die erwarteten Module korrekt
kundenspezifische Policies und Prozessvarianten bleiben intakt

Anforderungen:

Tests referenzieren echte Workflows eines Systems
Testdaten und Fixtures sind systemspezifisch
Assertions prüfen Fachresultate, nicht nur technische Responses
Tests müssen auch für Bestandskunden-Upgrade-Pfade nutzbar sein

Empfohlene Form:

systemnahe Test-Suites unter systems/<system>/tests/
standardisierte Test-Fixtures pro System
deklarative oder codebasierte Assertions, je nach Reifegrad

Warum das strategisch wichtig ist

Diese drei Ebenen sind die Voraussetzung für:

sichere AI-generierte Änderungen
kontrollierte SaaS-Templates
migrationsfähige Bestandskundensysteme
Vertrauen in CompanyOS als Runtime für kritische Abläufe

Ohne Business-Workflow-Tests bleibt Brezel bei jeder AI- oder Refactoring-Initiative zu riskant.

Stream 5: Change Proposal Model

Ziel: Änderungen an Brezel-Artefakten werden als prüfbare Vorschläge modelliert.

Ein Change Proposal sollte enthalten:

betroffene Ressourcen
fachliche Begründung
technische Diffs
Risikoklassifizierung
betroffene Workflows
empfohlene Tests
Apply-/Rollback-Information

Erstes technisches Zielbild

A. Explainability CLI oder Service

Erste denkbare Fähigkeiten:

system explain
system inventory
workflow catalog
workflow explain <identifier>

Diese Fähigkeiten können zunächst als internes Tooling oder API-Endpunkte entstehen.

B. Semantic Schema

Benötigt wird ein formales Schema für semantische Metadaten.

Optionen:

Einbettung direkt in bestehende Ressourcen
begleitende .semantic.*.json-Artefakte
hybride Lösung mit klarer Priorität auf lokaler Nähe zur Ressource

Entscheidungskriterium: Die Lösung muss maschinenlesbar, versionierbar und für Agenten leicht auffindbar sein.

C. Workflow Test Harness

Benötigt wird ein standardisierter Testrahmen für alle drei Ebenen.

Der Harness sollte erlauben:

einzelne Workflow-Elemente isoliert zu testen
einen Workflow kontrolliert zu dispatchen
Fixtures für ein System zu laden
Business-Assertions auf Systemebene auszuführen

Vorgeschlagene Repo-Übersetzung

Die folgenden Bereiche sind naheliegende Startpunkte:

brezel/api für Scanner, Test-Harness, Workflow-Engine-Tests und semantische Verarbeitung
brezel/brezel für Skeleton-Konventionen und Standardordner
brezel/installer für spätere Provisioning- und Bootstrapping-Unterstützung
brezel/wiki für Dokumentation, Konventionen und öffentliches Narrativ

Konkrete Deliverables für den ersten Implementierungsschnitt

Ein system inventory-Generator für bestehende Systeme.
Ein erstes workflow catalog-Artefakt mit Triggern und Modulbezügen.
Eine Spezifikation für semantische Metadaten von Modulen und Workflows.
Ein Testkonzept für alle drei Workflow-Testebenen.
Ein kleiner Referenzsatz von Workflow-Tests im Core.

Konkrete Deliverables für den zweiten Implementierungsschnitt

Ein erster system explain-Output.
Ein standardisiertes Verzeichnis- oder Dateikonzept für systemnahe Business-Workflow-Tests.
Erste Loader oder Helper für systemspezifische Test-Fixtures.
Verknüpfung von Change Proposals mit empfohlenen Tests.

Roadmap für Workflow-Testing

Schritt 1

Vorhandene Workflow-Tests im Core erfassen und kategorisieren:

Builder-Tests
Dispatch-Tests
Event-Tests
Controller-Tests

Schritt 2

Abdeckung der Element-Typen explizit machen.

Ergebnis:

Liste aller Element-Typen
Teststatus pro Element
Priorisierung nach Kritikalität

Schritt 3

Standardisierte Integrationsszenarien definieren.

Beispiele:

lineare Workflows
Branching
Nested Run
Fehlerpfade
Queue/Async
Persistenzpfade

Schritt 4

System-Level-Business-Tests definieren.

Benötigt wird:

Konvention für Speicherort
Fixture-Format
Assertion-Konzept
Test-Runner-Mechanik

Schritt 5

Workflow-Tests in Change- und Release-Prozesse einbinden.

Ziel: Änderungen an Workflows oder AI-generierte Vorschläge können gezielt die relevanten Tests auslösen.

Erste Architekturentscheidungen

Workflow-Testing wird als Plattformfähigkeit behandelt, nicht als projektbezogene Kür.
Business-Workflow-Tests auf Systemebene sind Teil der Roadmap, nicht späteres Nice-to-have.
Explainability und Testing gehören zusammen: Was erklärt werden kann, muss auch gezielt testbar sein.
Semantik, Inventar und Testing müssen auf denselben Ressourcenmodellen aufbauen.

Empfohlener unmittelbarer Start

Die nächste konkrete Umsetzung sollte diese Reihenfolge haben:

System-Inventory-Generator bauen.
Workflow-Katalog ausgeben.
Testmatrix für Workflow-Elemente und Workflow-Szenarien definieren.
Konvention für systemnahe Business-Workflow-Tests festlegen.
Erste Referenzimplementierung in brezel/api anlegen.

Definition of Done für Phase 1

Phase 1 ist abgeschlossen, wenn:

mindestens ein bestehendes System automatisch inventarisiert und zusammengefasst werden kann
Module und Workflows semantisch annotierbar sind
ein erster Explainability-Output vorliegt
die Workflow-Testpyramide dokumentiert und technisch begonnen ist
Framework- und Systemebene der Workflow-Tests in der Roadmap und im Code verankert sind