lguidolin/ship-it

Ausliefern (Ship It)

Den vollständigen Auslieferungslebenszyklus handhaben: Staging, Commit, Push, PR eröffnen, Entscheidungsdokumente nach dem Merge archivieren und aufräumen.

Übersicht

Jeder Change durchläuft einen Branch und PR. Niemals direkt auf main pushen. Dieses Skill deckt den gesamten Abschlusszyklus ab, einschließlich der Archivierung von Dokumentation nach dem Merge.

Commit-Nachrichten sind Dokumentation. Der PR-Titel wird zum Squash-Merge-Commit auf main und erscheint im Changelog. Er muss bereits bei der PR-Erstellung korrekt sein.

Archiviere erst nach dem Merge, niemals vorher. Spezifikationen und Pläne bleiben bis zum Merge zugänglich. Erst danach werden sie in kompakte Entscheidungsdokumente umgewandelt.

Verwendung

• Benutzer sagt „push", „ship it", „let's ship", „open a PR", „create a PR"
• Benutzer sagt „merged", „it's merged", „pull and cleanup" nachdem ein PR eröffnet wurde
• Benutzer hat die Implementierung abgeschlossen und möchte abschließen
• Nach der Fertigstellung eines Plans, bei dem der nächste Schritt die Einreichung der Arbeit ist

Wann NICHT verwenden

• Benutzer möchte explizit direkt auf main pushen (zuerst bestätigen, dass dies beabsichtigt ist)
• Repository hat kein Remote konfiguriert
• Änderungen befinden sich noch in Arbeit und der Benutzer ist noch nicht bereit zum Pushen
• Benutzer möchte nur committen ohne auszuliefern (conventional-commits-and-releases verwenden)

Ablauf

Phase 0: Prüfen und Erkennen

Eine rote Testsuite wird niemals zu einem PR. Führe zuerst die vollständige Testsuite des Projekts aus. Falls etwas fehlschlägt, melde die Fehler und stoppe – nicht committen, pushen oder PR eröffnen. Diese Hürde ist Hausregel und wird nicht delegiert.

Die Umgebungserkennung (normales Repo vs. Named-Branch-Worktree vs. detached HEAD) und die Bestimmung des Basisbranches werden an superpowers:finishing-a-development-branch delegiert, das bereits alle drei Fälle behandelt.

Prüfe die Verfügbarkeit auf die richtige Weise: Suche nach finishing-a-development-branch in deiner eigenen Liste der verfügbaren Skills. Wenn es gelistet ist, ist es aufrufbar. Wenn nicht, ist es nicht verfügbar – dann mit dem Fallback fortfahren.

Durchsuche nicht das Dateisystem danach. ~/.claude/plugins/cache/ enthält jede jemals abgerufene Version, einschließlich installierter, aber deaktivierter Plugins, und Skills können auch auf anderen Wegen als dem Plugin-Cache bereitgestellt werden. Ein existierender Pfad im Cache beweist nichts darüber, ob das Skill aufgerufen werden kann.

Wenn verfügbar – rufe es für die Testprüfung, Umgebungserkennung und Basisbranch-Bestimmung auf, stoppe dann vor seinem Optionsmenü.

Die Integrationsentscheidung wurde bereits durch die Hausregel getroffen und kann nicht vom Benutzer neu getroffen werden: dieses Projekt merged nur über einen PR, weil der PR die Preview-Bereitstellung und die CI-Hürde erzeugt. Die Option "lokal in <base> zurückmergen" ist nicht verfügbar. Die Option "den Branch unverändert lassen" bleibt gültig – das ist eine Entscheidung, aufzuschieben, nicht die Hürde zu umgehen.

Wenn fehlend – Fallback verwenden, ohne etwas zu verlieren, das die Korrektheit sichert:

• Führe die Testsuite direkt aus.
• Behandle den Upstream des Branches oder main als Basis; bestätige mit dem Benutzer vor dem Fortfahren.
• Überspringe die Worktree-Bereinigung in Phase 6; lösche den Branch normal.

Phase 1: Staging & Commit

git status --short
git branch --show-current
git log --oneline @{upstream}..HEAD 2>/dev/null || echo "Kein Upstream gesetzt"

