sync

输出风格（纯文字，不使用短横线）

这项技能生成的所有内容，无论是文件还是消息，都请使用简单明了的语言。请以 you 称呼读者，语气亲切直接，就像同事交流一样。请把每个步骤都写成建议，让读者可以选择执行或跳过，绝不要写成命令。保留有实际意义的技术术语，并用通俗的语言解释。绝不要把短横线或连字符用作标点：不能使用长破折号、短破折号，也不能使用带连字符的复合词。请写 read only，不要写 read-only。请用简单的词语表达，或改写句子。其他技能会匹配的代码、文件路径、命令标志和值，请保留其中的连字符。句子要短。请使用逗号或括号。清晰胜过巧妙。

这项技能的作用

完成更改后收尾：根据仓库当前情况同步 AGENTS.md 文件、范围文件以及关联规范中的 **Status**: 行，并指出不得编辑的内容（过时的规范、经过精心编写的文字）。下方的边界表是准确的约定。

agent-prompt.md 是维护规则的唯一准确信息来源；SKILL.md 只负责说明执行流程。主线程会读取该文件并自行完成维护（参见步骤 3）。

规范文件： 持久上下文保存在与工具无关的 AGENTS.md 中；CLAUDE.md 只是指向它的指针。/sync 会编辑或创建这两个文件，并且只把它们作为目标，绝不将其作为更改来源。

边界

操作	/sync	负责人
编辑现有的根目录或嵌套 AGENTS.md	✅ 维护	/sync
将根目录 AGENTS.md 的 ## Build approach 行与范围标题中的方案协调一致（只精确修改一行，例如技术栈行）	✅ 维护；若存在经过精心编写的内容差异则标记	/sync
在某项更改确立 UI 设计系统后，在最近的 AGENTS.md 中添加一行指向 design.md（UI 设计系统）的说明	✅ 维护（仅添加指针）	/sync
为本次更改中新建的区域创建嵌套 <area>/AGENTS.md	✅ 创建（差异包含该区域的完整上下文）并添加根目录指针	/sync
为已存在但没有文档的区域创建嵌套文档（差异仅覆盖部分区域）	❌ 标记“运行 /audit”	/audit
创建或重构根目录 AGENTS.md	❌ 标记“运行 /audit”	/audit
将规范的 **Status**: 行与其功能的范围状态协调一致（planned→Proposed，in-progress→In Progress，done→Accepted；Assumed 规范除外：保留 Assumed 并指出它，绝不将其协调为 Accepted）	✅ 仅修改状态行	/sync
清除规范的 Assumed 状态（将其移出 Assumed）	❌ 将其标记为待决策事项“运行 /architect 进行确认”（绝不将它与功能状态协调一致；只有经确认后才能清除）	/architect
编辑规范的内容或取代该规范	❌ 标记为过时	/architect
协调范围文件，仅处理相关工作区的范围文件（而非 docs/scope/ 中的所有文件）；根据仓库中的证据（代码、测试、AGENTS.md）勾选已完成的子任务，并推进状态	✅ 修正	/sync
在范围文件中添加或调整功能或子任务的顺序	❌ 不作更改	/scope
覆盖或改写经过精心编写的 AGENTS.md 内容	❌ 标记冲突，不作改写	人工处理

创建与否的分界在于上下文，而非策略：只有当本次更改展示了某个区域的完整情况时才创建文档；如果该区域在本次更改前就已存在，而你只看到了其中一部分，则交由 /audit 处理。如有疑问，标记出来，不要创建。

请求与执行

会执行操作。 只有在没有任何内容需要同步（更改集为空）时才会暂停。报告会列出对经过精心编写文件的每项修改，方便你审阅或还原。

制品归属

仅负责边界表授予的内容，不写入其他内容。作为通用子任务协调器，它会勾选所有能够根据仓库证据验证的范围子任务（包括其他技能不会勾选的 /test、/audit、/sync 子任务），并推进功能状态；具体规则见 agent-prompt.md。

制品基础目录。 规范和范围默认位于 docs/ 下；如果 docs/ 是已发布的文档站点，则使用 .workflow/；选择仓库中实际存在的目录（此处路径均假设使用 docs/）。

---

可移植性（适用于任何操作系统和 Agent）

• 命令：git 是唯一必需的 CLI，且在所有操作系统上的行为一致，请按原样运行 git 命令。其他 shell 片段是 POSIX 参考示例，并非可直接运行的脚本：不要假设 find、grep、sed、cat、test/[ ]、ls 或 xargs 可用；请使用 Agent 的跨平台文件工具，并自行应用分支逻辑，而不要使用 shell 的 if、变量或重定向。
• 随附文件：通过相对于此技能文件夹的路径引用。将该文件夹解析为绝对路径（这些相对路径已解析），并在写入时（步骤 3）自行读取 agent-prompt.md，不要在前面的步骤中读取。
• 整个维护过程都在主线程中内联运行，并严格遵循 agent-prompt.md 中的规则（以其为准）。

执行

1. 确定变更集范围（开销低，逐文件查看状态）

