Communitygithub.com

dubbl-a/house-rules

Este skill deve ser usado quando o usuário executar "/house-rules:sync", ou pedir para "sincronizar house", "atualizar regras vendidas", "puxar a versão house mais recente" ou "verificar arquivos gerenciados por edições locais".

O que é house-rules?

O skill `dubbl-a/house-rules` sincroniza arquivos de house rules (regras de desenvolvimento) entre um repositório e um plugin instalado, garantindo que edições locais nunca sejam descartadas silenciosamente. Ele é invocado exclusivamente através do comando `/house-rules:sync`, sendo projetado para escrever arquivos e não para consultas simples (essas devem usar `/house-rules:conventions`). O skill segue um fluxo determinístico que começa verificando a existência do arquivo `house.json` (se ausente, solicita bootstrap), executa um planejamento seco (dry-run) usando `node scripts/house render`, classifica cada arquivo gerenciado como limpo, ausente ou modificado localmente. Arquivos modificados localmente nunca são sobrescritos automaticamente: o skill oferece três saídas explícitas — enviar a mudança upstream, registrar uma derivação e desgerenciar o arquivo, ou forçar a sobrescrita com confirmação. Após o planejamento, a etapa de aplicação escreve arquivos limpos e ausentes, faz o staging por caminhos específicos, configura gitignore, confirma a versão do plugin, executa o verificador vendado e o doutor (`house doctor`) para relatar o estado completo do repositório. O skill também roteia problemas que o repositório não pode corrigir para issues únicas no repositório do pacote, evitando issues digest. Ele suporta qualquer repositório que adote house-rules, especialmente aqueles que usam plugins como Claude Code, Cursor ou Codex para gerenciar regras de desenvolvimento compartilhadas.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Sincronização House

Atualiza os arquivos house de um repositório com o plugin instalado, sem nunca descartar uma edição local silenciosamente. Invoque este skill apenas através de /house-rules:sync. Não é um skill de consulta e escreve arquivos, portanto nunca é acionado por uma pergunta simples sobre convenções (use /house-rules:conventions para isso).

O CLI que este skill controla:

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

--repo padrão é o diretório atual. Nada abaixo inventa um subcomando fora de init, render, check.

Caminho padrão: planejar, depois aplicar

A sincronização tem exatamente um caminho padrão. Execute-o nesta ordem toda vez.

1. Confirme que o repositório adotou house

Leia house.json na raiz do repositório. A ausência de house.json significa que este repositório nunca foi inicializado: pare e informe ao usuário para executar /house-rules:bootstrap primeiro. Não trate um manifesto ausente como "nada para sincronizar".

2. Planejamento (execução seca)

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

Sem --apply, isso apenas planeja. Ele lê .house/lock.json (cada entrada: path, module, source, bodySha256) e compara o hash atual do corpo de cada arquivo gerenciado no disco com o lock, e então com o que o novo corpo renderizado seria. Classifique cada arquivo gerenciado em exatamente um balde:

  • Limpo. O hash no disco corresponde ao lock. Plano: sobrescrever com o corpo recém-renderizado.
  • Ausente. Arquivo ausente no disco. Plano: restaurá-lo.
  • Modificado localmente. O hash no disco não corresponde nem ao lock nem a uma renderização sem alterações. Plano: recusar. Veja as três saídas abaixo.

Imprima o plano antes de fazer qualquer outra coisa. Não aplique nada neste passo, mesmo para arquivos limpos ou ausentes.

3. Modificado localmente: três saídas, nunca uma escolha silenciosa