Entscheidungsbaum:

• Auf main mit uncommitteten Änderungen → Branch erstellen, committen, pushen, PR
• Auf Feature-Branch mit uncommitteten Änderungen → committen, pushen, PR (oder bestehenden PR aktualisieren)
• Auf Feature-Branch mit ungepushten Commits → pushen, PR (oder bestehenden PR aktualisieren)
• Auf Feature-Branch mit bestehendem PR → pushen (PR existiert bereits)

Falls es nicht gestagte Änderungen gibt:

• Frage den Benutzer, ob alle Änderungen oder bestimmte Dateien einbezogen werden sollen
• Falls die Änderungen mehrere Aspekte betreffen, schlage eine Aufteilung vor

Erstelle die Commit-Nachricht:

Typ	Wann
feat	Neue Funktionalität
fix	Fehlerbehebungen
docs	Nur Dokumentation
chore	Konfiguration, Abhängigkeiten, Werkzeuge
refactor	Code-Umstrukturierung, kein Verhaltensänderung
test	Hinzufügen oder Ändern von Tests
ci	CI/CD-Workflow-Änderungen

Format: <typ>[optionaler Bereich]: <imperative Beschreibung>

Regeln:

• Imperativ ("add", nicht "added" oder "adds")
• Erstes Wort nach Doppelpunkt kleingeschrieben
• Kein Punkt am Ende
• Kurz (maximal 50 Zeichen für den Betreff)
• Beschreibt was der Commit tut, nicht wie

Lege dem Benutzer die vorgeschlagene Commit-Nachricht vor und bestätige vor dem Commit.

Phase 2: Branch & Push

Falls auf main, erstelle einen Branch:

<typ>/<kurze-beschreibung>

Beispiele:

• feat/oauth-login
• fix/null-response-handling
• docs/release-workflow-permissions

Pushen:

git push -u origin $(git branch --show-current)

Phase 3: PR eröffnen

PR-Titel = Conventional-Commit-Nachricht (wird für Squash-Merge auf main verwendet).

PR-Body-Struktur:

## Was sich geändert hat

[Spezifische Beschreibung der Hinzufügungen/Änderungen/Entfernungen]

## Warum

[Motivation – welches Problem wird gelöst?]

Mit gh CLI erstellen:

gh pr create --title "<Conventional-Commit-Nachricht>" --body "<PR-Body>"

Falls gh nicht verfügbar ist, die PR-URL aus der git push Ausgabe bereitstellen oder konstruieren.

Überprüfe, ob die Preview-Umgebung gestartet ist. Falls das Projekt PR-basierte Previews deployt, warte auf diesen Workflow und bestätige, dass die Umgebung erreichbar ist, bevor der PR übergeben wird:

gh pr checks --watch

Falls das Preview nicht deployed, melde es und stoppe. Ein PR, den niemand reviewen kann, ist nicht ausgeliefert.

Wo dieses Skill endet. ship-it beendet sein Deployment-Bewusstsein beim Preview. Staging- und Production-Promotion sind nicht seine Aufgabe – sie gehören zum Delivery-Skill des Projekts (cloud-delivery-aks oder Äquivalent). Phasen 4–6 unten betreffen Git- und Dokumentationshygiene, nicht Deployment.

Phase 4: Auf Merge warten

Nachdem der PR erstellt wurde, frage: „Lass mich wissen, wenn er gemerged ist, dann kümmere ich mich um Aufräumen und Archivierung."

