变更完成后同步 AGENTS.md、scope 与…

在一次变更完成、临近合并时，用仓库证据更新 AGENTS.md、勾选 scope 子任务并校正 spec 状态行，同时标记过时内容。

适用场景

解决思路

1. 在变更完成后的最后一步运行 /sync，用于同步 AGENTS.md 文件、scope 以及关联 spec 的 `**Status**:` 行，使其与仓库当前状态一致，并标记不可编辑的内容（过时 spec、人工撰写的 prose）。
2. 输出风格：用平实简单的语言写所有产出（文件和消息），以 `you` 称呼读者，像同事一样温暖直接，把每一步都呈现为可运行或跳过的建议而非命令；保留有实际意义的技术术语并用平实语言解释；绝不用破折号或连字符作标点（不用 em dash、en dash、连字符复合词），写 `read only` 而非 `read-only`；代码、文件路径、命令参数和其他技能匹配的值保留连字符；用短句、逗号或括号，清晰优先。
3. 以 `agent-prompt.md` 作为维护规则的唯一事实来源，SKILL.md 只负责编排；主线程读取它并自己执行维护。
4. 持久上下文放在工具无关的 `AGENTS.md` 中，`CLAUDE.md` 只是指向它的指针；/sync 编辑/创建两者，但只把它们当作目标，绝不当作变更来源。
5. 边界：编辑已存在的根/嵌套 AGENTS.md（由 /sync 维护）。
6. 边界：把根 AGENTS.md 的 `## Build approach` 行校正到 scope 头部的 approach（像 stack 一样做单行外科手术式编辑）；若出现人工撰写的分歧则标记。
7. 边界：当变更建立了 UI 设计系统时，在最近的 AGENTS.md 中添加一行指向 `design.md` 的指针（仅指针）。
8. 边界：为本次变更中净新增的区域创建嵌套 `<area>/AGENTS.md`（diff 即完整区域上下文）并添加根指针。
9. 边界：对已存在但未记录的区域（diff 只切到一部分）不创建嵌套文档，而是标记“run /audit”。
10. 边界：不创建或重构根 AGENTS.md，而是标记“run /audit”。
11. 边界：把 spec 的 `**Status**:` 行校正到其功能的 scope 状态（`planned`→`Proposed`，`in-progress`→`In Progress`，`done`→`Accepted`）；`Assumed` spec 是例外：保持 `Assumed` 并暴露它，绝不校正为 `Accepted`（仅 Status 行）。
12. 边界：不清除 `Assumed` spec（不把它移出 `Assumed`），而是标记为决策债务“run /architect to ratify”（绝不校正到功能状态；只有批准才能清除）。
13. 边界：不编辑 spec 内容或取代它，而是标记为过时。
14. 边界：只对相关 workspace 的 scope 文件（不是整个 `docs/scope/`）校正 scope，根据仓库证据（代码、测试、AGENTS.md）勾选任何已完成的子任务并推进状态。
15. 边界：不添加/重排 scope 中的功能或子任务，保持原样。
16. 边界：不覆盖或重写人工撰写的 AGENTS.md prose，而是标记冲突。
17. 创建的分界线是上下文而非策略：只有当本次变更展示了整个区域时才创建；当区域早于变更且只看到一部分时交给 /audit；不确定时标记而非创建。
18. 行为：主动执行，仅在没有任何可同步内容（空变更集）时暂停；对人工撰写文件的每次编辑都列在报告中以便审查或回滚。
19. 产物归属：只拥有 Boundaries 表授予的内容，不写其他；作为通用子任务校正者，勾选任何能从仓库证据验证的 scope 子任务（清扫其他技能不勾选的 /test、/audit、/sync 子任务）并推进功能状态，具体规则见 `agent-prompt.md`。
20. 产物基路径：spec 和 scope 默认位于 `docs/` 下，若 `docs/` 是已发布的文档站点则位于 `.workflow/`；使用仓库中存在的那个基路径（此处路径假设为 `docs/`）。
21. 可移植性：`git` 是唯一必需的 CLI，在所有 OS 上行为一致，按所示运行 `git` 行；其他 shell 片段是 POSIX 参考而非字面脚本，不要假设 `find`、`grep`、`sed`、`cat`、`test`/`[ ]`、`ls`、`xargs` 存在，使用 agent 的跨平台文件工具并自行应用分支逻辑，而非 shell `if`/变量/重定向。
22. 可移植性：捆绑文件用相对于本技能文件夹的路径引用；把文件夹解析为绝对路径，并在写入时（Step 3）自己读取 `agent-prompt.md`，而不是在更早的步骤中读取。
23. 整个维护在主线程内联运行，严格遵循 `agent-prompt.md`（权威）中的规则。
24. Step 1 界定变更集：先做新鲜度检查（团队场景）：`git fetch --quiet`；若 `git rev-list --count HEAD..origin/$BASE` > 0 则落后于 `origin/$BASE`，警告工程师先 pull，队友可能已同步这些文档。
25. 确定 base：若 `git rev-parse --verify main` 成功则用 `main`，否则用 `master`；当前分支用 `git rev-parse --abbrev-ref HEAD`；使用 `--name-status`（不是 `--name-only`），因为净新增区域和孤儿清理逻辑需要每个文件的 **A**dded vs **M**odified vs **D**eleted 状态。
26. 若当前分支就是 base，模式为 `uncommitted`：`git diff --name-status HEAD`。
27. 否则模式为 `branch`：`git merge-base "$BASE" HEAD`，然后 `git diff --name-status <merge-base>`。
28. 两种方式都要从 `git ls-files --others --exclude-standard` 添加未跟踪文件，每个前缀 `A` 状态（匹配 `--name-status` 格式）；记录模式、base 和 merge base 供写入步骤使用。
29. 去重后过滤出要同步 *来源* 的源文件：丢弃文档和配置（任意层级的 `AGENTS.md`、`docs/**`、`*.md`、`test-preferences.json`、锁文件、生成输出），/sync 把它们当作目标/上下文而非变更来源。
30. 丢弃测试文件（`*.test.*`、`*.spec.*`、`__tests__/` 等），测试不是持久的区域约定。
31. 把 `D`（删除）条目保留在单独列表中，它们驱动孤儿清理（Step 3），虽然不是同步 *来源*。
32. 把依赖清单变更保留在单独列表中用于工具发现，即使它们是配置而非源：`package.json`、`pyproject.toml`、`requirements*.txt`、`go.mod`、`Cargo.toml`、`composer.json`、`Gemfile`、`pubspec.yaml`、`mix.exs`、`*.csproj` 及等价包清单；锁文件只是信号，不要传递锁文件内容。
33. 若没有源文件也没有依赖清单变更（只改了文档/测试/锁/生成文件），停止，没有可同步内容，不要 spawn。
34. Step 2 定位上下文文件和 spec（只取路径，不要在此读取）：用 agent 的文件搜索/glob 工具，记录根 `AGENTS.md` 是否存在；找出所有 `AGENTS.md`（根 + 嵌套），排除 `node_modules/` 和 `.git/`；找出 `docs/specs/` 下所有以数字开头的 spec 并排序；找出 diff 实际触及的 workspace/功能的 scope 文件（monorepo 中，变更文件的工作区 `apps/<x>/…` 选择 `docs/scope/<x>/`）；绝不读取或传递整个 `docs/scope/`。
35. 记录路径、变更文件列表和 diff 命令；在写入时读取文件；现在读取根 AGENTS.md 内容（简短且有用，用于锚定）；对每个变更文件，记录其最近的含 `AGENTS.md` 的父目录（根或嵌套），那是最可能需要更新的上下文文件。
36. Step 2.5 仅当依赖清单变更或 diff 明显添加了重要外部工具时，发现新添加工具的 Agent Skills 和可选 MCP；跳过普通工具库，除非它们定义了持久工作流或集成。
37. 从清单 diff（不是完整锁文件）识别新添加的重要包/工具：框架、路由、样式/UI 套件、数据库、ORM/查询层、认证/会话、支付、邮件/通知、存储/上传、搜索、队列/后台任务、AI 提供商/向量数据库、浏览器/运行时测试、可观测性、托管/部署；包含包名和清单中的常见别名；不要只停在第一个技术。
38. 过滤掉已被已安装技能、已连接 MCP 或 `AGENTS.md` 拒绝条目覆盖的内容。
39. 搜索前必须先询问：在工程师做出选择前，不为 Agent Skill 和 MCP 发现搜索、抓取、安装或 spawn 任何东西；提供四个选项：帮我找、我来指定想要的、不并记录拒绝、稍后；只有第一个可以运行搜索命令；绝不静默跳过询问，绝不在工程师同意搜索前运行搜索。
40. 说出本次变更添加的工具，用一行说明 Agent Skill 给 agent 该工具的真实约定、MCP 服务器给 agent 对真实系统的实时访问，然后问：“Want me to find Agent Skills and MCP servers for the tools this change added?”（标题 `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` 不运行并在报告中记下候选工具。
41. 仅在 `Yes` 后，把搜索隔离在只读子代理中（能力优先）：把剩余集合交给发现子代理而非在主线程搜索；若 agent 支持则后台 spawn（不阻塞），否则阻塞；显式设置其模型为快速低成本层（不要继承会话模型；在 Claude Code 中作为 `researcher` 子代理类型 spawn，它固定模型）；它只返回紧凑候选列表；这使搜索输出不进入 /sync 的有界上下文；无子代理则内联搜索；无搜索能力则跳过并记录；询问面板留在主线程。
42. 对每个剩余项运行 `npx skills find <tool-or-package>`；若结果弱，用包/组织名别名重试；收集每个可信 Agent Skill 候选，并在可行时用 `npx skills add <owner>/<repo> --list` 确认；若 CLI 交互/不可用，搜索 `"<tool>" "agent skill"` 并在提供前确认。
43. MCP 搜索可选：先看连接器列表，否则对每项搜索 `"<tool>" "MCP server"`；MCP 是推荐的上行收益，非必需。
44. 发现要有上限且可缓存：最多 5 次 web 搜索和 8 个抓取页面，优先官方注册表/文档；当 `docs/.agent-cache/tool-discovery/<slug>.md` 不足 30 天时复用，先过滤已安装/拒绝项。
45. 在一个多选面板中按技术分组提供所有 Agent Skill 匹配：“Install relevant Agent Skills for newly added tools?” 加跳过/拒绝；然后单独提供 MCP：“Optional MCP servers that could help these tools” 加跳过/拒绝；绝不自动安装或连接。
46. 用 `npx skills add <owner>/<repo> -y` 安装选中的技能；对 MCP，指向用户的连接器/MCP 设置；连接后工具会自动使用。
47. 把结果携带为 `INSTALLED_SKILLS_OR_NONE`、`MCP_SERVERS_OR_NONE`、`DECLINED_TOOLS_OR_NONE`，并在写入时把持久行记录到正确的 `AGENTS.md` 文件；若没找到或没有能力，视为 `none`。
48. Step 3 由主线程自己做维护，绝不把 `AGENTS.md`/scope/spec 状态编辑交给子代理；现在（只在写入时）读取 `agent-prompt.md` 并严格遵循，它对维护规则是权威的；diff 读取是唯一可卸载的事，且仅对大型变更集，交给只读 `scout` 子代理用最便宜模型（Claude Code：`haiku`）返回紧凑映射；保持与旧工具授权相同的边界：`Edit` 已存在的文档、scope 和 spec `**Status**:` 行；`Write` 严格用于净新增区域的嵌套 AGENTS.md；不创建根、不编辑 spec *内容*（仅 Status 行）、不为已建立区域写浅层嵌套文档（这些是 `agent-prompt.md` 中的规则）。
49. Step 3 应用的输入：1) `MODE`、`BASE`、`MERGE_BASE`、`CHANGED_FILES`（name status 变更源列表）、`DIFF_COMMAND`（确切的 `git diff` 命令）；2) `DELETED_PATHS`（删除路径，用于孤儿清理）；3) `ROOT_AGENTS_MD`（根 AGENTS.md 内容）、`NESTED_PATHS`（嵌套 AGENTS.md 路径）；4) `SPEC_PATHS`（所有 spec 路径，用于 Status 行校正和过时标记）；5) `FILE_TO_CONTEXT_MAP`（变更文件 → 最近上下文文件）；6) `SCOPE_PATH_OR_NONE`（相关 workspace scope 路径，不是整个 `docs/scope/`；也是每个关联功能状态的来源，用于 spec Status 行校正）；7) 来自 Step 2.5 的 `INSTALLED_SKILLS_OR_NONE`、`MCP_SERVERS_OR_NONE`、`DECLINED_TOOLS_OR_NONE`。
50. Step 4 转达结果：若维护失败或没有可解析摘要，报告并重做，不要编造结果（真正的 `NOTHING_TO_SYNC` 是有效成功；崩溃或空输出不是）；否则转达紧凑摘要。
51. 摘要先一行说明校正了什么；然后只列出需要工程师处理的内容（按 `docs/conventions.md`）；编辑本身在文件中；模板：`## /sync complete · reconciled <N> changed files`，`**Updated <AGENTS.md files · scope features · spec statuses> to match the diff.**`（或 “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>)`。
52. 删除没有条目的 Heads up 项目符号，若没有则删除整个 Heads up 块；/sync 做了什么（AGENTS.md 行、scope 勾选、孤儿清理、状态校正）在文件中，不要列出；/sync 不替你运行 /architect 或 /audit，它只指向，你决定。
53. 子代理提示模板见 `agent-prompt.md`。

适用边界 · 注意事项

• 当变更集为空（没有源文件也没有依赖清单变更，只改了文档/测试/锁/生成文件）时，没有可同步内容，不要运行。
• 不要用它创建或重构根 AGENTS.md，也不要为已存在但未记录的区域创建嵌套文档，这些应交给 /audit。
• 不要用它编辑 spec 内容、取代 spec 或清除 `Assumed` spec，这些应交给 /architect。