Bootstrap
Bootstrap 将一个未管理的仓库转变为 house 的消费者。它会探测仓库,提议一个 house.json,并在 --apply 时写入内联规则、模板以及一个 CLAUDE.md 骨架。它从不编辑已有的 CLAUDE.md,也绝不会对同一清单运行两次。它只写入 CLAUDE.md 中属于 house 的一半,作为单独的骨架文件,而将另一部分留给平台自身的 init 命令,该命令会生成初始的 CLAUDE.md 或对已有的文件提出改进建议。
此技能会在磁盘上产生副作用,因此它永远不会自行触发。仅在被要求时运行。
默认路径
- 试运行:探测仓库并打印提议的
house.json。不写入任何内容。 - 向操作者展示提议,并等待他们表示同意应用。
- 应用:写入
house.json,然后渲染规则、模板和骨架。 - 打印下方的连接块,以便操作者可以将其粘贴到
package.json、CI 及终端中。
不要跳过步骤 2。操作者从未见过的提议不是提议,而是意外。
当清单已存在时拒绝
在探测之前,先检查 house.json 是否已存在于仓库根目录。
如果存在,则拒绝。打印提示,说明仓库已有清单,并引导使用 /house-rules:sync。即便在试运行模式下也是如此:bootstrap 绝不会在已有第一个提议的基础上再起草第二个提议,即使第一个提议尚未应用。每个仓库只获得一次 bootstrap。
探测仓库
通过试运行 CLI 来收集提议所需的信息:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house init --repo <path>
探测过程仅读取,不写入:
- 技术栈:
package.json及其脚本是否存在,以及根目录下是否有框架配置文件。 - 默认分支:
git symbolic-ref refs/remotes/origin/HEAD,如果不可用则回退到当前分支。 - 顶层目录,用于推测哪些可选模块适用(
db/表明可能适用database,部署配置表明可能适用deployment,依此类推)。 - 是否已存在
.claude/rules/或分支保护钩子,以便提议说明 bootstrap 将添加什么,以及仓库已有什么。 - 仓库当前的文档扫描是否已经排除了存档层,以便根据观察行为设置
scanArchive,而非猜测。 git check-ignore是否表明任何 house 写入目标(.claude/rules/house/、.house/)被忽略。检查器会遍历git ls-files,因此被忽略的规则文件对它不可见,首次运行时会打印一个它从未赚取到的零。探测过程会发出警告并指出修复方法:只忽略.claude/settings.local.json,绝不能忽略.claude/或.house/。
提议 house.json
每个探测过程无法排除的模块都以 "detect" 而非 true 或 false 的形式放入提议中。"detect" 意味着由仓库在渲染时决定,而不是由技能替它猜测。核心模块(docs、engineering、github、claude-code)始终启用。打印完整的提议 house.json 正文,而不是摘要,以便审查者在写入任何内容之前能阅读每个字段。
应用:写入清单、规则和骨架
仅在操作者表示同意应用之后执行:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house init --repo <path> --apply
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --apply
init --apply 写入 house.json。render --apply 写入内联的规则文件、模板、.house/check.mjs、.house/lock.json、.house/INDEX.md,以及一个额外的文件:
- 如果仓库有 CLAUDE.md,则在其旁边写入
CLAUDE.md.house-skeleton。不要打开现有的 CLAUDE.md,也不要向其中写入内容。 - 如果仓库没有 CLAUDE.md,仍然写入
CLAUDE.md.house-skeleton,而不是CLAUDE.md。Bootstrap 绝不会创建仓库的根文件。操作者需要手动将骨架合并进去。
无论哪种情况,现有的 CLAUDE.md 在每次 bootstrap 运行前后都是字节完全相同的。这就是本技能所坚持的控制标准:在应用前进行差异对比,应用后再次进行差异对比,如果发现有变化,则停止运行并报告失败。
骨架文件每个仓库仅提供一次:render 会将其记录在 .house/lock.json 的 scaffolds 字段中,因此一旦它被合并到 CLAUDE.md 并删除,后续的任何渲染都不会再次写入它。render --apply --scaffold 是重新请求它的方法。
确保仓库的 .gitignore 包含 .claude/worktrees/ 和 .superpowers/,并追加缺失的行。工具产生的临时文件出现在 git status 中时,只需一个 git add -A 就会被提交。
打印连接块
在成功应用后,逐字打印以下块,以便可以原样复制粘贴到终端中。不要填写任何内容;由操作者根据其 package.json 和工作流文件进行调整。
添加到 package.json 脚本中:
"check:docs": "node .house/check.mjs --only=drift,todo"
"check:house": "node .house/check.mjs"
添加一个执行以下操作的 CI 步骤:
node .house/check.mjs
每台机器安装一次插件:
claude plugin marketplace add dubbl-a/house-rules
claude plugin install house-rules@house-rules --scope user
每个克隆库启用一次 git 钩子(render --apply 和每次会话启动时也会执行此操作):
git config core.hooksPath "$(pwd)/.githooks"
core.hooksPath 位于 .git/config 中,任何克隆或 PR 都不会携带该配置,因此内联的 .githooks/ 目录在全新的检出中是无效的,直到某些内容设置了它。render --apply 和插件的 SessionStart 钩子都会启用它;上面的行适用于没有这两者的克隆库。这行命令或操作者都不应覆盖其他工具已拥有的 core.hooksPath。
如果仓库没有 .claude/settings.local.json,则在打印输出中说明。该文件是每个仓库选择退出某个 house 模块或钩子的地方,缺少该文件意味着仓库仅使用默认设置运行。
Bootstrap 之后
告知操作者尚未完成的事项:骨架文件需要手动合并到 CLAUDE.md 中然后删除(之后不会再写入),连接块仍需粘贴,并且在首次提交之前值得在本地运行 node .house/check.mjs,以便仓库从一个干净的门槛开始,而不是继承一个失败的状态。按路径暂存渲染的文件(house.json .house/ .claude/rules/house/,并且仅当 render 列出了 scripts/house/ 中的文件时才暂存它,因为 git 拒绝匹配任何不存在的路径规范):在暂存之前,清单家族会为每个文件报告 [untracked],而整个 .claude/ 或 .house/ 的忽略则是一个 [gitignored] 的结果,因为 git 看不见的文件是不会被家族检查的。这些都不是本技能的工作;bootstrap 在渲染后即停止。
禁止
- 不要在试运行期间写入
house.json或任何渲染后的文件。试运行只打印。 - 永远不要覆盖或追加到现有的 CLAUDE.md,无论在任何标志下都不行。
- 不要对已有
house.json的仓库重新提议。请将其引导到/house-rules:sync。 - 当探测结果不明确时,不要猜测模块是开启还是关闭。提议
"detect"并让仓库决定。