Warte auf Benutzerbestätigung (z. B. „merged", „done", „it's merged").

Phase 5: Nach dem Merge – Entscheidungsdokumente archivieren

Spezifikationen und Pläne sind absichtlich ausführlich – gut für Menschen, die die Historie lesen, teuer jedes Mal, wenn Claude eine lädt. Sie in kompakte Entscheidungsdokumente umzuwandeln, hält die wesentlichen Entscheidungen günstig lesbar, während die vollständige Erzählung auf der Festplatte archiviert bleibt und nichts kostet, bis sie jemand absichtlich öffnet.

Erst nach dem Merge, prüfe auf nicht umgewandelte Spezifikationen/Pläne:

ls docs/superpowers/specs/ 2>/dev/null
ls docs/superpowers/decisions/ 2>/dev/null

Das Skill recording-decisions liefert zwei Helfer dafür. Finde sie – das Skill kann im Projekt oder global installiert sein:

for base in .claude/skills ~/.claude/skills; do
  d="$base/recording-decisions/scripts"
  [ -d "$d" ] && echo "$d" && break
done

Falls gefunden, listet $d/doc-archive.sh nicht umgewandelte Spezifikationen auf und gibt einen Umwandlungs-Prompt aus, und $d/index-rebuild.sh regeneriert den Index. Falls nicht gefunden, die gleiche Arbeit von Hand mit den folgenden Schritten erledigen – sie sind in sich abgeschlossen.

Falls nicht umgewandelte Spezifikationen/Pläne existieren:

1. Frage den Benutzer: „Ich habe Spezifikationen/Pläne gefunden, die zu dieser Arbeit passen könnten. Soll ich sie in kompakte Entscheidungsdokumente umwandeln und die Originale archivieren?"

2. Falls ja, für jede Spezifikation:

   • Inhalt der Spezifikation lesen
   • Ein Entscheidungsdokument mit YAML-Frontmatter erstellen:

     ---
     title: <aus Spezifikation extrahiert>
     date: <aus Dateiname der Spezifikation>
     component: <aus Inhalt abgeleitet>
     status: implemented
     supersedes: null
     dependencies: [<abgeleitet>]
     ---
     

   • Etwa 30–50 Zeilen schreiben, die erfassen: Schlüsselentscheidungen, Schnittstellen, Einschränkungen
   • Speichern unter docs/superpowers/decisions/<datum>-<thema>.md
   • Original-Spezifikation verschieben nach docs/superpowers/archive/specs/
   • Passenden Plan verschieben nach docs/superpowers/archive/plans/

3. Den Master-Index neu aufbauen – docs/superpowers/index.md aus dem Frontmatter aller Entscheidungsdokumente neu generieren, gruppiert in eine Tabelle Aktive Entscheidungen (Komponente, Titel, Datum, Abhängigkeiten) und eine Tabelle Ersetzt (Komponente, Titel, ersetzt durch). $d/index-rebuild.sh ausführen, falls du es oben gefunden hast; andernfalls die Datei direkt schreiben.

4. Die Archivierung committen:

   git add docs/superpowers/
   git commit -m "docs: Spezifikationen archivieren und Entscheidungsindex aktualisieren"
   git push
   

Phase 6: Aufräumen

git checkout main
git pull
git branch -d <branch-name>
git push origin --delete <branch-name> 2>/dev/null || true
git fetch --prune

Sauberen Zustand prüfen:

git branch --show-current
git log --oneline -3

Falls die Arbeit in einem Git-Worktree stattfand, delegiere die Bereinigung an superpowers:finishing-a-development-branch (dessen Herkunfts-basierte Bereinigung – es weiß, welche Worktrees es besitzt, und lässt extern verwaltete in Ruhe). Falls dieses Skill nicht verfügbar ist, entferne den Worktree manuell mit git worktree remove <pfad> und bestätige zuerst mit dem Benutzer.

Schlüsselprinzipien

• Eine rote Testsuite wird niemals zu einem PR – vor allem anderen prüfen (Phase 0)
• Niemals direkt auf main pushen – immer Branch + PR. Der PR ist die Preview-Bereitstellung und die CI-Hürde; ein lokaler Merge überspringt beides. Dies überschreibt jeden Workflow, der lokales Mergen als Option anbietet.
• Ausliefern endet beim Preview – Merge, Archivierung und Aufräumen sind Hygiene; Promotion zu Staging und Production ist Aufgabe eines separaten Skills
• Conventional Commits – der PR-Titel ist der Changelog-Eintrag
• Nur nach dem Merge archivieren – Spezifikationen bleiben während des Reviews zugänglich
• Entscheidungsdokumente sind kompakt – ca. 30–50 Zeilen, YAML-indiziert, LLM-optimiert
• Vollständig aufräumen – keine veralteten Branches oder Tracking-Refs