wiki-smith

wiki-smith – das .wiki/ des Repos pflegen

Ein Wiki ist das Gedächtnis des Repos, geschrieben für Agents: Sie finden hier die Regel, anstatt erneut zu fragen. Das Tagebuch hält fest, was passiert ist; die Themenseite hält fest, was gilt. Eine Lektion, die nur im Tagebuch lebt, ist verloren. wiki-smith entscheidet, welche der beiden eine Sitzung benötigt, schreibt sie so, wie es die eigenen Regeln dieses Wikis vorgeben, und prüft sie.

Vollständige Methode (Dateitypen, Notizformat, Aufnahme, Verlinkung, Datumsangaben, Commit): references/method.md. Konfigurationsschlüssel: references/config.md. Danksagungen: ATTRIBUTION.md. Änderungen: CHANGELOG.md. Eigenes Gedächtnis: .wiki/.

<skill> unten ist der Ordner dieser Fähigkeit (z. B. ~/.claude/skills/wiki-smith). Jedes Skript nimmt -w <wiki-verzeichnis> (Standard ./.wiki) und -c <konfig> (Standard <wiki>/wiki.config) entgegen.

Schritt 0 – Das Wiki und seine Regeln finden

1. Das Wiki ist .wiki/ im Repo-Root. Wenn es keines hat, sagen Sie das und bieten Sie an, eines aus templates/ zu erstellen (wiki.config.example zuerst); erstellen Sie es niemals ungefragt.
2. Lesen Sie .wiki/wiki.config, falls vorhanden (Namen: Tagebuchordner, Posteingang, Index, Fußzeilenbeschriftung, Datumsschlüssel, Hauptbranch). Ohne Konfiguration gelten die englischen Standardwerte: journal/, inbox.md, index.md, Map:, ## History, created/updated.
3. Die eigenen Regeln des Wikis haben Vorrang. Wenn das Repo eine Seite zur Pflege hat (rg -n -i 'pfleg|wart' .wiki -l) oder eine AGENTS.md-Regel zum Wiki, lesen Sie diesen Abschnitt und folgen Sie ihm, wo er von dieser Fähigkeit abweicht.
4. Wenn der Benutzer nach „Wiki-Update“ gefragt hat und das Wiki (normalerweise der Index) sagt, zuerst zu bestätigen, führen Sie Schritt 1 und Schritt 2 nur als Plan aus: eine Zeile pro Seite mit den Änderungen, die Titel der neuen Notizen, dann fragen Sie „Anwenden?“ und bearbeiten Sie erst nach einem Ja. Andernfalls handeln Sie.

Schritt 1 – Prüfen, was passiert ist, dann weiterleiten

Lesen Sie die Sitzung (und git diff, git log für die geleistete Arbeit). Wählen Sie jede zutreffende Zeile und nichts anderes:

Was die Sitzung hatte	Was zu tun ist
Eine Entscheidung, Lieferung, Kursänderung, ein Vorfall oder eine Recherche	Ein Tagebucheintrag: scripts/note.sh -b "Titel, der die Änderung beschreibt" mit dem Absatz per Pipe. Dann die Zeile des Tages im Posteingang.
Eine Regel, Lektion oder Tatsache, die über den heutigen Tag hinaus gültig ist	Korrigieren Sie auch die Themenseite: die Regel, wie sie jetzt gilt, ohne Historie (Historie bleibt im Eintrag und im History-Abschnitt der Seite). Korrigieren Sie, was die Seite zuvor gesagt hat; stapeln Sie niemals „es war einmal“.
Ein neues Thema mit mehreren Facetten (es wird wiederkommen, und eine Seite würde Arten vermischen)	Eine Inhaltskarte moc-<thema>.md plus Seiten <thema>-<facette>.md (Spickzettel, Installation, Integration, Vergleich mit dem aktuellen Tool...). Siehe „Neues Thema“ unten.
Nichts Aufzeichnenswertes (nur Zwischenschritte oder das, was ein Commit bereits sagt)	Sagen Sie dies in einer Zeile und erstellen Sie nichts. Das Tagebuch aufzublähen macht es unlesbar.

Es wird nur ein neuer Eintrag für das Tagebuch erstellt; überschreiben Sie niemals den Eintrag eines anderen Agents.

Schritt 2 – Schreiben

Tagebucheintrag. scripts/note.sh "<titel>" erstellt <TAGEBUCH_VERZ>/<heute>/<HHMM>-<slug>.md in UTC und gibt den Pfad aus (Slug-Regeln und -2 bei Kollision sind im Skript). Stdin wird nur mit -b gelesen: Agent-Shells und CI lassen stdin offen, daher wartet das Skript ohne -b nie. Leiten Sie den Textkörper weiter: printf '%s\n' "<absatz>" | scripts/note.sh -b "<titel>"; -b setzt genau eine Leerzeile zwischen Titel und Textkörper. Ohne -b enthält die Datei nur die Titelzeile; um den Absatz später hinzuzufügen, beginnen Sie mit einer Leerzeile: printf '\n%s\n' "<absatz>" >> "$pfad". Der Textkörper ist ein gut geschriebener Absatz: was passiert ist, warum es wichtig ist, wo die Beweise sind (Commit, PR, Issue), mit einem Link zur Themenseite. Links sind relativ zum Tagesordner (../../seite.md). Vorlage: templates/note.md.

