Communitygithub.com

dubbl-a/house-rules

Cette compétence doit être utilisée lorsque l'utilisateur exécute "/house-rules:sync", ou demande à "synchroniser la maison", "mettre à jour les règles vendues", "tirer la dernière version de la maison" ou "vérifier les fichiers gérés pour les modifications locales".

Qu'est-ce que house-rules ?

Cette compétence, "house-sync", synchronise les fichiers de règles "vendus" d'un dépôt avec la version installée du plugin house, sans jamais supprimer silencieusement une modification locale. Elle est invoquée uniquement via la commande "/house-rules:sync" et ne doit pas être déclenchée par une simple question sur les conventions (utilisez plutôt "/house-rules:conventions"). Le processus suit une séquence stricte : vérifier que le dépôt a adopté house (via la présence de house.json), planifier les modifications en mode dry-run, puis les appliquer. Une attention particulière est portée aux fichiers modifiés localement, offrant trois options : envoyer la modification en amont vers le dépôt du package house, enregistrer une déviation et ne plus gérer le fichier, ou forcer l'écrasement. La compétence inclut également des étapes de vérification, de staging des fichiers, de configuration de .gitignore, de validation via un vérificateur vendu, et de rapport via un diagnostic. Les plateformes prises en charge sont les environnements où le plugin house est installé, comme Claude Code ou Cursor. Le fonctionnement repose sur des scripts Node.js et l'interface de ligne de commande "house" pour effectuer les opérations de rendu, de vérification et de diagnostic.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dubbl-a/house-rules/tree/HEAD/plugins/house/skills/sync

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Synchronisation de la maison (House sync)

Mettez à jour les fichiers de règles "vendus" d'un dépôt avec la version installée du plugin, sans jamais supprimer silencieusement une modification locale. Invoquez cette compétence uniquement via /house-rules:sync. Ce n'est pas une compétence de consultation et elle écrit des fichiers, donc elle ne se déclenche jamais à partir d'une simple question sur les conventions (utilisez /house-rules:conventions pour cela).

L'interface de ligne de commande (CLI) que cette compétence pilote :

node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <chemin>] [--apply] [--force-managed <chemin>]

--repo par défaut au répertoire courant. Rien ci-dessous n'invente une sous-commande en dehors de init, render, check.

Chemin par défaut : planifier, puis appliquer

La synchronisation a exactement un chemin par défaut. Exécutez-le dans cet ordre à chaque fois.

1. Confirmer que le dépôt a adopté house

Lisez house.json à la racine du dépôt. Absence de house.json signifie que ce dépôt n'a jamais été amorcé : arrêtez-vous et dites à l'utilisateur d'exécuter /house-rules:bootstrap d'abord. Ne traitez pas un manifeste manquant comme "rien à synchroniser".

2. Planifier (simulation)

node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <chemin>

Sans --apply, ceci ne fait que planifier. Il lit .house/lock.json (chaque entrée : path, module, source, bodySha256) et compare le hachage actuel du corps de chaque fichier géré sur le disque avec le verrou, puis avec ce que serait le nouveau corps rendu. Classez chaque fichier géré dans exactement un seau :

  • Propre. Le hachage sur le disque correspond au verrou. Plan : écraser avec le corps fraîchement rendu.
  • Manquant. Fichier absent du disque. Plan : le restaurer.
  • Modifié localement. Le hachage sur le disque ne correspond ni au verrou ni à un rendu sans opération. Plan : refuser. Voir les trois sorties ci-dessous.

Affichez le plan avant de faire quoi que ce soit d'autre. N'appliquez rien dans cette étape, même pour les fichiers propres ou manquants.

3. Modifié localement : trois sorties, jamais un choix silencieux

Un fichier géré modifié localement n'est pas fusionné, écrasé ou laissé tranquille silencieusement. Affichez le diff entre le fichier sur le disque et ce que house rendrait, puis affichez exactement ces trois sorties, dans cet ordre, et arrêtez-vous pour le fichier (il reste intact sous --apply aussi, il est simplement exclu de l'écriture) :

  1. Amont d'abord. Ouvrez une Pull Request (PR) contre le dépôt du package house lui-même (dubbl-a/house-rules) portant la modification souhaitée, afin que l'édition devienne la nouvelle règle house pour tout le monde au lieu d'un fork privé. C'est la sortie préférée.
  2. Enregistrer une déviation et ne plus gérer. Ajoutez une entrée au tableau deviations de house.json avec un why, retirez le fichier de l'ensemble géré, et reflétez-le dans la section ## Déviations de house du CLAUDE.md du dépôt. Utilisez ceci lorsque la modification est véritablement spécifique au dépôt et n'ira jamais en amont.
  3. Forcer l'écrasement. Exécutez :
    node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <chemin> --force-managed <chemin>
    
    Utilisez ceci uniquement lorsque la modification locale est confirmée comme jetable, jamais par défaut car c'est le plus rapide. Demandez à l'utilisateur de confirmer avant de l'exécuter ; ne le choisissez jamais de votre propre initiative sans y être invité.

