setup-repo

设置仓库

只需配置一次仓库，让其他所有技能都能读取其中的答案，而不必猜测。输出包括 docs/agents/ 下供 Agent 使用的配置文件、种子规范文件，以及仓库 Agent 指令中的一个指针块。

这是一个对话，而不是脚本：先探索并展示你的发现，再与用户一次讨论一项决定，最后写入文件。

模板种子文件位于此技能集的 templates/ 目录中——作为插件安装时，将其解析为 ${CLAUDE_PLUGIN_ROOT}/templates；否则，相对于此 SKILL.md，将其解析为 ../../../templates。

跟踪进度

此技能包含七个步骤，跳过步骤是最常见的问题——可能导致跟踪器未配置，或从未运行第 6 步验证关卡。在第 1 步之前，为下方每个编号步骤创建一个待办事项，并按顺序完成；只有满足对应的 完成条件 后，才能勾选。第 6 步（证明配置有效）不可跳过。

1. 读取设置状态

这一步只做一件事：确定仓库是否已针对该技能集完成配置，以及配置的完整程度。只读取仓库自身的文件——不要探查外部服务或其身份验证（不要运行 gh auth、gh label list、glab，也不要调用 Linear MCP），不要读取用户的 shell 环境（不要运行 env，也不要探查 *_API_KEY）。此处不负责检测：由用户在第 2 步决定要设置什么；任何特定服务或工具链的细节，都在用户作出选择后再收集，以支持该选择。

只需读取仓库中的文件，检查以下设置标记：

• docs/agents/project.md、docs/agents/issue-tracker.md、docs/agents/triage-labels.md——这些文件是否存在且已填写，还是缺失？
• docs/agents/project.md 中是否有 ## Team 章节？是否已填写，还是尚有空缺？
• CLAUDE.md / AGENTS.md 中是否有 ## Agent skills 章节（注明这两个文件中哪些存在）
• 技能集要求的种子文件：docs/specs/INDEX.md、一个术语表（CONTEXT.md 或 CONTEXT-MAP.md）
• .gitignore 中是否包含 .skills/ 和 .worktrees/

然后根据检查结果分支处理：

• 已配置（全部或部分）——这是一次补齐缺项，而不是重建。准确列出已有内容以及缺失或过时的内容，向用户展示摘要，并提出只补齐缺项。只处理第 2 步中输出缺失或用户明确要求更改的部分；所有已有内容一律保持不变（遵循第 4 步的增量规则）。
• 未配置——直接进入第 2 步的用户主导流程。不要根据 git 远程仓库或已连接的 MCP 服务猜测跟踪器，也不要自动检测应由用户选择的任何内容。询问用户希望如何设置仓库，一次讨论一个决定。

你仍可读取仓库自身的清单文件（锁文件、package.json 脚本、Cargo.toml、pyproject.toml、Makefile、测试配置），以便在后续步骤中预填建议；但读取仓库中的文件不等于探查服务，而预填建议绝不代表替用户作出决定。

**完成条件：**你已将仓库归类为已配置／部分配置／未配置，列出所有缺项，并向用户展示摘要。

2. 逐节作出决定

严格按照一次一项的顺序讨论以下十项决定（A–J；I 为可选项目文档）：先用两三句话解释这是什么、哪些技能会使用它，以及不同选择会带来哪些变化；接着用一句话说明你的建议及理由，然后等待用户回答，再进入下一项。绝不能一次性抛出所有章节。假设用户此前不了解这些概念。

A. 问题跟踪器

说明：读取或编写问题的技能（triage、file-issues、发布任务时的 write-plan、release）需要知道问题存放在哪里，以及哪些命令会操作它们。

选项：

• github — 通过 gh CLI 管理仓库问题
• gitlab — 通过 glab CLI 管理仓库问题
• linear — 通过已连接的 Linear MCP 服务（首选）或 Linear GraphQL API 管理 Linear 中的问题；适用于使用 Linear 而非代码托管平台跟踪工作的团队
• local — .scratch/<feature>/ 下的 Markdown 文件，每个文件都包含一行 Status:；适合个人仓库或没有远程仓库的仓库
• other — 用户用一段话描述其工作流；将其记录为自由文本

