set-up-project

设置项目

搭建并审查各仓库的配置，供各项技能使用：

• 规则文件：AGENTS.md，每个运行环境都会读取。CLAUDE.md 要么是单行 @AGENTS.md，要么是指向 AGENTS.md 的符号链接。如果存在 CLAUDE.md，Claude Code 会跳过项目的 AGENTS.md；上述两种形式都能让它读取相同的文本。
• 问题跟踪器：问题的存放位置。默认使用 GitHub，本地 Markdown 也开箱即用。
• 分类标签：用于五种标准分类角色的字符串
• 领域文档：GLOSSARY.md 和 ADR 的存放位置，以及读取这些文档的使用方规则
• 发布生命周期：docs/agents/releasing.md 说明项目如何发布版本，以便所有发布者遵循相同步骤。如果用户的工作站仓库中有共享发布规则，则从这些规则开始。
• 文件夹标准：orchestrating/folder-standard.md 中的 .gitignore 条目
• 仅允许项目权限：全局规则是这台机器的安全防护，项目自己的运行环境文件只提供便利。审查会标记每个削弱全局规则的项目文件。

你先进行探索，展示发现并与用户确认，然后再写入。再次运行时即为审查。

步骤

1. 检查机器

运行 set-up-machine 的验证器：在与本技能并列安装的 set-up-machine 技能中执行 python3 <set-up-machine skill>/scripts/verify.py。通过时退出代码为 0。如果退出代码不为 0，请先运行 set-up-machine 技能，然后再回来。验证器以退出代码 0 结束后，即完成此步骤。

2. 探索

检查当前仓库，了解其初始状态。读取所有现有内容；不要想当然：

