OpenSpec Merge

Was macht OpenSpec Merge?

Fasst mehrere zusammenhängende Fähigkeitsordner in openspec/specs/ zu einer einzigen Haupt-Feature-Spezifikation zusammen, über einen zweistufigen genehmigten Workflow. Es wird nie etwas unter openspec/specs/<capability>/ geändert, bis ein Mensch die Zusammenführung explizit genehmigt hat.

Wann dieses Skill anzuwenden ist

Der OpenSpec-Archivierungs-Workflow synchronisiert Deltas in openspec/specs/<capability>/spec.md pro Änderung. Wenn zusammenhängende Änderungen unter verschiedenen Fähigkeitsnamen archiviert werden (oft weil sie stufenweise gebaut wurden, z. B. user-show, user-detail, user-permissions), hat man mehrere Spezifikationsordner, die funktional ein einziges Feature beschreiben. Dieses Skill führt diese über einen Staging-Bereich zusammen, der eine menschliche Freigabe erfordert, bevor etwas Reales ersetzt wird.

Die zwei Phasen

• Phase A — Staging: Quell-Spezifikationen lesen, einen Merge-Entwurf in openspec/specs/.merged-specs/<feature>/spec.md mit Approved-by-human: no schreiben. Sonst ändert sich nichts.
• Phase B — Anwenden: Wird ausgelöst, sobald der Benutzer das Frontmatter auf Approved-by-human: yes gesetzt hat. Ersetzt die Quellordner mit dem genehmigten Inhalt und entfernt die Staging-Datei.

Immer erkennen, welche Phase zutrifft: Wenn openspec/specs/.merged-specs/<feature>/ bereits existiert, zuerst das Approved-by-human-Feld prüfen, anstatt von Grund auf neu zu stagen.

Phase A — Staging

1. Kandidatenordner identifizieren