只根据仓库的本地 Git 远程地址提出建议：GitHub 远程地址 → github，GitLab 远程地址 → gitlab，没有远程地址 → local；并始终允许用户推翻建议。不要探查服务或其身份验证方式来猜测跟踪器。Linear 是独立服务，不会出现在 git remote 中，因此应将其作为一个选项提供；只要用户表示团队使用 Linear，就应选择它，即使代码托管平台是 GitHub/GitLab。

后续问题（仅限 github/gitlab）：**外部拉取请求是否属于请求入口？**说明：开源仓库通常会通过 PR 收到功能请求——PR 就是附带代码的问题。如果是，triage 会将外部 PR 纳入同一队列和状态机。默认答案：否。对 linear/local/other 完全跳过此问题——对于使用 Linear 的团队，请求会作为 Linear 问题提交，任何 PR 都留在关联的代码托管平台中，不进入 triage 队列。

**完成条件：**确认跟踪器选项和 PR 入口问题的答案。

B. Triage 标签映射

说明：triage 会将问题推进到规范角色对应的状态，但必须应用此仓库实际使用的标签字符串，否则会创建重复标签。

规范角色——五种状态和两种类别：

角色	含义
needs-triage	等待评估
needs-info	等待报告者提供信息
ready-for-agent	规格完整；Agent 可以直接接手
ready-for-human	需要人工判断或访问权限
wontfix	不会处理
bug	出现问题
enhancement	新功能或改进

列出跟踪器现有的标签，并与这些角色并列展示，然后提出映射建议（默认：每个角色的字符串与其名称相同）；由用户确认。对于映射中跟踪器尚无的任何标签，询问是否要创建——只有获得用户明确同意后才能创建。对于本地跟踪器，角色名称本身就是用语；采用默认值即可。对于 linear，先列出团队现有的工作流状态和标签（通过 MCP 服务或 API），然后将状态角色映射到合适的 Linear 工作流状态（例如，ready-for-agent → “Todo”/“Ready”状态，wontfix → “Canceled”状态），并将类别角色（bug/enhancement）映射到 Linear 标签。

**完成条件：**每个规范角色都映射到经确认的标签字符串。

C. 验证命令

说明：tdd、verify、execute-plan 和 release 都会运行此仓库的验证命令；这些命令必须准确，不能靠猜测。

确认每项命令，并根据检测结果预先填入：类型检查、lint、单元测试、e2e/冒烟测试，以及单个测试文件的运行模式（运行一个测试文件的命令格式——tdd 紧密循环所在的环节）。

**完成条件：**用户已确认每项命令（或明确标记为“无”）。

D. 测试注释约定

说明：每项测试都带有所覆盖需求的 ID，而 trace 检查会通过 grep 在测试中查找这些 ID——因此，约定必须可通过 grep 查找，并与仓库使用的框架相匹配。

针对每个测试层，依据检测到的框架推荐一种约定（例如，e2e 标签 { tag: ['@CODE-N.M'] }、单元测试注释或测试名称中的 ID、编译型语言中的文档注释 /// REQ: CODE-N.M）。为每一层确认一种约定。

**完成条件：**仓库中的每个测试层都有经确认的 ID 约定。

E. 发布步骤

说明：release 技能会按顺序执行项目专属命令——构建、打包、签名、发布——不会临场发挥。

根据你找到的信息（构建脚本、打包配置）拟定有序步骤并确认。如果存在冒烟检查命令，也请列出。

**完成条件：**已确认有序的发布步骤（对于无需构建的库，空列表也是有效答案）。

F. 文档布局

说明：规范和发现技能会读取 docs/specs/、docs/adr/ 和领域术语表；它们需要了解文档结构。

请确认：

• 规范位于 docs/specs/，ADR 位于 docs/adr/（如果目录不存在，请创建）
• 术语表布局：单上下文（一个根目录 CONTEXT.md——适用于大多数仓库）或多上下文（根目录 CONTEXT-MAP.md 指向各上下文的 CONTEXT.md 文件——通常适用于单体仓库）

**完成条件：**已确认布局。

G. 项目定位

