migrate-design-system

迁移到设计系统

1. 选择模式。只有当请求明确提到迁移，或用户接受了提议时，才运行完整模式（build-design-system/references/run-record.md，术语）。其他情况均为审计模式。
2. 确定框架：应用所有默认值，编写 frame.md 和 standing-orders.md（references/run-folder.md）。
3. 清点、映射并核对一致性，仅供读取（references/inventory.md）。审计模式到此结束，并提供 plan.md、其中的「发现但未修复」表格以及提议。
4. 在进行任何编辑之前建立基线（references/verification.md，基线）。
5. 共享层由一个 Agent 独自负责（references/inventory.md，共享层）。
6. 端到端完成试点，然后根据其配方编写 codemod（references/worker-brief.md）。
7. 在滚动窗口中分派任务，每个工作器负责一个界面，并由另一个 Agent 验证（references/orchestration.md，references/verification.md）。
8. 将每个已验证的界面分别作为独立提交落地，然后用 close.md 和一张「发现但未修复」表格收尾（references/run-folder.md，close.md）。

绝不可交付：

• 在审计模式下进行编辑，或因「把应用整理一下」这类含糊请求而启动完整模式。
• 界面未经未参与编写的验证者验证就落地。
• 为填补缺口而臆造令牌、组件、属性或变体。
• 把行为变更伪装成迁移的一部分。
• 某个旧模块的最后一个调用方迁移后仍保留该模块，除非某个门禁明确指定负责人和移除日期。
• 交接时仍有检查失败，或放宽了断言条件。

此技能作为其他协调器下的子 Agent 运行时，会以前台调用方式启动工作器；在一条消息中同时启动多个工作器，让同一轮任务并行进行；并且绝不会在后台工作器仍在运行时结束当前轮次，因为宿主会在步骤 Agent 交还控制权时孤立或终止该工作器。等整轮任务全部返回后，再排空队列。

系统已经定型。一个协调器将应用拆分成多个界面，并让工作器 Agent 一次负责一个界面，同时保持行为不变。同级技能的路径从 <skills> 开始。界面、运行分支、相同值替换、决策、门禁、许可、占用量、状态词和 <skills> 的含义均以 build-design-system/references/run-record.md（术语）中的定义为准。此流程绝不设计系统。缺少令牌或组件时，应向系统负责人提出请求。除非常设指令授权，否则不得部署。frame.md 载明预算之前，不得启动编辑工作器。

写入流程会将每个界面和每个已决定的门禁默认值都提交到运行分支（ds/<yyyy-mm-dd>-migrate，除非另有指定），这样 Next 就可以直接合并。每项可见变更都需要门禁或决策、变更前后截图，以及一行蒙太奇记录（references/verification.md）。

协调器调用时

协调器会传入模式、系统位置、范围、试点、预算或运行文件夹。使用其提供的信息，其余内容采用 Inputs 中的默认值，并将问题记入 gates.md。未答复的门禁采用其默认值，标记为 default (unanswered)，流程绝不因此等待。若负责人在不支持子 Agent 的宿主上担任此角色，则将此情况记录为一条决策记录。回复以状态行开头，接着是 Commit: <run branch head>，然后提供最终报告、审计模式下的 plan.md，或下方的停止格式。审计模式可以与构建并行运行（references/inventory.md，审计模式和 plan.md）。

已完成

已完成意味着 frame.md 中的谓词在最终集成提交上成立，并且已通过运行文件夹中的记录证明。

• 清单脚本在该提交上运行 --check 并以 0 退出：没有旧版导入，没有 allowlist.tsv 以外的原始值，没有 frame.md 计入的调色板用法，也没有旧版文件。
• queue.tsv 中的每一行都标记为 done，且在该提交上有一条 verified 或 self-verified 的台账记录。在界面分支提交上的判定或重新打开的行都不计入。
• 阻止新增旧版用法的规则会在植入违规时使 CI 失败，并在每次交接时以 0 退出，剩余发现项列在已提交的忽略列表中（references/inventory.md）。交接时检查失败即意味着运行失败。
• baselines/MANIFEST.sha256 仍然匹配，并且每个已合并差异都通过了禁止路径检查。
• 每个已启动的 Agent 都在 agents.tsv 中有终结状态行，且 decisions.tsv 中的每一行都指向可解析的证据。
• 每个重复出现的修复都已转化为检查，或者报告说明了无法转化的原因。
• 没有任何门禁读取 todo：每项均为 done、default (unanswered)、带有已列出默认值的 gate，或 skipped (<reason>)。

首次更改某个界面的提交会修复 frame.md 中引用的投诉，并且每项声明都注明了所用命令。最终消息是运行记录中的交接报告（Handoff report），包含 migrate 的计数和 close.md 中的 Next；先列出未回答的默认值，最后列出 Found, not fixed 表。如果运行停止，请返回导致停止的规则、目前已验证的计数、运行文件夹路径、恢复时的首个操作，以及解除阻塞所需的最简回复。

输入

