bootstrap-repo

搭建项目脚手架

为全新仓库搭建基础框架，并验证其达到基线要求：构建一个骨架，确保每个质量工具都已接入且运行正常，让第一个功能从全绿状态开始。

不要跳到功能代码。交付内容是工具链，并通过一个示例测试证明其有效，仅此而已。

跟踪进度

为以下每个步骤（0–4）创建一项待办，并按顺序完成；只有在满足对应的 完成条件 后，才将该项标记为完成。步骤 0 是一道关卡：如果它阻止你继续（目标不是全新项目），就放弃清单并转向其他流程。否则，这道关卡要防止的就是跳过步骤——基线从未经过验证，或忘了将工作移交给 configure-repo。

0. 确认目标是全新项目 — 关卡

搭建脚手架会写入项目根目录（git 仓库、根目录清单文件、根目录 README、根目录 CI、根目录 pre-commit 钩子）。在现有项目上这么做会造成冲突，或覆盖真实配置。因此，开始之前，先确定要在哪个位置搭建脚手架，并确认该位置为空。此关卡不可跳过，也不能凭感觉判断——请运行检查。

确定目标目录。 默认使用当前工作目录。如果用户指定了目标位置（例如“在 packages/ 下搭建一个 bot 包的脚手架”），目标就是该路径。如果当前工作目录本身是已填充内容的仓库根目录，但用户要求创建一个新子包，则将目标确定为该新子目录，并对该目录进行分类——不要停留在仓库根目录的判断结果上。

自行检查（绝不要询问用户目录中有什么——自己查看）：

• ls -A <target> — 目录是否存在，是否为空？
• git -C <target> rev-parse --is-inside-work-tree 和 git -C <target> ls-files | wc -l — 目录是否位于 git 仓库中？有多少文件已被跟踪？
• 目标目录中是否有包清单文件（package.json、Cargo.toml、pyproject.toml、go.mod 等）？

分类并选择后续操作：

目标状态	含义	操作
目录不存在，或目录存在但为空／仅包含 .git、README、LICENSE，且没有清单文件	全新项目	继续步骤 1。
位于现有 git 仓库内的新建／空子目录（例如 monorepo 中的 packages/bot）	子包	以该子目录为目标继续步骤 1，并设置 inside-existing-repo = true（步骤 2 跳过会触及仓库根目录的部分）。
目录存在且包含清单文件或许多已跟踪文件——这是一个真实项目	不是全新项目 — 停止	不要搭建脚手架。按下文指引转向其他流程。

必须停止时，应按以下方式转向，不要自行列出选项：

• 如果用户想在现有仓库中使用这套技能（配置跟踪器、验证命令、完善文档），那应该使用 configure-repo，而不是搭建脚手架。请告知用户运行该流程。
• 如果用户想在此仓库中创建新包，请确认新子目录路径，然后针对该子目录重新运行此关卡（应归入“子包”一行）。
• 如果用户误入此流程，则停止并让他们重新考虑。

说明你检测到的情况，以及适用的转向方式。**完成条件：**目标已分类为全新项目或子包，且已与用户确认最终路径；或者你已停止并指出应转向的流程。

1. 确定技术栈

必需子技能：使用 clarify-decisions 确定目标的技术栈和布局；每项都必须使用完整的问题卡片（仅内联呈现），并包含选项、后果和推荐的默认选项：

• 项目名称（用于清单文件和 README）
• 语言和运行时
• 框架（或“无——普通库／CLI”）
• 测试运行器
• 格式化工具和代码检查工具
• 包管理器
• 仓库布局（单包还是工作区／monorepo；源代码和测试目录的结构）
• 许可证
• 先提交或暂存结果以供审核

自行查明事实（用户已安装哪些工具、子包模式下父仓库已使用什么）；只将需要判断的事项交给用户决定。

**完成条件：**以上每项决定都已得到明确确认，并在一个摘要块中重新陈述——包括已确定的目标路径——且用户已批准该摘要。

2. 搭建脚手架