N'offrez pas de quatrième option et ne transformez pas cela en un menu interactif qui boucle en attendant un choix. Énoncez les trois sorties comme le résultat de l'exécution, puis laissez l'utilisateur (ou une invocation ultérieure de cette compétence) agir sur l'une d'elles.

4. Appliquer

Une fois que les fichiers propres et manquants sont pris en compte et que chaque fichier modifié localement a été orienté vers l'une des trois sorties (ou délibérément refusé), appliquez :

node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <chemin> --apply

Ceci écrit les fichiers propres et manquants. Il n'écrit jamais un fichier modifié localement toujours refusé ; --force-managed est le seul chemin qui le fait, et uniquement pour le chemin nommé.

Si render a affiché une ligne warning: ... is git-ignored, arrêtez-vous et corrigez la règle d'ignore avant de continuer : une destination que git ne peut pas voir n'atteint jamais le vérificateur ou l'intégration continue (CI). Ignorez uniquement .claude/settings.local.json, jamais .claude/ ou .house/.

Si render ou le vérificateur a affiché warning: module is not in house.json, but <dir>/ exists here, un module a été expédié après que le house.json de ce dépôt a été écrit, et ses règles ne sont pas vendues tant que le dépôt n'ajoute pas "<name>": {"enabled": true} sous modules. N'ajoutez pas la clé vous-même : copiez la ligne d'avertissement textuellement dans le corps de la PR de synchronisation, sous une ligne indiquant qu'un nouveau module s'applique à ce dépôt et nécessite le choix de l'adopteur.

4b. Stager ce que render a écrit, par chemin

git add house.json .house/ .claude/rules/house/

Ajoutez scripts/house/ à cette commande uniquement lorsque le plan de render listait un fichier là-bas ; git refuse la commande entière lorsqu'un motif de chemin ne correspond à rien. Par chemin explicite, jamais git add -A : le vérificateur et le CI lisent git ls-files, donc un fichier rendu qui n'est pas stagé n'est vérifié par personne, et un ajout général balayerait tout ce qui traîne dans l'arbre.

La liste Scaffolded de render (.github/PULL_REQUEST_TEMPLATE.md, .github/workflows/pr-checks.yml, le squelette CLAUDE.md) n'est pas un fichier géré, donc l'avertissement [untracked] ne peut pas le voir : examinez ces fichiers, puis stagez-les également par chemin.

Un échafaudage est offert une fois par dépôt, pas une fois par rendu. La liste scaffolds du verrou enregistre quels modèles ce dépôt a déjà reçus ; un modèle enregistré là n'est jamais réécrit, que son fichier soit encore sur le disque ou non. Ainsi, un CLAUDE.md.house-skeleton qui a été fusionné dans CLAUDE.md et supprimé reste supprimé, et aucune resynchronisation n'a à faire rm dessus. Si un dépôt en veut un nouveau, render --apply --scaffold écrit tout échafaudage manquant et n'écrase toujours jamais un fichier qui est là. Attendez-vous à ce que la clé scaffolds apparaisse dans le diff du verrou lors de la première synchronisation à la version 0.2.3 ou ultérieure ; c'est un enregistrement, pas un hachage, et rien ne le refuse.

4c. Ignorer les données temporaires des outils

Assurez-vous que le .gitignore du dépôt contient .claude/worktrees/ et .superpowers/, en ajoutant la ligne manquante. Les données temporaires d'outil qui apparaissent dans git status sont à un git add -A d'être commitées.

5. Confirmer la version épinglée (pin)

Confirmez que house.json porte désormais la version du plugin chargé ; render l'a écrit, ne le modifiez jamais à la main. render --apply définit le champ version sur la version du plugin dans :

