davidvictor/build-in-public

Build in Public

Übersicht

Verwende diesen Skill, wenn das Projekt bereits funktioniert und es darum geht, es präsentabel, sicher und öffentlich nutzbar zu machen. Das Standardziel ist ein Sandbox-Repository unter ~/.codex/workspaces/default/repos/ oder ~/.codex/workspaces/default/labs/, aber der Workflow funktioniert für jedes lokale Repository.

Ressourcen

• references/public-release-checklist.md Wird für das Public-Release-Gate und den finalen Abschlussdurchgang verwendet.
• references/readme-template.md Wird beim Schreiben oder Umstrukturieren der README.md verwendet.
• scripts/create_release_zip.sh Wird verwendet, um ein sauberes ZIP aus dem aktuellen HEAD zu erstellen, nachdem das Repository bereit ist.

Native Codex-Funktionen

Wenn der Host native Codex-App- oder CLI-Funktionen bereitstellt, verwende sie als Beschleuniger, ohne sie zu harten Abhängigkeiten zu machen:

• Verwende die Websuche für aktuelle Fakten zu Veröffentlichungsplattformen, Paketmanager-Verhalten, Sicherheitswarnungen oder Dokumentationen, die sich geändert haben könnten. Bevorzuge Primärquellen und zitiere sie im Abschlussbericht.
• Verwende die integrierte Bildgenerierung für projektgebundene README-Visuals, wenn ein Repo-Map, Architekturdiagramm, Banner oder eine veranschaulichende Grafik das Projekt verständlicher macht. Generiere das Bild, überprüfe es, kopiere die endgültige ausgewählte Datei unter assets/ in das Repository, füge sie an der richtigen narrativen Stelle in die README ein, verwende beschreibenden Alternativtext und behalte kritische technische Beschriftungen in Markdown, Mermaid, SVG oder nahem Prosa bei, wenn generierter Text nicht perfekt ist.
• Verwende den In-App-Browser für lokale Webvorschauen, dateibasierte Vorschauen und visuelle Überprüfungen öffentlicher Seiten, die keine Anmeldung erfordern.
• Verwende Computer Use nur für enge GUI-Überprüfungen, wenn das Projekt eine Desktop-App, ein Simulator-Workflow, eine Tabellenkalkulation, ein Dokument oder eine andere Oberfläche ist, die nicht durch normale Shell-/Browser-Tools überprüft werden kann.
• Verwende Codex-App-Worktrees für isolierte explorative oder parallele Release-Vorbereitungsarbeiten und übernehme dann nur die beabsichtigten Dateien in den Veröffentlichungszweig.
• Verwende native Git-Review, Staging, Commit, Push und PR-Unterstützung, wenn verfügbar, überprüfe aber trotzdem den Diff und halte den Arbeitsbaum frei von nicht zusammenhängenden lokalen Zuständen.
• Verwende Automatisierungen nur für wiederkehrende Release-Gesundheitschecks, geplante Wartungsberichte oder Folgemaßnahmen; mache einmalige Veröffentlichungsentscheidungen nicht zu wiederkehrenden Hintergrundarbeiten.
• Verwende native Unteragenten nur, wenn der Benutzer oder die Host-Richtlinie parallele Delegation zulässt, und teile unabhängige Aufgaben wie Risiko-Audit, Dokumentationsreview und Verifizierung auf, ohne sich überschneidende Dateibesitzverhältnisse.

Standardergebnis

Am Ende dieses Skills sollte das Repository haben:

• eine README, die das Problem, den Grund für die Erstellung, die Funktionsweise und die Nutzung klar erklärt
• ein optionales projektgebundenes Diagramm oder visuelles Asset, wenn es die Orientierung eines fremden Lesers wesentlich verbessert
• eine saubere öffentliche Beschreibung und vorgeschlagene GitHub-Themen
• grundlegende Härtung für Setup, Fehler, ignorierte Dateien und benutzerseitige Standardeinstellungen
• Tests oder Smoke-Checks, die den Hauptpfad und mindestens einen Rand- oder Fehlerfall beweisen
• eine Lizenz und eine Beispielkonfiguration, wo nötig
• ein sauberes ZIP-Artefakt aus dem committeten Code
• entweder ein öffentliches GitHub-Repository im persönlichen Profil des Benutzers oder einen genauen Blockergrund, warum die Veröffentlichung warten sollte

