x-multi-llm-align

x-multi-llm-align — 跨子 agent 协议对齐器

这个 skill 解决什么

把"两个子 agent 各自代表自己实现方立场来回审稿协议"的高质量对齐流程固化下来。

为什么这种流程比单方面写文档更有价值：

• 不同子 agent 分别代表不同实现方的立场，会从自己实现侧的"我得真去实现"角度提问，挖出对方写文档时漏掉的实现陷阱
• 用户作为人类中间人传递反馈，不需要两个子 agent 之间直接通信，也保留人类对关键产品决策的拍板权
• 多轮迭代后产出的契约双方都站得住脚，开发时返工率低
• 保留推理过程，后续接手的 agent 能直接读懂整套对齐逻辑，不用从头推一遍

适用与不适用

适用：

• 协议对齐（JSON/JSONL/HTTP API/RPC 契约）
• 数据结构对齐（事件 schema、消息格式、状态机定义）
• 流程对齐（接入流程、生命周期约定、错误处理流程）

不适用（这些场景将来可能有姊妹 skill）：

• 代码 PR 正确性评审 → 用 x-cr
• 写作 peer review（论文/博客/PRD）
• 单方面文档 review（不涉及第二个子 agent）

---

工作流

阶段 0 — 触发后的准备

第一步：识别讨论文件位置（按优先级）

1. 用户提供的 spec 目录下，新建/读取 discussion-<topic>.md（不污染原 spec 文档）
2. 当前项目的 dev-pipeline/discussions/discussion-<topic>.md（不存在则 mkdir -p）
3. 绝对 fallback：/tmp/multi-llm-align/discussion-<topic>.md（保留旧目录名，兼容历史讨论文件）

topic 取自 spec 主题名（如 claude-sidecar-contract、thread-event-schema），不要太泛。

单文件追加：所有轮次都写在同一份文件里（不每轮新建），让后续接手的 agent 一次读完所有上下文。

第二步：识别自己的子 agent 名

每次发言都要标注子 agent 名，方便后续接手时区分谁说的。

识别策略（按优先级）：

1. 优先使用当前子 agent / reviewer / 实现方名称。
2. 找不到就一句话问用户："我用什么名字署名？"
3. 对方子 agent 的名字：用户提供，或从 spec 文档作者标记里读，找不到就标 [<对方未知>]

发言标签格式：[agent-a] / [agent-b] / [实现方-A] / [<对方未知>]

第三步：如果讨论文件已存在

直接读完整个文件，搞清当前在第几轮、上一轮决议是什么，然后接力进入下一轮。不要重新发起第 1 轮。

---

阶段 1 — 单轮 review 流程

每轮必做这 5 步：

1.1 读全文（第一轮）或读 diff（后续轮）

第一轮：完整读所有相关 spec 文档，不抽样、不靠目录推测内容。漏读的部分会变成"我没发现的对齐问题"，下一轮才暴露，浪费一次往返。

第二轮起：只读对方改了什么（用 git 或对照之前版本），同时全文档扫一遍确认命名空间没漂移（特别要检查状态机表、映射表、错误处理段落、跨文档引用——这些位置最容易漏改）。

1.2 建立编号反馈清单

按问题性质给前缀编号：

前缀	含义	例子
E	Error / 不一致 / 矛盾（必改）	E1 — 04 和 05 文档对 content 类型定义不一致
Q	Question / 不明确点（待敲板）	Q1 — 进程是 thread 级还是 run 级？
N	New / 我建议新增的事项	N1 — 缺 generic_chat 路径定义
D	Decision / 待用户拍板的产品决策	D1 — deny 后是否强制 fail？

每个问题用统一格式：

### E1 — <一句话问题描述>
**现状**：<对方文档怎么写的，引用具体行/段落>
**问题**：<为什么这是问题，不改会发生什么后果>
**推荐**：<具体怎么改，给最终态文字而不是泛泛建议>
**理由**：<为什么这么改最好——给硬背书：实测/SDK 源码/类比同类系统>
**影响面**：<协议字段 / 状态机 / 实现细节 / 产品决策>