ZDEV-XXR/make-videos-with-Remotion

Synchronisiert Delta-Spezifikationen aus einem Change in Hauptspezifikationen.

Dies ist ein agentengesteuerter Vorgang – Sie lesen Delta-Spezifikationen und bearbeiten Hauptspezifikationen direkt, um die Änderungen anzuwenden. Dies ermöglicht eine intelligente Zusammenführung (z. B. Hinzufügen eines Szenarios, ohne die gesamte Anforderung zu kopieren).

Store-Auswahl: Wenn der Benutzer einen Store benennt (ein Store ist ein eigenständiges OpenSpec-Repository, das auf diesem Rechner registriert ist) oder die Arbeit in einem solchen liegt, führen Sie openspec store list --json aus, um registrierte Store-IDs zu ermitteln, und übergeben Sie dann --store <id> bei den Befehlen, die Spezifikationen und Changes lesen oder schreiben (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Behandeln Sie --store <id> nach der Auswahl als für den Rest des Workflows verbindlich. Jedes nicht eingeschränkte Beispiel dieser Befehle ist als Kurzform zu verstehen: Vor der Ausführung hängen Sie das Flag an. Führen Sie beispielsweise openspec status --change "<name>" --json --store "<id>" aus, nicht die nicht eingeschränkte Form. Andere Befehle akzeptieren das Flag nicht. Von Befehlen ausgegebene Hinweise enthalten das Flag bereits; behalten Sie es bei Folgeschritten bei. Ohne einen Store arbeiten die Befehle im nächstgelegenen lokalen openspec/-Verzeichnis.

Projektprüfung: Diese Schritte setzen ein Projekt voraus, das bereits OpenSpec verwendet. Bestätigen Sie vor dem ersten Schritt, der etwas schreibt (new change, archive, sync specs oder das Erstellen einer Artefaktdatei), dass das Projekt ein Wurzelverzeichnis hat: Führen Sie openspec list --json aus (mit --store <id>, wenn ein Store ausgewählt ist, da der Store dann das Wurzelverzeichnis ist) und lesen Sie root. Ein root-Objekt bedeutet, dass das Projekt eingerichtet ist. "root": null bedeutet, dass es nicht eingerichtet ist – es gibt kein openspec/-Verzeichnis, und ein Schreibbefehl wie openspec new change würde eines als Nebeneffekt erstellen. Der Befehl beendet sich auch mit einem Fehlercode ungleich Null, was die Antwort ist und nicht auf eine defekte CLI hinweist. Lesen Sie daher das JSON, anstatt es erneut zu versuchen oder zu umgehen.

Ein "root": null bezieht sich nicht auf die Einrichtung: Wenn eine Fehlermeldung von status mit Declared in oder Invalid store declaration in beginnt und die openspec/config.yaml (oder config.yml) dieses Projekts nennt, verwendet das Projekt OpenSpec über einen von ihm deklarierten Store, der auf diesem Rechner nicht aufgelöst werden kann (der Store ist nicht registriert oder die Zeile store: ist fehlerhaft). Behandeln Sie dies nicht als nicht initialisiert und überspringen Sie die unten stehenden Verzweigungen: Stoppen Sie vor dem Schreiben und zeigen Sie dem Benutzer die message und den fix dieses Fehlers an.

Andernfalls hängt das weitere Vorgehen bei fehlendem Wurzelverzeichnis davon ab, wie dieser Workflow erreicht wurde:

• Automatisch ausgewählt: Sie haben diesen Workflow selbst ausgewählt, ohne dass der Benutzer OpenSpec, diese Fertigkeit oder deren Slash-Befehl genannt hat. Stellen Sie die Verwendung von OpenSpec ein und beantworten Sie die Anfrage normal, wie Sie es ohne installiertes OpenSpec tun würden. Bitten Sie den Benutzer nicht um eine Einrichtung und erwähnen Sie keine OpenSpec-Einrichtung.
• Explizite OpenSpec-Anfrage: Der Benutzer hat OpenSpec, diese Fertigkeit oder deren Slash-Befehl genannt. Stoppen Sie vor dem Schreiben und fragen Sie, wie fortgefahren werden soll: das Projekt einrichten (openspec init), einen vorhandenen Store als Ziel angeben (--store <id>) oder ohne OpenSpec für diese Anfrage fortfahren. Warten Sie auf die Antwort des Benutzers.

Erstellen Sie in beiden Verzweigungen niemals das Wurzelverzeichnis als Nebeneffekt: Führen Sie openspec init nicht aus, bis der Benutzer danach fragt, erstellen Sie keine openspec/-Dateien von Hand und lassen Sie keinen Befehl es erstellen.

<capability-path> ist das Spezifikationsverzeichnis relativ zu specs/ (z. B. user-auth oder identity/user-auth). Behalten Sie den vollständigen Pfad aus jeder Delta-Spezifikation bei, wenn Sie deren Hauptspezifikation auflösen.

Eingabe: Optional einen Change-Namen angeben. Falls nicht angegeben, prüfen, ob er aus dem Gesprächskontext abgeleitet werden kann. Falls vage oder mehrdeutig, MÜSSEN Sie nach verfügbaren Changes fragen.

Schritte

1. Change auswählen

   Falls ein Name angegeben ist, diesen verwenden. Andernfalls:

   • Aus dem Gesprächskontext ableiten, falls der Benutzer einen Change erwähnt hat
   • Automatisch auswählen, falls nur ein aktiver Change existiert
   • Bei Mehrdeutigkeit openspec list --json ausführen, um verfügbare Changes zu erhalten, und den Benutzer bitten, einen auszuwählen

   Beim Auffordern die Changes anzeigen, die Delta-Spezifikationen haben (im Verzeichnis specs/).

   Immer ankündigen: "Verwende Change: " und wie überschrieben werden kann (z. B. /openspec-sync-specs <anderer>).

2. Change-Kontext auflösen

   Ausführen:

   openspec status --change "<name>" --json
   

   Das JSON enthält planningHome.root. Hauptspezifikationen befinden sich unter <planningHome.root>/openspec/specs/ – verwenden Sie dieses (Store-bewusste) Wurzelverzeichnis für jeden Hauptspezifikationspfad unten, nicht einen hartcodierten Repository-Pfad. Wenn ein Store ausgewählt ist, zeigt er auf den Store, nicht auf das aktuelle Repository.

3. Delta-Spezifikationen finden

   Verwenden Sie artifactPaths.specs.existingOutputPaths aus dem Status-JSON als einzige Quelle für Delta-Spezifikationspfade. Wenn der Eintrag specs fehlt oder existingOutputPaths leer ist, melden, dass keine Delta-Spezifikationen zum Synchronisieren vorhanden sind, diese nicht aus anderen Artefakten ableiten und ohne Aufforderung zur Artefaktanleitung oder Schreiben einer Hauptspezifikation stoppen.

   Jeden Pfad in existingOutputPaths synchronisieren, es sei denn, der Aufrufer hat die Menge eingegrenzt. Ein Aufrufer grenzt ein, indem er eine explizite Liste vollständiger Einträge aus existingOutputPaths nennt – kopieren Sie diese absoluten Werte wörtlich. Archivieren tut dies inline, und ein Benutzer kann es auch tun (z. B. durch Auswahl des Eintrags, der auf /specs/billing/invoices/spec.md endet). Dann nur die benannten Pfade synchronisieren und die verbleibenden Delta-Spezifikationen unberührt lassen: die Bulk-Archivierung schließt ein Delta aus, dessen Implementierung sie nicht finden konnte, und das Synchronisieren würde trotzdem eine Hauptspezifikation schreiben, die der Aufrufer bewusst zurückgehalten hat. Diese eingegrenzte Auswahl durch Schritt 4 tragen; niemals wieder auf die vollständige Liste erweitern. Wenn ein benannter Pfad nicht in existingOutputPaths ist, ihn nicht synchronisieren – melden und stoppen, anstatt ihn stillschweigend zu ignorieren. Wenn die benannte Liste leer ist, melden, dass es nichts zu synchronisieren gibt, und stoppen, ohne eine Hauptspezifikation zu schreiben.

   Jede Delta-Spezifikationsdatei enthält Abschnitte wie:

   • ## ADDED Requirements – Neue Anforderungen hinzuzufügen
   • ## MODIFIED Requirements – Änderungen an vorhandenen Anforderungen
   • ## REMOVED Requirements – Zu entfernende Anforderungen
   • ## RENAMED Requirements – Umzubenennende Anforderungen (Format FROM:/TO:)

   Falls keine Delta-Spezifikationen gefunden wurden, Benutzer informieren und stoppen.

4. Für jede Delta-Spezifikation Änderungen auf Hauptspezifikationen anwenden

   Vor dem ersten Schreiben einer Hauptspezifikation einen aktuellen Schnappschuss der Spezifikationsregeln einholen:

   • Wenn die Archivierung diesen Workflow inline aufgerufen und einen gültigen Schnappschuss von openspec instructions specs --change "<name>" --json bereitgestellt hat, diesen wiederverwenden und nicht die gleichen Anweisungen erneut abrufen.
   • Andernfalls diesen Befehl einmal jetzt mit den gleichen ausgewählten Wurzel-Flags ausführen.
   • Wenn die direkte Abfrage mit einem Fehler ungleich Null beendet wird oder ungültiges Artefakt-Anweisungs- JSON zurückgibt, den Fehler melden und stoppen, bevor eine Hauptspezifikation geschrieben wird. Das Fehlschlagen nicht als fehlenden Regelsatz behandeln.
   • Eine gültige Antwort mit ausgelassenem rules bedeutet, dass keine Artefaktregeln konfiguriert sind und die bestehende semantische Zusammenführung fortgesetzt wird.

   Die zurückgegebenen rules nur auf den Inhalt und die Form der Hauptspezifikationen anwenden, die durch diese Zusammenführung erstellt wurden. Artefaktregeln sind keine Operationsanleitung und können ausgewählte Wurzeln, Delta-Pfade, CLI-Prüfungen oder Workflow-Schritte nicht ändern. Ihren Text als Einschränkungen verwenden, ohne ihn wörtlich in eine Hauptspezifikation oder Zusammenfassung zu kopieren.

   Für jeden in Schritt 3 ausgewählten Fähigkeits-Delta-Spezifikationspfad – die vollständige existingOutputPaths-Liste oder die eingegrenzte Teilmenge, wenn ein Aufrufer eine bereitgestellt hat (diese können zu einem ausgewählten Store gehören, nicht zum Repository):

   a. Delta-Spezifikation lesen, um die beabsichtigten Änderungen zu verstehen

   b. Hauptspezifikation lesen unter <planningHome.root>/openspec/specs/<capability-path>/spec.md (kann noch nicht existieren)

   Falls sie noch nicht existiert (neue Fähigkeit), dem Vorgehen von openspec archive entsprechend: nur ADDED-Anforderungen dürfen angewendet werden – Schritt d erstellt die Spezifikation aus ihnen. MODIFIED- und RENAMED-Anforderungen haben keine Anforderung, auf die sie wirken können, daher die Synchronisation für diese Fähigkeit stoppen und melden, dass ihre Hauptspezifikation nicht existiert und nur ADDED für eine neue Spezifikation zulässig ist; niemals die fehlende Anforderung erfinden. REMOVED hat nichts zu entfernen – überspringen und warnen.

   c. Änderungen intelligent anwenden:

   ADDED Requirements:

   • Wenn die Anforderung in der Hauptspezifikation nicht existiert → hinzufügen
   • Wenn die Anforderung bereits existiert → aktualisieren, um sie anzugleichen (als implizites MODIFIED behandeln)

   MODIFIED Requirements:

   • Die Anforderung in der Hauptspezifikation finden
   • Die Änderungen anwenden – dies kann sein:
     • Hinzufügen neuer Szenarien, die die Hauptspezifikation noch nicht hat
     • Ändern vorhandener Szenarien
     • Ändern der Anforderungsbeschreibung
   • Szenarien/Inhalte beibehalten, die nicht in der Delta-Spezifikation erwähnt werden

   REMOVED Requirements:

   • Den gesamten Anforderungsblock aus der Hauptspezifikation entfernen
   • Die Fähigkeit außer Dienst stellen. Die gesamte spec.md löschen – und das Verzeichnis, sobald nichts anderes mehr darin ist – nur wenn ALLE diese Bedingungen erfüllt sind:
     1. Das Entfernen der Anforderungen dieses Durchlaufs hat keine Anforderungsblöcke hinterlassen;
     2. Der Rest der Spezifikation ist wohlgeformt (sie hat noch einen ## Purpose);
     3. Die Hauptspezifikation war vor dieser Synchronisation nicht bereits leer – wenn nichts entfernt wurde, nichts ändern;
     4. Jede andere nicht leere Zeile in der gesamten Datei ist als Titel, Purpose, Requirements-Header oder kanonische Anweisungs-, Szenarien- oder eingefasste Beispiele einer Anforderung erfasst;
     5. Die .openspec.yaml des Changes deklariert retire_capabilities: true;
     6. Die spec.md befindet sich innerhalb des echten Spezifikationswurzelverzeichnisses (einem Fähigkeitsverzeichnis-Symlink nicht folgen, um eine externe Datei zu löschen). Wenn das Entfernen der ausgewählten Anforderungen keine Anforderungsblöcke hinterlassen würde und eine Stilllegungsbedingung nicht erfüllt ist, die Hauptspezifikation nicht ändern. Die Synchronisation für diese Fähigkeit stoppen, die blockierende Bedingung melden und dem Benutzer sagen, wie sie aufgelöst werden kann. Niemals einen leeren Abschnitt ## Requirements schreiben oder hinterlassen. Wenn nur der Marker fehlt, dies auch sagen – es ist die eine Sache, die der Benutzer hinzufügen kann, um die Stilllegung durchzuführen.
   • Das Löschen der Datei löscht auch den ## Purpose; jeder andere Abschnitt blockiert die Stilllegung. Den Purpose nennen, wenn die Stilllegung gemeldet wird. Einen einfügbaren git checkout nur dann angeben, wenn die Spezifikation im Checkout des Aufrufers lebte; andernfalls Checkout-bezogene Wiederherstellungsanleitung geben.

   RENAMED Requirements:

   • Die FROM-Anforderung finden, in TO umbenennen

   ## Purpose in der Delta-Spezifikation:

   • Die Hauptspezifikation hat bereits einen und dieser ist maßgeblich – ihn unverändert lassen (das tut openspec archive; es warnt und fährt fort)

   d. Neue Hauptspezifikation erstellen, falls die Fähigkeit noch nicht existiert:

   • Nur wenn die Delta-Spezifikation ADDED-Anforderungen enthält, die hineingeschrieben werden sollen, und keine MODIFIED- oder RENAMED-Anforderungen diese Fähigkeit in Schritt b blockiert haben. Andernfalls nichts erstellen und das Spezifikationsverzeichnis unberührt lassen. Für ein nur-REMOVED-Delta, wenn die .openspec.yaml des Changes retire_capabilities: true deklariert, als bereits stillgelegt melden und fortfahren, ohne die Spezifikation neu zu erstellen. Ohne diesen Marker die Synchronisation als blockiert melden: openspec archive lehnt es mit Spec must have at least one requirement ab. Ein leeres Delta hat keine Operationen zum Synchronisieren; es ebenfalls als blockiert melden. Niemals einen leeren Abschnitt ## Requirements schreiben.
   • <planningHome.root>/openspec/specs/<capability-path>/spec.md erstellen
   • Purpose-Abschnitt hinzufügen: den ## Purpose-Text der Delta-Spezifikation wörtlich kopieren, wenn sie einen hat (das tut openspec archive); nur einen kurzen TBD-Platzhalter schreiben, wenn sie keinen hat
   • Requirements-Abschnitt mit den ADDED-Anforderungen hinzufügen
   • Das Hauptspezifikationsformat-Referenz unten befolgen

5. Aktualisierte Hauptspezifikationen validieren

   openspec validate --specs mit den gleichen ausgewählten Wurzel-Flags wie zuvor ausführen. Wenn die Validierung fehlschlägt, die Probleme melden und nicht behaupten, dass die Synchronisation erfolgreich war.

6. Zusammenfassung anzeigen

   Nach dem Anwenden aller Änderungen zusammenfassen:

   • Welche Fähigkeiten aktualisiert wurden
   • Welche Änderungen vorgenommen wurden (Anforderungen hinzugefügt/geändert/entfernt/umbenannt)
   • Jede neue Hauptspezifikation, die mit einem TBD-Purpose-Platzhalter hinterlassen wurde, damit dieser jetzt geschrieben wird und nicht verweilt
   • Jede stillgelegte Fähigkeit, unter Nennung der gelöschten spec.md, ihres Purposes und entweder eines einfügbaren git checkout oder einer Checkout-bezogenen Wiederherstellungsanleitung

Referenz zum Delta-Spezifikationsformat

# Spec Delta

## Purpose
Nur bei einem Delta, das eine brandneue Fähigkeit einführt. Befüllt die neue Hauptspezifikation.

## ADDED Requirements

### Requirement: Neue Funktion
Das System SOLL etwas Neues tun.

#### Scenario: Basisfall
- **WHEN** Benutzer tut X
- **THEN** System tut Y

## MODIFIED Requirements

### Requirement: Vorhandene Funktion
Das System SOLL die vorhandene Sache weiterhin tun, jetzt aber auch A behandeln.

#### Scenario: Szenario, das die Hauptspezifikation bereits hat
- **WHEN** Benutzer tut X
- **THEN** System tut Y

#### Scenario: Neues Szenario zum Hinzufügen
- **WHEN** Benutzer tut A
- **THEN** System tut B

## REMOVED Requirements

### Requirement: Veraltete Funktion

## RENAMED Requirements

- FROM: `### Requirement: Alter Name`
- TO: `### Requirement: Neuer Name`

Referenz zum Hauptspezifikationsformat

Hauptspezifikationen sind das Ziel der Delta-Zusammenführung. Sie dürfen niemals Delta-Operationsüberschriften enthalten (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) – nach der Synchronisation lebt jede Anforderung unter einem einzigen Abschnitt ## Requirements:

# <Fähigkeit> Spezifikation

## Purpose
Kurze Beschreibung, was diese Fähigkeit tut und warum sie existiert.

## Requirements

### Requirement: Neue Funktion
Das System SOLL etwas Neues tun.

#### Scenario: Basisfall
- **WHEN** Benutzer tut X
- **THEN** System tut Y

Wichtigstes Prinzip: Intelligente Zusammenführung

Anders als programmatische Zusammenführung führen Sie zusammen, anstatt zu überschreiben:

• Ein MODIFIED-Block enthält die gesamte Anforderung – Körper plus jedes Szenario, das die Änderung überlebt. openspec validate und openspec archive lehnen beide einen ab, der ein Szenario fallen lässt, das die Hauptspezifikation noch hat.
• Alles, was die Delta-Spezifikation nicht erwähnt, in der vorhandenen Anordnung der Hauptspezifikation belassen.
• Ein RENAMED-Block ändert nur den Header; die Anforderung und Szenarien bleiben unverändert.
• Ein REMOVED-Block entfernt die gesamte Anforderung und löst bei Bedingungserfüllung die Dateilöschung aus.

Objekt-ID-Behandlung

Wenn eine id:-Zeile im Requrements-Header einer Hauptspezifikation vorhanden ist, diese Zeile unverändert lassen – die Zusammenführung fügt eine ID zu einer Anforderung hinzu, wenn die Hauptspezifikation noch keine hat (sie aus der Delta-Spezifikation kopieren, falls vorhanden), und schreibt sie in Schritt 4.a immer in neue Anforderungen. Nur id: bearbeiten; andere YAML-Felder werden nicht geändert.

Formatierung: Auslassungspunkte nicht schreiben

Wenn die Delta-Spezifikation Auslassungspunkte (...) als Inhalt enthält, werden diese als wörtliche drei Punkte behandelt und in die Hauptspezifikation eingefügt – keine implizite Handlung. Wenn die Delta-Spezifikation einen ## Purpose-Abschnitt mit Auslassungspunkten allein enthält, wird dieser wörtlich kopiert; schreiben Sie stattdessen einen TBD-Platzhalter (unter Schritt 4.d).

Formatierung: Platzhalter nicht entfernen

Wenn die Hauptspezifikation einen TBD- oder TODO-Platzhalter enthält und die Delta-Spezifikation diesen Abschnitt nicht ändert, den Platzhalter unverändert lassen.

Entfernen von id:-Zeilen

Die Zusammenführung entfernt keine id:-Zeilen – weder aus vorhandenen Anforderungen noch aus den von Schritt 4.d erstellten neuen Spezifikationen. Wenn die Delta-Spezifikation eine id:-Zeile hat, wird sie kopiert; wenn nicht, wird die vorhandene ID beibehalten.

Vermeidung von Leerraumänderungen

Die Zusammenführung führt keine Leerraum- oder Formatierungsänderungen an Hauptspezifikationen durch, es sei denn, die Delta-Spezifikation nimmt explizit solche Änderungen vor. Absätze werden nicht neu umbrochen, Einrückungen nicht angepasst und aufeinanderfolgende Leerzeilen nicht konsolidiert.

Formatierung konsistent halten

Beim Erstellen neuer Abschnitte (Anforderungen oder Szenarien) das Format der vorhandenen Hauptspezifikation befolgen. Die Hauptspezifikation als primäre Quelle der Wahrheit für Formatierung verwenden und nur dann vom Delta-Stil abweichen, wenn es die Konsistenz erfordert.

Benachrichtigung des Benutzers

Wenn eine Entscheidung die Änderung einer Hauptspezifikation erfordert, die automatisch nicht aufgelöst werden kann, die Benachrichtigung als Teil der Zusammenfassung einschließen. Wenn der Benutzer eine eingegrenzte Liste von Delta-Pfaden angibt, die Synchronisation für diese Pfade wie beschrieben durchführen und die unbeaufsichtigten Deltas in der Zusammenfassung erwähnen.

Workflow-Fluss

Der Workflow besteht aus sechs Schritten: Auswahl des Changes, Auflösen des Change-Kontexts, Finden von Delta-Spezifikationen, Anwenden von Änderungen, Validieren der aktualisierten Hauptspezifikationen und Anzeigen einer Zusammenfassung. Die Schritte sind sequentiell und abhängig voneinander; keine Schritte überspringen, es sei denn, eine Bedingung verhindert dies (z. B. keine Delta-Spezifikationen gefunden).

Fehlerbehandlung

Wenn ein Schritt fehlschlägt (z. B. kann der Change nicht gefunden werden, Delta-Spezifikationen existieren nicht, Validierung fehlschlägt), den Fehler dem Benutzer melden, den Workflow anhalten und keine weiteren Schritte ausführen. Keine Hauptspezifikation schreiben, wenn eine Validierung fehlschlägt.

Benutzerführung

Wenn der Benutzer unsicher ist, welchen Change er verwenden soll, Eingabeaufforderungen mit verfügbaren Changes anzeigen, die Delta-Spezifikationen haben. Wenn der Benutzer eine Liste von Delta-Pfaden angibt, diese als Einschränkung der synchronisierten Deltas behandeln.