Erster Eintrag des Tages: scripts/day-index.sh erstellt den Tagesindex; dann fügen Sie den Tag oben in die „letzten Tage“ im Posteingang ein. Wenn die Notiz die Funktionsweise des Repos ändert, fügen Sie auch eine Zeile zu den Highlights des Posteingangs hinzu. Der Posteingang enthält niemals eine Notiz.

Themenseite (Aufnahme). Finden Sie sie (rg -n -i '<wort>' .wiki); wenn sie nicht existiert und das Thema wiederkommen wird, erstellen Sie sie (Vorlage: templates/page.md); wenn sie klein ist, setzen Sie sie in einen Abschnitt einer nahegelegenen Seite. Schreiben Sie die Regel, wie sie jetzt gilt. Wenn eine Änderung die Behauptung der Seite verändert, fügen Sie eine Zeile oben im History-Abschnitt hinzu. Die Notiz verlinkt auf die Seite.

Neues Thema.

1. Schreiben Sie zuerst die Seiten, eine pro Facette, jede ab dem ersten Satz in sich geschlossen. Typische Facetten: Spickzettel (die zum Starten: Adressen, Befehle, Tastenkombinationen), Installation, Integration, Vergleich mit dem aktuell verwendeten Tool.
2. Erstellen Sie moc-<thema>.md (templates/moc.md): ein Einleitungsabsatz, „die Seiten“ (eine Zeile pro Seite, Spickzettel zuerst), „was zuerst wissen“ (die wenigen Regeln, die beißen).
3. Versehen Sie jede Seite mit der Fußzeile (Map: [moc-<thema>](moc-<thema>.md) · Verwandt: ...), fügen Sie die Karte und jede Seite zum Index hinzu und verlinken Sie die Karte von mindestens einer anderen Karte.
4. Ein Eintrag im Tagebuch sagt, was erstellt wurde, und verlinkt die Karte.

Schritt 3 – Abschluss (immer, in dieser Reihenfolge)

1. scripts/dates.sh – die created/updated-Frontmatter, aus git. Idempotent.
2. scripts/day-index.sh – den Tagesindex neu generieren. Niemals von Hand bearbeiten.
3. python3 -I scripts/lint.py – jede datei:zeile: typ: nachricht, die es ausgibt, korrigieren, bis es mit 0 beendet wird (Exit 2 bedeutet Probleme). Keinen roten Lint ausliefern.
4. Commit nur Ihre eigenen Dateien, per Pfad, niemals git add -A: scripts/sync.sh -m "wiki: <was>" <pfad>.... Es committet direkt, wenn der Checkout auf <main> ist, aktuell und ohne Änderungen außerhalb Ihrer Pfade; andernfalls überträgt es Ihre Pfade in einen frischen git worktree von origin/<main>. In beiden Fällen lintet es genau das, was es committet, und verweigert einen roten Lint (Exit 1, Checkout unberührt, Übertragungs-Worktree entfernt). Bei der Übertragung wird der generierte Tagesindex nie kopiert: Er wird im Worktree neu generiert, sodass er nur die Notizen auflistet, die im Commit sind. Fügen Sie die vom Repo oder Host geforderten Zuschreibungszeilen zur Nachricht hinzu.
   • Gemeinsame Dateien (Index, Posteingang), die auch eine andere Sitzung bearbeitet haben könnte: Übergeben Sie sie nicht an eine Übertragung. scripts/sync.sh -W erstellt einen frischen Worktree von origin/<main>; führen Sie Ihre Bearbeitungen dort durch (das Wiki ist unter demselben relativen Pfad), führen Sie dates.sh, day-index.sh, lint.py aus, dann führen Sie sync.sh -m ... [-p] <pfade> von innerhalb dieses Worktrees aus. Es committet dort, und mit -p rebased, pusht, fast-forwarded den Haupt-Checkout, wo möglich, und entfernt den Worktree. Eine Übertragung, die Zeilen einer anderen Sitzung transportiert (z. B. einen Link zu einer Seite, die nur im Checkout existiert), lässt den Lint fehlschlagen und stoppt, bevor etwas committet wird; dieses Scheitern ist das Signal, -W zu verwenden.
5. Nur pushen, wenn der Benutzer zur Synchronisierung aufgefordert hat: derselbe Aufruf mit -p (fetch, rebase, push HEAD:<main>, fast-forward des Checkouts, Worktree entfernen). Niemals force-pushen, niemals die modifizierten Dateien anderer berühren: Eine Datei, die von dem, was Sie gepusht haben, abweicht und möglicherweise Bearbeitungen einer anderen Sitzung enthält (Index, Posteingang), wird so belassen, wie sie ist. Wenn der Checkout nicht fast-forwarded werden kann (lokaler <main> divergiert oder überlappende lokale Bearbeitungen), wird dies gemeldet und trotzdem mit 0 beendet, da der Push funktioniert hat. Nur auf Anfrage einen PR öffnen.