Um arquivo gerenciado modificado localmente não é mesclado, sobrescrito ou deixado quieto por si só. Imprima o diff entre o arquivo no disco e o que house renderizaria, depois imprima exatamente estas três saídas, nesta ordem, e pare para o arquivo (ele permanece intacto sob --apply também, é simplesmente excluído da escrita):

  1. Upstream-first. Abra um PR contra o próprio repositório do pacote house (dubbl-a/house-rules) carregando a alteração pretendida, para que a edição se torne a nova regra house para todos, em vez de um fork privado. Esta é a saída preferida.
  2. Registre um desvio e desgerencie. Adicione uma entrada ao array deviations do house.json com um why, remova o arquivo do conjunto gerenciado e espelhe-o na seção ## Deviations from house do CLAUDE.md do repositório. Use isso quando a edição for genuinamente específica do repositório e nunca for para o upstream.
  3. Force a sobrescrita. Execute:
    node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <caminho> --force-managed <caminho>
    
    Use isso apenas quando a edição local for confirmadamente descartável, nunca como padrão porque é o mais rápido. Peça confirmação ao usuário antes de executar; nunca escolha por conta própria sem solicitação.

Não ofereça uma quarta opção e não transforme isso em um menu interativo que fica em loop esperando uma escolha. Apresente as três saídas como o resultado da execução, então deixe o usuário (ou uma invocação posterior deste skill) agir sobre uma.

4. Aplicar

Depois que os arquivos limpos e ausentes forem contabilizados e cada arquivo modificado localmente tiver sido direcionado para uma das três saídas (ou deliberadamente deixado recusado), aplique:

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

Isso escreve arquivos limpos e ausentes. Nunca escreve um arquivo modificado localmente que ainda foi recusado; --force-managed é o único caminho que faz isso, e apenas para o caminho nomeado.

Se o render imprimiu uma linha warning: ... is git-ignored, pare e corrija a regra de ignore antes de continuar: um destino que o git não vê nunca chega ao verificador ou CI. Ignore apenas .claude/settings.local.json, nunca .claude/ ou .house/.

Se o render ou o verificador imprimiu warning: module is not in house.json, but <dir>/ exists here, um módulo foi enviado após a escrita do house.json deste repositório, e suas regras não estão vendidas até que o repositório adicione "<nome>": {"enabled": true} sob modules. Não adicione a chave você mesmo: copie a linha de aviso literalmente no corpo do PR de sincronização, sob uma linha dizendo que um novo módulo se aplica a este repositório e precisa da escolha do adotante.

4b. Faça stage do que o render escreveu, por caminho

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

Adicione scripts/house/ a esse comando apenas quando o plano de render listar um arquivo lá; o git recusa o comando inteiro quando qualquer pathspec não corresponde a nada. Por caminho explícito, nunca git add -A: o verificador e o CI leem git ls-files, então um arquivo renderizado que não foi staged é um que ninguém verifica, e um add geral varreria qualquer outra coisa que esteja na árvore.

A lista Scaffolded do render (.github/PULL_REQUEST_TEMPLATE.md, .github/workflows/pr-checks.yml, o esqueleto CLAUDE.md) não é um arquivo gerenciado, então o aviso [untracked] não pode vê-lo: revise esses arquivos, depois faça stage deles também por caminho.

Um scaffold é oferecido uma vez por repositório, não uma vez por render. A lista scaffolds do lock registra quais templates este repositório já recebeu; um template registrado lá nunca é escrito novamente, mesmo que seu arquivo ainda esteja no disco. Portanto, um CLAUDE.md.house-skeleton que foi mesclado em CLAUDE.md e deletado permanece deletado, e nenhuma nova sincronização precisa fazer rm dele. Se um repositório quiser um de volta, render --apply --scaffold escreve qualquer scaffold ausente e ainda nunca sobrescreve um arquivo que está lá. Espere que a chave scaffolds apareça no diff do lock na primeira sincronização na versão 0.2.3 ou posterior; é um registro, não um hash, e nada recusa com base nele.

4c. Gitignore de ferramenta scratch

Garanta que o .gitignore do repositório contenha .claude/worktrees/ e .superpowers/, acrescentando a linha que estiver faltando. O scratch de ferramenta que aparece em git status está a um git add -A de ser commitado.

5. Confirme o pin

Confirme que house.json agora carrega a versão do plugin carregado; o render o escreveu, nunca edite manualmente. render --apply define o campo version para a versão do plugin em:

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

Nunca leia installed_plugins.json para verificar isso. Ele registra o estado de instalação entre repositórios e pode atrasar ou diferir do que está carregado no momento; plugin.json sob CLAUDE_PLUGIN_ROOT é a versão que realmente está executando esta sincronização.