说明：项目有两项长期信息——交付意图（产出需要多可靠）和生命周期阶段（项目目前处于哪个阶段）。brainstorm 和 grilling 会读取这些信息，以便合理调整流程的严谨程度（原型无需权衡数据迁移或弃用；已发布且正在扩展的系统则需要重点考虑这些因素）；interpret 也会复用这些信息，避免重复询问。这些信息存放在 docs/agents/project.md 中，项目阶段变化时，用户可以直接编辑这两行。

请根据仓库信号预填并确认两项信息——不得臆造：

• 交付意图——Production / MVP / Prototype / Research / Learning。根据仓库情况给出建议（已发布的软件包或发布工作流 → Production；空白的新项目探索 → Prototype）；不明确时默认 MVP。
• 生命周期阶段——Idea / Early development / Active development / Released / Scaling / Maintenance。根据 git 信号给出建议（存在标签或发布历史 → Released；较新的仓库且提交较少 → Early development）；不明确时默认 Early development。

**完成条件：**用户已确认两项定位信息。

H. 团队

说明：团队组成——成员名单（人员／角色）以及可选的 CODEOWNERS 归属说明——是 brainstorm、grilling、write-plan、execute-plan、code-review、finish-branch 和 handoff 的长期上下文。这些技能会根据团队规模（Solo / Small / Multi）打包协作流程，规则写在 docs/agents/project.md 的 ## Team 部分。规模判断错误会导致协作流程不当（例如，在单人仓库中臆造审核者，或在多人仓库中不明确归属）。这与项目定位属于同类信息，但不影响交付意图或生命周期阶段。

运行决策 H 时，请阅读本文件旁的 team-inference.md 并严格遵循——仅使用本地 git / CODEOWNERS / AUTHORS / CONTRIBUTORS / 软件包清单；先推断，再确认。

给用户的简短说明：你会看到一份根据本地元数据拟定的成员名单；可以编辑姓名、角色，或改用人数形式（N × Role）；只有确认后才会写入任何内容。

建议：知道占位角色的真实职称时，将其替换后接受草案；涉及隐私时，使用人数形式；只有在名单与仓库的实际运作方式不符时（例如，单体仓库只有一位 Agent 用户），才设置工作流规模覆盖项。

想法	实际情况
“我会通过 gh api 获取协作者”	仅使用本地元数据——不调用协作者 API
“提交量足以证明谁是技术负责人”	绝不臆造职称；在用户重新分配角色前，默认使用 Contributor
“Git 历史为空——臆造一位独立开发者”	提供空白草案并询问；绝不臆造姓名
“先写入草案，以后再修正”	必须经过确认：本次运行中未获得明确确认，不得写入团队信息

**完成条件：**用户已确认成员名单（具名和／或人数形式）、可选的归属说明以及可选的规模覆盖项，或明确表示暂缓团队信息（仍视为未解决项）。

I. 项目文档层（可选 — 默认选 No）

说明：大型或长期维护的项目可以在功能工作流之上添加一个可选的仓库级层，包括产品愿景（docs/product/vision.md）、带 ID 的架构不变量主干（docs/architecture/）和工程指南（docs/product/guidelines.md），均由 establish-project 编写。存在这些文档时，brainstorm、write-design、write-plan、execute-plan 和 code-review 会参考它们；不存在时则不会有任何变化。小型仓库应选择不添加——之后可以通过 /establish-project 添加。

建议：除非这是一个大型、多功能项目，否则选择 No。

如果选择 Yes：记下这一点，供第 4 步使用（创建三个文档并添加 Agent 技能行）。如果 docs/agents/project.md 或现有的 CLAUDE.md/AGENTS.md 已经包含工程指南，则提议将其迁移到 docs/product/guidelines.md，并留下指向新位置的说明。

完成条件： 已选择启用或不启用此层。

J. 默认 PR 基础分支

说明：prepare-change 会将 docs/agents/project.md 中的 Default PR base: 作为其基础分支解析顺序中的第三优先级——排在显式调用指定的基础分支和现有 PR 中已记录的基础分支之后。因此，一旦记录了主干分支，它就不会再询问。finish-branch 仍会执行自己的拓扑检测（第 2 步）；选择选项 1 时，如果本次会话存在 PR 软件包记录的 Base:，则优先使用该值，而非检测结果——此字段用于 prepare-change 的解析，不是 finish-branch 直接使用的值。