先检查最新状态（团队协作时）： 运行 git fetch --quiet；如果 git rev-list --count HEAD..origin/$BASE > 0，则说明当前分支落后于 origin/$BASE，请提醒工程师先拉取更新，因为队友可能已经同步了这些文档。

基准分支：如果 git rev-parse --verify main 成功，则使用 main，否则使用 master。当前分支：git rev-parse --abbrev-ref HEAD。使用 --name-status（不要使用 --name-only）；新增区域和孤立文件清理逻辑需要逐文件区分 Added（新增）、Modified（修改）和 Deleted（删除）状态。

• 如果当前分支就是基准分支，模式为 uncommitted：git diff --name-status HEAD。
• 否则，模式为 branch：git merge-base "$BASE" HEAD，然后运行 git diff --name-status <merge-base>。

无论哪种情况，都要将 git ls-files --others --exclude-standard 中的未跟踪文件加入列表，并为每个文件添加 A 状态前缀（与 --name-status 的格式一致）。记录模式、基准分支和合并基点，以供写入步骤使用。

移除重复项，然后筛选出作为同步来源的源文件：

• 排除文档和配置（任意层级的 AGENTS.md、docs/**、*.md、test-preferences.json、锁文件、生成的输出）；/sync 会将它们作为目标或上下文读取，绝不将其作为变更来源。
• 排除测试文件（*.test.*、*.spec.*、__tests__/ 等）；测试不是持久的区域惯例。
• 将状态为 D 的条目单独保留；它们用于孤立文件清理（步骤 3），但不会作为同步来源。
• 将依赖清单变更单独保留，用于发现工具，即使它们属于配置也不例外：package.json、pyproject.toml、requirements*.txt、go.mod、Cargo.toml、composer.json、Gemfile、pubspec.yaml、mix.exs、*.csproj 及同类包清单。锁文件仅作为信号；不要传递锁文件内容。

如果没有剩余的源文件或依赖清单变更（只改动了文档、测试、锁文件或生成文件），则停止，无需同步。不要启动其他 Agent。

2. 定位上下文文件和规格说明（仅查找路径，此处不要读取文件）

使用 Agent 的文件搜索 / glob 工具：

• 记录根目录下是否存在 AGENTS.md。
• 查找所有 AGENTS.md（根目录及嵌套目录），排除 node_modules/ 和 .git/。
• 查找 docs/specs/ 下名称以数字开头的所有规格说明，并按名称排序。
• 查找 diff 实际涉及的范围文件（在 monorepo 中，变更文件所在的工作区 apps/<x>/… 对应 docs/scope/<x>/）；不要读取或传递整个 docs/scope/。

记录路径、变更文件列表和 diff 命令；在写入时读取文件。现在读取根目录 AGENTS.md 的内容（简短且有助于确定上下文）。对于每个变更文件，记录其最近的、包含 AGENTS.md 的上级目录（根目录或嵌套目录）；这是最可能需要更新的上下文文件。

2.5 为新添加的工具发现 Agent Skills 和可选 MCP

仅当依赖清单发生变化，或差异明显新增了重要外部工具时才运行。普通实用程序库可跳过，除非它们定义了持久工作流或集成。

• 根据清单差异（而非完整锁定文件）识别新添加的重要软件包／工具：框架、路由器、样式／UI 套件、数据库、ORM／查询层、身份验证／会话、支付、电子邮件／通知、存储／上传、搜索、队列／后台任务、AI 提供商／向量数据库、浏览器／运行时测试、可观测性、托管／部署。包括清单中的软件包名称和常见别名。不要找到第一个技术就停止。

• 排除已由已安装的技能、已连接的 MCP 或 AGENTS.md 中已拒绝的条目覆盖的内容。

• 搜索前先询问。

  必须询问，但不一定要搜索。 在工程师作出选择前，不得为发现 Agent Skill 和 MCP 搜索、获取、安装或启动任何内容。提供四个选项：帮我查找、我会列出想要的项目、不需要并记录拒绝、暂不处理。只有选择第一个选项时才能运行搜索命令。切勿悄悄跳过询问，也绝不能在工程师同意前搜索。

  说出此次更改新增的工具，并用一行说明：Agent Skill 可向 Agent 提供该工具的实际惯例，MCP 服务则可让其实时访问实际系统；然后询问：“要我为此次更改新增的工具查找 Agent Skills 和 MCP 服务吗？”（标题为 Agent skills），并提供 Yes, find them for me（推荐）· I'll name the ones I want · No, skip it · Not now, later。选择 Yes 后继续以下步骤。选择 I'll name the ones I want 后，接收列表并直接进入安装步骤，不进行任何搜索。选择 No, skip it 后，不运行任何操作并记录拒绝。选择 Not now, later 后，不运行任何操作，并在报告中注明候选工具。

• 将搜索隔离在只读子 Agent 中（先确认能力，且仅在选择 Yes 后）。 将剩余项目交给发现子 Agent，而不要在主线程中搜索：如果 Agent 支持，则在后台启动（不阻塞）；否则阻塞启动；明确指定其模型为快速、低成本档位（不要继承会话模型；在 Claude Code 中，将其作为 researcher 子 Agent 类型启动，该类型会固定模型）；它只返回简洁的候选列表。这样可避免搜索结果占用 /sync 的有限上下文。没有子 Agent 时，在当前线程内搜索；没有搜索能力时，跳过并注明。询问面板始终留在主线程。

• 对每个剩余项目，运行 npx skills find <tool-or-package>；如果结果不充分，则用软件包／组织名称的别名重试。收集所有可信的 Agent Skill 候选项，并在可行时通过 npx skills add <owner>/<repo> --list 确认。如果 CLI 需要交互或不可用，则搜索 "<tool>" "agent skill"，并在提供候选项前确认。

• MCP 搜索为可选：优先查看连接器列表，否则对每个项目搜索 "<tool>" "MCP server"。MCP 是推荐的增益项，而非必需项。

• 限制发现范围并确保结果可缓存：最多进行 5 次网页搜索，最多获取 8 个页面；优先查阅官方注册表／文档。过滤已安装／已拒绝的项目后，如果 docs/.agent-cache/tool-discovery/<slug>.md 不超过 30 天，则复用该文件。

• 在一个多选面板中按技术分组，提供所有 Agent Skill 匹配项：“要为新添加的工具安装相关 Agent Skills 吗？”并提供跳过／拒绝选项。然后单独提供 MCP：“可助力这些工具的可选 MCP 服务”，并提供跳过／拒绝选项。绝不自动安装或连接。

• 使用 npx skills add <owner>/<repo> -y 安装选定的技能。对于 MCP，指引用户前往连接器／MCP 设置；连接后即可自动使用这些工具。

• 将结果记为 INSTALLED_SKILLS_OR_NONE、MCP_SERVERS_OR_NONE 和 DECLINED_TOOLS_OR_NONE，并在写入时将持久记录写入合适的 AGENTS.md 文件。如果没有发现任何内容或不具备相应能力，则视为 none。

3. 执行维护（主线程）

主线程自行执行维护；绝不将 AGENTS.md / 范围 / 规格状态编辑交给子 Agent。现在（仅在写入时）阅读 agent-prompt.md，并严格遵循其要求；它是维护规则的权威依据。差异阅读是唯一可以委派的事项，而且仅限变更集较大时，委派给使用最便宜模型（Claude Code：haiku）的只读 scout 子 Agent，并让它返回简洁的映射。遵守旧工具授权所表达的相同边界：Edit 现有文档、范围和规格中的 **Status**: 行；Write 仅用于新增的区域级嵌套 AGENTS.md；不得创建根文件，不得编辑规格内容（仅限 Status 行），不得为已有区域创建浅层嵌套文档（这些规则见 agent-prompt.md）。

要应用的输入：

1. MODE、BASE、MERGE_BASE、CHANGED_FILES（名称状态变更源列表）、DIFF_COMMAND（确切的 git diff 命令）
2. DELETED_PATHS（已删除的路径，用于清理孤立内容）
3. ROOT_AGENTS_MD（根 AGENTS.md 内容）、NESTED_PATHS（嵌套 AGENTS.md 路径）
4. SPEC_PATHS（所有规格路径，用于 Status 行核对和过时标记）
5. FILE_TO_CONTEXT_MAP（变更文件 → 最近的上下文文件）
6. SCOPE_PATH_OR_NONE（相关工作区范围路径，不包括 docs/scope/ 下的所有路径；也是每个已关联功能的状态来源，用于核对规格 Status 行）
7. 第 2.5 步中的 INSTALLED_SKILLS_OR_NONE、MCP_SERVERS_OR_NONE、DECLINED_TOOLS_OR_NONE

4. 转达结果

如果维护失败或未生成可解析的摘要，请报告并重做，不要捏造结果（确实的 NOTHING_TO_SYNC 属于有效成功；崩溃或空输出则不属于）。否则转达简洁摘要：

开头用一行说明核对了哪些内容；随后仅列出需要工程师处理的事项（参见 docs/conventions.md）。编辑内容已写入文件。模板：

## /sync complete · reconciled <N> changed files

**Updated <AGENTS.md files · scope features · spec statuses> to match the diff.**   (or "everything already current, nothing to sync")
Heads up (need you):
- Stale spec → /architect: `<file>` (<why, or a status mismatch /sync couldn't safely resolve>)
- Assumed, not ratified → /architect: `<file>` (<feature>; owes ratification, doesn't block `done`)
- Context gap → /audit: `<area>` (established area /sync can't document from the diff alone)
- Conflict, decide manually: `<path>` (<curated content that would need rewriting>)

删除没有事项的“注意事项”条目；若没有任何注意事项，则删除整个“注意事项”区块。/sync 执行的操作（AGENTS.md 行、范围勾选项、孤立内容清理、状态核对）均已记录在文件中；不要列出这些内容。/sync 不会替你运行 /architect 或 /audit；它只会指出相关内容，由你自行决定。

---

子 Agent 提示词模板

参见 agent-prompt.md。