House-Sync
Bringe die eingebundenen House-Dateien eines Repos auf den neuesten Stand des installierten Plugins, ohne jemals eine lokale Änderung stillschweigend zu verwerfen. Rufe diesen Skill nur über /house-rules:sync auf. Es ist kein Nachschlage-Skill und er schreibt Dateien, daher wird er niemals durch eine einfache Frage nach Konventionen ausgelöst (verwende dafür /house-rules:conventions).
Das CLI, das dieser Skill antreibt:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <Pfad>] [--apply] [--force-managed <Pfad>]
--repo standardmäßig das aktuelle Verzeichnis. Nichts unten erfindet einen Unterbefehl außerhalb von init, render, check.
Standardpfad: Planen, dann anwenden
Sync hat genau einen Standardpfad. Führe ihn jedes Mal in dieser Reihenfolge aus.
1. Bestätige, dass das Repo House übernommen hat
Lese house.json im Stammverzeichnis des Repos. Fehlt house.json, wurde dieses Repo nie initialisiert ("bootstrapped"): Stoppe und teile dem Benutzer mit, dass er zuerst /house-rules:bootstrap ausführen soll. Behandle ein fehlendes Manifest nicht als "nichts zu synchronisieren".
2. Planen (Dry Run)
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <Pfad>
Ohne --apply wird nur geplant. Es liest .house/lock.json (jeder Eintrag: path, module, source, bodySha256) und vergleicht den aktuellen Body-Hash jeder verwalteten Datei auf der Festplatte mit dem Lock und dann mit dem, was der neu gerenderte Body wäre. Klassifiziere jede verwaltete Datei in genau einen Eimer:
- Sauber. Der Hash auf der Festplatte stimmt mit dem Lock überein. Plan: Überschreibe mit dem frisch gerenderten Body.
- Fehlend. Datei auf der Festplatte nicht vorhanden. Plan: Stelle sie wieder her.
- Lokal geändert. Der Hash auf der Festplatte stimmt weder mit dem Lock noch mit einem gerenderten No-Op überein. Plan: Verweigere. Siehe die drei Ausgänge unten.
Gib den Plan aus, bevor du etwas anderes tust. Wende in diesem Schritt nichts an, nicht einmal für saubere oder fehlende Dateien.
3. Lokal geändert: Drei Ausgänge, niemals eine stille Wahl
Eine lokal geänderte verwaltete Datei wird nicht zusammengeführt, nicht überschrieben und nicht stillschweigend in Ruhe gelassen. Gib den Diff zwischen der Datei auf der Festplatte und dem, was House rendern würde, aus, dann gib genau diese drei Ausgänge in dieser Reihenfolge aus und stoppe für die Datei (sie bleibt auch unter --apply unberührt, sie wird einfach vom Schreibvorgang ausgeschlossen):
- Upstream-first. Erstelle einen PR gegen das House-Paket-Repo selbst (
dubbl-a/house-rules), der die beabsichtigte Änderung enthält, damit die Bearbeitung zur neuen Hausregel für alle wird, anstatt eine private Abspaltung zu sein. Dies ist der bevorzugte Ausgang. - Zeichne eine Abweichung auf und entferne die Verwaltung. Füge einen Eintrag zum
deviations-Array inhouse.jsonmit einemwhyhinzu, entferne die Datei aus der Verwaltungsmenge und spiegele sie im Abschnitt## Abweichungen von HousederCLAUDE.mddes Repos. Verwende dies, wenn die Bearbeitung wirklich repospezifisch ist und niemals upstream gehen wird. - Erzwinge das Überschreiben. Führe aus:
Verwende dies nur, wenn die lokale Bearbeitung als wegwerfbar bestätigt ist, niemals als Standard, weil es am schnellsten ist. Frage den Benutzer vor der Ausführung um Bestätigung; wähle es niemals unaufgefordert in ihrem Namen.node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <Pfad> --force-managed <Pfad>
Biete keine vierte Option an und verwandle dies nicht in ein interaktives Menü, das auf eine Auswahl wartet. Gib die drei Ausgänge als Ergebnis des Laufs an, und lass dann den Benutzer (oder einen späteren Aufruf dieses Skills) einen davon ausführen.
4. Anwenden
Sobald saubere und fehlende Dateien berücksichtigt wurden und jede lokal geänderte Datei einem der drei Ausgänge zugewiesen (oder bewusst verweigert) wurde, wende an:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <Pfad> --apply
Dies schreibt saubere und fehlende Dateien. Es schreibt niemals eine noch verweigerte lokal geänderte Datei; --force-managed ist der einzige Pfad, der dies tut, und nur für den einen genannten Pfad.
Wenn render eine Zeile warning: ... is git-ignored ausgibt, stoppe und korrigiere die Ignorierregel, bevor du fortfährst: Ein Ziel, das git nicht sehen kann, erreicht niemals den Checker oder CI. Ignoriere nur .claude/settings.local.json, niemals .claude/ oder .house/.
Wenn render oder der Checker warning: module is not in house.json, but <dir>/ exists here ausgibt, wurde ein Modul ausgeliefert, nachdem dieses Repos house.json geschrieben wurde, und seine Regeln werden nicht eingebunden, bis das Repo "<name>": {"enabled": true} unter modules hinzufügt. Füge den Schlüssel nicht selbst hinzu: Kopiere die Warnzeile wörtlich in den Body des Sync-PRs, unter eine Zeile, die besagt, dass ein neues Modul für dieses Repo gilt und die Wahl des Übernehmers benötigt.
4b. Stage, was render geschrieben hat, nach Pfad
git add house.json .house/ .claude/rules/house/
Füge scripts/house/ zu diesem Befehl nur hinzu, wenn der Render-Plan eine Datei dort aufgelistet hat; git verweigert den gesamten Befehl, wenn ein Pfadspezifikation nichts findet. Nach explizitem Pfad, niemals git add -A: Der Checker und CI lesen git ls-files, also ist eine gerenderte Datei, die nicht gestaged ist, eine, die niemand überprüft, und ein pauschales Hinzufügen würde alles andere mitnehmen, was im Baum liegt.
Die Scaffolded-Liste von Render (.github/PULL_REQUEST_TEMPLATE.md, .github/workflows/pr-checks.yml, das CLAUDE.md-Grundgerüst) ist keine verwaltete Datei, daher kann die [untracked]-Warnung sie nicht sehen: Überprüfe diese Dateien, dann stage sie auch nach Pfad.
Ein Grundgerüst wird einmal pro Repo angeboten, nicht einmal pro Render. Die scaffolds-Liste des Locks zeichnet auf, welche Vorlagen dieses Repo bereits erhalten hat; eine dort aufgezeichnete Vorlage wird nie wieder geschrieben, unabhängig davon, ob ihre Datei noch auf der Festplatte ist. Also bleibt ein CLAUDE.md.house-skeleton, das in CLAUDE.md zusammengeführt und gelöscht wurde, gelöscht, und kein erneuter Sync muss es rmen. Wenn ein Repo eines zurückhaben möchte, schreibt render --apply --scaffold jedes fehlende Grundgerüst und überschreibt dennoch niemals eine Datei, die vorhanden ist. Erwarte, dass der scaffolds-Schlüssel beim ersten Sync mit Version 0.2.3 oder höher im Lock-Diff erscheint; es ist eine Aufzeichnung, kein Hash, und nichts verweigert darauf.
4c. Gitignore-Werkzeug-Scratch
Stelle sicher, dass die .gitignore des Repos .claude/worktrees/ und .superpowers/ enthält, indem die jeweils fehlende Zeile angehängt wird. Werkzeug-Scratch, das in git status auftaucht, ist ein git add -A davon entfernt, committet zu werden.
5. Bestätige den Pin
Bestätige, dass house.json jetzt die geladene Plugin-Version trägt; render hat sie geschrieben, niemals per Hand bearbeiten. render --apply setzt das Feld version auf die Plugin-Version in:
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json
Lies niemals installed_plugins.json, um dies zu überprüfen. Es zeichnet den Installationsstatus über Repos hinweg auf und kann veraltet sein oder sich von dem unterscheiden, was gerade geladen ist; plugin.json unter CLAUDE_PLUGIN_ROOT ist die Version, die diesen Sync tatsächlich ausführt.
6. Verifiziere mit dem eingebundenen Checker
Führe den Checker so aus, wie CI und prebuild ihn tatsächlich ausführen werden, nicht die eigene Kopie des Plugins:
node .house/check.mjs
node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <Pfad> führt die identische Logik gegen die eigene Nutzlast des Plugins aus und ist nützlich, bevor .house/check.mjs in das Repo eingebunden wurde (ein erstmaliger Sync). Sobald die eingebundene Kopie existiert, beweist das direkte Ausführen, dass die Datei, die ausgeliefert wird, die Datei ist, die besteht, und nicht eine Kopie, die nur gleich aussieht.
Eine [untracked]-Warnung hier bedeutet, dass Schritt 4b für diese Datei übersprungen wurde; stage sie und führe erneut aus. Ein [gitignored]-Fund bedeutet, dass die Ignorierregel aus Schritt 4 immer noch eine verwaltete Datei verschluckt.
7. Gib Doctor-Output aus
Nachdem der Check gelaufen ist, führe den Doctor aus und berichte seine Zeilen:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <Pfad>
Was jede gedruckte Zeile bedeutet (Bezeichnungen, wie doctor sie druckt):
effective branch guard: plugin | repo | NONE.NONE: keinehouse.jsonund kein repo-lokaler Hook. Nichts schützt derzeit vor direkten Commits auf einen geschützten Branch.repo: eine repo-lokale Datei.claude/hooks/no-direct-master.shexistiert, oder.claude/settings.jsonträgt einenhooks-Block. Der Repo-Hook gewinnt während der Migration; der Plugin-Hook weicht aus und beendet sich mit 0.plugin:house.jsonexistiert und kein repo-lokaler Hook ist vorhanden. Der Plugin-Hook ist derjenige, der tatsächlichbranchPolicyundprotectedBranchesdurchsetzt. Es wird alsplugin (recorded <Datum>)gedruckt, wennhouse.jsoneinenguard-Eintrag trägt, und alsplugin (unrecorded), wenn nicht, was nur darüber ist, ob dieguard-Warnung des Checkers gelöscht ist: Der Hook setzt das gleiche durch, so oder so.
git-hook floor: .... Ob der eingebundene.githooks/-Baum tatsächlich mit git IN DIESEM CLONE verbunden ist.core.hooksPathlebt in.git/config, also ist es Maschinenzustand, den kein Clone, kein Render und kein PR trägt; der Checker liest ihn nie (ADR 0008 hält den Checker repo-only) und Doctor ist, wo stattdessen davon berichtet wird.armed (core.hooksPath=<Pfad>, <Bereich>): git führt den Floor hier aus. Nichts zu tun.NOT armed -- core.hooksPath is unset in this clone: Der Floor ist gerendert und inert.house render --applyaktiviert ihn, ebenso wie das Starten einer Sitzung im Repo mit installiertem Plugin.NOT armed -- core.hooksPath is <anderer>: Ein anderes Werkzeug (husky, lefthook, eine Monorepo-Konvention) besitzt den einen hooksPath, den dieses Repo hat. House überschreibt ihn nie. Verkette den Floor von den Hooks dort, oder hebe die Einstellung auf und führe render erneut aus.not rendered here (missing: <Pfade>): Mindestens eine der sieben Floor-Dateien fehlt, und die Zeile benennt welche. Alle sieben fehlend ist einfach ein Repo, das den Floor noch nicht gerendert hat. Eines fehlend ist schlimmer, als es aussieht: Jeder Guard sourced.githooks/house-lib.shund beendet sich mit einem Fehler, wenn das Source fehlschlägt, also schlägt ein Floor, dem nur die Bibliothek fehlt, jeden geschlossenen Commit fehl, anstatt offen fehlzuschlagen. In beiden Fällen: render.not applicable: Keinehouse.jsonan dieser Wurzel, oderbranchPolicyist nichtpr.- Die eingerückten Folgezeilen berichten, was den Floor eher ruhig als schützend machen würde.
foreign hooks in this clone's .git/hooks: Die Aktivierung wird verweigert, weilcore.hooksPath.git/hookspauschal ersetzt und sie stillschweigend deaktivieren würde.not executable: git ignoriert stillschweigend einen Hook ohne das Bit, also ist ein verlorener Modus ein Fail-Open; render stellt ihn wieder her (fügt das Bit nur für die Klassen hinzu, die die Datei bereits lesen können, also kommt ein absichtlich 0600 Hook als 0700 zurück und wird nie erweitert).reference-transaction: supported by git <Version> (>= 2.28)oderinert on git <Version> (needs 2.28): Auf 2.28 und neuer hat der Floor ein Mitglied, das kein Flag ausschaltet, und die inerte Zeile ist eine echte Lücke und keine kosmetische. Unter 2.28 umgeht--no-verifypre-commitundpre-pushzusammen, und nichts anderes ist da, um es abzufangen, also wird das Flag auf diesem Git nur durch den Session-Zeit-PreToolUse-Hook verweigert, der nicht da ist, wenn keine Session in der Schleife ist. Behandle die Zeile als Aufforderung, Git zu aktualisieren, nicht als Hinweis.
jq on PATH: yes | no. Der Hook verweigert auch ohne (handgeschriebenes deny-JSON), aber berichte die Lücke, damit sie behoben wird.pin vX matches plugin vY|pin vX differs from installed plugin vY.house.json'sversiongegen dieplugin.jsondes Plugins selbst, der gleiche Vergleich wie Schritt 5.differsbedeutet, dass der Pin-Bump noch nicht gelandet ist oder übersprungen wurde.npm wiring (.house/check.mjs referenced by): <Scripts> | none found. Erwarte eincheck:docs(oder ein gleichwertiges leichtgewichtigtes) Skript, das.house/check.mjs --only=drift,todoaufruft, und eincheck:house-Skript, das das vollständige.house/check.mjsaufruft. Wenn eines fehlt, drucke den kopierbaren Schnipsel, anstattpackage.jsondirekt zu bearbeiten:"check:docs": "node .house/check.mjs --only=drift,todo" "check:house": "node .house/check.mjs"rule-load positive control: .... Ob einInstructionsLoaded-Hook verdrahtet ist und was sein eigenes Log tatsächlich gesehen hat; ohne einen sieht eine Regel, deren Glob nie passt, genauso aus wie eine Regel, die nichts tut.repo (.claude/settings.json): Das Repo deklariert seinen eigenen Hook.plugin hook; log <Pfad>: last load <ts>, <n> of <m> vendored rules seen: Der eigene Hook des Plugins ist verdrahtet und hat mindestens einen Ladevorgang protokolliert, mit einer echten Anzahl, wie viele eingebundene Regeldateien er tatsächlich geladen gesehen hat. Wenn<n>kleiner als<m>ist, wird die Zeile fortgesetzt mit; not seen in this log: <Namen>, wobei jede eingebundene Regel genannt wird, für die das Log keinen Ladevorgang führt, weil die Anzahl allein sagt, dass etwas falsch ist, und niemals, welche Datei zu öffnen ist. Lies diese Liste als Hinweis und nicht als Urteil: Das Log trimmt sich selbst, also kann eine Regel dort erscheinen, nachdem sie nur vor langer Zeit geladen wurde, und der ehrliche nächste Schritt ist, eine Datei zu öffnen, die diepaths:der Regel beansprucht, und doctor erneut auszuführen. Ein Name, der das überlebt, ist eine Regel, deren Geltungsbereich die Dateien nicht erreicht, für die sie geschrieben wurde.plugin hook declared; no log yet for this checkout: Der Hook des Plugins ist verdrahtet, hat aber hier noch nichts protokolliert – starte eine Sitzung in diesem Repo und führe doctor erneut aus.none wired: Nichts deklariert den Hook überhaupt.git-ignored house destinations: none | <Pfade>. Alles andere alsnoneist ein Ziel, das der Checker nicht sehen kann; korrigiere die Ignorierregel wie in Schritt 4.
8. Leite das, was das Repo nicht upstream beheben kann, als ein Issue pro Element weiter
Ein Sync- oder Compliance-Durchlauf fördert oft Erkenntnisse und Warnungen zutage, auf die nur das Paket reagieren kann: eine Checker-Lücke, ein Regelanker, der eine hier nicht existierende Datei benennt, ein Konfigurationsslot, den das Repo benötigt und dem Schema fehlt. Für jedes solche Element behebe es entweder upstream in derselben Sitzung (Branch und PR gegen das Paket-Repo, derselbe Upstream-First-Ausgang wie Schritt 3) oder erstelle EIN Issue pro bearbeitbarem Element im Paket-Repo, das klein genug ist, um mit einer einzigen Änderung geschlossen zu werden.
Bündele sie niemals in einem Multi-Item-Digest-Issue: Ein Digest kann nicht geschlossen werden, bis sein langsamstes Element landet, seine Elemente können nicht unabhängig priorisiert werden, und halb gelöste Digests häufen sich an. Was in diesem Repo bleibt, ist nur das, was dieses Repo beheben kann.
Ausweichmöglichkeiten
Dies sind Ausnahmen, die inline im obigen Standardpfad auftauchen, kein separates Menü, aus dem man vorab wählen kann:
- Kein
house.json: Stoppe bei Schritt 1, verweise auf/house-rules:bootstrap. - Lokal geänderte Datei: die drei Ausgänge in Schritt 3.
- Als wegwerfbar bestätigte lokale Bearbeitung:
--force-managed <Pfad>, nur nach Nachfrage. - Erster Sync in einem Repo,
.house/check.mjsnoch nicht eingebunden: Verwendehouse check --repo <Pfad>in Schritt 6 anstelle des eingebundenen Pfads und beachte, dass dies ein einmaliger Ersatz ist, nicht der Dauerzustand.
Nicht tun
- Führe keine lokal geänderte Datei zusammen