输入	必需	缺失时的处理
目标系统：令牌来源、组件、文档，以及版本或提交	是	按照 references/inventory.md（Finding the target system）查找；先检查已安装系统的 SKILL.md，并在 frame.md 中固定提交
标准	否	使用已安装系统 SKILL.md 中的规则；否则使用系统规格和文档。所有验证者和 ui-review 都使用同一个文件
能够构建和运行的应用仓库	是	若无法构建则停止，审计模式除外。若无法运行，则只能提供审计模式，因为无法验证任何内容。
模式	否	审计，除非请求明确说明迁移
范围	否	清单发现的所有内容，并列在 frame.md 中供相关人员删减
试点界面	否	相关人员投诉的界面；否则选择系统组件最多且包含失败状态的界面
预算	否	会话，并在 frame.md 中注明
宽度和主题	否	应用的最窄和最宽宽度，默认值为 390 和 1280，以及应用提供的所有主题
对等模式，exact 或 mapped	否	当系统值与旧版值不同时使用 mapped（references/verification.md）
使用工作树隔离的并行 Agent	否	references/platforms.md
视觉测试工具	否	capture.mjs，在 CI 环境中运行

项目说明（AGENTS.md、CLAUDE.md）会作为常设指令的基础。界面数量不超过 8 个时，按照 build-design-system/references/coordinator-path.md（Small app）中的小型应用流程，由一名工作者依次执行各阶段；清单、基线、台账和谓词仍不可少，因为打开窗口的成本高于它所节省的成本。

流程

在 Frame 前阅读 references/orchestration.md 和 references/run-folder.md。盘点是只读的，并在编写 Frame 时同步开始。每个步骤在其参考文件指定的运行文件能够证明该步骤完成时结束。

1. Frame。 在生成任何 Agent 前，确认每个字段都已填写或设有明确默认值。
2. 盘点。 一名 Agent 构建或复用盘点脚本和阻止新增旧用法的 lint 规则，映射人员则针对每个界面运行 token-mapping。有歧义的条目变为关卡。inventory/counts.txt 记录了计数、每个发现项都有对应界面，且该规则能对人为植入的违规项报错时结束。审计模式不添加规则。
3. 兼容性。 一名只读 Agent 在 parity.tsv 中为每个旧调用点给出判定。存在阻塞性缺口时，停止整个扇出，直至缺口解决。审计模式在此处写入 plan.md 后停止。
4. 基线。 每个界面都有基线或明确注明 not captured 的原因，并且清单已写入时结束。
5. 共享层。 该层已合并、运行时检查通过，并且每项基线仍然匹配或其差异已有说明时结束。
6. 试点。 工作人员、验证人员、台账条目、合并。将发现的问题修复到模板中。试点标记为 verified 并已合并时结束。
7. 构建 codemod。 在试点的起始提交上运行 codemod，并将结果与手动迁移进行比较。记录差异且第二次运行不产生更改时结束。
8. 扇出。 在 frame.md 设定的上限内使用滚动窗口，每名工作者负责一个界面，并使用各自的分支和工作树（或使用 references/platforms.md 中的备用方案）。预算使用约 70% 时停止生成 Agent。
9. 验证每个界面。 未编写代码的验证人员检查视觉差异、渲染后的检查清单、无障碍快照、行为及其变化，并运行 ui-review。台账针对该界面的当前提交给出判定时，该界面的验证结束。
10. 持续集成。 将每个已验证界面连同其捕获内容作为独立提交合并，然后运行集成检查。集成构建失败时，停止合并，直至构建通过。
11. 删除旧代码。 当某个旧模块的调用方数量为零时，由一名人员在一次更改中删除该模块、其适配器和相应的允许列表条目，并由 lint 规则禁止该路径。
12. 收尾。 最后排空队列，在最终集成提交上重新捕获每个界面，写入 close.md，审计 decisions.tsv，将每项反复出现的修复转化为检查，并清理临时文件。

边界

只要可以生成子 Agent，协调者就绝不编写产品代码。在不支持子 Agent 的主机上，协调者会自行按顺序执行各阶段，并依据 references/verification.md 自行验证。

无需询问，直接决定并记录：界面的拆分与顺序、上限内的窗口大小、重试与拆分（build-design-system/references/coordinator-path.md，开发服务器与重试）、运行验证的人员、干净的合并、证据支持的简要修复或 codemod、任何界面上的同值替换、已确定的关卡默认值，以及仅添加无障碍改进（build-design-system/references/traps.md，仅添加无障碍改进）。

将事项暂存到 gates.md，设定默认值并继续工作。已映射的像素更改、颜色调整、组件替换，以及非试点界面上的 codemod，都是默认在运行分支上连同捕获内容一起合并的关卡。这些关卡的默认值是保持代码原样：系统缺少的 token 或组件；无人能解释的视觉差异，或会移除、重命名或重构语义的更改；基线中已有的 blocking ui-review 发现项（该界面仍可通过验证）；任何规模的行为更改；代码与之矛盾的长期指令；一次重新规划后仍未解决的死路；删除仓库外部正在使用的数据或导出内容。

绝不让两名工作者编辑同一个文件，也绝不让任何工作者在共享层阶段结束后触碰共享层。绝不将 checks-only、blocked 或自我报告计为已验证，也绝不以决策条目代替验证人员的判定。