${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json

Ne lisez jamais installed_plugins.json pour vérifier cela. Il enregistre l'état d'installation entre les dépôts et peut être en retard ou différer de ce qui est chargé actuellement ; plugin.json sous CLAUDE_PLUGIN_ROOT est la version qui exécute réellement cette synchronisation.

6. Vérifier avec le vérificateur vendu

Exécutez le vérificateur comme le CI et le prebuild le feront réellement, pas la propre copie du plugin :

node .house/check.mjs

node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <chemin> exécute la logique identique par rapport à la propre charge utile du plugin et est utile avant que .house/check.mjs ait été vendu dans le dépôt (une première synchronisation). Une fois que la copie vendue existe, l'exécuter directement prouve que le fichier livré est le fichier qui réussit, pas une copie qui semble seulement similaire.

Un avertissement [untracked] ici signifie que l'étape 4b a été ignorée pour ce fichier ; stagez-le et réexécutez. Une constatation [gitignored] signifie que la règle d'ignore de l'étape 4 avale toujours un fichier géré.

7. Afficher la sortie du diagnostic

Après l'exécution du vérificateur, exécutez le diagnostic et rapportez ses lignes :

node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <chemin>

Ce que chaque ligne affichée signifie (étiquettes telles que doctor les imprime) :

  • effective branch guard: plugin | repo | NONE.
    • NONE : pas de house.json et pas de hook local au dépôt. Rien ne protège les commits directs vers une branche protégée pour le moment.
    • repo : un fichier .claude/hooks/no-direct-master.sh local au dépôt existe, ou .claude/settings.json porte un bloc hooks. Le hook du dépôt remporte la priorité lors de la migration ; le hook du plugin se retire et sort avec le code 0.
    • plugin : house.json existe et aucun signal de hook local au dépôt n'est présent. Le hook du plugin est celui qui applique réellement branchPolicy et protectedBranches. Il s'affiche comme plugin (enregistré le <date>) lorsque house.json porte un enregistrement guard et plugin (non enregistré) lorsque ce n'est pas le cas, ce qui concerne uniquement si l'avertissement guard du vérificateur est effacé : le hook applique la même chose dans les deux cas.
  • git-hook floor: .... Si l'arbre .githooks/ vendu est réellement connecté à git dans CE clone. core.hooksPath vit dans .git/config, donc c'est un état de machine qu'aucun clone, rendu ou PR ne transporte ; le vérificateur ne le lit jamais (l'ADR 0008 maintient le vérificateur uniquement dans le dépôt) et c'est là que le diagnostic le signale.
    • armed (core.hooksPath=<chemin>, <portée>) : git exécute le socle ici. Rien à faire.
    • NOT armed -- core.hooksPath est non défini dans ce clone : le socle est rendu et inerte. house render --apply l'arme, tout comme le démarrage d'une session dans le dépôt avec le plugin installé.
    • NOT armed -- core.hooksPath est <autre> : un autre outil (husky, lefthook, une convention de monorepo) possède le seul hooksPath que ce dépôt a. House ne l'écrase jamais. Chaînez le socle à partir des hooks là-bas, ou désactivez-le et réexécutez render.
    • not rendered here (manquant : <chemins>) : au moins un des sept fichiers du socle est absent, et la ligne nomme lesquels. Les sept manquants sont simplement un dépôt qui n'a pas encore rendu le socle. Un seul manquant est pire qu'il n'y paraît : chaque garde source .githooks/house-lib.sh et sort avec un code non nul lorsque cette source échoue, donc un socle auquel il manque seulement la bibliothèque fait échouer chaque commit fermé au lieu d'échouer ouvert. Dans les deux cas, render.
    • not applicable : pas de house.json à cette racine, ou branchPolicy n'est pas pr.
    • Les lignes de suivi en retrait rapportent ce qui rendrait le socle silencieux plutôt que protecteur. foreign hooks in this clone's .git/hooks : l'armement est refusé, car core.hooksPath remplace .git/hooks en totalité et les désactiverait silencieusement. not executable : git ignore silencieusement un hook sans le bit, donc un mode perdu est un échec ouvert ; render le restaure (ajoutant le bit uniquement pour les classes qui peuvent déjà lire le fichier, donc un fichier délibérément en mode 0600 revient en 0700 et n'est jamais élargi). reference-transaction: supported by git <version> (>= 2.28) ou inert on git <version> (needs 2.28) : sur git 2.28 et plus récent, le socle a un membre qu'aucun drapeau ne désactive, et la ligne inerte est un véritable écart plutôt que cosmétique. En dessous de git 2.28, --no-verify saute pre-commit et pre-push ensemble et rien d'autre n'est là pour l'attraper, donc sur ce git le drapeau n'est refusé que par le hook PreToolUse de session, qui n'est pas là quand aucune session n'est dans la boucle. Traitez la ligne comme une incitation à mettre à jour git, pas comme une note.
  • jq sur PATH : oui | non. Le hook refuse toujours sans (refus JSON écrit à la main), mais signalez l'écart pour qu'il soit corrigé.
  • pin vX correspond au plugin vY | pin vX diffère du plugin installé vY. version de house.json par rapport au propre plugin.json du plugin, la même comparaison qu'à l'étape 5. diffère signifie que le coup de pouce de l'épingle n'a pas encore atterri ou a été sauté.
  • npm wiring (.house/check.mjs référencé par) : <scripts> | aucun trouvé. Attendez-vous à un script check:docs (ou équivalent léger) invoquant .house/check.mjs --only=drift,todo et un script check:house invoquant le .house/check.mjs complet. Si l'un ou l'autre manque, imprimez l'extrait copiable plutôt que de modifier package.json directement :
    "check:docs": "node .house/check.mjs --only=drift,todo"
    "check:house": "node .house/check.mjs"
    
  • rule-load positive control: .... Si un hook InstructionsLoaded est câblé, et ce que son propre journal a réellement attesté ; sans cela, une règle dont le glob ne correspond jamais ressemble exactement à une règle qui ne fait rien. repo (.claude/settings.json) : le dépôt déclare son propre hook. plugin hook; log <chemin> : dernier chargement <ts>, <n> sur <m> règles vendues vues : le propre hook du plugin est câblé et a enregistré au moins un chargement, avec un nombre réel de combien de fichiers de règles vendus il a réellement vu charger. Lorsque <n> est inférieur à <m>, la ligne continue ; non vu dans ce journal : <noms>, nommant chaque règle vendue pour laquelle le journal ne porte aucun chargement, car le seul nombre dit que quelque chose ne va pas et jamais quel fichier ouvrir. Lisez cette liste comme une piste et non un verdict : le journal s'auto-élague, donc une règle peut y apparaître après avoir chargé il y a longtemps seulement, et la prochaine étape honnête est d'ouvrir un fichier que les paths: de la règle revendique et de réexécuter le diagnostic. Un nom qui survit à cela est une règle dont la portée n'atteint pas les fichiers pour lesquels elle a été écrite. plugin hook declared; pas encore de journal pour cette extraction : le hook du plugin est câblé mais n'a encore rien enregistré ici -- démarrez une session dans ce dépôt et réexécutez le diagnostic. none wired : rien ne déclare le hook du tout.
  • git-ignored house destinations: none | <chemins>. Tout sauf none est une destination que le vérificateur ne peut pas voir ; corrigez la règle d'ignore comme à l'étape 4.

8. Acheminer ce que le dépôt ne peut pas corriger en amont, un problème par élément

Un passage de synchronisation ou de conformité fait souvent remonter des constatations et des avertissements que seul le package peut traiter : un écart du vérificateur, un ancrage de règle nommant un fichier qui n'existe pas ici, un emplacement de configuration dont le dépôt a besoin et que le schéma n'a pas. Pour chaque élément de ce type, soit corrigez-le en amont dans la même session (branche et PR contre le dépôt du package, la même sortie amont d'abord qu'à l'étape 3), soit déposez UN problème par élément actionnable dans le dépôt du package, suffisamment petit pour être fermé avec un seul changement.

Ne les regroupez jamais en un problème de synthèse multi-éléments : une synthèse ne peut pas être fermée tant que son élément le plus lent n'atterrit pas, ses éléments ne peuvent pas être priorisés indépendamment, et les synthèses à moitié résolues s'accumulent. Ce qui reste dans ce dépôt n'est que ce que ce dépôt peut corriger.

Échappatoires

Ce sont des exceptions signalées en ligne dans le chemin par défaut ci-dessus, pas un menu séparé à choisir au départ :

  • Pas de house.json : arrêtez-vous à l'étape 1, pointez vers /house-rules:bootstrap.
  • Fichier modifié localement : les trois sorties à l'étape 3.
  • Modification locale confirmée jetable : --force-managed <chemin>, uniquement après avoir demandé.
  • Première synchronisation dans un dépôt, .house/check.mjs pas encore vendu : utilisez house check --repo <chemin> à l'étape 6 au lieu du chemin vendu, et notez qu'il s'agit d'une substitution ponctuelle, pas de l'état stable.

À ne pas faire

  • Ne fusionnez pas une modification locale...

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Skills associés