Committen Sie, was Sie in derselben Sitzung geschrieben haben, ohne darauf zu warten, gefragt zu werden; das Veröffentlichen ist die Entscheidung des Benutzers.

Das Wiki konsultieren

rg -n -i '<stichwort>' .wiki (oder den Index überfliegen), dann nur die passende Seite oder den passenden Abschnitt lesen, niemals das gesamte Wiki. Für das, was passiert ist: den Posteingang (kurz), dann nur die relevanten Tage; ein Tag = sein Index und die darin aufgeführten Notizen. Wenn das Repo Spezifikationen hat, sagen diese, was das System verspricht: rg -n -i '<stichwort>' <spezifikationen-verz>.

Fallstricke

• Das Tagebuch ist nicht die Seite. Eine Regel, die nur in einer Notiz steht, ist verloren; nehmen Sie sie in derselben Sitzung in die Themenseite auf.
• Regeln ohne Historie. „Vor dem Erstellen einer Karte nach vorhandenen suchen“, nicht „wir haben früher Karten dupliziert“. Die Geschichte bleibt in der Notiz.
• Eine Notiz pro Datei. Mehrere Agents schreiben am selben Tag; sie dürfen niemals dieselbe Datei bearbeiten. Der Tagesindex wird generiert; Konflikte dort werden durch erneutes Ausführen von day-index.sh gelöst.
• Gemeinsame Dateien über Sitzungen hinweg. Der Tagesindex, index.md und der Posteingang enthalten alle nicht committeten Bearbeitungen aller Sitzungen in einem Checkout. sync.sh überträgt den Tagesindex nie (er wird im Worktree neu generiert) und lintet vor dem Commit, kann aber nicht unterscheiden, welche Hünke eines von Hand bearbeiteten index.md oder Posteingangs von Ihnen stammen: Die Übertragung übernimmt den gesamten Diff. Wenn eine andere Sitzung sie möglicherweise bearbeitet hat, verwenden Sie sync.sh -W und bearbeiten Sie im Worktree. Eine fremde Zeile, die den Lint zufällig nicht bricht, wird dennoch übertragen; das ist die dokumentierte Grenze der Übertragung.
• Nie auf stdin warten. note.sh liest den Textkörper nur mit -b; in einer Agent-Shell blockiert ein bloßes Lesen für immer. Das Gleiche gilt für jedes von Ihnen hinzugefügte Skript.
• Vergängliches nicht aufzeichnen: ein Befehl, der einmal fehlschlug und beim erneuten Versuch funktionierte, eine Umgebungsstörung, eine einmalige Aufgabe. Halten Sie die funktionierende Lösung auf der Themenseite fest, niemals „X ist kaputt“ (es verhärtet sich zu einer Verweigerung, nachdem die Ursache verschwunden ist).
• Links: relativ, erste Erwähnung pro Abschnitt nur; ein Anker ist der GitHub-Slug der Überschrift (Kleinbuchstaben, keine Satzzeichen, Akzente bleiben, Leerzeichen werden zu Bindestrichen). Das Umbenennen einer Überschrift zerbricht ihre Anker; der Lint sagt dies. Setzen Sie ein Link-Beispiel in Backticks, damit der Lint es nicht liest.
• Seite umbenennen oder löschen: rg -l 'alter-name' .wiki und jeden Link korrigieren, einschließlich Anker; erst löschen, nachdem der Inhalt verschoben wurde.
• Seitengröße: Ab etwa 150 Zeilen oder wenn sich Regel, Vorgehen, Referenz und Historie vermischen, nach Art aufteilen.
• Private Daten bleiben draußen. Wiki-Seiten werden committet; halten Sie Geheimnisse, Token und persönliche Daten heraus und verweisen Sie stattdessen darauf, wo das Geheimnis lebt.
• Lint-Grenzen: Er erfasst keine Widersprüche zwischen Seiten oder veraltete Behauptungen; das ist eine Überprüfung durch den Agent, wenn die Zeit es erlaubt.
• day-index.sh-Grenze: Eine Tagesdatei mit von Hand geschriebenen Notizen im alten Format ist ein Fehler (Datei:Zeile), wird nicht migriert; verschieben Sie jede Notiz mit note.sh in eine eigene Datei und führen Sie es erneut aus.

Schritt 4 – Ihr eigenes Wiki pflegen

Wenn dieser Durchlauf etwas über den Betrieb von wiki-smith selbst gelehrt hat (ein Routing-Fehler, eine Skript-Eigenheit), fügen Sie eine Zeile zu .wiki/lessons.md hinzu: - YYYY-MM-DD — <Regel + Grund>. Bearbeiten Sie den Quell-Clone (biliboss/wiki-smith) und installieren Sie neu (npx skills add biliboss/wiki-smith -g --copy -a claude-code -y), nicht die installierte Kopie, die eine Neuinstallation überschreibt. Designentscheidungen gehören in .wiki/design.md.