openspec/specs/* auflisten und nach Ordnern suchen, die:

• Einen gemeinsamen Namenspräfix oder -bereich (user-show, user-detail, user-permissions) teilen
• Dieselbe Entität/Ressource in ihren Anforderungen referenzieren (gleiches Modell, gleiche API-Endpunkte, gleiche UI-Seite)
• Zeitlich nahe beieinander archiviert wurden (Daten in openspec/changes/archive/ prüfen)

Wenn der Benutzer bestimmte Ordner explizit genannt hat, diese verwenden, anstatt zu raten.

Wenn mehr als eine plausible Gruppierung existiert, anhalten und den Benutzer fragen, welche Ordner zusammengehören, bevor etwas gestaged wird.

2. Jede Kandidaten-spec.md vollständig lesen

Für jeden Ordner die gesamte spec.md lesen, nicht nur die Überschriften. Anforderungsnamen, Szenarien, Markierungen für Veraltetes und alles notieren, was wie eine Änderung/Ersetzung einer Anforderung in einem anderen Kandidatenordner aussieht.

3. Den Ziel-Fähigkeitsnamen ableiten

Aus dem gemeinsamen Präfix oder dem gemeinsamen Bereichsnamen der Kandidatenordner ableiten (z. B. user-show + user-detail + user-permissions → user, oder user-management, falls das natürlicher klingt).

• Klarer gemeinsamer Präfix/Bereich → verwenden, nicht fragen.
• Kein offensichtlicher gemeinsamer Name (z. B. checkout-flow und invoice-export nur durch ein vages "Abrechnungs"-Thema verbunden) → den Benutzer bitten, den Ziel-Fähigkeitsnamen vor dem Fortfahren zu nennen.

Den abgeleiteten Namen explizit in der Ausgabe nennen, damit der Benutzer ihn überschreiben kann.

4. Die Anforderungen zusammenführen

Regeln, in der Reihenfolge:

• Vereinigung der HINZUGEFÜGTEN Anforderungen: Jede eindeutige Anforderung aus jedem Quellordner wird behalten.
• Konfliktierende/doppelte Anforderungen (gleicher Name oder gleiches Verhalten doppelt beschrieben): Die vollständigste/aktuellste Version behalten, nicht widersprechende Details zusammenführen, anstatt eine stillschweigend zu verwerfen.
• ENTFERNTE/veraltete Anforderungen: Aus der zusammengeführten Spezifikation ausschließen.
• Niemals Anforderungen erfinden. Ambiguitäten oder Widersprüche inline markieren (z. B. <!-- KONFLIKT: Quelle A sagt X, Quelle B sagt Y — benötigt menschliche Entscheidung -->) anstatt stillschweigend eine auszuwählen.
• Originalszenariotext nach Möglichkeit beibehalten; Prosa nur umschreiben, wenn zwei überlappende Anforderungen zu einer zusammengeführt werden.

5. Die Staging-Datei schreiben

Schreiben nach:

openspec/specs/.merged-specs/<abgeleiteter-name>/spec.md

Mit folgendem Frontmatter am Anfang:

---
Approved-by-human: no
merged-from:
  - user-show
  - user-detail
  - user-permissions
---

Gefolgt vom Inhalt der zusammengeführten Spezifikation.

6. Dem Benutzer kurz mitteilen

• Welche Quellordner zusammengeführt wurden und der abgeleitete Zielname
• Alle Konflikte, die inline markiert wurden und eine Entscheidung benötigen
• Was genau als nächstes zu tun ist: openspec/specs/.merged-specs/<abgeleiteter-name>/spec.md öffnen, überprüfen, ggf. bearbeiten und im Frontmatter Approved-by-human: yes setzen, sobald zufrieden
• Dass noch nichts unter openspec/specs/<capability>/ geändert wurde

Phase B — Anwenden

Auslöser: Der Benutzer bittet um Anwendung/Finalisierung eines Merges, oder Sie stellen fest, dass openspec/specs/.merged-specs/<feature>/spec.md Approved-by-human: yes gesetzt hat.

1. Die Staging-Datei erneut lesen und Approved-by-human: yes bestätigen. Wenn es noch no ist, anhalten und dem Benutzer mitteilen, dass zuerst eine Genehmigung erforderlich ist — nicht anwenden.
2. merged-from aus dem Frontmatter lesen, um zu wissen, welche Quellordner ersetzt werden sollen.
3. Das Frontmatter aus dem Staging-Inhalt entfernen (beide Felder), sodass eine saubere spec.md ohne Frontmatter übrig bleibt.
4. Die Quellordner durch das zusammengeführte Ergebnis ersetzen:
   • openspec/specs/<abgeleiteter-name>/spec.md mit dem vom Frontmatter befreiten Inhalt erstellen/überschreiben.
   • Die anderen Quellordner aus merged-from entfernen, die nicht der Zielname selbst sind.
5. Den Staging-Ordner openspec/specs/.merged-specs/<abgeleiteter-name>/ entfernen.
6. Dem Benutzer bestätigen, was ersetzt/entfernt wurde, damit es leicht mit git diff vor dem Commit überprüft werden kann.

Schritt 4 niemals ohne ein explizites Approved-by-human: yes in der Datei ausführen — den Benutzer nicht bitten, verbal im Chat zuzustimmen; die Genehmigung muss das geänderte Frontmatter-Feld selbst sein.

Beispiel

Phase A — Eingabe: openspec/specs/user-show/, openspec/specs/user-detail/, openspec/specs/user-permissions/ — alle beschreiben verschiedene Aspekte desselben Benutzerprofil-Features.

Ausgabe: openspec/specs/.merged-specs/user/spec.md:

---
Approved-by-human: no
merged-from:
  - user-show
  - user-detail
  - user-permissions
---

# User

## Anforderung: ...
...

Nachricht an den Benutzer: zusammengeführt aus user-show, user-detail, user-permissions in die abgeleitete Fähigkeit user (Ordner umbenennen, falls user-management bevorzugt wird); keine Konflikte gefunden; openspec/specs/.merged-specs/user/spec.md überprüfen und Approved-by-human: yes setzen, wenn bereit.

Phase B — Sobald der Benutzer Approved-by-human: yes setzt und um Anwendung bittet: openspec/specs/user/spec.md wird mit dem frontmatterfreien, zusammengeführten Inhalt erstellt/überschrieben, user-show/, user-detail/, user-permissions/ werden entfernt und openspec/specs/.merged-specs/user/ wird gelöscht.