scaffold-project

搭建项目脚手架

为一个全新仓库搭建基础结构，并验证其达到基准要求：创建一个骨架项目，其中每个质量工具都已接入并有明确的运行证明，让第一个功能从全绿状态开始。

不要提前编写功能代码。交付内容仅限工具链，并通过一个示例测试证明其有效。

跟踪进度

为以下每个步骤（0–4）创建一项待办，并按顺序完成；只有满足各步骤的 完成条件 后，才能将其勾选。步骤 0 是一道关卡：如果它阻止你继续（目标并非全新项目），就放弃这份清单并转到相应流程。否则，这道关卡旨在防止漏掉步骤——基准从未得到验证，或者忘记移交给 setup-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 仓库中的新建／空子目录（例如，单体仓库中的 packages/bot）	子包	以该子目录为目标继续执行步骤 1，并设置 inside-existing-repo = true（步骤 2 跳过会触及根目录的部分）。
目录已存在，且包含清单文件或许多已跟踪文件——这是一个真实项目	并非全新项目——停止	不要搭建脚手架。转到下方所述流程。

必须停止时，应转到相应流程——不要自行列出选项：

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

说明你检测到的情况，以及适用的转向流程。完成条件： 已将目标分类为全新项目或子包，并与用户确认解析后的路径；或者已停止并说明应转到哪个流程。

1. 详细确定技术栈

必需的子技能：使用 grilling 确定目标的技术栈和目录布局决策——每个问题都必须使用完整的问题卡（仅限内联），并包含选项、影响和推荐默认值：

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

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

完成条件： 上述每项决策都已明确确认，并在一个摘要块中重述——包括解析后的目标路径——且用户已批准。

2. 搭建脚手架

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

1. Git (仅根目录) — 如果目录还不是 Git 仓库，则运行 git init；为所用技术栈编写合理的 .gitignore。在子包模式下，不要初始化 Git，也不要修改根目录的 .gitignore；只有在需要时才添加包级忽略配置。
2. 项目骨架 — 清单文件、源代码目录和最精简的入口文件。在子包模式下，扩展工作区的共享工具链配置（例如，tsconfig 继承根目录配置），并将该包注册到工作区。
3. 测试框架 — 安装并配置测试运行器，另外添加恰好一个通过的示例测试。该测试的目的是验证各部分已正确连通（导入可解析、运行器能找到文件、断言能执行），而不是测试实际功能。
4. 格式化工具和代码检查配置 — 提交配置文件，并确保 format、lint 和 typecheck（适用时）都能通过单条命令运行。在子包模式下，继承根目录配置，只添加包级覆盖项。
5. 提交前钩子 (仅根目录) — 每次提交时：格式化暂存文件，然后运行 lint、typecheck 和测试。使用该技术栈惯用的钩子机制。在子包模式下，将钩子集成到父级仓库现有钩子中（限定到该包），不要另行安装重复的根目录钩子。
6. CI 桩 (仅根目录) — 添加一个工作流，在 push 和 pull request 时运行相同的验证命令。在子包模式下，向现有 CI 添加一个筛选该包的任务，不要另建一条流水线。
7. README 骨架 — 项目名称、一段描述占位文本，以及安装和验证命令。将文件放在目标位置（子包模式下：<target>/README.md，绝不能放在仓库根目录）。
8. 文档种子文件 — 在目标目录下创建 CONTEXT.md（取自技能集的 templates/CONTEXT.md）、docs/specs/INDEX.md（取自 templates/specs-INDEX.md）和一个空的 docs/adr/ 目录。**可选的项目文档层：**只询问一次（全新且功能较多的项目会受益；小型项目可以跳过，之后通过 /establish-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。如果用户拒绝，不要创建其中任何文件——移交给 setup-repo 后仍可启用该文档层。

**完成条件：**所有适用条目均已创建并提交（或按用户在第 1 步中的选择暂存）。

3. 验证基线

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

如果脚手架移交时存在失败或尚未验证的检查，就不算完成。继续之前，请修复或移除有问题的部分。

**完成条件：**所有验证命令均通过，并且已向用户展示通过的输出。

4. 移交

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

**整个技能的完成标准：**从仓库根目录运行，一条命令即可安装依赖，另一条命令即可使目标的验证套件全部通过——在最终总结中明确写出这两条命令（子包模式下，验证命令应限定到新建的包）。