输出风格（使用简洁文字，无破折号，无连字符）
本技能生成的所有内容，无论是文件还是消息，都使用简洁的语言。以 你 称呼读者，如同事般温暖直接，并将每一步都呈现为可供运行或跳过的建议，而非命令。保留有实际含义的技术术语，但用简洁的语言解释每个术语。绝不用破折号或连字符作为标点：不使用长破折号、短破折号和连字符复合词。写 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 行与范围标题中的 approach 协调一致（外科手术式单行编辑，与栈相同） | ✅ 维护；标记人工撰写的分歧 | /sync |
当变更新建了 UI 设计系统时，在最近的 AGENTS.md 中添加一行指向 design.md 的指针 | ✅ 维护（仅指针） | /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 |
根据仓库证据（代码、测试、AGENTS.md）对相关工作区的范围文件（而非全部 docs/scope/）进行协调，勾选任何已完成的子任务，推进状态 | ✅ 修正 | /sync |
| 在范围中添加/重排功能或子任务 | ❌ 不做修改 | /scope |
| 覆盖或重写人工撰写的 AGENTS.md 散文 | ❌ 标记冲突 | 人类 |
创建的划分线是上下文，而非策略：仅当本次变更向您展示了整个区域时才创建；如果该区域先于变更存在，且您仅看到了一部分，则推迟到 /audit。不确定时，标记而非创建。
询问 vs 行动
行动。 仅在没有内容可同步（空变更集）时暂停。对人工撰写文件的每次编辑都会在报告中列出，以便您审查或撤销。
制品所有权
完全拥有“边界”表所授予的内容，不编写任何其他内容。作为通用子任务协调器，它会勾选任何可从仓库证据（扫描 /test//audit//sync 其他技能未勾选的子任务）验证的范围子任务，并推进功能状态；具体规则见 agent-prompt.md。
制品基准。 规范和范围默认位于 docs/ 下，如果 docs/ 是已发布的文档站点，则位于 .workflow/ 下；使用仓库中存在的任一基准（此处路径假定为 docs/）。
可移植性（任何操作系统，任何代理）
- 命令：
git是唯一必需的 CLI，并且在每个操作系统上行为相同，按所示运行git行。其他 shell 片段是 POSIX 参考，而非字面脚本：不要假定find、grep、sed、cat、test/[ ]、ls或xargs存在；使用您代理的跨平台文件工具，并自行应用分支逻辑，而不要使用 shellif/变量/重定向。 - 捆绑文件：通过相对于本技能文件夹的路径引用。将文件夹解析为绝对路径（您已经解析了这些相对路径），并在写入时（步骤 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以及等效的包清单。锁定文件仅是信号；不传递锁定文件内容。
如果没有源文件且没有依赖清单更改剩余（仅文档/测试/锁定/生成文件发生更改），则停止，无需同步。不要产生分支。
2. 定位上下文文件和规范（仅路径，在此处不要读取它们）
使用您代理的文件搜索/通配工具：
- 注意根
AGENTS.md是否存在。 - 查找每个
AGENTS.md（根 + 嵌套），排除node_modules/和.git/。 - 查找
docs/specs/下所有名称以数字开头的规范，并排序。 - 查找差异实际涉及的工作区（在此仓库中，更改文件的路径
apps/<x>/…选择docs/scope/<x>/）的范围文件；不要读取或传递所有docs/scope/。
记下路径以及更改的文件列表和差异命令；在写入时读取文件。现在读取根 AGENTS.md 内容（简短且有助于定位）。对于每个更改的文件，记下其最近的包含 AGENTS.md 的父目录（根或嵌套）；这是最可能需要更新的上下文文件。
2.5 为新增工具发现代理技能和可选的 MCP
仅当依赖清单发生更改或差异明确添加了重要的外部工具时运行。跳过普通的工具库，除非它们定义了持久的工作流或集成。
-
从清单差异（而非完整锁定文件）中识别新添加的重要包/工具：框架、路由器、样式/UI 套件、数据库、ORM/查询层、认证/会话、支付、电子邮件/通知、存储/上传、搜索、队列/后台任务、AI 提供者/向量数据库、浏览器/运行时测试、可观测性、托管/部署。包括包名称和清单中的常见别名。不要在第一项技术后就停止。
-
过滤掉已由已安装技能、已连接的 MCP 或
AGENTS.md的拒绝条目涵盖的任何内容。 -
在搜索之前询问。
询问是强制的。搜索则不是。 在工程师选择之前，不会搜索、获取、安装或产生 Agent Skill 和 MCP 发现的子进程。提供四个选项：帮我找到它们、我会命名我想要的、不搜索并记录拒绝、或者现在不搜索。只有第一个选项才能运行搜索命令。切勿静默跳过此询问，并且在工程师同意之前切勿运行搜索。
列出此变更添加的工具，用一句话说明 Agent Skill 可以为代理提供该工具的实际约定，MCP 服务器可以为其提供对真实系统的实时访问，然后询问：“是否希望我为此变更添加的工具找到 Agent Skill 和 MCP 服务器？”（标题
Agent skills），选项为是的，帮我找到它们（推荐）·我会命名我想要的·不，跳过·现在不，以后再说。如果选择“是的”则继续下文。如果选择“我会命名我想要的”，则获取列表并直接进入安装步骤，不搜索任何内容。如果选择“不，跳过”，则不运行任何操作并记录拒绝。如果选择“现在不，以后再说”，则不运行任何操作并在报告中记录候选工具。 -
将搜索隔离在只读子代理中（仅在‘是’之后，能力优先）。 将剩余集合交给发现子代理，而不是在主线程上搜索：如果您的代理支持，则在后台生成它（它不阻塞），否则阻塞；将其模型明确设置为快速、低成本层级（不要继承会话模型；在 Claude Code 上，将其生成为
researcher子代理类型，该类型固定模型）；它仅返回紧凑的候选列表。这使搜索输出保留在/sync的有界上下文之外。无子代理 → 内联搜索；无搜索能力 → 跳过并注明。询问面板仍保留在主线程上。 -
对于每个剩余项目，运行
npx skills find <tool-or-package>；如果结果较弱，则重试包/组织名称的别名。收集每个可信的 Agent Skill 候选，并在可行时使用npx skills add <owner>/<repo> --list进行确认。如果 CLI 是交互式的/不可用，则搜索“<tool>” “agent skill”并在提供之前确认。 -
MCP 搜索是可选的：首先使用连接器列表，否则每个项目使用
“<tool>” “MCP server”。MCP 是推荐的上行优势，不是必需的。 -
保持发现上限且可缓存：最多 5 次 Web 搜索和总共 8 个获取页面，优先官方注册表/文档。当
docs/.agent-cache/tool-discovery/<slug>.md未满 30 天时重用，在过滤已安装/拒绝的项目后。 -
在一个多选面板中提供所有 Agent Skill 匹配项，按技术分组：“为新增工具安装相关的 Agent Skill？”加上跳过/拒绝。然后单独提供 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-prompt.md 并严格遵循它；它是维护规则的权威。差异读取是唯一可以卸载的事情，并且仅限于大型变更集，可以通过最便宜模型上的只读 scout 子代理（Claude Code：haiku）返回紧凑映射。保持在旧工具授予所表达的相同边界内：Edit 现有文档、范围和规范 **Status**: 行；Write 严格用于全新区域嵌套 AGENTS.md；不创建根目录，不编辑规范内容（仅限状态行），不为已建立的区域创建浅层嵌套文档（这些是 agent-prompt.md 中的规则）。
要应用的输入：
MODE、BASE、MERGE_BASE、CHANGED_FILES（名称状态更改的源列表）、DIFF_COMMAND（确切的git diff命令）DELETED_PATHS（已删除的路径，用于孤立项清理）ROOT_AGENTS_MD（根 AGENTS.md 内容）、NESTED_PATHS（嵌套 AGENTS.md 路径）SPEC_PATHS（所有规范路径，用于状态行协调和过时标记）FILE_TO_CONTEXT_MAP（更改的文件 → 最近的上下文文件）SCOPE_PATH_OR_NONE（相关工作区的范围路径，而非全部docs/scope/；也是每个链接功能的状态来源，用于规范状态行协调）- 来自步骤 2.5 的
INSTALLED_SKILLS_OR_NONE、MCP_SERVERS_OR_NONE、DECLINED_TOOLS_OR_NONE
4. 传递结果
如果维护失败或未生成可解析的摘要，报告该问题并重试，不要编造结果（真正的 NOTHING_TO_SYNC 是有效的成功；崩溃或空输出则不是）。否则传递紧凑摘要：
首先用一行说明它协调了什么；然后仅列出需要工程师注意的内容（根据 docs/conventions.md）。编辑本身已包含在文件中。模板：
## /sync 完成 · 已协调 <N> 个变更文件
**已将 <AGENTS.md 文件 · 范围功能 · 规范状态> 更新以匹配差异。** （或“一切已是最新，无需同步”）
提醒事项（需要您的操作）：
- 过时规范 → /architect：`<文件>`（<原因，或 /sync 无法安全协调的状态不匹配>
- 假定规范 → /architect：`<文件>`（<规范名称> 仍为 Assumed；需要确认才能推进）
- 区域冲突 → 人类：`<文件>`（/sync 在此发现了人工撰写的散文并保留了它；请手动协调）
- 工具未安装 → 您自己：`<代理技能名称>` 留待以后
仅在特别配置的情况下，才将人类操作项从 /sync 输出中排除；否则列出所有。其思想是提供一个清晰、可操作的报告，以便工程师知道下一步该做什么。
协议
必填确认。 在步骤 4 之后，等待工程师通过说“合并并清理”或等效短语来确认。然后，如果当前分支不是基准，则以压缩提交的形式提交所有 /sync 的更改（消息为 sync: <摘要>）并推送到当前分支，不合并。对于未提交的模式，仅报告；不要提交。