6. Verifique com o verificador vendado

Execute o verificador como CI e prebuild realmente o executarão, não a cópia do próprio plugin:

node .house/check.mjs

node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <caminho> executa a lógica idêntica contra a carga útil do próprio plugin e é útil antes de .house/check.mjs ter sido vendado no repositório (uma primeira sincronização). Uma vez que a cópia vendada existe, executá-la diretamente prova que o arquivo que é enviado é o que passa, não uma cópia que apenas parece igual.

Um aviso [untracked] aqui significa que o passo 4b foi pulado para aquele arquivo; faça stage dele e execute novamente. Um achado [gitignored] significa que a regra de ignore do passo 4 ainda engole um arquivo gerenciado.

7. Imprima a saída do doutor

Após a execução do check, execute o doutor e relate suas linhas:

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

O que cada linha impressa significa (rótulos como o doctor os imprime):

  • effective branch guard: plugin | repo | NONE.
    • NONE: nenhum house.json e nenhum hook local do repositório. Nada está protegendo commits diretos para um branch protegido agora.
    • repo: um arquivo .claude/hooks/no-direct-master.sh local do repositório existe, ou .claude/settings.json carrega um bloco hooks. O hook do repositório vence durante a migração; o hook do plugin recua e sai com código 0.
    • plugin: house.json existe e nenhum sinal de hook local do repositório está presente. O hook do plugin é o que realmente está aplicando branchPolicy e protectedBranches. Ele imprime como plugin (recorded <data>) quando house.json carrega um registro guard e plugin (unrecorded) quando não, o que é apenas sobre se o aviso do verificador guard está limpo: o hook aplica o mesmo de qualquer forma.
  • git-hook floor: .... Se a árvore .githooks/ vendada está realmente conectada ao git NESTE clone. core.hooksPath vive em .git/config, então é estado da máquina que nenhum clone, nenhum render e nenhum PR carrega; o verificador nunca o lê (ADR 0008 mantém o verificador apenas no repositório) e o doctor é onde ele é relatado.
    • armed (core.hooksPath=<caminho>, <escopo>): git executa o floor aqui. Nada a fazer.
    • NOT armed -- core.hooksPath is unset in this clone: o floor está renderizado e inerte. house render --apply o arma, e também o início de uma sessão no repositório com o plugin instalado.
    • NOT armed -- core.hooksPath is <outro>: outra ferramenta (husky, lefthook, uma convenção de monorepo) possui o único hooksPath que este repositório tem. House nunca o sobrescreve. Encadeie o floor a partir dos hooks lá, ou desdefina-o e execute render novamente.
    • not rendered here (missing: <caminhos>): pelo menos um dos sete arquivos do floor está ausente, e a linha nomeia quais. Todos os sete ausentes é simplesmente um repositório que ainda não renderizou o floor. Um ausente é pior do que parece: todo guard faz source de .githooks/house-lib.sh e sai com código não zero quando esse source falha, então um floor faltando apenas a biblioteca faz todo commit falhar fechado em vez de falhar aberto. De qualquer forma, render.
    • not applicable: nenhum house.json nesta raiz, ou branchPolicy não é pr.
    • As linhas subsequentes indentadas relatam o que tornaria o floor silencioso em vez de protetivo. foreign hooks in this clone's .git/hooks: armar é recusado, porque core.hooksPath substitui .git/hooks completamente e os desabilitaria silenciosamente. not executable: git ignora silenciosamente um hook sem a permissão, então um modo perdido é uma falha aberta; render o restaura (adicionando a permissão apenas para as classes que já podem ler o arquivo, então um arquivo deliberadamente 0600 volta como 0700 e nunca é ampliado). reference-transaction: supported by git <versão> (>= 2.28) ou inert on git <versão> (needs 2.28): no 2.28 e mais novos, o floor tem um membro que nenhuma bandeira desliga, e a linha inerte é uma lacuna real em vez de cosmética. Abaixo de 2.28 --no-verify pula pre-commit e pre-push juntos e nada mais está lá para pegá-lo, então nesse git a bandeira é recusada apenas pelo hook PreToolUse de sessão, que não está lá quando nenhuma sessão está no loop. Trate a linha como um incentivo para atualizar o git, não como uma nota.
  • jq on PATH: yes | no. O hook ainda nega sem ele (deny JSON escrito à mão), mas relate a lacuna para que seja corrigida.
  • pin vX matches plugin vY | pin vX differs from installed plugin vY. version do house.json contra o plugin.json do próprio plugin, a mesma comparação do passo 5. differs significa que o bump do pin ainda não foi implantado ou foi pulado.
  • npm wiring (.house/check.mjs referenced by): <scripts> | none found. Espere um script check:docs (ou equivalente leve) invocando .house/check.mjs --only=drift,todo e um script check:house invocando .house/check.mjs completo. Se algum estiver faltando, imprima o snippet copiável em vez de editar package.json diretamente:
    "check:docs": "node .house/check.mjs --only=drift,todo"
    "check:house": "node .house/check.mjs"
    
  • rule-load positive control: .... Se um hook InstructionsLoaded está conectado, e o que seu próprio log realmente testemunhou; sem um, uma regra cujo glob nunca corresponde parece exatamente como uma regra que não faz nada. repo (.claude/settings.json): o repositório declara seu próprio hook. plugin hook; log <caminho>: last load <ts>, <n> of <m> vendored rules seen: o hook do próprio plugin está conectado e registrou pelo menos um load, com uma contagem real de quantos arquivos de regra vendados ele realmente viu carregar. Quando <n> é menor que <m>, a linha continua ; not seen in this log: <nomes>, nomeando cada regra vendada para a qual o log não carrega, porque a contagem sozinha diz que algo está errado e nunca qual arquivo abrir. Leia essa lista como uma pista e não um veredito: o log se auto-apara, então uma regra pode aparecer lá após carregar apenas há muito tempo, e o próximo passo honesto é abrir um arquivo que a regra paths: afirma e executar doctor novamente. Um nome que sobrevive a isso é uma regra cujo escopo não está alcançando os arquivos para os quais foi escrito. plugin hook declared; no log yet for this checkout: o hook do plugin está conectado mas não registrou nada aqui ainda -- inicie uma sessão neste repositório e execute doctor novamente. none wired: nada declara o hook.
  • git-ignored house destinations: none | <caminhos>. Qualquer coisa diferente de none é um destino que o verificador não pode ver; corrija a regra de ignore como no passo 4.