• git remote -v 和 .git/config：这是 GitHub 仓库吗？是哪一个？
• 仓库根目录中的 AGENTS.md 和 CLAUDE.md：是否存在其中任一个？其中是否已有 ## Agent skills 或 ## Environment defaults 部分？
• 仓库根目录中的 GLOSSARY.md 和 GLOSSARY-MAP.md，以及仓库中任何 CONTEXT.md 或 CONTEXT-MAP.md：这些是技能已不再读取的领域文档旧名称
• docs/adr/ 和任何 src/*/docs/adr/ 目录
• docs/agents/：此技能之前的输出是否已存在？
• .efforts/：这表明已在使用本地 Markdown 问题跟踪器
• docs/assets/：这是文件夹标准中的旧图片文件夹
• 是否已安装 triage 技能？如果与本技能并列存在 triage 技能文件夹，或 triage 在可用技能列表中，则表示已安装。这决定是否会运行 B 节。
• 单体仓库信号：pnpm-workspace.yaml、package.json 中的 workspaces 字段，或带有自身 src/ 的非空 packages/*。只有真正的大型多包仓库才会存在这些信号；没有这些信号则表示是单上下文仓库，几乎所有仓库都是如此。
• 项目当前的发布方式：查找 CHANGELOG.md、保存版本号的文件、标签，以及 gh release list 显示的 GitHub Releases；还要查找向注册表发布的内容，以及 AGENTS.md 或其他文档中已有的发布步骤。没有 "private": true 的 package.json、Homebrew cask 和发布工作流都会向注册表发布。这些信号决定是否会运行 E 节。
• 用户的共享发布规则：如果指针 ~/.config/agents/source.md 指向某个工作站仓库，则在文件存在时读取 <path-to-workstation-repo>/setup/releasing.md。如果没有指针或该文件不存在，则仅以种子模板为起点。
• 项目自己的文档是否要求角色技能名称对应的工具，例如 docs/worktrees.md 中提到的 worktree 工具，或其脚本依赖的会话主机。这决定是否会运行 D 节。

3. 展示发现并提问

总结已有内容和缺失内容。然后按顺序逐个处理这些部分。一次处理一个部分，给出一个答案，然后再处理下一个。

每个部分都先给出推荐答案，让用户可以用一个词接受。只有在选项确实存在分歧时，才用一行说明；如果探索已经确定了结果，则跳过该部分。

如果未安装 triage，跳过 Section B；如果既没有 monorepo，也没有旧版 CONTEXT.md 或 CONTEXT-MAP.md，跳过 Section C；如果项目没有为某个角色指定工具，跳过 Section D；如果项目从未发布过且没有发布信号，跳过 Section E。

Section A：问题跟踪器

说明：对于此仓库，“问题跟踪器”是存放问题的地方。to-tickets、triage 和 to-spec 等技能会从中读取内容并写入其中。它们需要知道应该调用 gh issue create、在 .efforts/ 下写入 Markdown 文件，还是遵循你描述的其他工作流。请选择你实际用来跟踪此仓库工作事项的地方。

默认建议：这些技能是为 GitHub 设计的。如果 git remote 指向 GitHub，则建议使用 GitHub。如果 git remote 指向 GitLab（无论是 gitlab.com 还是自托管主机），则建议使用 GitLab。 否则，或者用户偏好其他跟踪器时，提供以下选项：

• GitHub：问题存放在仓库的 GitHub Issues 中，通过 gh CLI 操作。
• GitLab：问题存放在仓库的 GitLab Issues 中，通过 glab CLI 操作。
• 本地 Markdown：问题以文件形式存放在此仓库的 .efforts/<effort>/ 下，适合个人项目和没有远程仓库的项目。
• 其他，例如 Jira 或 Linear：请用户用一段话描述工作流，并将其作为自由文本记录。

将选择记录在 docs/agents/issue-tracker.md 中。GitHub 和 GitLab 模板都包含一个“将 PR 作为请求入口”的标记，默认设为 off。保持关闭，不要提起：希望将外部 PR 纳入 triage 队列的用户之后可以在文件中自行启用此标记。

Section B：triage 标签词汇

如果探索发现未安装 triage 技能，则完全跳过此部分，因为未安装的技能不需要标签。

如果已安装，只问一个问题：

你想保留默认的 triage 标签吗？推荐答案是 是。

默认值为五个规范角色，且每个标签字符串都与其名称相同：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。回答 是时，按原样写入。只有用户回答否时（通常是因为他们的跟踪器已经使用其他名称，例如用 bug:triage 对应 needs-triage），才收集覆盖设置，以便 triage 使用现有标签而不是创建重复标签。

Section C：领域文档

默认使用 单一上下文，即在仓库根目录放置一个 GLOSSARY.md 和一个 docs/adr/。 这适用于几乎所有仓库，因此直接写入，无需提问。

只有在探索发现 monorepo 信号时，才提供 多上下文 选项，即在根目录放置一个 GLOSSARY-MAP.md，指向每个上下文各自的 GLOSSARY.md。然后确认用户希望采用哪种布局。

如果探索发现旧版 CONTEXT.md 或 CONTEXT-MAP.md，建议使用 git mv 重命名每个文件，以保留其历史记录：git mv CONTEXT.md GLOSSARY.md、git mv CONTEXT-MAP.md GLOSSARY-MAP.md，以及每个上下文对应的 CONTEXT.md。如果新名称已存在，git mv 会拒绝执行：建议将旧文件合并到新文件中，并询问内容不一致时以哪份为准。同时，建议更新映射文件中的链接以及任何提到旧文件名的其他文件；AGENTS.md 和 docs/agents/domain.md 的草稿已经使用了新名称。

如果探索发现 docs/assets/ 文件夹，建议按照 ../orchestrating/folder-standard.md 中的“从旧版布局迁移”部分，使用 git mv 移动每个主题的内容：项目附带或展示的图片移至 assets/images/<topic>/，截图移至 assets/screenshots/<topic>/，并更新指向这些内容的每个相对链接。

D 部分：项目环境默认设置

建议不添加任何内容。 仅当探索发现项目需要某个工具来承担特定职责时，才询问用户：然后为该工具提出一行 ## Environment defaults，以覆盖用户的全局设置行。 agents-md.md > “Environment defaults” 说明了可填写的内容。

E 部分：发布生命周期

建议根据 releasing.md 编写 docs/agents/releasing.md，并将用户共享的发布规则应用于其中，再补充探索发现的内容：发布包含什么、发布顺序，以及谁负责执行每个步骤。 保持文档简短，每个步骤用一两行说明。 省略共享规则已说明的内容，例如版本规则、变更日志格式以及标签和说明的格式；也省略命令、安装说明，以及项目尚未使用的注册表相关计划。 若项目采用了共享规则未提及的做法，则保留项目做法并明确说明。 若两者存在冲突，则同时列出并询问项目应遵循哪一种。 如果发布步骤已写在其他文档中，则建议将其移入 docs/agents/releasing.md，并在原位置留下指向该文档的说明。

4. 确认并写入

向用户展示以下内容的草稿：

• AGENTS.md：根据 agents-md.md 新建，或展示现有文件，并添加 ## Agent skills 块和任何 ## Environment defaults 行；现有 CLAUDE.md 中的每一行也都移入其中
• CLAUDE.md：单行 @AGENTS.md，或保持现有指向 AGENTS.md 的符号链接不变。若存在 CLAUDE.md，Claude Code 会跳过项目的 AGENTS.md；这两种形式向其提供的文本相同。
• .gitignore：添加 .scratch/ 和 .claude/worktrees/，且仅在缺少相应条目时添加
• docs/agents/issue-tracker.md 和 docs/agents/domain.md 的内容；安装了 triage 时，还包括 docs/agents/triage-labels.md 的内容；运行了 E 部分时，还包括 docs/agents/releasing.md 的内容
• C 部分提出的每项旧 CONTEXT.md 或 CONTEXT-MAP.md 重命名或合并，以及对引用这些文件的文件所做的编辑
• 提出的每项从 docs/assets/ 移出的文件，以及相应更新的链接

允许用户编辑，然后对所有内容征求一次批准。之后写入：

1. 编辑 AGENTS.md，绝不编辑 CLAUDE.md。如果已存在 ## Agent skills 块，则就地更新其内容，不要追加重复块，并保留用户在其周围所做的编辑。仅当已安装 triage 且运行了 B 部分时，才添加 ### Triage labels 子块；仅当运行了 E 部分时，才添加 ### Releases 子块。

2. 若 CLAUDE.md 仅包含 @AGENTS.md 或是指向 AGENTS.md 的符号链接，则保持原样，并补上 .gitignore 中缺少的行。

3. 以此技能文件夹中的种子模板为起点编写文档文件：

   • issue-tracker-github.md：GitHub 问题跟踪器
   • issue-tracker-gitlab.md：GitLab 问题跟踪器
   • issue-tracker-local.md：本地 Markdown 问题跟踪器
   • triage-labels.md：标签映射，仅在安装了 triage 时编写
   • domain.md：领域文档的使用规则和布局
   • releasing.md：发布生命周期，仅在运行了 E 部分时编写

   对于“其他”问题跟踪器，根据用户的描述，从头编写 docs/agents/issue-tracker.md。

   为每个 docs/agents/issue-tracker.md 添加模板中的 ## Title prefixes 部分，使创建问题的每项技能都以相同方式为问题命名。根据项目现有未关闭问题的标题，为语义列表添加种子内容；每个领域各占一行，并说明其涵盖范围。

4. 执行每项已批准的旧 CONTEXT.md 或 CONTEXT-MAP.md 重命名或合并，然后更新引用这些文件的文件。

5. 执行每项已批准的 docs/assets/ 文件移出操作，然后更新相应链接。

所有已批准的更改均已完成后，即为完成。

5. 审计

从根目录开始，逐一检查项目持有的所有工具配置文件，并依据 set-up-machine 的 rules.json 审核，无论这台机器是否已配置相应工具：.claude/settings.json 和 settings.local.json、.cursor/cli.json、opencode.json 或 opencode.jsonc 和 .opencode/、.codex/config.toml。references/project-files.md 说明了各工具配置中的项目文件如何影响全局规则，以及如何判断条目。按以下类别报告每项发现：

• weakens：某个工具配置中的条目导致某条全局规则不再按机器上的设置生效。说明是哪条规则以及原因，并提出修复方案：删除该条目，或将其范围缩小至项目自身的命令。该文件属于项目，只有用户批准后才能修改。
• overlaps：某条允许规则涵盖了全局规则中的命令，但全局规则仍然生效。建议缩小允许规则的范围。
• extra：项目级拒绝或询问规则；以及 gap：无法判断的内容。逐项列出。

还要报告仓库中仍存在的每个旧版 CONTEXT.md 或 CONTEXT-MAP.md，并列出 Section C 建议为其采用的重命名方案。报告缺少 ## Title prefixes 部分的 docs/agents/issue-tracker.md，并建议采用步骤 3 写入的部分。报告存在发布信号但没有 docs/agents/releasing.md 的项目，以及与用户共享的发布规则不一致的 docs/agents/releasing.md，并建议采用 Section E 写入的更新。

审计在没有 weakens 时通过。完成条件是审计通过；或者用户选择保留某个 weakens 条目，此时审计仍判定为失败，并在报告中指出该条目。

6. 完成

告知用户设置已完成、审计发现了什么，以及哪些技能接下来会读取这些文件。说明用户之后可以直接编辑 AGENTS.md 和 docs/agents/*.md；再次运行此技能会重新审计项目，在共享发布规则更改时更新发布页面，并在用户需要时切换问题跟踪器。提交工作由用户或调用此技能的技能负责。