仅将 dev、staging、main 和仓库自己的本地分支列表作为建议；不预先选择任何值——始终由用户自行指定分支。

建议：使用仓库实际的主干分支（通常是 main）——理由：除非另有说明，否则 prepare-change 和 finish-branch 已默认使用该分支。

如果用户不选择：完全不写入任何值，并跳过第 4 步中与此字段相关的事项——此后 prepare-change 每次调用都会询问基础分支，这正是 ARCH-2 下确保此字段确实可选的方式。

完成条件： 用户已确认一个值，或已明确选择不设置且不会写入任何值。

3. 起草并确认

写入任何内容之前，向用户展示：

• 三个 docs/agents/*.md 文件的内容（包括在确认决策 H 时确定的 ## Team）
• 计划写入 CLAUDE.md/AGENTS.md 的 ## Agent skills 区块

允许用户编辑。完成条件： 用户批准草稿。

4. 写入

增量规则：现有文件应原地编辑，绝不覆盖。 如果目标文件已存在，将内容合并到其中，并保留用户编写的所有内容。

1. 使用 templates/agents/project.md、templates/agents/issue-tracker.md 和 templates/agents/triage-labels.md 作为基础，写入 docs/agents/project.md、docs/agents/issue-tracker.md 和 docs/agents/triage-labels.md。在 issue-tracker 文件中仅保留所选追踪器的操作部分，并记录 PR 范围的回答。

2. 如果缺少 docs/specs/INDEX.md，则根据 templates/specs-INDEX.md 创建该文件。

3. 如果缺少术语表，请根据 templates/CONTEXT.md 创建 CONTEXT.md（如果用户的回答适用于多个上下文，则创建 CONTEXT-MAP.md）。

4. 在 docs/agents/project.md 的 Project posture 部分填写已确认的交付意图和生命周期阶段（决策 G）——共两行，替换模板占位符。（采用增量方式：如果该部分已有实际值，只更新用户要求更改的内容。）

5. 根据已确认的决策 H 内容（成员名单、职责说明、可选的级别覆盖）填写 ## Team，并合并到 templates/agents/project.md 的模板结构中。只替换 Team 部分已确认的字段；不要覆盖其他部分。如果用户暂缓填写 Team，请保留模板占位符，或留待补全信息时再添加。

6. 如果用户选择启用项目文档层（决策 I）： 根据 templates/product-vision.md、templates/architecture-INDEX.md 和 templates/product-guidelines.md 创建 docs/product/vision.md、docs/architecture/INDEX.md 和 docs/product/guidelines.md（采用增量方式，遵循上述规则）。如果是迁移，则将现有工程规则移至 docs/product/guidelines.md，并在 docs/agents/project.md 中留下注明其位置的指引。如果用户拒绝启用该层，则跳过此步骤——不要创建这些文件。

7. 添加 ## Agent skills 区块。该区块只能存在于一个规范文件中；任何第二个文件只能作为简短指引，不得复制该区块。

   • CLAUDE.md 和 AGENTS.md 均不存在（默认情况）：创建 AGENTS.md 作为规范文件（在其中放置该区块），并创建简短的 CLAUDE.md，其全文仅指向 AGENTS.md——这样 Claude Code 可通过其原生文件名找到指令，同时避免重复。不要询问要创建哪个文件；此模式适用于两者。
   • **仅有一个文件存在：**该文件即为规范文件——在其中添加或更新该区块。如果它是 AGENTS.md，且目标环境包含 Claude Code，也添加 CLAUDE.md 指引。如果它是 CLAUDE.md，则保持其为规范文件——不要将其降为指引文件，也不要创建与之竞争的 AGENTS.md。
   • **两个文件都存在：**将该区块放入已有实际 Agent 指令的文件中；如果另一个文件没有实质内容，则将其改为指引文件。绝不要在两个文件中都放置该区块。
   • 如果规范文件中已有 ## Agent skills 部分，就在原处更新——绝不要追加重复内容，也不要改动周围部分。

   创建 CLAUDE.md 指引文件时，内容如下：

   # CLAUDE.md
   
   The canonical agent instructions for this repo live in **[AGENTS.md](AGENTS.md)** —
   read it first. It applies to Claude too; this file exists only so Claude Code
   finds it by its native name.
   

区块内容如下（仅当决策 I 为 Yes 时，才包含项目文档项目符号）：

## Agent skills

This repo is configured for a spec-driven skill set.

- Feature flow: `brainstorm` → `write-requirements` → `write-design` →
  `write-plan` → `execute-plan`
- Bug on-ramp: `debug` (root cause first, then a guarded fix)
- Capture a conversation/spec/idea into tracker issues: `/file-issues` (user-run)
- Incoming issues and PRs: `/triage` (user-run)
- Traceability check: the `trace` skill — run by `verify` and `release`;
  keep it clean
- Project docs (layer enabled): `/establish-project` maintains
  `docs/product/vision.md`, the `docs/architecture/` invariant spine, and
  `docs/product/guidelines.md`; the feature skills consult them

Repo config the skills read:

- Verify commands, test annotations, release steps: `docs/agents/project.md`
- Team composition (roster, ownership notes, workflow band): `docs/agents/project.md` (`## Team`)
- Issue tracker operations: `docs/agents/issue-tracker.md`
- Triage label mapping: `docs/agents/triage-labels.md`

8. 确保本地工作目录已加入 git 忽略列表：技能生成的临时文件——execute-plan 的日志和简报，以及规范技能写入的扫描/审查摘要——存放在 .skills/ 下；隔离工作区存放在 .worktrees/ 下；两者都不应纳入版本控制。对每个模式幂等执行：grep -qxF '.skills/' .gitignore 2>/dev/null || printf '.skills/\n' >> .gitignore（.worktrees/ 同理），然后暂存 .gitignore。（检查是否存在该行，而不是使用 git check-ignore——带尾斜杠的模式只匹配已存在的目录，因此在目录尚不存在时，check-ignore 会再次追加该模式。）
9. 如果已确认决策 J（默认 PR 基准分支），则根据上述增量规则，在 docs/agents/project.md 的 Project posture 部分添加 - **Default PR base:** \`——合并添加，绝不要覆盖用户已设置的值。如果用户拒绝决策 J，则不写入任何内容：保留该字段为空缺，以便 prepare-change` 在每次调用时询问。

**完成条件：**所有文件均已写入，.skills/ 和 .worktrees/ 均已加入 git 忽略列表，并且 git status 仅显示预期的新增或修改项。

5. 提供会话启动钩子

这套技能不会向仓库安装其他内容——不安装代码检查工具、不添加 CI 步骤，也不添加 git 钩子。还有两个可选建议——一个能让技能使用门禁持续生效，另一个能让技能获取最新的库信息：

会话启动钩子。 如果安装这套技能时没有插件钩子支持，可以建议添加一个 SessionStart 钩子（匹配器为 startup|clear|compact），让门禁在执行 /clear 和压缩后仍然生效。将钩子纳入仓库——绝不要引用仓库外的路径。 绝对路径（例如指向技能集自身工作副本的路径）会被提交到 .claude/settings.json，并在其他机器、CI 环境或该副本移动后失效。请改为：

• 将 templates/session-start.sh 复制到仓库中的 .claude/hooks/session-start.sh，并执行 chmod +x。该脚本无依赖（使用纯 cat），因此无论项目使用什么工具链，都能运行。
• 在 .claude/settings.json 中通过项目目录变量引用该脚本，而非使用绝对路径：

  { "hooks": { "SessionStart": [ { "matcher": "startup|clear|compact",
    "hooks": [ { "type": "command",
      "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh\"" } ] } ] } }
  

• 以增量方式合并到任何现有的 SessionStart 配置块中；不要覆盖其他钩子。

Context7 MCP——用于获取最新的库文档。 有些技能需要分析第三方库——例如，当问题取决于某个库的行为时，research 会用到；当复用阶梯涉及新的依赖时，write-design 也会用到。如果只依赖训练知识，Agent 引用的版本和 API 可能已经过时数月。建议用户安装 Context7 MCP 服务，它可提供源自原始来源的、按版本区分的最新文档；并说明库相关技能在其可用时会优先使用，不可用时则会改为获取官方文档。这是 Agent 环境中的工具，不是仓库文件：对于 Claude Code，将其添加到项目的 .mcp.json（或用户的 MCP 配置）中；对于其他运行环境（Kimi、Codex、……），则添加到相应运行环境的 MCP 配置中。如果用户同意启用，请在 docs/agents/project.md 中记录（添加一行“库文档：Context7 MCP（首选）”），让技能知道优先使用它。这只是建议——绝不要因此阻止设置，也不要尝试自行安装或验证身份。

完成条件： 会话启动钩子和 Context7 MCP 建议都已明确得到“是”或“否”的答复；任何得到“是”的选项都已落实（安装钩子，或将 Context7 说明写入 docs/agents/project.md）。

6. 证明配置确实可用 — GATE

用户确认并不等于配置在本项目中可用。命令是根据你检测到的信息预先填写的；清单路径错误、脚本缺失或工具未安装，都可能在几周后的 tdd、verify 或 release 中导致任务中途失败。趁你还了解当前上下文，现在就验证这些命令。这正是将 verify 技能的原则应用到刚写好的配置上：运行命令、阅读输出，并相信输出，而不是配置。

重新运行每条已配置的验证命令并对结果分类。关键在于区分接线问题与内容问题：

• 接线失败 — 命令无法按原样运行：出现“command not found”／退出码 127、“missing script”、“no such file or directory”、错误的 --manifest-path 或未知标志，或工具未安装。这是必须修复的配置错误：重新检测，修正 docs/agents/project.md，然后重新运行，直到问题消失。只要仍有命令未正确接线，设置就尚未完成。
• 内容失败 — 工具正常运行，但报告了问题（类型错误、lint 警告、测试失败）。命令接线正确；仓库存在先前已有的问题。记录下来告知用户；这些问题不会阻碍设置。
• 通过 — 接线正确且检查通过。

注意控制成本 — 无需运行整套测试来验证接线：

• 类型检查和 lint：完整运行（需控制运行范围）。
• 单元／端到端测试运行器：以较低成本确认运行器能解析其配置 — 使用 project.md 中的单测试文件模式，针对一个现有测试文件运行；或者使用运行器的仅收集／列表模式。设置期间绝不触发完整的端到端测试；说明完整测试应由用户之后运行。
• Trace 检查：运行该检查（必需的子技能：使用 trace），并确认结果集干净 — 零条需求也是有效的干净状态。该检查会通过 grep／git 搜索 docs/specs/ 和测试 glob，因此无需安装任何内容；如果它搜索的测试 glob 与仓库布局不匹配，现在就将正确的 glob 记录到 docs/agents/project.md。
• 如果安装了会话启动钩子，执行 .claude/hooks/session-start.sh，并确认它输出一行有效的 JSON。
• 如果跟踪器是远程服务（github／gitlab／linear），通过一次只读调用证明其可访问且已通过身份验证 — 使用 gh issue list／glab issue list；对于 Linear，进行一次 MCP 列表调用（或一个最简 issues GraphQL 查询）。这用于验证用户已经选择的跟踪器；这不是设置期间的检测步骤 1（该步骤禁止检测）— 用户已经做出选择，此调用只是证明配置可用。CLI 缺失、会话未经身份验证，或 MCP 服务已断开或未经身份验证，都属于接线失败；否则这些问题可能一直隐藏到几周后 triage 失败才会暴露。local 和 other 无需检查可访问性。

报告一张简明表格：每条命令 → 是否接线正确？→ 通过／失败／先前已有问题。

完成条件： 每条已配置命令都已证明接线正确（不再有接线失败），Trace 检查正常运行且结果干净，钩子（如已安装）已触发，已配置的跟踪器已响应只读调用，并且所有内容问题都已列出告知用户。

7. 完成

告知用户设置已完成、现在会读取此配置的技能，以及验证表展示了哪些配置已正确接线、哪些问题是先前已有的；之后可以直接编辑 docs/agents/*.md — 只有更换跟踪器或从头开始时，才需要重新运行此向导。