Release-Strategie

Wähle vor dem Bearbeiten den sichereren Pfad:

1. Verwende das bestehende Repository wieder, wenn seine Git-Historie, Dateimenge und Benennung bereits sicher zu veröffentlichen sind.
2. Erstelle ein sauberes Public-Export-Repository, wenn das funktionierende Projekt gut ist, aber das bestehende Repository eine chaotische Historie, private Notizen, experimentelle Überreste oder Geheimnisse in der Historie hat.

Regeln:

• Bevorzuge für Sandbox-Projekte ein benachbartes öffentliches Repository unter ~/.codex/workspaces/default/repos/<slug>-public, wenn die öffentliche Historie fragwürdig ist.
• Bewahre die Herkunft in einer kurzen Notiz, aber gib keine privaten Pfade, internen Projektnamen oder persönlichen Maschinendetails preis.
• Wenn eine Historie-Umschreibung erforderlich wäre, um das aktuelle Repository sicher zu machen, bevorzuge einen frischen öffentlichen Export, es sei denn, der Benutzer möchte explizit die Historie erhalten.
• Veröffentliche nichts, bis das Repository für einen Fremden bei einem sauberen Klon verständlich ist.

Workflow

1. Preflight

1. Überprüfe das Ziel-Repository, Remotes, Git-Status, Build-System, Test-Befehle und jede AGENTS.md im Geltungsbereich.

2. Lies references/public-release-checklist.md.

3. Lies references/readme-template.md, wenn die README erstellt oder neu geschrieben werden muss.

4. Entscheide, ob du vor Ort härten oder ein sauberes Public-Export-Repository erstellen möchtest.

5. Leite den wahrscheinlichen öffentlichen Namen, die einzeilige Beschreibung, den Installationsablauf und die Zielgruppe aus dem Repository selbst ab. Frage nur, wenn diese wirklich mehrdeutig sind.

6. Setze das Standardveröffentlichungsziel auf das persönliche GitHub des Benutzers mit öffentlicher Sichtbarkeit, wenn die Anfrage "Build in Public" lautet.

7. Überprüfe, welche nativen Codex-Funktionen in der aktuellen Umgebung verfügbar sind, und wähle dann den leichtesten nützlichen Pfad: lokale Shell für deterministische Repository-Arbeit, Websuche für aktuelle externe Fakten, Browser/Computer Use für UI-Verifizierung, Bildgenerierung für hilfreiche Visuals und Worktrees/Unteragenten nur, wenn sie den Durchsatz sicher verbessern.

8. Frage nach dem Funken. Bevor du etwas schreibst, lies den Code tief genug, um drei plausible Hypothesen zu bilden, warum dies gebaut wurde. Frage dann den Benutzer – präsentiere deine drei besten Vermutungen als Optionen, plus ein Freitextfeld für etwas ganz anderes:

   Was war der Moment, der dich dazu gebracht hat, das zu bauen?

   1. [Deine erste Hypothese, aus dem Code abgeleitet]
   2. [Deine zweite Hypothese]
   3. [Deine dritte Hypothese]
   4. Etwas anderes – sag es mir in deinen eigenen Worten

   Dieses Muster gilt für jeden AskUserQuestion-Aufruf in diesem Skill: schlage immer drei konkrete Optionen basierend auf dem vor, was du bereits gelesen hast, und lasse dann Raum für den Benutzer, um zu widersprechen. Es ist schneller als offene Fragen, und deine Hypothesen decken oft eine Perspektive auf, die der Benutzer nicht in Betracht gezogen hat.

   Behandle die Antwort als Kontext, nicht als Evangelium. Der Benutzer kennt seine eigene Motivation, unterschätzt aber möglicherweise das technische Interesse, übersieht, was am Design tatsächlich überzeugend ist, oder formuliert es zu eng. Deine Aufgabe ist es, den Code zu lesen und das zu finden, worüber es sich wirklich zu sprechen lohnt, und dann ihre Antwort als Linse zu verwenden. Der Code ist die primäre Quelle. Ihre Antwort ist ein Hinweis.

2. Öffentliches Risiko auditieren

Überprüfe das Repository auf alles, was nicht öffentlich werden sollte:

• Geheimnisse, .env-Dateien, Tokens, API-Schlüssel, private Anmeldedaten oder kopierte Shell-Historie
• interne URLs, persönliche E-Mails, absolute lokale Pfade, maschinenspezifische Anweisungen oder private Screenshots
• private Datensätze, Anbieter-Assets oder Beispieldateien, die nicht weiterverteilt werden können
• Caches, Logs, generierte Datenbanken, Debug-Ausgaben und nur lokale Artefakte
• chaotische Commit-Historie, die die falsche Geschichte erzählt oder privaten Kontext preisgibt

Anleitung:

• Verwende zuerst schnelle lokale Inspektion: rg, git status, git log, git ls-files und gezielte Dateiauslesungen.
• Wenn das Risiko im Arbeitsbaum liegt, räume es auf.
• Wenn das Risiko nur in der Historie liegt, bevorzuge ein sauberes Export-Repository anstelle einer riskanten Historie-Chirurgie.

3. Das Repository härten

Führe den kleinsten glaubwürdigen Durchgang durch, der das Projekt für andere Menschen nutzbar macht:

• mache Installations- und Ausführungsschritte deterministisch
• füge env.example, Beispielkonfiguration und Ignorierregeln hinzu oder verschärfe sie, wo nötig
• verbessere den primären Einstiegspunkt, sodass Fehler lesbar sind und Standardeinstellungen sinnvoll sind
• entferne toten experimentellen Ballast, der Erstbenutzer verwirrt
• füge Tests hinzu oder verbessere sie, sodass der Hauptpfad plus mindestens ein Fehler- oder Randfall abgedeckt ist
• passe den Beweis an die Produktform an:
  • CLIs: Befehls-Hilfe plus einen echten Befehls-Smoke-Test
  • Bibliotheken: Unit-Tests um die öffentliche API
  • Web-Apps: Browser- oder Anfrageebene-Smoke auf dem Hauptfluss
  • APIs/Dienste: Anfrage-Antwort-Beweis plus Fehlerbehandlungsprüfungen
• füge leichtgewichtiges CI nur hinzu, wenn das Repository bereits einen unkomplizierten Befehl hat, der sich zur Automatisierung lohnt
• setze die Standardlizenz auf MIT, es sei denn, das Repository oder der Benutzer weist klar auf etwas anderes hin

Mache daraus keine große Umschreibung. "Öffentlich bereit" bedeutet poliert genug, um ehrlich geteilt zu werden, nicht von Grund auf neu gebaut.

4. Öffentliche Dokumente schreiben

Erstelle oder überarbeite die öffentlichen Dokumente, damit sich ein Fremder schnell orientieren kann:

• verwende references/readme-template.md für die README-Struktur
• erkläre zuerst das Problem, dann warum dieses Repository existiert, dann wie man es ausführt
• füge einen konkreten Quick-Start-Pfad ein, der von einem frischen Klon aus funktioniert
• dokumentiere den Testbefehl und alle erforderlichen lokalen Abhängigkeiten
• sei explizit über aktuelle Einschränkungen, Plattformannahmen oder Kanten
• füge eine kurze Build-in-Public-Notiz ein, die den Ursprung des Projekts erklärt, ohne internen Kontext preiszugeben
• füge eine visuelle Repo-Map oder ein Architekturdiagramm ein, wenn es einem kalten Leser hilft, das Dateilayout, den Datenfluss oder den Benutzerworkflow zu verstehen. Bevorzuge Mermaid oder repo-native Diagramme für exakte Beschriftungen; verwende native Bildgenerierung für polierte Dark-Mode-Illustrationen, Banner oder unterstützende Visuals.
• bereite vor:
  • eine einzeilige GitHub-Beschreibung
  • eine kurze Themenliste
  • optionale Release-Notizen, wenn der Benutzer eine erste Version veröffentlichen möchte

Generiere das ASCII-Banner. Jede README erhält ein figlet-Banner ganz oben, über allem anderen. Verwende die Schriftart rectangles – keine schrägen Zeichen. Führe aus:

figlet -f rectangles -w 200 "<Bannertext>"

Bannertext-Regeln:

• Verwende den Anzeigenamen des Projekts, nicht seinen Repo-Slug
• Ersetze alle Bindestriche durch Leerzeichen (build-in-public → build in public)
• Alles in Kleinbuchstaben (Mock Pop → mock pop)
• Wenn der Anzeigename vom Repo-Slug abweicht (z. B. Repo superwhisperer-lab, Anzeigename superwhisper lab), verwende den Anzeigenamen