8. Roteie o que o repositório não pode corrigir upstream, um item por issue

Uma passagem de sincronização ou conformidade frequentemente revela achados e avisos que apenas o pacote pode resolver: uma lacuna no verificador, um nome de âncora de regra que nomeia um arquivo que não existe aqui, um slot de configuração que o repositório precisa e o esquema não possui. Para cada item, corrija-o upstream na mesma sessão (branch e PR contra o repositório do pacote, a mesma saída upstream-first do passo 3) ou abra UMA issue por item acionável no repositório do pacote, pequena o suficiente para ser fechada com uma única alteração.

Nunca coloque em lote em uma issue digest de múltiplos itens: um digest não pode ser fechado até que seu item mais lento chegue, seus itens não podem ser priorizados independentemente e digests meio resolvidos se acumulam. O que fica neste repositório é apenas o que este repositório pode corrigir.

Saídas de escape

Estas são exceções levantadas inline no caminho padrão acima, não um menu separado para escolher de antemão:

  • Sem house.json: pare no passo 1, aponte para /house-rules:bootstrap.
  • Arquivo modificado localmente: as três saídas no passo 3.
  • Edição local confirmadamente descartável: --force-managed <caminho>, apenas depois de perguntar.
  • Primeira sincronização em um repositório, .house/check.mjs ainda não vendado: use house check --repo <caminho> no passo 6 em vez do caminho vendado, e note que esta é uma substituição única, não o estado estável.

Não

  • Não mescle uma modificação local sem decisão explícita.
  • Não ofereça um menu interativo no lugar das três saídas.
  • Não use git add -A.

Individual skills in this repo

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

Habilidades Relacionadas