robsonprod/portfolio

Synchronisiert Delta-Spezifikationen aus einer Änderung mit den Hauptspezifikationen.

Dies ist eine agentengesteuerte Operation – du wirst Delta-Spezifikationen lesen und Hauptspezifikationen direkt bearbeiten, 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 nennt (ein Store ist ein eigenständiges OpenSpec-Repository, das auf diesem Rechner registriert ist) oder die Arbeit in einem lebt, führe openspec store list --json aus, um registrierte Store-IDs zu ermitteln, und übergib dann --store <id> bei den Befehlen, die Spezifikationen und Änderungen lesen oder schreiben (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Einmal ausgewählt, behandle --store <id> als persistent für den Rest des Workflows. Jedes nicht begrenzte Beispiel der folgenden Befehle ist eine Kurzform: Vor der Ausführung das Flag anhängen. Führe zum Beispiel openspec status --change "<name>" --json --store "<id>" aus, nicht die unbegrenzte Form unten. Andere Befehle akzeptieren das Flag nicht. Hinweise, die von Befehlen ausgegeben werden, enthalten das Flag bereits; behalte es bei Folgefragen. Ohne einen Store agieren Befehle im nächstgelegenen lokalen openspec/-Stammverzeichnis.

Projektprüfung: Diese Schritte erwarten ein Projekt, das bereits OpenSpec verwendet. Bevor der erste Schritt etwas schreibt (new change, archive, sync specs oder das Erstellen einer Artefaktdatei), bestätige, dass das Projekt ein Stammverzeichnis hat: Führe openspec list --json aus (mit --store <id>, wenn ein Store ausgewählt ist, da der Store dann das Stammverzeichnis ist) und lies root. Ein root-Objekt bedeutet, dass das Projekt eingerichtet ist. "root": null bedeutet, dass es nicht eingerichtet ist – es gibt hier kein openspec/-Verzeichnis, und ein Schreibbefehl wie openspec new change würde eines als Nebeneffekt erstellen. Der Befehl wird auch mit einem Nicht-Null-Exit-Code beendet, was eher diese Antwort darstellt als eine defekte CLI. Lese daher das JSON, anstatt es erneut zu versuchen oder zu umgehen.

Ein "root": null betrifft nicht die Einrichtung: Wenn eine status-Fehlermeldung mit Declared in oder Invalid store declaration in beginnt und die Datei openspec/config.yaml (oder config.yml) dieses Projekts nennt, dann verwendet das Projekt OpenSpec über einen Store, den es deklariert, den diese Maschine jedoch nicht auflösen kann (der Store ist nicht registriert oder die Zeile store: ist fehlerhaft). Behandle es nicht als nicht initialisiert und überspringe die folgenden Zweige: Halte vor dem Schreiben an und zeige dem Benutzer die message und den fix dieses Fehlers.

Andernfalls, ohne Stammverzeichnis, hängt das weitere Vorgehen davon ab, wie dieser Workflow erreicht wurde:

• Automatisch ausgewählt: Du hast diesen Workflow selbst gewählt, ohne dass der Benutzer OpenSpec genannt, diesen Skill benannt oder seinen Slash-Befehl ausgeführt hat. Stelle die Verwendung von OpenSpec ein und beantworte die Anfrage normal, wie du es ohne installiertes OpenSpec tun würdest. Bitte den Benutzer nicht, etwas einzurichten, und erwähne keine OpenSpec-Einrichtung.
• Explizite OpenSpec-Anfrage: Der Benutzer hat OpenSpec genannt, diesen Skill benannt oder seinen Slash-Befehl ausgeführt. Halte vor dem Schreiben an und frage, wie fortgefahren werden soll: Dieses Projekt einrichten (openspec init), einen bereits vorhandenen Store anvisieren (--store <id>), oder ohne OpenSpec für diese Anfrage fortfahren. Warte auf seine Antwort.

Erstelle in beiden Zweigen niemals das Stammverzeichnis als Nebeneffekt: Führe openspec init erst aus, wenn der Benutzer danach fragt, erstelle keine openspec/-Dateien von Hand und lasse keinen Befehl sie erstellen.

<capability-path> ist das Spezifikationsverzeichnis relativ zu specs/ (zum Beispiel user-auth oder identity/user-auth). Behalte den vollständigen Pfad aus jeder Delta-Spezifikation bei, wenn du ihre Hauptspezifikation auflöst.

Eingabe: Optional einen Änderungsnamen angeben. Falls nicht angegeben, prüfe, ob er aus dem Gesprächskontext abgeleitet werden kann. Bei vagen oder mehrdeutigen Angaben MUSST du nach verfügbaren Änderungen fragen.

Schritte

1. Die Änderung auswählen

   Wenn ein Name angegeben ist, verwende ihn. Andernfalls:

   • Leite aus dem Gesprächskontext ab, ob der Benutzer eine Änderung erwähnt hat
   • Automatisch auswählen, wenn nur eine aktive Änderung existiert
   • Bei Mehrdeutigkeit openspec list --json ausführen, um verfügbare Änderungen zu erhalten, und den Benutzer bitten, eine auszuwählen

   Frage nach Änderungen, die Delta-Spezifikationen haben (unter dem Verzeichnis specs/).

   Gib immer bekannt: "Verwende Änderung: " und wie man sie überschreibt (z. B. /opsx:sync <other>).

2. Änderungskontext auflösen

   Führe aus:

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

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

3. Delta-Spezifikationen finden

   Verwende artifactPaths.specs.existingOutputPaths aus dem Status-JSON als einzige Quelle für Delta-Spezifikationspfade. Wenn der Eintrag specs fehlt oder existingOutputPaths leer ist, melde, dass es keine zu synchronisierenden Delta-Spezifikationen gibt, leite sie nicht aus anderen Artefakten ab, und stoppe, ohne Artefaktanweisungen anzufordern oder eine Hauptspezifikation zu schreiben.

   Synchronisiere jeden Pfad in existingOutputPaths, es sei denn, der Aufrufer hat die Menge eingeschränkt. Ein Aufrufer schränkt sie ein, indem er eine explizite Liste vollständiger Einträge aus existingOutputPaths nennt – kopiere diese absoluten Werte wörtlich. Archive tut dies inline, und ein Benutzer kann es auch tun (z. B. durch Auswahl des Eintrags, der auf /specs/billing/invoices/spec.md endet). Synchronisiere dann nur die genannten Pfade und lasse die restlichen Delta-Spezifikationen unberührt: Bulk-Archive schließt eine Delta aus, deren Implementierung es nicht finden konnte, und das Synchronisieren würde trotzdem eine Hauptspezifikation schreiben, die der Aufrufer bewusst zurückgehalten hat. Trage diese eingeschränkte Auswahl durch Schritt 4; erweitere sie niemals wieder auf die vollständige Liste. Wenn ein benannter Pfad nicht in existingOutputPaths ist, synchronisiere ihn nicht – melde ihn und stoppe, anstatt ihn stillschweigend zu ignorieren. Wenn die benannte Liste leer ist, melde, dass es nichts zu synchronisieren gibt, und stoppe, ohne eine Hauptspezifikation zu schreiben.

   Jede Delta-Spezifikationsdatei enthält Abschnitte wie:

   • ## ADDED Requirements – Neue Anforderungen, die hinzugefügt werden sollen
   • ## MODIFIED Requirements – Änderungen an bestehenden Anforderungen
   • ## REMOVED Requirements – Anforderungen, die entfernt werden sollen
   • ## RENAMED Requirements – Anforderungen, die umbenannt werden sollen (FROM:/TO:-Format)

   Wenn keine Delta-Spezifikationen gefunden werden, informiere den Benutzer und stoppe.

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

   Vor dem ersten Schreiben in eine Hauptspezifikation einen aktuellen Spezifikationsregel-Schnappschuss abrufen:

   • Wenn Archive diesen Workflow inline aufgerufen und einen gültigen Schnappschuss von openspec instructions specs --change "<name>" --json bereitgestellt hat, verwende ihn erneut und hole dieselben Anweisungen nicht erneut.
   • Andernfalls führe diesen Befehl jetzt einmal mit denselben ausgewählten Stamm-Flags aus.
   • Wenn die direkte Abfrage mit einem Nicht-Null-Exit endet oder ungültiges Artefakt-Anweisungs-JSON zurückgibt, melde den Fehler und stoppe vor dem Schreiben einer Hauptspezifikation. Behandle den Fehler nicht als fehlendes Regelset.
   • Eine gültige Antwort mit ausgelassenem rules bedeutet, dass keine Artefaktregeln konfiguriert sind und der bestehende semantische Merge fortgesetzt wird.

   Wende die zurückgegebenen rules nur auf den Inhalt und die Form der durch diesen Merge erzeugten Hauptspezifikationen an. Artefaktregeln sind keine Betriebsanleitung und können ausgewählte Stammverzeichnisse, Delta-Pfade, CLI-Prüfungen oder Workflow-Schritte nicht ändern. Verwende ihren Text als Einschränkungen, 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 eingeschränkte Teilmenge, wenn ein Aufrufer eine bereitgestellt hat (diese können zu einem ausgewählten Store gehören, nicht zum Repository):

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

   b. Lies die Hauptspezifikation unter <planningHome.root>/openspec/specs/<capability-path>/spec.md (existiert möglicherweise noch nicht)

   Wenn sie noch nicht existiert (eine neue Fähigkeit), entspricht dem, was openspec archive tut: nur ADDED-Anforderungen dürfen angewendet werden – Schritt d erstellt die Spezifikation aus ihnen. MODIFIED und RENAMED haben keine Anforderung zum Handeln, stoppe daher die Synchronisation für diese Fähigkeit und berichte, dass ihre Hauptspezifikation nicht existiert und nur ADDED für eine neue Spezifikation zulässig ist; erfinde niemals die fehlende Anforderung. REMOVED hat nichts zu entfernen – überspringe es und warne.

   c. Wende Änderungen intelligent an:

   ADDED Requirements:

   • Wenn die Anforderung in der Hauptspezifikation nicht existiert → füge sie hinzu
   • Wenn die Anforderung bereits existiert → aktualisiere sie, um sie anzugleichen (behandle als implizites MODIFIED)

   MODIFIED Requirements:

   • Finde die Anforderung in der Hauptspezifikation
   • Wende die Änderungen an – dies kann sein:
     • Hinzufügen neuer Szenarien, die die Hauptspezifikation noch nicht hat
     • Modifizieren vorhandener Szenarien
     • Ändern der Anforderungsbeschreibung
   • Behalte Szenarien/Inhalte bei, die in der Delta nicht erwähnt werden

   REMOVED Requirements:

   • Entferne den gesamten Anforderungsblock aus der Hauptspezifikation
   • Die Fähigkeit zurückziehen. Lösche die gesamte spec.md – und das Verzeichnis, sobald nichts anderes mehr darin ist – nur, wenn ALLE diese Bedingungen zutreffen:
     1. Das Entfernen der Anforderungen in diesem Durchlauf hat keine Anforderungsblöcke hinterlassen;
     2. Der Rest der Spezifikation ist wohlgeformt (sie hat noch ein ## Purpose);
     3. Die Hauptspezifikation war vor dieser Synchronisation nicht bereits leer – wenn du nichts entfernt hast, ändere nichts;
     4. Jede andere nicht leere Zeile in der gesamten Datei ist als Titel, Purpose, Requirements-Überschrift oder eine kanonische Anforderungsaussage, Szenarien oder Codebelege erklärt;
     5. Die .openspec.yaml der Änderung deklariert retire_capabilities: true;
     6. Die spec.md liegt innerhalb des tatsächlichen Spezifikations-Stammverzeichnisses (folge keinem Fähigkeitsverzeichnis-Symlink, um eine externe Datei zu löschen). Wenn das Entfernen der ausgewählten Anforderungen keine Anforderungsblöcke hinterlassen würde und eine Ruhestandsbedingung nicht erfüllt ist, ändere die Hauptspezifikation nicht. Stoppe die Synchronisation für diese Fähigkeit, melde die blockierende Bedingung und teile dem Benutzer mit, wie er sie beheben kann. Schreibe oder hinterlasse niemals einen leeren Abschnitt ## Requirements. Wenn nur der Marker fehlt, sage auch das – es ist das eine, was der Benutzer hinzufügen kann, um den Ruhestand durchzuführen.
   • Das Löschen der Datei löscht auch ihr ## Purpose; jede andere Blockade verhindert den Ruhestand. Nenne Purpose, wenn du den Ruhestand meldest. Füge einen einfügungsfertigen git checkout nur bei, wenn die Spezifikation im Checkout des Aufrufers lebte; andernfalls gib checkout-übergreifende Wiederherstellungsanleitung.

   RENAMED Requirements:

   • Finde die FROM-Anforderung, benenne sie in TO um

   ## Purpose in der Delta:

   • Die Hauptspezifikation hat bereits eine und diese ist maßgeblich – lasse sie in Ruhe (das tut openspec archive; es warnt und fährt fort)

   d. Erstelle neue Hauptspezifikation, wenn die Fähigkeit noch nicht existiert:

   • Nur, wenn die Delta ADDED-Anforderungen zum Einfügen hat und keine MODIFIED- oder RENAMED-Anforderungen diese Fähigkeit in Schritt b blockiert haben. Andernfalls erstelle nichts und lasse das Spezifikationsverzeichnis unberührt. Bei einer REMOVED-only-Delta, wenn die .openspec.yaml der Änderung retire_capabilities: true deklariert, melde sie als bereits zurückgezogen und fahre fort, ohne die Spezifikation neu zu erstellen. Ohne diesen Marker melde die Synchronisation als blockiert: openspec archive lehnt sie mit Spec must have at least one requirement ab. Eine leere Delta hat keine Operationen zum Synchronisieren; melde sie ebenfalls als blockiert. Schreibe niemals einen leeren Abschnitt ## Requirements.
   • Erstelle <planningHome.root>/openspec/specs/<capability-path>/spec.md
   • Füge einen Purpose-Abschnitt hinzu: Kopiere den Text von ## Purpose der Delta wörtlich, wenn sie einen hat (das tut openspec archive); schreibe nur einen kurzen TBD-Platzhalter, wenn sie keinen hat
   • Füge einen Requirements-Abschnitt mit den ADDED-Anforderungen hinzu
   • Folge der Referenz zum Format der Hauptspezifikation unten

5. Aktualisierte Hauptspezifikationen validieren

   Führe openspec validate --specs mit denselben zuvor verwendeten ausgewählten Stamm-Flags aus. Wenn die Validierung fehlschlägt, melde die Probleme und behaupte nicht, dass die Synchronisation erfolgreich war.

6. Zusammenfassung anzeigen

   Nachdem alle Änderungen angewendet wurden, fasse zusammen:

   • 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 sie jetzt geschrieben wird, statt zu verweilen
   • Jede zurückgezogene Fähigkeit, nenne die gelöschte spec.md, ihren Purpose und entweder einen einfügungsfertigen git checkout oder checkout-übergreifende Wiederherstellungsanleitung

Referenz zum Format der Delta-Spezifikation

# Spec Delta

## Purpose

Nur in einer Delta, die eine brandneue Fähigkeit einführt. Sät die neue Hauptspezifikation.

## ADDED Requirements

### Requirement: New Feature
Das System SOLL etwas Neues tun.

#### Scenario: Basis-Fall
- **WENN** Benutzer X tut
- **DANN** tut System Y

## MODIFIED Requirements

### Requirement: Existing Feature
Das System SOLL das Bestehende weiterhin tun und jetzt auch A behandeln.

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

#### Scenario: Neues hinzuzufügendes Szenario
- **WENN** Benutzer A tut
- **DANN** tut System B

## REMOVED Requirements

### Requirement: Deprecated Feature

## RENAMED Requirements

- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`

Referenz zum Format der Hauptspezifikation

Hauptspezifikationen sind das, IN DAS die Delta zusammengeführt wird. Sie dürfen niemals Delta-Operationsköpfe enthalten (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) – nach der Synchronisation lebt jede Anforderung unter einem einzigen Abschnitt ## Requirements:

# <capability> Specification

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

## Requirements

### Requirement: New Feature
Das System SOLL etwas Neues tun.

#### Scenario: Basis-Fall
- **WENN** Benutzer X tut
- **DANN** tut System Y

Schlüsselprinzip: Intelligentes Zusammenführen

Im Gegensatz zum programmatischen Zusammenführen führst du intelligent zusammen, anstatt zu überschreiben:

• Ein MODIFIED-Block trägt 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.
• Behalte alles bei, was die Delta nicht erwähnt, in der bestehenden Reihenfolge der Hauptspezifikation
• Verwende die Abschnittsstrukturen der Hauptspezifikation als Grundordnung für ADDED-Blöcke