Verpacke die Ausgabe in einen gefensterten Code-Block. Wenn figlet nicht installiert ist: brew install figlet. Dies ist das Erste, was jemand sieht – es signalisiert, dass das Projekt eine echte Identität hat.

Generiere und platziere README-Visuals. Wenn ein generiertes Bild in die README gehört, behandle es wie ein committetes Projektartefakt, nicht wie eine temporäre Vorschau:

1. Entscheide über den Zweck und die Platzierung des Bildes, bevor du es generierst:

   • repo-weite Übersicht, Architektur-Map oder Heldenvisual: platziere es nahe dem Anfang der README.md, unmittelbar nach dem Titel und der einzeiligen Zusammenfassung oder nach dem kurzen Einführungsabsatz, wenn das besser liest
   • Feature-Screenshot oder Workflow-Bild: platziere es in dem Abschnitt, den es erklärt, vor dem detaillierten Prosa oder Beispiel, das es unterstützt
   • ergänzendes Bild: platziere es weiter unten in der README oder lasse es weg, wenn es nichts klärt

2. Generiere das Bild mit nativer Codex-Bildgenerierung, wenn verfügbar, oder verwende Mermaid/SVG/repo-native Ausgabe, wenn exakter Text oder deterministische Struktur wichtiger ist.

3. Überprüfe das Ergebnis auf Lesbarkeit, verzerrte Beschriftungen, private Informationen und ob es das Projekt tatsächlich klärt.

4. Kopiere das endgültig ausgewählte Bild in das Repository, normalerweise assets/<beschreibender-Name>.<ext> oder docs/assets/<beschreibender-Name>.<ext>. Lasse kein in der README referenziertes Asset nur in einem generierten-Bilder-, Downloads-, Temp- oder lokalen Cache-Verzeichnis liegen.

5. Füge das Bild in die README.md mit einem relativen Pfad und aussagekräftigem Alternativtext ein:

   ![Dark-mode-Repository-Strukturdiagramm](assets/repo-structure-dark.png)
   

6. Committe das Bild und das README-Update zusammen, damit der Pfad für Klone, Forks, GitHub-Rendering und Release-ZIPs gültig ist.

7. Wenn das Visual neu generiert wird, verwende einen stabilen Dateinamen, wenn die README immer das neueste Bild zeigen soll, oder versionierte Dateinamen, wenn die Erhaltung vorheriger Ausgaben wichtig ist. Behalte den Generierungs-Prompt, das Quell-Diagramm oder das Skript im Repository, wenn Wiederholbarkeit wichtig ist.

Baue die Erzählung aus dem Code auf, informiert durch den Benutzer. Die Funkenantwort des Benutzers ist Kontext – verwende sie, um die Absicht zu verstehen, nicht um ihre Geschichte wörtlich für sie zu schreiben. Die wirkliche Erzählung kommt aus dem genauen Lesen des Codes: welches Problem löst das Design tatsächlich, was ist die nicht offensichtliche Entscheidung, was würde ein anderer Entwickler interessant oder nachahmenswert finden?

Deine Aufgabe als Erzähler:

• finde das Ding im Code, das wirklich interessant ist – die Einschränkung, die das Design geprägt hat, den Ansatz, der sich von der offensichtlichen Lösung unterscheidet, den Kompromiss, der bewusst eingegangen wurde
• rahme das Problem auf der richtigen Spezifitätsebene: konkret genug, dass jemand, der die gleiche Frustration hatte, es erkennt, allgemein genug, dass es nicht nur um die genaue Maschine des Benutzers geht
• gib ihm eine Stimme – keinen Hype, keinen Marketingtext, sondern den klaren, leicht aufgeregten Ton eines Entwicklers, der tatsächlich etwas Ärgerliches gelöst hat und dir erzählen möchte, wie

Wenn die Erklärung des Benutzers oberflächlich ist („Ich brauchte es einfach, um zu funktionieren“), grabe dich in den Code und finde die wahre Geschichte selbst. Wenn ihre Erklärung technisch reichhaltiger ist, als der Code rechtfertigt, ziehe sie zurück. Die README sollte ehrlich darüber sein, was das Projekt ist – ein kleines, nützliches, gut gemachtes Werkzeug –, nicht übertrieben.