根据已确认的选择，在确定的目标位置搭建骨架。在子包模式（inside-existing-repo = true）下，跳过标记为 (仅根目录) 的步骤——父级仓库已经负责这些事项——并继承父级的共享配置，而不是创建重复配置。

1. Git (仅根目录) — 如果该目录尚未是仓库，则运行 git init；为技术栈编写合理的 .gitignore。在子包模式下，不要初始化 Git，也不要修改根目录的 .gitignore；仅在需要时添加包级别的忽略文件。
2. 项目骨架 — 清单、源代码目录和最小入口点。在子包模式下，扩展工作区的共享工具链配置（例如，让 tsconfig 继承根配置），并将该包注册到工作区。
3. 测试框架 — 安装并配置测试运行器，另外提供且仅提供一个通过的示例测试。该测试用于证明各部分已正确连接（导入可以解析、运行器能找到文件、断言可以执行），而不是测试实际行为。
4. 格式化工具和代码检查工具配置 — 提交配置文件，并确保 format、lint 和 typecheck（如适用）都能通过单条命令运行。在子包模式下，继承根配置，仅添加包级别的覆盖项。
5. 提交前钩子 (仅根目录) — 每次提交时：格式化已暂存文件，然后运行 lint、typecheck 和 test。使用该技术栈惯用的钩子机制。在子包模式下，将钩子集成到父级仓库现有的钩子中（作用范围限定为该包），而不是安装另一个根级钩子。
6. CI 存根 (仅根目录) — 创建一个工作流，在推送和拉取请求时运行相同的验证命令。在子包模式下，向现有 CI 添加一个按包筛选的任务，而不是编写新的流水线。
7. README 骨架 — 项目名称、一段描述占位文本，以及安装和验证命令。将其放在目标位置（子包模式下：<target>/README.md，绝不要放在仓库根目录）。
8. 文档种子文件 — CONTEXT.md（来自技能集的 templates/CONTEXT.md）、 docs/specs/INDEX.md（来自 templates/specs-INDEX.md 的领域路由文件）、 docs/specs/catalog/app.md（来自 templates/specs-catalog-domain.md，领域为 App），以及一个空的 docs/adr/ 目录，以上路径均相对于目标位置。按以下顺序解析种子文件包，使用第一个存在的路径：(1) 此 SKILL.md 同级的 templates/， (2) 设置了该变量时的 ${CLAUDE_PLUGIN_ROOT}/templates，(3) 相对于此 SKILL.md 的 ../../../templates。可选的项目文档层： 只询问一次（全新且包含多个功能的项目通常受益；小型项目可以跳过，之后通过 /define-project 添加）。如果用户选择启用，还要根据 templates/product-vision.md、 templates/architecture-INDEX.md 和 templates/product-guidelines.md 创建 docs/product/vision.md、docs/architecture/INDEX.md 和 docs/product/guidelines.md。如果用户拒绝，则不创建这些文件——configure-repo 的写入交接仍可启用该层。

完成标准： 所有适用项目均已存在并已提交（或按用户在第 1 步中的选择暂存）。

3. 验证基线

必须使用子技能：使用 prove-claim——重新运行完整的验证套件（typecheck、lint、test），并阅读输出。在根目录模式下，还要证明提交前钩子确实会触发并通过（可使用一次性提交或试运行）。

如果交接时存在失败或未经验证的检查，则脚手架尚未完成。继续之前，修复或移除导致问题的部分。

完成标准： 每条验证命令均通过，并已向用户展示通过的输出。

4. 交接

告知用户脚手架已完成，下一步是运行 configure-repo，以编写面向 Agent 的配置（docs/agents/*.md — 验证命令、跟踪工具、标签、发布步骤）。不要自行编写 docs/agents/；该向导负责管理它。

**整个技能的完成标准：**从仓库根目录运行一条命令安装依赖，再运行一条命令通过目标的验证套件 — 在最终摘要中明确写出这两条命令（在子包模式下，将验证命令限定为新包）。