Der Ton ist: „Hier ist ein echtes Problem, hier ist, was ich gebaut habe, hier ist, was an der Funktionsweise interessant ist.“ Kleine Werkzeuge können gute Geschichten haben. Mache sie nicht platt, aber blase sie auch nicht auf.

Vermeide Dokumentationsausuferung. Eine starke README, eine Lizenz und die minimalen unterstützenden Dateien schlagen einen Stapel zeremonieller Dokumente.

5. Verifizieren und packen

Führe die stärkste Verifizierung durch, die das Repository vernünftigerweise unterstützen kann:

1. Führe die relevanten Installations-, Build-, Lint-, Test- und Smoke-Befehle aus.
2. Verifiziere die Quick-Start-Anleitung gegen den tatsächlichen Code.
3. Simuliere, wenn praktikabel, einen Kalt-Klon-Pfad, anstatt dem aktuellen Maschinenzustand zu vertrauen.
4. Verwende für Web- oder visuelle Oberflächen den In-App-Browser, wenn verfügbar, und erfasse das Verifizierungsergebnis im Bericht.
5. Verwende für reine GUI-Oberflächen Computer Use gezielt und protokolliere, was überprüft wurde.
6. Erstelle das öffentliche ZIP-Artefakt aus dem committeten Code:

bash "$(dirname "$0")/scripts/create_release_zip.sh" <Repo-Pfad>
# Oder aus einem installierten Skill:
#   bash ~/.claude/skills/build-in-public/scripts/create_release_zip.sh <Repo-Pfad>   # Claude Code
#   bash ~/.codex/skills/build-in-public/scripts/create_release_zip.sh <Repo-Pfad>    # Codex

Das Hilfsskript schreibt das ZIP unter ~/.codex/workspaces/default/repos/<slug>-public/ oder den aktuellen Ausgabepfad.

6. Public-Release-Gate

Überprüfe die Public-Release-Checkliste aus den Referenzen. Wenn alle Bedingungen erfüllt sind, erstelle das öffentliche GitHub-Repository und pushe:

1. Erstelle das Repository unter dem persönlichen Konto des Benutzers mit öffentlicher Sichtbarkeit, es sei denn, der Benutzer wünscht ausdrücklich etwas anderes.
2. Verwende den bereinigten Ordner, nicht das Original mit potenziellen Geheimnissen in der Historie.
3. Committe die README, Lizenz, Konfiguration, Assets und Tests.
4. Pushe in das neue öffentliche Repository.
5. Erstelle das ZIP-Artefakt erneut aus dem gepushten Commit, damit es mit dem veröffentlichten Stand übereinstimmt.
6. Wenn die Veröffentlichung blockiert ist, dokumentiere den genauen Blockergrund im Terminal-Bericht, nicht im Repository.

7. Abschluss

Erstelle einen abschließenden Statusbericht, der zusammenfasst:

• was getan wurde (Repository erstellt, Dokumentation geschrieben, Tests durchgeführt, veröffentlicht oder blockiert)
• alle während des Prozesses getroffenen Entscheidungen und warum
• alle verbleibenden Risiken oder Empfehlungen
• öffentliche GitHub-URL, wenn veröffentlicht, oder den genauen Grund für die Blockierung
• Speicherort des ZIP-Artefakts
• wenn generierte Visuals vorhanden sind, wo sie platziert wurden und warum dieser visuelle Ansatz gewählt wurde (Bildgenerierung vs. Mermaid vs. SVG)
• alle Quellen, die während des Prozesses zitiert wurden

Zitiere Quellen. Der Abschlussbericht und die README sollten, wenn relevant, Quellen angeben: für Sicherheitsstandards, Lizenzentscheidungen, Konfigurationsmuster oder andere Referenzen, die nicht aus dem Projekt selbst stammen. Verwende ein konsistentes Zitierformat (z. B. [ref-name] oder Fußnoten). Dies baut Vertrauen und erleichtert dem Benutzer die Überprüfung deiner Arbeit.

Schreibe in den Terminal-Output. Der Abschlussbericht geht in das Terminal (stdout/stderr), nicht in das Repository. Er ist deine Zusammenfassung an den Benutzer, nicht ein Teil des veröffentlichten Projekts.